fix(mcp): migrate to MCP SDK 2.x and pin all dependency versions (#436)

mcp 2.0.0 removed mcp.server.fastmcp, breaking test collection and the
0.12.0 release build. Migrate the server to the 2.x API:

- FastMCP -> mcp.server.mcpserver.MCPServer; transport options (host,
  port, json_response, stateless_http) are run() kwargs instead of
  server settings
- tools are async so they execute on the event loop thread; SDK 2.x
  runs sync tools on worker threads, which breaks the repository's
  thread-bound SQLite connection
- client CallToolResult.isError -> is_error in integration tests

Also pin the remaining ranged dependencies (rich, pygls, lsprotocol,
mcp) to exact versions like the rest of pyproject.toml.

Signed-off-by: Jimisola Laursen <jimisola.laursen@resurs.se>
Co-authored-by: Jimisola Laursen <jimisola.laursen@resurs.se>

Author: jimisola

pyproject.toml

@@ -47,17 +47,17 @@ dependencies = [
     "pygit2==1.20.0",
     "referencing==0.37.0",
     "requests-file==3.0.1",
-    "rich>=13.0",
+    "rich==15.0.0",
     "ruamel.yaml==0.19.1",
     "reqstool-python-decorators==0.1.0",
     "packaging==26.3",
     "requests==2.34.2",
     "beautifulsoup4==4.15.0",
     "defusedxml==0.7.1",
     "expandvars==1.1.2",
-    "pygls>=2.0,<3.0",
-    "lsprotocol>=2024.0.0",
-    "mcp>=1.0",
+    "pygls==2.1.1",
+    "lsprotocol==2025.0.0",
+    "mcp==2.0.0",
 ]
 
 [project.urls]

src/reqstool/command.py

@@ -592,7 +592,7 @@ def command_mcp(self, mcp_args: argparse.Namespace):
             from reqstool.mcp.server import start_server
         except ImportError:
             print(
-                "MCP server requires extra dependencies: pip install 'mcp>=1.0'",
+                "MCP server requires extra dependencies: pip install 'mcp>=2.0'",
                 file=sys.stderr,
             )
             sys.exit(1)

src/reqstool/mcp/server.py

@@ -29,9 +29,9 @@ def start_server(  # noqa: C901
     port: int = 8000,
 ) -> None:
     try:
-        from mcp.server.fastmcp import FastMCP
+        from mcp.server.mcpserver import MCPServer
     except ImportError as exc:
-        raise ImportError("MCP server requires extra dependencies: pip install 'mcp>=1.0'") from exc
+        raise ImportError("MCP server requires extra dependencies: pip install 'mcp>=2.0'") from exc
 
     session = ProjectSession(location)
     session.build()
@@ -44,69 +44,71 @@ def start_server(  # noqa: C901
     repo: RequirementsRepository = session.repo
     urn_source_paths = session.urn_source_paths
 
-    mcp = FastMCP("reqstool")
-    mcp.settings.host = host
-    mcp.settings.port = port
+    mcp = MCPServer(name="reqstool")
+
+    # SDK 2.x: transport options are run() kwargs instead of server settings.
+    run_kwargs: dict = {}
+    if transport in ("sse", "streamable-http"):
+        run_kwargs.update(host=host, port=port)
     if transport == "streamable-http":
-        mcp.settings.json_response = True
-        mcp.settings.stateless_http = True
+        run_kwargs.update(json_response=True, stateless_http=True)
 
     @mcp.tool()
-    def list_requirements(urn: str | None = None, lifecycle_state: str | None = None) -> list[dict]:
+    async def list_requirements(urn: str | None = None, lifecycle_state: str | None = None) -> list[dict]:
         """List requirements with id, title, and lifecycle state.
         Filter by urn and/or lifecycle_state (draft|effective|deprecated|obsolete)."""
         return get_requirements_list(repo, urn=urn, lifecycle_state=lifecycle_state)
 
     @mcp.tool()
-    def get_requirement(id: str) -> dict:
+    async def get_requirement(id: str) -> dict:
         """Get full details for a requirement by ID (e.g. REQ_010)."""
         result = get_requirement_details(id, repo, urn_source_paths)
         if result is None:
             raise ValueError(f"Requirement {id!r} not found")
         return result
 
     @mcp.tool()
-    def get_requirements_status(urn: str | None = None, include_post_build: bool = False) -> list[dict]:
+    async def get_requirements_status(urn: str | None = None, include_post_build: bool = False) -> list[dict]:
         """Batch status for all requirements: id, urn, lifecycle_state, completed, implementation_type,
         automated_tests, manual_tests. Use this to find requirements that are incomplete, partially
         tested, or not yet implemented. Optionally filter by URN. Set include_post_build=True for
         parity with `status --with-post-tests` (scopes to post-build-phase SVCs too)."""
         return _get_requirements_status_all(repo, urn=urn, include_post_build=include_post_build)
 
     @mcp.tool()
-    def list_svcs(urn: str | None = None, lifecycle_state: str | None = None) -> list[dict]:
+    async def list_svcs(urn: str | None = None, lifecycle_state: str | None = None) -> list[dict]:
         """List SVCs with id, title, lifecycle state, and verification type.
         Filter by urn and/or lifecycle_state (draft|effective|deprecated|obsolete)."""
         return get_svcs_list(repo, urn=urn, lifecycle_state=lifecycle_state)
 
     @mcp.tool()
-    def get_svc(id: str) -> dict:
+    async def get_svc(id: str) -> dict:
         """Get full details for an SVC by ID (e.g. SVC_010)."""
         result = get_svc_details(id, repo, urn_source_paths)
         if result is None:
             raise ValueError(f"SVC {id!r} not found")
         return result
 
     @mcp.tool()
-    def list_mvrs(urn: str | None = None, passed: bool | None = None) -> list[dict]:
+    async def list_mvrs(urn: str | None = None, passed: bool | None = None) -> list[dict]:
         """List MVRs with id and passed status. Filter by urn and/or passed (True|False)."""
         return get_mvrs_list(repo, urn=urn, passed=passed)
 
     @mcp.tool()
-    def get_mvr(id: str) -> dict:
+    async def get_mvr(id: str) -> dict:
         """Get full details for an MVR by ID."""
         result = get_mvr_details(id, repo, urn_source_paths)
         if result is None:
             raise ValueError(f"MVR {id!r} not found")
         return result
 
     @mcp.tool()
-    def get_status() -> dict:
+    async def get_status() -> dict:
         """Get overall traceability status — completion per requirement, test totals."""
         return StatisticsService(repo).to_status_dict()
 
     @mcp.tool()
-    def get_requirement_status(id: str, include_post_build: bool = False) -> dict:
+    async def get_requirement_status(id: str, include_post_build: bool = False) -> dict:
         """Status check for one requirement: lifecycle_state, completed, implementation_type,
         automated_tests, manual_tests. Set include_post_build=True for parity with
         `status --with-post-tests` (scopes to post-build-phase SVCs too)."""
@@ -116,7 +118,7 @@ def get_requirement_status(id: str, include_post_build: bool = False) -> dict:
         return result
 
     @mcp.tool()
-    def list_annotations(urn: str | None = None) -> list[dict]:
+    async def list_annotations(urn: str | None = None) -> list[dict]:
         """List implementation annotations (@Requirements) found in source code. Optionally filter by URN."""
         impl_annotations = repo.get_annotations_impls(urn=urn)
         result = []
@@ -133,20 +135,20 @@ def list_annotations(urn: str | None = None) -> list[dict]:
         return result
 
     @mcp.tool()
-    def list_urns() -> list[dict]:
+    async def list_urns() -> list[dict]:
         """List all URNs in the project graph with variant, title, url, location, and file paths."""
         return get_urns_list(repo, urn_source_paths)
 
     @mcp.tool()
-    def get_urn_details(urn: str) -> dict:
+    async def get_urn_details(urn: str) -> dict:
         """Get details for a URN: variant, title, location, file paths, and entity counts."""
         result = _get_urn_details(urn, repo, urn_source_paths)
         if result is None:
             raise ValueError(f"URN {urn!r} not found")
         return result
 
     @mcp.tool()
-    def enrich_document(content: str, preset: str) -> str:
+    async def enrich_document(content: str, preset: str) -> str:
         """Enrich an OpenSpec document by resolving requirement/SVC/MVR IDs.
 
         Injects titles and further fields next to each known ID according to the
@@ -162,6 +164,6 @@ def enrich_document(content: str, preset: str) -> str:
 
     try:
         logger.info("Starting reqstool MCP server (transport=%s, host=%s, port=%s)", transport, host, port)
-        mcp.run(transport=transport)
+        mcp.run(transport=transport, **run_kwargs)
     finally:
         session.close()

tests/integration/reqstool/mcp/test_mcp_integration.py

@@ -13,7 +13,7 @@
 
 
 def _parse_result(result) -> list | dict:
-    """FastMCP returns each list item as a separate TextContent block."""
+    """The MCP server returns each list item as a separate TextContent block."""
     blocks = [json.loads(b.text) for b in result.content if hasattr(b, "text")]
     return blocks if len(blocks) != 1 else blocks[0]
 
@@ -75,7 +75,7 @@ async def test_get_requirement_known(mcp_session):
 
 async def test_get_requirement_not_found(mcp_session):
     result = await mcp_session.call_tool("get_requirement", {"id": "REQ_NONEXISTENT"})
-    assert result.isError
+    assert result.is_error
 
 
 # ---------------------------------------------------------------------------
@@ -112,7 +112,7 @@ async def test_get_svc_known(mcp_session):
 
 async def test_get_svc_not_found(mcp_session):
     result = await mcp_session.call_tool("get_svc", {"id": "SVC_NONEXISTENT"})
-    assert result.isError
+    assert result.is_error
 
 
 # ---------------------------------------------------------------------------
@@ -131,7 +131,7 @@ async def test_list_mvrs(mcp_session):
 
 async def test_get_mvr_not_found(mcp_session):
     result = await mcp_session.call_tool("get_mvr", {"id": "MVR_NONEXISTENT"})
-    assert result.isError
+    assert result.is_error
 
 
 # ---------------------------------------------------------------------------
@@ -165,7 +165,7 @@ async def test_get_requirement_status(mcp_session):
 
 async def test_get_requirement_status_not_found(mcp_session):
     result = await mcp_session.call_tool("get_requirement_status", {"id": "REQ_NONEXISTENT"})
-    assert result.isError
+    assert result.is_error
 
 
 @pytest.mark.parametrize("include_post_build", [False, True])
@@ -174,7 +174,7 @@ async def test_get_requirement_status_not_found_with_include_post_build(mcp_sess
     result = await mcp_session.call_tool(
         "get_requirement_status", {"id": "REQ_NONEXISTENT", "include_post_build": include_post_build}
     )
-    assert result.isError
+    assert result.is_error
 
 
 async def test_get_requirement_status_missing_automated_test_not_met(mcp_session):

tests/unit/reqstool/mcp/test_server_startup.py

@@ -1,27 +1,28 @@
 # Copyright © LFV
 
-from types import SimpleNamespace
+
+import asyncio
 from unittest.mock import patch
 
-import mcp.server.fastmcp
+import mcp.server.mcpserver
 from reqstool_python_decorators.decorators.decorators import SVCs
 
 from reqstool.locations.local_location import LocalLocation
 from reqstool.mcp import server as mcp_server
 
 
-class _FakeFastMCP:
-    """Stand-in for mcp.server.fastmcp.FastMCP: captures registered tools and the run() call."""
+class _FakeMCPServer:
+    """Stand-in for mcp.server.mcpserver.MCPServer: captures registered tools and the run() call."""
 
-    instances: list["_FakeFastMCP"] = []
+    instances: list["_FakeMCPServer"] = []
 
-    def __init__(self, name):
+    def __init__(self, name=None, **kwargs):
         self.name = name
-        self.settings = SimpleNamespace()
         self.tools = {}
         self.run_transport = None
+        self.run_kwargs = None
         self.status_result = None
-        _FakeFastMCP.instances.append(self)
+        _FakeMCPServer.instances.append(self)
 
     def tool(self):
         def decorator(fn):
@@ -30,10 +31,12 @@ def decorator(fn):
 
         return decorator
 
-    def run(self, transport):
+    def run(self, transport, **kwargs):
         """Simulate a connected client calling a registered tool while the server is up."""
         self.run_transport = transport
-        self.status_result = self.tools["get_status"]()
+        self.run_kwargs = kwargs
+        # Tools are async so they execute on the event loop thread (SQLite affinity).
+        self.status_result = asyncio.run(self.tools["get_status"]())
 
 
 @SVCs("SVC_MCP_0001")
@@ -42,11 +45,12 @@ def test_start_server_serves_resolved_dataset(local_testdata_resources_rootdir_w
     and exposes its dataset through the registered tools."""
     location = LocalLocation(path=local_testdata_resources_rootdir_w_path("test_basic/baseline/ms-101"))
 
-    with patch.object(mcp.server.fastmcp, "FastMCP", _FakeFastMCP):
+    with patch.object(mcp.server.mcpserver, "MCPServer", _FakeMCPServer):
         mcp_server.start_server(location=location, transport="stdio")
 
-    fake_mcp = _FakeFastMCP.instances[-1]
+    fake_mcp = _FakeMCPServer.instances[-1]
     assert fake_mcp.run_transport == "stdio"
+    assert fake_mcp.run_kwargs == {}
     assert fake_mcp.status_result is not None
     assert fake_mcp.status_result["totals"]["requirements"]["total"] > 0
 
@@ -57,12 +61,9 @@ def test_start_server_streamable_http_configures_settings(local_testdata_resourc
     configured host and port."""
     location = LocalLocation(path=local_testdata_resources_rootdir_w_path("test_basic/baseline/ms-101"))
 
-    with patch.object(mcp.server.fastmcp, "FastMCP", _FakeFastMCP):
+    with patch.object(mcp.server.mcpserver, "MCPServer", _FakeMCPServer):
         mcp_server.start_server(location=location, transport="streamable-http", host="0.0.0.0", port=9000)
 
-    fake_mcp = _FakeFastMCP.instances[-1]
+    fake_mcp = _FakeMCPServer.instances[-1]
     assert fake_mcp.run_transport == "streamable-http"
-    assert fake_mcp.settings.host == "0.0.0.0"
-    assert fake_mcp.settings.port == 9000
-    assert fake_mcp.settings.json_response is True
-    assert fake_mcp.settings.stateless_http is True
+    assert fake_mcp.run_kwargs == {"host": "0.0.0.0", "port": 9000, "json_response": True, "stateless_http": True}

tests/unit/reqstool/test_command.py

@@ -411,7 +411,7 @@ def test_mcp_missing_extra_reports_and_exits(capsys):
         with pytest.raises(SystemExit) as exc:
             cmd.command_mcp(mcp_args)
     assert exc.value.code == 1
-    assert "pip install 'mcp>=1.0'" in capsys.readouterr().err
+    assert "pip install 'mcp>=2.0'" in capsys.readouterr().err
 
 
 @SVCs("SVC_MCP_0003")