feat(mcp): migrate to mcp 2.x (MCPServer), lift the <2 pin

mcp 2.0.0 removed `mcp.server.fastmcp`. This repo was pinned to <2
(6723829) to stop a rebuild from crash-looping the container the way
seed-mcp (2026-09-01) and zerto-docs (2026-08-11) did. This lifts the
pin by doing the port — the same mechanical change as
justin/seed-mcp#23 and justin/morpheus-docs#10.

- import: FastMCP -> MCPServer, plus TransportSecuritySettings
- constructor takes no transport options: MCPServer(f"{PRODUCT_NAME}-docs")
- host/port/stateless_http/transport_security are run() kwargs;
  `mcp.settings` no longer exists
- requirement becomes plain `mcp>=2,<3` (2.x has no [fastmcp] extra)

@mcp.tool() decorators and all handler signatures are unchanged.

CI now smokes `import docs_mcp.server` twice in both workflows — once
after pip install, once inside the built image — so a green build can
never ship a non-importing container again.

Verified on python:3.12-slim (matches the image):
- tools/list dumped in wire format is BYTE-FOR-BYTE IDENTICAL between
  mcp 1.30.0 and 2.2.0, all 10 tools
- streamable-http boots; initialize returns HTTP 200, both from
  localhost and with a container-DNS `Host: hvm-docs-mcp:8000` header
  (passing host= to run() keeps DNS-rebinding protection off)
- no mcp-session-id response header, i.e. stateless_http is in effect
- stdio boots; initialize + tools/list return 10 tools
- production image builds and imports under mcp 2.2.0; httpx 0.28.1 and
  httpx2 2.12.0 coexist as expected

Retrieval is untouched, so no eval numbers are included.

Closes #12

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01QBx2P1VhKQEzJWoZ96QcnH

docs_mcp/server.py

@@ -25,9 +25,10 @@ import logging
 import os
 import re
 from pathlib import Path
-from typing import Annotated
+from typing import Annotated, Any
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
+from mcp.server.transport_security import TransportSecuritySettings
 from pydantic import Field
 
 from .usage import TimedCall
@@ -65,13 +66,12 @@ RRF_K = int(os.environ.get("RRF_K", "60"))
 
 
 # ---------------------------------------------------------------------------
-# FastMCP setup.
+# MCPServer setup.
 #
-# stateless_http=True — every request creates an ephemeral session and
-# discards it on return. Critical for production: clients don't get
-# 404 storms when the container is recreated by Watchtower.
+# mcp 2.x moved every transport option (stateless_http, host, port,
+# transport_security, ...) off the constructor and onto run() — see main().
 # ---------------------------------------------------------------------------
-mcp = FastMCP(f"{PRODUCT_NAME}-docs", stateless_http=True)
+mcp = MCPServer(f"{PRODUCT_NAME}-docs")
 
 
 # ---------------------------------------------------------------------------
@@ -1141,14 +1141,22 @@ def main() -> None:
 
     if args.transport == "stdio":
         mcp.run()
-    else:
-        mcp.settings.host = args.host
-        mcp.settings.port = args.port
+        return
+
+    # mcp 2.x: transport options are run() kwargs, and `mcp.settings` is gone.
+    run_kwargs: dict[str, Any] = {"host": args.host, "port": args.port}
+    if args.transport == "streamable-http":
+        # Was a constructor arg under 1.x. Every request creates an ephemeral
+        # session and discards it on return, so clients don't get 404 storms
+        # when Watchtower recreates the container.
+        run_kwargs["stateless_http"] = True
+    if os.environ.get("MCP_DISABLE_DNS_REBINDING_PROTECTION") in {"1", "true", "yes"}:
         # DNS-rebinding protection defaults to localhost-only — disable for
         # container-network DNS hostnames. See PLAN.md "Hosting" notes.
-        if os.environ.get("MCP_DISABLE_DNS_REBINDING_PROTECTION") in {"1", "true", "yes"}:
-            mcp.settings.transport_security.enable_dns_rebinding_protection = False
-        mcp.run(transport=args.transport)
+        run_kwargs["transport_security"] = TransportSecuritySettings(
+            enable_dns_rebinding_protection=False,
+        )
+    mcp.run(transport=args.transport, **run_kwargs)
 
 
 if __name__ == "__main__":