chore(mcp): migrate fastmcp 2.x → 3.x (precondition for caching middleware, prompts, prefab UI)

[dougborg]

Problem

frontapp_mcp_server/pyproject.toml pins fastmcp>=2.13.0. Sibling repos stocktrim (PR #155) and statuspro have both moved to fastmcp 3.x and unlocked several capabilities frontapp wants:

• ResponseCachingMiddleware (built-in read-tool caching) — see issue #TBD-CACHE
• Native MCP Prompts as a first-class primitive — see issue #TBD-PROMPTS
• PrefabApp / MCP Apps spec alignment — see issue #TBD-PREFAB
• Cleaner OTel span instrumentation (replaces our bespoke observe_* decorators) — see issue #TBD-OBSERVE

This is a precondition issue. Land it first, then the dependent issues become straightforward.

Plan

1. Read the fastmcp 3.x changelog/migration guide
2. Audit frontapp_mcp_server/src/frontapp_mcp/_fastmcp_patches.py — many of these patches likely become obsolete on 3.x; document which can go away
3. Bump frontapp_mcp_server/pyproject.toml fastmcp>=3.0.0
4. Adapt server entry point (server.py), middleware registration, and any 2.x-specific call sites
5. Verify uv run poe full-check passes
6. Verify uv run poe mcp-dev starts cleanly and the inspector lists the same tool/resource set

Files likely affected

• frontapp_mcp_server/pyproject.toml
• frontapp_mcp_server/src/frontapp_mcp/_fastmcp_patches.py
• frontapp_mcp_server/src/frontapp_mcp/server.py
• frontapp_mcp_server/src/frontapp_mcp/__main__.py
• Possibly frontapp_mcp_server/tests/conftest.py for any test-side fixtures

Acceptance criteria

• fastmcp>=3.0.0 pinned, lockfile regenerated
• _fastmcp_patches.py audited; obsolete patches removed with a one-line comment per remaining patch
• uv run poe full-check passes
• uv run poe mcp-dev lists same tools and resources as before
• Manual smoke in Claude Desktop: at least one read tool and one mutation work end-to-end

Reference

• build(deps,mcp): bump uv group + fastmcp v3 minimum, address v3 breaking changes stocktrim-openapi-client#155 — exemplar migration

[dougborg]

Audit notes from #114 work (2026-05-06)

Two preconditions discovered while shipping the elicit fix and destructive-hint annotations:

_fastmcp_patches.py shim

frontapp_mcp_server/src/frontapp_mcp/_fastmcp_patches.py is a monkey-patch keeping fastmcp 2.x working with Pydantic 2.12+ (per its module docstring). Before bumping to 3.x:

1. Read the patch's intent (one specific fastmcp internal it's working around)
2. Verify fastmcp 3.x has merged the equivalent fix upstream
3. Likely delete the shim entirely — its existence is "fastmcp 2.x bug we monkey-patch around"

New tests/test_tool_annotations.py may need touch-up

Added in #117. Uses tool.fn to introspect each tool's signature for confirm:. Verify fastmcp 3.x exposes the same accessor — if renamed (e.g., tool.callable or tool.func), update the helper. The test is the regression guard for the destructiveHint contract, so it should keep working after the bump.

Migration order suggestion

1. Read fastmcp 3.x changelog — note breaking changes
2. Audit _fastmcp_patches.py against the changelog; document which patches are obviated
3. Bump version, fix breakages
4. Verify test_tool_annotations.py still passes (or update it)
5. Then unblock feat(mcp): wire ResponseCachingMiddleware for read tools (5m TTL) #109 (caching) / chore(mcp): remove unused observe_tool / observe_service decorators in favor of native fastmcp 3.x OTel spans #110 (obs decorators) / feat(mcp): scaffold MCP Prompts infrastructure (drafts, conversations, triage) #112 (prompts)