feat(phase-4): MCP server (FastMCP) exposing 21 JDM tools

- src/jdm_agent/mcp/server.py: FastMCP server reusing the same Python
functions wrapped as LangChain tools (no duplication). Each StructuredTool
exposes .func, registered with mcp.tool(fn, name=, description=) so the
MCP schema is auto-derived from type hints + docstring.
- Server instructions encourage grounded triplet citation + disambiguate-first
for polysemic terms.
- CLI: --transport stdio (default) / sse / streamable-http with --host/--port.
- pyproject: jdm-mcp script entry point.

Smoke (build_server + asyncio.run(server.list_tools)) shows 21 tools registered;
call_tool('get_synonyms', voiture) returns real JDM triplets (guimbarde w=204,
charrette w=130, ...).

Tests: +2 (test_build_server_registers_all_tools, test_mcp_call_tool_returns_triplets).
Total 30/30 passing.

README: Claude Desktop / Claude Code JSON snippets for plug-and-play install.

README.md

@@ -60,6 +60,39 @@ python -m jdm_agent.apps.qa_cli -q "synonymes de voiture"
 python -m jdm_agent.apps.qa_eval --provider ollama --model llama3.2:3b --show-tools
 ```
 
+### Serveur MCP (Claude Desktop / Claude Code / Cursor)
+
+Expose les 21 outils JDM à n'importe quel client MCP. Lancement standalone :
+
+```bash
+python -m jdm_agent.mcp.server      # ou: jdm-mcp
+```
+
+**Configuration côté Claude Desktop** (`%APPDATA%\Claude\claude_desktop_config.json`) :
+
+```json
+{
+  "mcpServers": {
+    "jdm": {
+      "command": "python",
+      "args": ["-m", "jdm_agent.mcp.server"]
+    }
+  }
+}
+```
+
+**Configuration côté Claude Code** (`~/.claude.json`, dans `mcpServers`) :
+
+```json
+"jdm": {
+  "command": "python",
+  "args": ["-m", "jdm_agent.mcp.server"]
+}
+```
+
+Une fois branché, demande au LLM des requêtes du type *« utilise JDM pour me dire
+les synonymes de voiture »* ou *« avec JDM, quels sont les sens du mot avocat ? »*.
+
 ## Tests
 
 ```bash
@@ -71,8 +104,8 @@ pytest
 - [x] Phase 0 — Bootstrap
 - [x] Phase 1 — Client JDM typé + cache disque
 - [x] Phase 2 — Couche LangChain (tools + agent)
-- [x] Phase 3 — App Q&A NL → JDM
-- [ ] Phase 4 — Serveur MCP
+- [x] Phase 3 — App Q&A NL → JDM (+ raffinements décodés, outils prédicatifs)
+- [x] Phase 4 — Serveur MCP
 - [ ] Phase 5 — Fact-checker
 - [ ] Phase 6 — Enrichissement actif
 - [ ] Phase 7 — Spike graphe local (DuckDB/NetworkX)

pyproject.toml

@@ -36,6 +36,7 @@ dev = [
 [project.scripts]
 jdm-qa = "jdm_agent.apps.qa_cli:main"
 jdm-eval = "jdm_agent.apps.qa_eval:main"
+jdm-mcp = "jdm_agent.mcp.server:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/jdm_agent"]

src/jdm_agent/mcp/server.py

