Refactor mcp_server.py into a modular gitea_tools package #65

New Issue

2026-07-02T05:43:19-05:00

jcwalker3 commented

2026-07-02 05:43:19 -05:00

Curated 2026-07-02 to reflect review consensus (issue text only; not started).

Refactor mcp_server.py (currently ~1689 lines) into a modular gitea_tools
package. This is a staged refactor, not a single all-at-once rewrite. Do
not start implementation until the staging and compatibility work below is
agreed.

Required before/within implementation

Compatibility matrix (produce first): document every MCP tool's name,
parameters, return payload shape, and error behavior as the backward-compatible
contract the refactor must preserve.

Staged extraction plan (land as separate PRs, each independently green):

API/client extraction (request, pagination, error wrapping).
Auth/config/profile extraction.
Audit/redaction extraction.
Issue / PR / review / label / tracker domain extraction (by domain).
Final thin mcp_server.py = MCP tool registration layer only.

Acceptance criteria

Compatibility matrix exists and is referenced by each stage.
Tests prove no mutation path bypasses profile / allowed-operation / audit gates.
Existing MCP tool names remain backward compatible.
Existing return payloads remain backward compatible.
Full test suite passes after each stage.
No unrelated behavior changes.

Non-goals

No behavior changes beyond module movement (unless explicitly documented).
Do not begin coding before the compatibility matrix and stage boundaries are approved.

_Curated 2026-07-02 to reflect review consensus (issue text only; not started)._ Refactor `mcp_server.py` (currently ~1689 lines) into a modular `gitea_tools` package. This is a **staged** refactor, not a single all-at-once rewrite. Do **not** start implementation until the staging and compatibility work below is agreed. ## Required before/within implementation **Compatibility matrix** (produce first): document every MCP tool's name, parameters, return payload shape, and error behavior as the backward-compatible contract the refactor must preserve. **Staged extraction plan** (land as separate PRs, each independently green): 1. API/client extraction (request, pagination, error wrapping). 2. Auth/config/profile extraction. 3. Audit/redaction extraction. 4. Issue / PR / review / label / tracker domain extraction (by domain). 5. Final thin `mcp_server.py` = MCP tool registration layer only. ## Acceptance criteria * Compatibility matrix exists and is referenced by each stage. * Tests prove no mutation path bypasses profile / allowed-operation / audit gates. * Existing MCP tool names remain backward compatible. * Existing return payloads remain backward compatible. * Full test suite passes after each stage. * No unrelated behavior changes. ## Non-goals * No behavior changes beyond module movement (unless explicitly documented). * Do not begin coding before the compatibility matrix and stage boundaries are approved.