gitea-mcp-remote/docs/sprint-proposals/sprint-01-issue-breakdown.md

# Sprint 01: Issue Breakdown

## Issue Structure

Each issue is sized for 1-4 hours of work and includes:
- Clear acceptance criteria
- Dependencies on other issues
- Reference to implementation guide
- Appropriate labels

---

## Issue #1: Rename Package Directory and Update Config

**Title:** `[Sprint 01] refactor: Rename package to gitea_mcp_remote and update configuration`

**Estimated Time:** 2-3 hours

**Labels:**
- `Type/Refactor`
- `Priority/High`
- `Component/Core`
- `Size/M`

**Dependencies:** None

**Description:**

Rename the package directory from `gitea_http_wrapper` to `gitea_mcp_remote` and update the configuration module with new fields required for MCP protocol.

**Tasks:**
- [ ] Rename `src/gitea_http_wrapper/` to `src/gitea_mcp_remote/`
- [ ] Update `config/settings.py`:
  - Make `gitea_repo` optional (allow None)
  - Add `mcp_auth_mode: str = "optional"` field
  - Change HTTP defaults: `http_host="0.0.0.0"`, `http_port=8080`
  - Remove `get_gitea_mcp_env()` method
- [ ] Update `config/__init__.py` imports
- [ ] Verify imports work: `from gitea_mcp_remote.config import GiteaSettings`

**Acceptance Criteria:**
- Package directory is `src/gitea_mcp_remote/`
- Config has `mcp_auth_mode` field
- Config has optional `gitea_repo` field
- HTTP defaults are `0.0.0.0:8080`
- Can import: `from gitea_mcp_remote.config import GiteaSettings`

**Implementation Reference:**
See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 1, Issues #1-2

---

## Issue #2: Update Middleware and Filtering Modules

**Title:** `[Sprint 01] refactor: Update middleware and filtering with new import paths`

**Estimated Time:** 1 hour

**Labels:**
- `Type/Refactor`
- `Priority/High`
- `Component/Core`
- `Size/S`

**Dependencies:** Issue #1

**Description:**

Update middleware and filtering modules to use new package name. Middleware requires only import changes, filtering changes ValueError to warning.

**Tasks:**
- [ ] Update `middleware/__init__.py` imports
- [ ] Update `middleware/auth.py` - imports only
- [ ] Update `filtering/__init__.py` imports
- [ ] Update `filtering/filter.py`:
  - Add logging import
  - Change line 29-32 ValueError to logger.warning
- [ ] Verify imports work

**Acceptance Criteria:**
- Middleware imports from `gitea_mcp_remote.middleware`
- Filtering imports from `gitea_mcp_remote.filtering`
- ToolFilter logs warning instead of raising ValueError when both filter types specified
- Can import both modules successfully

**Implementation Reference:**
See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 2, Issues #3-4

---

## Issue #3: Relocate Tests and Update Imports

**Title:** `[Sprint 01] refactor: Move tests to repository root and update imports`

**Estimated Time:** 1-2 hours

**Labels:**
- `Type/Refactor`
- `Priority/High`
- `Component/Tests`
- `Size/M`

**Dependencies:** Issue #1, Issue #2

**Description:**

Move test suite from `src/gitea_mcp_remote/tests/` to repository root `tests/` directory and update all test imports to use new package name.

**Tasks:**
- [ ] Move `src/gitea_mcp_remote/tests/` to `tests/`
- [ ] Update imports in `tests/conftest.py`
- [ ] Update imports in `tests/test_config.py`
- [ ] Update imports in `tests/test_middleware.py`
- [ ] Update imports in `tests/test_filtering.py`
- [ ] Update `pytest.ini` to use `testpaths = tests`
- [ ] Run pytest and verify all tests pass

**Acceptance Criteria:**
- Tests located at repository root: `tests/`
- No tests in `src/gitea_mcp_remote/tests/`
- All test imports use `gitea_mcp_remote` package name
- All existing tests pass: `pytest tests/ -v`
- pytest.ini references `testpaths = tests`

**Implementation Reference:**
See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 3, Issues #5-6