@@ -0,0 +1,93 @@
+"""Serveur MCP exposant les outils JeuxDeMots à n'importe quel client MCP
+(Claude Desktop, Claude Code, Cursor, etc.).
+
+Réutilise les mêmes fonctions Python que la couche LangChain — pas de
+duplication. Chaque `StructuredTool` LangChain expose la fonction d'origine
+via `.func`, qu'on enregistre ensuite comme outil MCP.
+
+Lancement :
+    python -m jdm_agent.mcp.server         # stdio (par défaut, pour Claude Desktop/Code)
+    jdm-mcp                                # même chose via le script installé
+
+Configuration côté Claude Desktop/Code (`claude_desktop_config.json` ou
+`~/.claude.json` selon l'outil) :
+
+    {
+      "mcpServers": {
+        "jdm": {
+          "command": "python",
+          "args": ["-m", "jdm_agent.mcp.server"]
+        }
+      }
+    }
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+
+from fastmcp import FastMCP
+
+from jdm_agent.client import JDMClient
+from jdm_agent.tools.jdm_tools import ALL_TOOLS, set_default_client
+
+
+logger = logging.getLogger("jdm-mcp")
+
+
+def build_server(client: JDMClient | None = None) -> FastMCP:
+    """Construit l'instance FastMCP et enregistre tous les outils JDM."""
+    if client is not None:
+        set_default_client(client)
+    else:
+        # Force la création paresseuse pour pré-charger les types relations
+        # (un seul HTTP au démarrage).
+        set_default_client(JDMClient())
+
+    mcp = FastMCP(
+        name="jdm-agent",
+        instructions=(
+            "Outils JeuxDeMots (graphe lexico-sémantique du français). "
+            "Pour toute affirmation factuelle, appelle un outil JDM et cite "
+            "les triplets renvoyés (source | relation | target, poids w). "
+            "Pour les termes polysémiques, commence par `disambiguate`."
+        ),
+    )
+
+    # Chaque LangChain @tool a un attribut .func = la fonction Python d'origine
+    # (avec ses annotations + docstring). FastMCP en infère le schéma.
+    for t in ALL_TOOLS:
+        fn = getattr(t, "func", None) or t  # fallback si l'attribut change
+        mcp.tool(fn, name=t.name, description=t.description)
+
+    return mcp
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Serveur MCP JeuxDeMots.")
+    parser.add_argument(
+        "--transport",
+        choices=("stdio", "sse", "streamable-http"),
+        default="stdio",
+        help="Transport MCP (stdio = défaut pour clients desktop).",
+    )
+    parser.add_argument(
+        "--host", default="127.0.0.1",
+        help="Hôte pour les transports HTTP/SSE.",
+    )
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--log-level", default="WARNING")
+    args = parser.parse_args()
+
+    logging.basicConfig(level=args.log_level.upper(), format="[%(name)s] %(message)s")
+    server = build_server()
+
+    if args.transport == "stdio":
+        server.run()  # transport par défaut stdio
+    else:
+        server.run(transport=args.transport, host=args.host, port=args.port)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_mcp_server.py

@@ -0,0 +1,68 @@
+"""Smoke tests du serveur MCP (sans transport réseau).
+
+On vérifie que :
+- build_server() ne lève pas
+- tous les outils LangChain sont bien enregistrés côté MCP
+- un call_tool fonctionne et renvoie le contenu structuré attendu
+"""
+from __future__ import annotations
+
+import asyncio
+
+import httpx
+import pytest
+import respx
+
+from jdm_agent.client import JDMClient
+from jdm_agent.client.cache import DiskJSONCache
+from jdm_agent.tools.jdm_tools import ALL_TOOLS, set_default_client
+
+
+BASE = "https://jdm-api.demo.lirmm.fr"
+
+
+@pytest.fixture
+def mcp_with_mocks(tmp_path):
+    """Construit le serveur MCP avec un JDMClient mocké."""
+    pytest.importorskip("fastmcp")
+    from jdm_agent.mcp.server import build_server
+
+    client = JDMClient(base_url=BASE, cache=DiskJSONCache(cache_dir=tmp_path / "cache"))
+    set_default_client(client)
+    server = build_server(client=client)
+    return server
+
+
+def test_build_server_registers_all_tools(mcp_with_mocks):
+    server = mcp_with_mocks
+    tools = asyncio.run(server.list_tools())
+    names = {t.name for t in tools}
+    expected = {t.name for t in ALL_TOOLS}
+    assert expected.issubset(names), f"manquants: {expected - names}"
+
+
+def test_mcp_call_tool_returns_triplets(mcp_with_mocks):
+    """call_tool('get_synonyms') exécute la vraie fonction et renvoie ses résultats."""
+    server = mcp_with_mocks
+
+    with respx.mock(base_url=BASE) as mock:
+        mock.get("/v0/relations_types").mock(return_value=httpx.Response(200, json=[
+            {"id": 5, "name": "r_syn", "help": "synonymes"},
+        ]))
+        mock.get("/v0/nodes_types").mock(return_value=httpx.Response(200, json=[
+            {"id": 1, "name": "n_generic", "help": ""},
+        ]))
+        mock.get("/v0/relations/from/chat").mock(return_value=httpx.Response(200, json={
+            "nodes": [
+                {"id": 150, "name": "chat", "type": 1, "w": 7967},
+                {"id": 999, "name": "matou", "type": 1, "w": 100},
+            ],
+            "relations": [{"id": 1, "node1": 150, "node2": 999, "type": 5, "w": 80.0}],
+        }))
+
+        result = asyncio.run(server.call_tool(
+            "get_synonyms", {"term": "chat", "min_weight": 0, "limit": 5}
+        ))
+
+    payload = result.structured_content["result"]
+    assert any(t["target"] == "matou" and t["relation"] == "r_syn" for t in payload)