docs: FastMCP + Prefab/MCP Apps migration feasibility study

[willwebster5]

Summary

• Research-only design doc evaluating a migration from the official mcp Python SDK's built-in FastMCP helper to PrefectHQ fastmcp (v3.2+) with Prefab / MCP Apps for interactive in-chat UI
• Resolves the recurring "which FastMCP are we on?" confusion: today we use mcp.server.fastmcp.FastMCP (official SDK), not the PrefectHQ package that ships Prefab
• Recommends a staged migration (v4.4 framework port, v4.5 NGSIEM Prefab pilot) rather than a single big-bang change
• Motivates the migration primarily on context-window arbitrage for NGSIEM — FastMCPApp's @app.ui() / @app.tool() split lets bulk CQL results render in a sandboxed iframe without entering the model's context, which directly addresses the pressure behind the ngsiem-alert-analysis-timeout-fix and ngsiem-read-expansion work

What's in the doc

• Background on the two "FastMCP" packages
• Host-support matrix (Claude Desktop + Claude.ai shipped since 2026-01-26; Claude Code expected no-render; VS Code, Goose, ChatGPT shipped)
• Migration surface mapped against our current server.py, modules/base.py, and one module — imports, decorator behavior, add_tool, resources, transports, ASGI middleware, registry, tests
• Rough effort estimate (~1 day framework port, ~3–4 days NGSIEM pilot)
• Context-window arbitrage analysis with quantitative sketch (~95–99% reduction in per-query context pressure)
• Module-by-module UI vision: NGSIEM query app, Threat Graph pivot explorer, Spotlight vuln table; second-tier backlog for alerts, cloud_security, case_management, correlation
• Risks, decision framework, and remaining open questions focused on transport/middleware parity

Path

docs/superpowers/specs/2026-04-21-fastmcp-prefab-migration-feasibility.md

Test plan

• Read the doc end-to-end
• Sanity-check §4 host matrix against current Anthropic product docs
• Sanity-check §5 migration surface against recent server.py / modules/base.py
• Confirm recommendation (§1, §10) reflects how you want to gate the work
• Decide whether to schedule the transport-parity spike from §10

No code changes — pure design doc.

🤖 Generated with Claude Code