Phase 8f: MCP Rewrite (SDK Wrappers)
Goal: Rewrite all 26 MCP tools to wrap SDK methods instead of raw httpx. Add 7 new tools (6 block + delete_sprint). Achieve 32/32 SDK method coverage. Reduce tool code from ~794 lines to ~250 lines.
Owner: Dev agent
Repo:
forgejo_admin/pal-e-docs-mcpDepends on: 8e (integration tests verify SDK works against live service)
Vision
The MCP server is the capability boundary of the AI Agency. Agents can only do what MCP tools allow. Today, 6 block SDK methods exist with no MCP tools — agents can't do block-level operations. This phase removes that bottleneck and delivers the primitives that skills (sprint-sync, update-docs, implement-phase) will compose into token-efficient workflows.
After 8f: every SDK method has an MCP tool. 100% coverage. The skill design space opens up — skills can browse TOCs, read individual sections, update single blocks instead of downloading and rewriting entire notes.
Sub-Phases
| # | Sub-Phase | Slug | What | Status |
|---|---|---|---|---|
| 8f-1 | SDK Publish Pipeline | <code>phase-postgres-8f1-sdk-publish</code> | Activate pal-e-docs-sdk in Woodpecker, verify publish to Forgejo PyPI, configure MCP server to resolve SDK from registry | COMPLETED |
| 8f-2 | MCP Rewrite Core | <code>phase-postgres-8f2-mcp-rewrite-core</code> | Rewrite server.py + all 26 existing tools + add 7 new tools. PR #23 merged. v0.2.0 published. | COMPLETED |
| 8f-3 | Param Alignment Audit | <code>phase-postgres-8f3-param-alignment</code> | Verified 13 param translations (8 documented + 5 discovered). Fixed tags=None edge case. 25 tests. PR #25 merged. | COMPLETED |
| 8f-4 | QA Nits Cleanup | <code>phase-postgres-8f4-qa-nits</code> | .gitignore + l→lbl E741 rename. Batched into PR #25. | COMPLETED |
SDK Coverage Target: 32/32
| Mixin | SDK Methods | MCP Tools Before | MCP Tools After |
|---|---|---|---|
| NotesMixin (6) | list, get, create, update, delete, revisions | 6/6 | 6/6 |
| SearchMixin (1) | search_notes | 1/1 | 1/1 |
| BlocksMixin (6) | get_note_toc, list_blocks, get_section, update_block, create_block, delete_block | <strong>0/6</strong> | 6/6 |
| SprintsMixin (11) | list, create, get, update, delete, backlog, list_items, add_item, update_item, delete_item, bulk_move | 10/11 | 11/11 |
| LinksMixin (2) | get_note_links, update_note_links | 2/2 | 2/2 |
| ProjectsMixin (2) | list, create | 2/2 | 2/2 |
| ReposMixin (3) | list, create, update | 3/3 | 3/3 |
| TagsMixin (1) | list_tags | 1/1 | 1/1 |
| <strong>Total</strong> | <strong>32</strong> | <strong>25/32</strong> | <strong>32/32</strong> |
Architectural Changes
- server.py: get_client() → get_sdk() — Swap
httpx.ClientforPalEDocsClientfrom SDK - server.py: _ok(response) → _ok(data) — Takes parsed dict/list from SDK, not httpx.Response. Follows woodpecker-mcp pattern.
- server.py: _error_response() — Catches
PalEDocsErrorand subclasses (NotFoundError, ValidationError, ServerError) instead ofhttpx.HTTPStatusError - pyproject.toml — Replace
httpx>=0.27withpal-e-docs-sdk>=0.1.0. Configure Forgejo PyPI index. - tools/__init__.py — Add
blocksmodule registration
Param Translation Map (13 items — audited 2026-03-07)
See
phase-postgres-8f3-param-alignment for the full audit. All 13 verified correct or fixed. Edge case #12 (tags=None) fixed in PR #25. CSV hardening (trailing comma filter) applied across notes.py, sprints.py, links.py.Reference Pattern
woodpecker-mcp wrapping woodpecker-sdk is the proven pattern. Key differences: _ok(data: Any) instead of _ok(response: httpx.Response), SDK client instead of httpx.Client, typed exceptions instead of HTTP status errors.Skill Impact (delivered by 8f, consumed by 7f + Epilogue)
8f delivers the block-level primitives. Downstream phases rewire skills to use them:
| Skill | Current Pattern | Enabled by 8f | Rewired in |
|---|---|---|---|
| /update-docs | get_note ×4 (~20K tokens) | get_section ×4 (~2K tokens) | 7f |
| /implement-phase | get_note ×4 (~20K tokens) | get_toc + get_section (~1.4K tokens) | Epilogue item 3 |
| /sprint-sync | No block need | No change needed | N/A |
| Session injection | 4× get_note (~8.7K tokens) | get_toc + get_section (~400 tokens) | Epilogue item 3 |
Related
phase-postgres-8-mcp-optimization— parent phasephase-postgres-8e-integration-tests— proves SDK works against live servicephase-postgres-7d-api-mcp-tools— block API endpoints the new tools wrapphase-postgres-7f-doc-cleanup-sop— consumes block tools for skill rewritesphase-postgres-epilogue-cleanup— item 3 consumes block tools for session upgradetodo-forgejo-pypi— Forgejo PyPI pattern (established, SDK not yet published)