# 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.