[iddv]

Summary

mcp-forge 3.0 targets the mcp Python SDK 2.x and the 2026-07-28 protocol revision. It also adds 14 protocol features, 5 distribution features (Claude Code plugin, Agent Skill, MCPB, Docker, MCP Registry), and ships mcp-forge itself as a Claude Code plugin with a skill.

Why this is urgent: mcp 2.0 (2026-07-28) removed mcp.server.fastmcp. Projects generated by mcp-forge 2 declare mcp[cli]>=1.6.0, so a fresh install resolves 2.x and server.py fails with ModuleNotFoundError.

Plan: docs/superpowers/plans/2026-10-11-mcp-forge-v3.md

Changes

• SDK 2.x templates. MCPServer from mcp.server.mcpserver, mcp[cli]>=2.3,<3, and tests using an in-process Client.
• Fixed snippets.
  • context called async logging without await (and protocol logging is now deprecated).
  • elicitation broke on 2026 clients.
  • auth was only comments; it is now a real TokenVerifier + AuthSettings.
• New protocol features:
  • resource-templates, completions, annotations, structured-output, media
  • errors, notifications, sampling, roots
  • lifespan, middleware, http, apps (MCP Apps)
• Elicitation, sampling and roots work on both protocol eras. They use Resolve parameters, so they work over the 2026-07-28 retry flow and with handshake-era clients.
• HTTP configuration. http reads MCP_HOST/MCP_PORT, so auth advertises the correct resource URL (MCP_PUBLIC_URL overrides it). MCP_REQUEST_STATE_KEY makes multi-replica deployments work.
• New distribution features.
  • skill: SKILL.md listing the server's tools.
  • plugin: .claude-plugin/plugin.json + marketplace.json.
  • mcpb: manifest.json.
  • docker: Dockerfile.
  • registry: server.json.
• CLI. add takes several features at once, is idempotent, and resolves requirements (auth adds http). A new mcp-forge features command lists them.
• mcp-forge as a plugin. The repo is now a Claude Code plugin + marketplace with an mcp-forge skill.

Testing

• 94 tests pass. The integration tests scaffold a project with every feature and exercise each one through a real MCP client against SDK 2.3.0, on both the 2026-07-28 and handshake protocols.
• Manual testing on a Linux box:
  • stdio: a subprocess server called by a real client.
  • Live HTTP: stateless mode, auth on a custom port, and elicitation/sampling/roots round-trips.
  • MCP Inspector CLI: tools, calls, templates and prompts all work.
  • MCPB: mcpb validate and mcpb pack pass, and the unpacked bundle's uv run command works.
  • Claude Code: claude plugin validate --strict passes. A generated plugin loaded with --plugin-dir connected, and Claude called its tools.
  • mcp-forge skill: a headless Claude built a working server with it.
• Not tested: docker build (no daemon access on the test box) and the MCP Inspector web UI.

Before releasing: PyPI name

The PyPI name mcp-forge belongs to an unrelated project: click/jinja2-based, versions 0.2.0–1.0.0, first upload 2025-03-21. This repo has never been published. Tagging v3.0.0 will run the publish workflow and fail on that name. Also, the README's pip install mcp-forge currently installs the other package. Pick a free name before the first release (e.g. mcpforge-cli, mcp-forge-kit) and update pyproject.toml, the README and the skill.

🤖 Generated with Claude Code