personal-projects/gitea-mcp-remote
1
0
Fork 0
generated from personal-projects/leo-claude-mktplace
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
809eef132ab9e2c918882c2b5ccd7fec290d3c60
gitea-mcp-remote/docs/sprint-proposals/SPRINT-01-SUMMARY.md
lmiranda 16436c847a 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

8.8 KiB
Raw Blame History

Sprint 01: Core Architecture Correction - SUMMARY

Status: 🟡 AWAITING APPROVAL Milestone: Sprint 01: Core Architecture Correction Sprint Duration: 1 week (Feb 3-10, 2026) Total Estimated Effort: 19-28 hours

Sprint Overview

This sprint addresses three fatal architectural problems introduced in the v1.0.0 release. This is surgical correction work, not a rewrite - supporting modules (config, middleware, filtering, tests) are solid and only need import path updates.

The Three Fatal Problems

  1. Subprocess Architecture → Direct Python Import

    • Current: Spawns gitea-mcp-server as subprocess
    • Required: Direct Python import from marketplace package

  2. Custom REST API → MCP Streamable HTTP Protocol

    • Current: Custom endpoints /tools/list and /tools/call
    • Required: MCP protocol POST /mcp with JSON-RPC 2.0

  3. Missing Marketplace Dependency

    • Current: Comment about installing separately
    • Required: Actual pip dependency from marketplace Git repo

Issues Created

All issues are in Gitea milestone: Sprint 01: Core Architecture Correction

Issue Title Type Size Est. Time Dependencies
#19 Rename package to gitea_mcp_remote and update configuration Refactor M 2-3h None
#20 Update middleware and filtering with new import paths Refactor S 1h #19
#21 Move tests to repository root and update imports Refactor M 1-2h #19, #20
#22 Add marketplace dependency and update project config Build S 1h #19
#23 Remove old server and create MCP base server structure Feature M 2-3h #19, #20, #22
#24 Implement MCP Streamable HTTP protocol endpoints Feature M 2-3h #23
#25 Create Docker multi-service infrastructure with Caddy Build M 3-4h #22, #24
#26 Create startup scripts and MCP server tests Test M 2-3h #24
#27 Create CLAUDE.md and update deployment documentation Docs M 2-3h All
#28 Final validation and integration testing Test M 2-3h All

Total Issues: 10 (was 9, split large task into 2 medium tasks)

Execution Order

The dependency graph ensures proper execution order:

#19 (Rename + Config) ← FOUNDATION
  ├─→ #20 (Middleware + Filtering)
  │     └─→ #21 (Tests)
  │
  ├─→ #22 (pyproject.toml)
  │     ├─→ #23 (MCP Base Server)
  │     │     ├─→ #24 (MCP Protocol)
  │     │     │     ├─→ #25 (Docker)
  │     │     │     └─→ #26 (Scripts + Tests)
  │     │     │
  │     └─→ #21 (Tests - can run parallel)
  │
  └─→ All above
        └─→ #27 (Documentation)
              └─→ #28 (Final Validation)

Recommended sequence:

  1. #19 → #20 → #22 → #21 (Foundation - Day 1-2)
  2. #23 → #24 (Core server - Day 2-3)
  3. #25 → #26 (Infrastructure - Day 3-4)
  4. #27 → #28 (Documentation and validation - Day 4-5)

What to KEEP (Rename Imports Only)

These modules are well-tested and solid:

  • ✅ config/settings.py - Minor field changes only
  • ✅ middleware/auth.py - Import paths only
  • ✅ filtering/filter.py - Change ValueError to warning
  • ✅ All tests - Move to root, update imports
  • ✅ DEPLOYMENT.md - Update references

What to REPLACE

  • ❌ server.py → ✅ server_http.py (new MCP implementation)
  • ❌ pyproject.toml → ✅ Updated with marketplace dependency
  • ❌ docker-compose.yml → ✅ docker/docker-compose.yml (two services)
  • ❌ Dockerfile → ✅ docker/Dockerfile (git + port 8080)

New Files to CREATE

  • 📄 docker/Caddyfile - Reverse proxy config
  • 📄 CLAUDE.md - Project guidance for Claude Code
  • 📄 tests/test_server_http.py - MCP server tests
  • 📄 scripts/start.sh - Production startup
  • 📄 scripts/healthcheck.sh - Docker healthcheck

Success Criteria (16 Validations)

Package Structure (3)

  • src/gitea_mcp_remote/ exists (not gitea_http_wrapper)
  • No imports reference gitea_http_wrapper
  • tests/ is at repository root (not in src/)

Configuration (3)

  • 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 (4)

  • 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 (3)

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

Docker (3)

  • 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

Timeline

Effort Distribution

  • Small (1-2h): 2 issues (#20, #22) = 2-4 hours
  • Medium (2-4h): 8 issues (#19, #21, #23-28) = 17-24 hours
  • Total: 19-28 hours ≈ 23.5 hours average

Sprint Schedule (1 week)

  • Day 1-2: Foundation (Issues #19-22) - 5-7 hours
  • Day 2-3: Core Server (Issues #23-24) - 4-6 hours
  • Day 3-4: Infrastructure (Issues #25-26) - 5-7 hours
  • Day 4-5: Docs & Validation (Issues #27-28) - 4-6 hours
  • Buffer: 1-2 hours for unexpected issues

Risk Assessment

Low Risk ✅

  • Config, middleware, filtering: Well-tested, only import changes
  • Test relocation: No logic changes

Medium Risk ⚠️

  • server_http.py: New file, but following MCP HTTP spec
  • MCP protocol integration: Well-documented standard

High Risk 🔴

  • Docker multi-service: Requires Caddy configuration
  • Marketplace Git dependency: Must be accessible during build

Mitigation

  1. Execute in exact dependency order
  2. Test at each major milestone
  3. Validate Docker build before deployment
  4. Keep development branch for rollback

Documentation Created

  1. sprint-01-core-architecture-correction.md

    • Executive summary
    • Three fatal problems explained
    • What to keep vs replace
    • Architecture diagram
    • Risk assessment

  2. sprint-01-implementation-guide.md

    • Step-by-step technical implementation
    • Code snippets for each change
    • Validation commands
    • Complete file replacements

  3. sprint-01-issue-breakdown.md

    • Detailed issue descriptions
    • Dependency graph
    • Execution order
    • Size distribution

  4. SPRINT-01-SUMMARY.md (this file)

    • Sprint overview
    • Issue table with links
    • Success criteria
    • Approval checklist

Links

Approval Checklist

Before execution begins, verify:

  • All 10 issues created and assigned to milestone
  • Dependencies correctly set between issues
  • Labels applied correctly (Type, Priority, Component, Size)
  • Implementation guide reviewed and accurate
  • Timeline is realistic (1 week)
  • Success criteria are clear and testable
  • Rollback plan understood (development branch)
  • User has reviewed and approved the plan

Next Steps

AWAITING USER APPROVAL to begin execution.

Once approved:

  1. Start with Issue #19 (Foundation)
  2. Follow dependency order strictly
  3. Update issue status as work progresses
  4. Run validation after each major milestone
  5. Complete sprint with Issue #28 (Final Validation)

Note: This is attempt #3. User emphasized paying close attention to details. All requirements from the architectural correction prompt have been captured in the issue breakdown.

Reference in New Issue View Git Blame Copy Permalink