gitea-mcp-remote/docs/sprint-proposals/SPRINT-01-SUMMARY.md

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

• Milestone: https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/milestone/29
• Repository: https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote
• Branch: development
• Marketplace: https://gitea.hotserv.cloud/personal-projects/leo-claude-mktplace

---

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.