---

## Issue #4: Replace pyproject.toml with Marketplace Dependency

**Title:** `[Sprint 01] build: Add marketplace dependency and update project configuration`

**Estimated Time:** 1 hour

**Labels:**
- `Type/Build`
- `Priority/Critical`
- `Component/Dependencies`
- `Size/S`

**Dependencies:** Issue #1

**Description:**

Replace pyproject.toml with new configuration including the marketplace Git dependency for gitea-mcp-server.

**Tasks:**
- [ ] Update `pyproject.toml`:
  - Add marketplace Git dependency
  - Update package name to `gitea-mcp-remote`
  - Change entry point to `gitea-mcp-remote`
  - Update version to 1.1.0
  - Update test paths to `testpaths = ["tests"]`
- [ ] Test installation: `pip install -e .`
- [ ] Verify marketplace dependency installs
- [ ] Verify entry point exists: `which gitea-mcp-remote`

**Acceptance Criteria:**
- pyproject.toml includes marketplace Git dependency
- Entry point is `gitea-mcp-remote` (not `gitea-http-wrapper`)
- Can run: `pip install -e .` successfully
- Marketplace dependency installs from Git repository
- Command `gitea-mcp-remote` is available

**Implementation Reference:**
See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 5, Issue #9

---

## Issue #5: Implement MCP HTTP Server

**Title:** `[Sprint 01] feat: Implement MCP Streamable HTTP protocol server`

**Estimated Time:** 4-6 hours

**Labels:**
- `Type/Feature`
- `Priority/Critical`
- `Component/Core`
- `Size/L` → **BREAKDOWN REQUIRED**

**Dependencies:** Issue #1, Issue #2, Issue #4

**Description:**

**NOTE:** This is a Large (L) task that should be broken down into Medium (M) subtasks:

### Subtask 5.1: Remove Old Server and Create MCP Base Server (2-3 hours)
- Delete `src/gitea_mcp_remote/server.py`
- Create `src/gitea_mcp_remote/server_http.py` with:
  - Imports from marketplace `mcp_server`
  - GiteaMCPServer class with GiteaClient initialization
  - Startup/shutdown handlers
  - Basic route structure

### Subtask 5.2: Implement MCP Protocol Endpoints (2-3 hours)
- Add HEAD /mcp endpoint (protocol version)
- Add POST /mcp endpoint (JSON-RPC 2.0 handler)
- Implement MCP methods:
  - `initialize`
  - `tools/list`
  - `tools/call`
- Add error handling for JSON-RPC

**Combined Tasks:**
- [ ] Delete old `server.py`
- [ ] Create new `server_http.py`
- [ ] Import from marketplace: `from mcp_server import ...`
- [ ] Implement GiteaMCPServer class
- [ ] Implement HEAD /mcp (protocol version)
- [ ] Implement POST /mcp (JSON-RPC handler)
- [ ] Implement initialize method
- [ ] Implement tools/list method with filtering
- [ ] Implement tools/call method with dispatcher
- [ ] Keep health endpoints: /health, /healthz, /ping
- [ ] Add JSON-RPC error handling
- [ ] Verify imports: `from gitea_mcp_remote.server_http import GiteaMCPServer`

**Acceptance Criteria:**
- Old `server.py` deleted
- New `server_http.py` exists
- Imports from marketplace `mcp_server` package
- MCP endpoints exist: `POST /mcp`, `HEAD /mcp`
- Health endpoints exist: `/health`, `/healthz`, `/ping`
- No subprocess spawning code
- Can import server module successfully
- JSON-RPC 2.0 request/response handling works

**Implementation Reference:**
See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 4, Issues #7-8

**Recommendation:** Create two separate issues (5.1 and 5.2) to keep within M size.

---

## Issue #6: Create Docker Infrastructure

**Title:** `[Sprint 01] build: Create Docker multi-service infrastructure with Caddy`

**Estimated Time:** 3-4 hours

**Labels:**
- `Type/Build`
- `Priority/High`
- `Component/Docker`
- `Size/M`

**Dependencies:** Issue #4, Issue #5

