pal-e-docs

Phase 8f-2: MCP Rewrite Core

phase-postgres-8f2-mcp-rewrite-core Phase

Project
Goal: Rewrite server.py, rewrite all 26 existing tools to SDK wrappers, add 7 new tools (6 block + delete_sprint). Achieve 32/32 SDK coverage. Bump version to fix publish pipeline.
Owner: Dev agent
Repo: forgejo_admin/pal-e-docs-mcp
Depends on: 8f-1 (SDK must be published and importable)

Scope

server.py changes

  • Replace import httpx with from pal_e_docs_sdk import PalEDocsClient, PalEDocsError, NotFoundError, ValidationError, ServerError
  • get_client() → get_sdk() — returns PalEDocsClient instead of httpx.Client
  • _ok(response: httpx.Response) → _ok(data: Any) — takes parsed data from SDK, returns json.dumps(data, indent=2). Returns {"ok": true} for None.
  • _error_response() — catch PalEDocsError hierarchy instead of httpx.HTTPStatusError. Extract exc.status_code and exc.detail.

pyproject.toml changes

  • Replace httpx>=0.27 with pal-e-docs-sdk>=0.1.0
  • Bump version from 0.1.0 → 0.2.0 (fixes publish pipeline #31 failure)
  • Add Forgejo PyPI index configuration

26 existing tools rewritten

Each tool: validate/transform MCP params → get_sdk().method() → _ok(result). Try/except catches SDK exceptions.
Simple (~5 lines): get_note, delete_note, get_note_revisions, get_note_links, list_projects, list_tags, list_repos, get_sprint, list_sprints, remove_sprint_item, get_backlog, get_sprint_board (12 tools)
Param bridging (~8-10 lines): create_note, update_note, search_notes, update_note_links, create_sprint, update_sprint, add_sprint_item, move_sprint_item, bulk_move_items, list_notes, create_project, create_repo, update_repo (14 tools)

7 new tools

Tool SDK Method Purpose
<code>get_note_toc</code> <code>get_note_toc(slug)</code> Browse note heading structure. ~200 tokens vs ~5000.
<code>list_blocks</code> <code>list_blocks(slug)</code> List all blocks with types and anchors.
<code>get_section</code> <code>get_section(slug, anchor_id)</code> Read one heading + content blocks. The surgical read.
<code>update_block</code> <code>update_block(slug, anchor_id, ...)</code> Edit one block without rewriting the note.
<code>create_block</code> <code>create_block(slug, ...)</code> Insert a block at a position.
<code>delete_block</code> <code>delete_block(slug, anchor_id)</code> Remove a block.
<code>delete_sprint</code> <code>delete_sprint(slug)</code> Full sprint lifecycle. DB is backed up.

New file: tools/blocks.py + tools/__init__.py update

6 block tools in new file. Register in register_all_tools().

Deliverables

  • To be filled after completion
  • phase-postgres-8f-mcp-rewrite — parent sub-phase
  • phase-postgres-8f1-sdk-publish — must be done first
  • phase-postgres-8f3-param-alignment — verifies the param bridging done here