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)