**Description:**

Create Docker infrastructure with two-service architecture: Python app and Caddy reverse proxy.

**Tasks:**
- [ ] Create `docker/` directory
- [ ] Create `docker/docker-compose.yml` with two services (app + caddy)
- [ ] Create `docker/Dockerfile`:
  - Install git package
  - Expose port 8080
  - Use curl for healthcheck
  - Install marketplace dependency
- [ ] Create `docker/Caddyfile`:
  - HTTPS termination
  - Proxy to app:8080
  - MCP endpoint routing
- [ ] Validate Dockerfile builds
- [ ] Validate docker-compose configuration
- [ ] Validate Caddyfile syntax

**Acceptance Criteria:**
- `docker/docker-compose.yml` has two services (app + caddy)
- `docker/Dockerfile` installs git and uses port 8080
- `docker/Caddyfile` exists and proxies to app:8080
- Can build: `docker build -f docker/Dockerfile -t test .`
- Can validate: `docker-compose -f docker/docker-compose.yml config`
- Caddy config validates successfully

**Implementation Reference:**
See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 6, Issues #11-14

---

## Issue #7: Create Utility Scripts and Server Tests

**Title:** `[Sprint 01] test: Create startup scripts and MCP server tests`

**Estimated Time:** 2-3 hours

**Labels:**
- `Type/Test`
- `Priority/Medium`
- `Component/Tests`
- `Size/M`

**Dependencies:** Issue #5

**Description:**

Create production utility scripts and comprehensive tests for the new MCP HTTP server.

**Tasks:**
- [ ] Create `scripts/start.sh` (production startup)
- [ ] Create `scripts/healthcheck.sh` (Docker healthcheck)
- [ ] Make scripts executable
- [ ] Create `tests/test_server_http.py`:
  - Health endpoint tests
  - MCP HEAD endpoint test (protocol version)
  - MCP POST endpoint tests (initialize, tools/list, tools/call)
  - JSON-RPC error handling tests
  - Tool filtering integration test
- [ ] Run new tests and verify they pass

**Acceptance Criteria:**
- `scripts/start.sh` validates environment and starts server
- `scripts/healthcheck.sh` checks health endpoint
- Both scripts are executable
- `tests/test_server_http.py` exists with comprehensive coverage
- All new tests pass: `pytest tests/test_server_http.py -v`
- All existing tests still pass: `pytest tests/ -v`

**Implementation Reference:**
See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 7-8, Issues #15-16

---

## Issue #8: Create Documentation

**Title:** `[Sprint 01] docs: Create CLAUDE.md and update deployment documentation`

**Estimated Time:** 2-3 hours

**Labels:**
- `Type/Documentation`
- `Priority/Medium`
- `Component/Documentation`
- `Size/M`

**Dependencies:** All previous issues

**Description:**

Create comprehensive project documentation for Claude Code and update deployment guide with new MCP protocol and Docker structure.

**Tasks:**
- [ ] Create `CLAUDE.md`:
  - Project overview
  - Architecture diagram
  - Development workflows
  - MCP protocol notes
  - Configuration reference
  - Deployment instructions
  - Troubleshooting guide
- [ ] Update `DEPLOYMENT.md`:
  - Replace custom REST API refs with MCP protocol
  - Update Docker structure (docker/ directory, two services)
  - Update marketplace dependency installation
  - Update Claude Desktop config example
  - Add MCP protocol debugging section
- [ ] Verify documentation accuracy

**Acceptance Criteria:**
- `CLAUDE.md` exists with complete project guidance
- `DEPLOYMENT.md` updated with MCP protocol references
- No references to old `/tools/list` or `/tools/call` endpoints
- Docker paths reference `docker/docker-compose.yml`
- Claude Desktop config shows `/mcp` endpoint
- All code examples are accurate

**Implementation Reference:**
See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Phase 9, Issues #17-18

---

## Issue #9: Final Validation and Integration Testing

**Title:** `[Sprint 01] test: Final validation and integration testing`

**Estimated Time:** 2-3 hours

