feat: migrate to mcp 2.0 (FastMCP → MCPServer)

.claude/CLAUDE.md

@@ -61,7 +61,7 @@ All server code lives under `server/`. The system has two main phases: **ingesti
 
 ### MCP interface (`server/main.py`)
 
-FastMCP serves tools and prompts over stdio, SSE, or HTTP. HTTP indexing endpoints (`POST /reindex`,
+`MCPServer` (`mcp` 2.x) serves tools and prompts over stdio, SSE, or HTTP. HTTP indexing endpoints (`POST /reindex`,
 `POST /reindex-history`) return streaming NDJSON for CI/CD consumption.
 
 ### Configuration

.claude/rules/fastmcp-http.md → .claude/rules/mcp-http.md

@@ -4,30 +4,37 @@ paths:
   - "server/tools/**/*.py"
 ---
 
-# FastMCP + Starlette HTTP conventions
+# MCPServer + Starlette HTTP conventions
 
-This project uses **FastMCP**. HTTP routes are registered on the
-`FastMCP` instance via `@mcp.custom_route`. Never add routes to a separate
-FastAPI or Starlette app.
+This project uses **MCPServer** (the `mcp` 2.x successor to FastMCP). HTTP routes
+are registered on the `MCPServer` instance via `@mcp.custom_route`. Never add
+routes to a separate FastAPI or Starlette app.
 
 ## Route registration pattern
 
-Wrap registration in a `register_*` function that accepts `mcp: FastMCP`. Call it
+Wrap registration in a `register_*` function that accepts `mcp: MCPServer`. Call it
 from `server/main.py`:
 
 ```python
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 from starlette.requests import Request
 from starlette.responses import StreamingResponse
 
 
-def register_http_routes(mcp: FastMCP) -> None:
+def register_http_routes(mcp: MCPServer) -> None:
 
     @mcp.custom_route("/reindex", methods=["POST"])
     async def reindex(request: Request) -> StreamingResponse: ...
 ```
 
-Same pattern for MCP tools — `register_*_tools(mcp: FastMCP)` in `server/tools/`.
+Same pattern for MCP tools — `register_*_tools(mcp: MCPServer)` in `server/tools/`.
+
+## Bind address
+
+`host`/`port` are not constructor kwargs — they belong to `run()` and to the app
+factories. Always pass `host=settings.mcp_host` to `streamable_http_app()` /
+`sse_app()`: those factories auto-enable DNS rebinding protection when `host` is
+a loopback address, which rejects container traffic with `421 Invalid Host header`.
 
 ## Request body parsing
 

pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "semcode"
-version = "1.0.0"
+version = "1.1.0"
 description = "MCP server for semantic code search across microservices codebases"
 requires-python = ">=3.12"
 dependencies = [
-    "mcp>=1.28.1",
+    "mcp>=2.0.0",
     "qdrant-client>=1.18.0",
     "tree-sitter>=0.26.0",
     "tree-sitter-go>=0.23.0",

server/main.py

@@ -3,9 +3,10 @@
 import logging
 from collections.abc import AsyncIterator
 from contextlib import asynccontextmanager
+from importlib.metadata import PackageNotFoundError, version
 
 import uvicorn
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 from starlette.applications import Starlette
 
 from server.config import settings
@@ -29,7 +30,7 @@
 
 
 @asynccontextmanager
-async def lifespan(_: FastMCP) -> AsyncIterator[None]:
+async def lifespan(_: MCPServer) -> AsyncIterator[None]:
     logger.info("Starting semcode MCP server...")
     embedder = get_embedding_provider()
     logger.info(
@@ -70,8 +71,17 @@ async def lifespan(_: FastMCP) -> AsyncIterator[None]:
 # so the per-MCP-session lifespan would re-init the store on every client connect.
 _HTTP_TRANSPORTS = {"streamable-http", "sse"}
 
-mcp = FastMCP(
+try:
+    # Reported to clients as serverInfo.version; sourced from pyproject so there is
+    # no second place to bump. Absent only if the package isn't installed (e.g. a
+    # bare source checkout), which must not be fatal at import time.
+    _VERSION = version("semcode")
+except PackageNotFoundError:  # pragma: no cover
+    _VERSION = "0.0.0"
+
+mcp = MCPServer(
     "semcode",
+    version=_VERSION,
     instructions=(
         "Semantic code search across microservices codebases. Hybrid retrieval "
         "(dense embeddings + BM25) over symbols parsed with Tree-sitter. Supports "
@@ -80,8 +90,6 @@ async def lifespan(_: FastMCP) -> AsyncIterator[None]:
         "Compose, Markdown, JSON, HTML, CSS, and XML."
     ),
     lifespan=lifespan if settings.mcp_transport not in _HTTP_TRANSPORTS else None,
-    host=settings.mcp_host,
-    port=settings.mcp_port,
 )
 
 
@@ -114,10 +122,13 @@ def main() -> None:
     register_http_routes(mcp)
 
     if settings.mcp_transport in _HTTP_TRANSPORTS:
+        # `host` must match the bind address: the app factories auto-enable DNS
+        # rebinding protection (allowed_hosts = localhost only) when host is a
+        # loopback address, which would reject container traffic on 0.0.0.0.
         app = (
-            mcp.streamable_http_app()
+            mcp.streamable_http_app(host=settings.mcp_host)
             if settings.mcp_transport == "streamable-http"
-            else mcp.sse_app()
+            else mcp.sse_app(host=settings.mcp_host)
         )
         _wrap_http_lifespan(app)
         uvicorn.run(

server/prompts/service.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 
 
-def register_service_prompts(mcp: FastMCP) -> None:
+def register_service_prompts(mcp: MCPServer) -> None:
     @mcp.prompt(
         name="service_overview",
         description="Produce an architectural overview of a service: HTTP entry points, main domain types,"

server/prompts/system.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 
 
-def register_system_prompts(mcp: FastMCP) -> None:
+def register_system_prompts(mcp: MCPServer) -> None:
     @mcp.prompt(
         name="system_design_overview",
         description="Produce a complete architectural overview of the whole system: service inventory,"

server/routes/reindex.py

@@ -5,7 +5,7 @@
 import json
 import logging
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 from starlette.requests import Request
 from starlette.responses import JSONResponse, StreamingResponse
 
@@ -17,7 +17,7 @@
 logger = logging.getLogger(__name__)
 
 
-def register_http_routes(mcp: FastMCP) -> None:
+def register_http_routes(mcp: MCPServer) -> None:
 
     @mcp.custom_route("/reindex", methods=["POST"])
     async def reindex(request: Request) -> StreamingResponse:

server/tools/history.py

@@ -1,13 +1,13 @@
 from __future__ import annotations
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 
 from server.embeddings import get_embedding_provider
 from server.indexer.git_history import GitHistoryPipeline
 from server.state import get_commit_store
 
 
-def register_history_tools(mcp: FastMCP) -> None:
+def register_history_tools(mcp: MCPServer) -> None:
 
     @mcp.tool()
     async def search_commits(

server/tools/index.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 
 from server.indexer.pipeline import IndexPipeline
 from server.state import get_store
 
 
-def register_index_tools(mcp: FastMCP) -> None:
+def register_index_tools(mcp: MCPServer) -> None:
 
     @mcp.tool()
     async def reindex(

server/tools/search.py

@@ -3,7 +3,7 @@
 import logging
 
 import httpx
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 
 from server.config import settings
 from server.embeddings import get_embedding_provider
@@ -19,7 +19,7 @@
 USAGE_OVERFETCH = 5
 
 
-def register_search_tools(mcp: FastMCP) -> None:
+def register_search_tools(mcp: MCPServer) -> None:
 
     @mcp.tool()
     async def search_code(

server/tools/stats.py

@@ -2,15 +2,15 @@
 
 import logging
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 
 from server.config import settings
 from server.state import get_service_registry, get_store
 
 logger = logging.getLogger(__name__)
 
 
-def register_stats_tools(mcp: FastMCP) -> None:
+def register_stats_tools(mcp: MCPServer) -> None:
 
     @mcp.tool()
     async def list_indexed_services() -> str:

tests/test_reindex_route.py

@@ -5,7 +5,7 @@
 
 import httpx
 import pytest
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 
 from server.indexer.pipeline import ProgressEvent
 from server.routes.reindex import register_http_routes
@@ -19,7 +19,7 @@
 
 @pytest.fixture
 def app():
-    mcp = FastMCP("test")
+    mcp = MCPServer("test")
     register_http_routes(mcp)
     return mcp.streamable_http_app()
 

tests/tools/conftest.py

@@ -4,13 +4,13 @@
 from dataclasses import dataclass, field
 from typing import Any
 
-from mcp.server.fastmcp import FastMCP
+from mcp.server.mcpserver import MCPServer
 
 
-def get_tool(register: Callable[[FastMCP], None], name: str) -> Callable:
-    """Register a tool module against a throwaway FastMCP instance and return
+def get_tool(register: Callable[[MCPServer], None], name: str) -> Callable:
+    """Register a tool module against a throwaway MCPServer instance and return
     the underlying async function, bypassing MCP's request/response plumbing."""
-    mcp = FastMCP("test")
+    mcp = MCPServer("test")
     register(mcp)
     return mcp._tool_manager._tools[name].fn