docs: Add Sprint 01 planning documentation

Create comprehensive sprint planning documentation for Core Architecture Correction sprint. This addresses three fatal architectural problems from v1.0.0 release. Sprint documents include: - Executive proposal with architecture analysis - Detailed implementation guide with code snippets - Issue breakdown with dependencies - Sprint summary with approval checklist Sprint creates 10 issues in Gitea milestone 29: - Issues #19-28 covering package rename, MCP protocol implementation, Docker infrastructure, testing, and documentation - Total estimated effort: 19-28 hours (1 week sprint) - All issues properly sized (S/M), labeled, and dependency-tracked This is attempt #3 - all details from architectural correction prompt have been captured. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-02-03 17:53:59 -05:00
parent c9961293d9
commit 16436c847a
4 changed files with 2516 additions and 0 deletions
--- a/docs/sprint-proposals/sprint-01-issue-breakdown.md
+++ b/docs/sprint-proposals/sprint-01-issue-breakdown.md
@@ -0,0 +1,489 @@
+# 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)