**Labels:**
- `Type/Test`
- `Priority/Critical`
- `Component/Integration`
- `Size/M`

**Dependencies:** All previous issues

**Description:**

Run complete validation checklist to ensure all architectural corrections are in place and working correctly.

**Tasks:**
- [ ] Verify package structure (no gitea_http_wrapper)
- [ ] Verify no old imports remain
- [ ] Verify config has all new fields
- [ ] Verify server has MCP endpoints
- [ ] Run: `pip install -e .` successfully
- [ ] Run: `pytest tests/ -v` - all tests pass
- [ ] Build Docker image successfully
- [ ] Validate docker-compose configuration
- [ ] Validate Caddyfile syntax
- [ ] Test MCP endpoint responds to protocol version request
- [ ] Test MCP endpoint handles JSON-RPC messages
- [ ] Document any issues found
- [ ] Create follow-up issues if needed

**Acceptance Criteria:**
All 16 validation items pass:

**Package Structure:**
- [ ] `src/gitea_mcp_remote/` exists (not `gitea_http_wrapper`)
- [ ] No imports reference `gitea_http_wrapper`
- [ ] `tests/` is at repository root (not in `src/`)

**Configuration:**
- [ ] `config/settings.py` has `mcp_auth_mode` field
- [ ] `config/settings.py` has `gitea_repo: str | None`
- [ ] HTTP defaults are `0.0.0.0:8080`

**Server Implementation:**
- [ ] `server_http.py` imports from `mcp_server` package
- [ ] MCP endpoints exist: `POST /mcp`, `HEAD /mcp`
- [ ] Health endpoints exist: `/health`, `/healthz`, `/ping`
- [ ] No subprocess spawning code

**Dependencies:**
- [ ] `pyproject.toml` has marketplace Git dependency
- [ ] Entry point is `gitea-mcp-remote` (not `gitea-http-wrapper`)
- [ ] Can run: `pip install -e .` successfully

**Docker:**
- [ ] `docker/docker-compose.yml` has two services (app + caddy)
- [ ] `docker/Dockerfile` installs git and uses port 8080
- [ ] `docker/Caddyfile` exists and proxies to app:8080

**Tests:**
- [ ] All tests pass: `pytest tests/`

**Implementation Reference:**
See `docs/sprint-proposals/sprint-01-implementation-guide.md` - Final Validation section

---

## Issue Dependencies Graph

```
Issue #1 (Rename + Config)
    ├─→ Issue #2 (Middleware + Filtering)
    │       └─→ Issue #3 (Tests)
    │
    ├─→ Issue #4 (pyproject.toml)
    │       ├─→ Issue #5 (MCP Server)
    │       │       ├─→ Issue #6 (Docker)
    │       │       └─→ Issue #7 (Scripts + Tests)
    │       │
    │       └─→ Issue #3 (Tests)
    │
    └─→ All above
            └─→ Issue #8 (Documentation)
                    └─→ Issue #9 (Final Validation)
```

## Execution Order

1. Issue #1 - Rename + Config (Foundation)
2. Issue #2 - Middleware + Filtering (Supporting modules)
3. Issue #4 - pyproject.toml (Dependencies before server)
4. Issue #3 - Tests (Can run in parallel with #4)
5. Issue #5 - MCP Server (Core implementation) **Consider splitting into 5.1 and 5.2**
6. Issue #6 - Docker (Deployment infrastructure)
7. Issue #7 - Scripts + Tests (Validation tools)
8. Issue #8 - Documentation (After implementation complete)
9. Issue #9 - Final Validation (Sprint completion)

## Size Distribution

- **Small (1-2h):** Issues #2, #4 (2 issues)
- **Medium (2-4h):** Issues #1, #3, #6, #7, #8, #9 (6 issues)
- **Large (4-6h):** Issue #5 (1 issue - SHOULD BE SPLIT)

**Recommendation:** Split Issue #5 into two Medium issues for better tracking and clearer completion criteria.

## Total Estimated Time

- Minimum: 19 hours
- Maximum: 28 hours
- Average: 23.5 hours
- **Sprint Duration:** 1 week (5 working days)