personal-projects/gitea-mcp-remote
1
0
Fork 0
generated from personal-projects/leo-claude-mktplace
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
fb8cc0811228116dad8d4c0b8376c963120e736f
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

245 lines
8.8 KiB
Markdown
Raw Blame History

# Sprint 01: Core Architecture Correction - SUMMARY
**Status:** 🟡 AWAITING APPROVAL
**Milestone:** [Sprint 01: Core Architecture Correction](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/milestone/29)
**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](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/19) | Rename package to gitea_mcp_remote and update configuration | Refactor | M | 2-3h | None |
| [#20](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/20) | Update middleware and filtering with new import paths | Refactor | S | 1h | #19 |
| [#21](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/21) | Move tests to repository root and update imports | Refactor | M | 1-2h | #19, #20 |
| [#22](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/22) | Add marketplace dependency and update project config | Build | S | 1h | #19 |
| [#23](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/23) | Remove old server and create MCP base server structure | Feature | M | 2-3h | #19, #20, #22 |
| [#24](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/24) | Implement MCP Streamable HTTP protocol endpoints | Feature | M | 2-3h | #23 |
| [#25](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/25) | Create Docker multi-service infrastructure with Caddy | Build | M | 3-4h | #22, #24 |
| [#26](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/26) | Create startup scripts and MCP server tests | Test | M | 2-3h | #24 |
| [#27](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/27) | Create CLAUDE.md and update deployment documentation | Docs | M | 2-3h | All |
| [#28](https://gitea.hotserv.cloud/personal-projects/gitea-mcp-remote/issues/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](./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](./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](./sprint-01-issue-breakdown.md)**
- Detailed issue descriptions
- Dependency graph
- Execution order
- Size distribution
4. **[SPRINT-01-SUMMARY.md](./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.
Reference in New Issue View Git Blame Copy Permalink