propaths-mcp 0.1.0__tar.gz

propaths_mcp-0.1.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

propaths_mcp-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+.venv/
+venv/
+*.pyc
+.pytest_cache/
+.uv/

propaths_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ProPaths
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

propaths_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: propaths-mcp
+Version: 0.1.0
+Summary: MCP server for the ProPaths verified protein-interactome API.
+Project-URL: Homepage, https://propaths.net
+Project-URL: Documentation, https://propaths.net/documentation
+Project-URL: Repository, https://github.com/Tahsin-Kazi/propaths-mcp
+Author: ProPaths
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bioinformatics,interactome,mcp,propaths,protein
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.0
+Description-Content-Type: text/markdown
+
+# propaths-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the **ProPaths**
+verified protein-interactome as read-only tools for AI agents. It is a thin
+client over the public ProPaths API (`https://propaths.net`), so every tool
+returns exactly the API's JSON. No account, no API key.
+
+ProPaths reads a protein's primary literature and returns a verified graph of
+**typed, directed, mechanistic** interactions plus a pathway ontology. One
+protein (ATXN3) is fully mapped today.
+
+## Quickstart (Claude Desktop / any MCP client)
+
+Add this to your MCP client config. `uvx` fetches and runs the server; nothing
+to clone or install.
+
+```json
+{
+  "mcpServers": {
+    "propaths": {
+      "command": "uvx",
+      "args": ["propaths-mcp"]
+    }
+  }
+}
+```
+
+Then ask, e.g., *"search ProPaths for SCA3 and summarize its strongest
+mechanistic interaction."* The agent will call `search_proteins` then
+`get_protein`, and drill in with `get_interaction`.
+
+Prefer the raw API? It is public and keyless:
+
+```bash
+curl https://propaths.net/api/protein/ATXN3
+curl 'https://propaths.net/api/search?q=SCA3'
+```
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_proteins(q, limit=20)` | Find a protein by symbol, alias, or name (start here) |
+| `get_protein(symbol)` | Compact interactome overview (the main entry point) |
+| `get_interaction(interaction_id, query=None)` | One interaction's full mechanism + evidence |
+| `get_interaction_between(a, b)` | The interaction(s) between two proteins, in one call |
+| `list_interactions(symbol, kind=, type=, pathway=, min_evidence=, sort=, limit=)` | Filtered/sorted headline rows |
+| `list_interaction_types()` | The controlled vocabulary (edge kinds, types, directions) + counts |
+| `get_pathway(pathway_id)` | A pathway node with its lineage and member interactions |
+| `get_pathway_tree()` | The full pathway scaffold (resolves pathway ids to names) |
+| `get_highlights()` | The best-evidenced interactions |
+| `export_network(symbol, format="tsv")` | Export a protein's network as TSV / SIF / GraphML (Cytoscape, networkx) |
+| `describe_schema()` | The graph vocabulary + how to use the tools (offline) |
+
+Also exposed as MCP **resources** (`propaths://schema`, `propaths://interaction-types`,
+`propaths://pathways/tree`, and the `propaths://protein/{symbol}` template) and
+**prompts** (`profile-protein`, `strongest-evidence`, `explain-pathway`).
+
+All tools are read-only and idempotent.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `PROPATHS_API_URL` | `https://propaths.net` | API base URL. Point at `http://localhost:8000` to run against a local API. |
+
+## Run without uvx
+
+```bash
+pip install propaths-mcp
+propaths-mcp            # runs the stdio server
+# or: python -m propaths_mcp
+```
+
+Before it is published, you can run straight from the repo:
+
+```bash
+uvx --from git+https://github.com/Tahsin-Kazi/propaths-mcp propaths-mcp
+```
+
+## Notes
+
+- Read-only and public; reads are rate-limited per client. Write/enrichment
+  access and a hosted MCP are gated. Get in touch.
+- Errors are graceful: a missing protein returns `{"error": "...", "status": 404}`;
+  an unreachable API raises with a hint.
+
+Docs: <https://propaths.net/quick-start> · License: MIT

propaths_mcp-0.1.0/README.md

@@ -0,0 +1,88 @@
+# propaths-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that exposes the **ProPaths**
+verified protein-interactome as read-only tools for AI agents. It is a thin
+client over the public ProPaths API (`https://propaths.net`), so every tool
+returns exactly the API's JSON. No account, no API key.
+
+ProPaths reads a protein's primary literature and returns a verified graph of
+**typed, directed, mechanistic** interactions plus a pathway ontology. One
+protein (ATXN3) is fully mapped today.
+
+## Quickstart (Claude Desktop / any MCP client)
+
+Add this to your MCP client config. `uvx` fetches and runs the server; nothing
+to clone or install.
+
+```json
+{
+  "mcpServers": {
+    "propaths": {
+      "command": "uvx",
+      "args": ["propaths-mcp"]
+    }
+  }
+}
+```
+
+Then ask, e.g., *"search ProPaths for SCA3 and summarize its strongest
+mechanistic interaction."* The agent will call `search_proteins` then
+`get_protein`, and drill in with `get_interaction`.
+
+Prefer the raw API? It is public and keyless:
+
+```bash
+curl https://propaths.net/api/protein/ATXN3
+curl 'https://propaths.net/api/search?q=SCA3'
+```
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `search_proteins(q, limit=20)` | Find a protein by symbol, alias, or name (start here) |
+| `get_protein(symbol)` | Compact interactome overview (the main entry point) |
+| `get_interaction(interaction_id, query=None)` | One interaction's full mechanism + evidence |
+| `get_interaction_between(a, b)` | The interaction(s) between two proteins, in one call |
+| `list_interactions(symbol, kind=, type=, pathway=, min_evidence=, sort=, limit=)` | Filtered/sorted headline rows |
+| `list_interaction_types()` | The controlled vocabulary (edge kinds, types, directions) + counts |
+| `get_pathway(pathway_id)` | A pathway node with its lineage and member interactions |
+| `get_pathway_tree()` | The full pathway scaffold (resolves pathway ids to names) |
+| `get_highlights()` | The best-evidenced interactions |
+| `export_network(symbol, format="tsv")` | Export a protein's network as TSV / SIF / GraphML (Cytoscape, networkx) |
+| `describe_schema()` | The graph vocabulary + how to use the tools (offline) |
+
+Also exposed as MCP **resources** (`propaths://schema`, `propaths://interaction-types`,
+`propaths://pathways/tree`, and the `propaths://protein/{symbol}` template) and
+**prompts** (`profile-protein`, `strongest-evidence`, `explain-pathway`).
+
+All tools are read-only and idempotent.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---------|---------|---------|
+| `PROPATHS_API_URL` | `https://propaths.net` | API base URL. Point at `http://localhost:8000` to run against a local API. |
+
+## Run without uvx
+
+```bash
+pip install propaths-mcp
+propaths-mcp            # runs the stdio server
+# or: python -m propaths_mcp
+```
+
+Before it is published, you can run straight from the repo:
+
+```bash
+uvx --from git+https://github.com/Tahsin-Kazi/propaths-mcp propaths-mcp
+```
+
+## Notes
+
+- Read-only and public; reads are rate-limited per client. Write/enrichment
+  access and a hosted MCP are gated. Get in touch.
+- Errors are graceful: a missing protein returns `{"error": "...", "status": 404}`;
+  an unreachable API raises with a hint.
+
+Docs: <https://propaths.net/quick-start> · License: MIT

propaths_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "propaths-mcp"
+version = "0.1.0"
+description = "MCP server for the ProPaths verified protein-interactome API."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "ProPaths" }]
+keywords = ["mcp", "bioinformatics", "protein", "interactome", "propaths"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "mcp>=2.0,<3",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://propaths.net"
+Documentation = "https://propaths.net/documentation"
+Repository = "https://github.com/Tahsin-Kazi/propaths-mcp"
+
+[project.scripts]
+propaths-mcp = "propaths_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/propaths_mcp"]

propaths_mcp-0.1.0/src/propaths_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""ProPaths MCP server: read-only agent tools over the ProPaths interactome API."""
+
+__version__ = "0.1.0"

propaths_mcp-0.1.0/src/propaths_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m propaths_mcp``."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

propaths_mcp-0.1.0/src/propaths_mcp/server.py

@@ -0,0 +1,455 @@
+"""ProPaths local/stdio MCP server.
+
+Exposes the ProPaths verified interactome graph as MCP tools that mirror the
+read-only HTTP API contract (the ``reads`` tag of the FastAPI OpenAPI spec)
+1:1. Each tool is a thin pass-through to the API: the value it returns IS the
+API's camelCase JSON body, so tool output cannot drift from the frozen API
+contract.
+
+Transport: stdio (the default). By default it targets the hosted API at
+``https://propaths.net``; override with the ``PROPATHS_API_URL`` env var to
+point at a local server. The API's read endpoints are Postgres-only, so nothing
+here ever triggers the LLM pipeline.
+
+Run against a local API:
+    PROPATHS_API_URL=http://localhost:8000 python -m propaths_mcp
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Optional
+from urllib.parse import quote
+
+import httpx
+from mcp.server import MCPServer
+from mcp.types import Completion, ToolAnnotations
+
+
+def _ann(title: str) -> ToolAnnotations:
+    """Read-only, idempotent, closed-world annotations for every tool.
+
+    Signals to MCP clients that these tools are safe to call freely: they never
+    mutate state, repeat calls return the same result, and they operate over a
+    closed dataset (no open-ended external effects).
+    """
+    return ToolAnnotations(
+        title=title,
+        read_only_hint=True,
+        idempotent_hint=True,
+        open_world_hint=False,
+    )
+
+DEFAULT_API_URL = "https://propaths.net"
+_HTTP_TIMEOUT = 30.0
+
+
+def _api_base() -> str:
+    """Base URL of the ProPaths read API (no trailing slash)."""
+    return os.getenv("PROPATHS_API_URL", DEFAULT_API_URL).rstrip("/")
+
+
+def _make_client() -> httpx.AsyncClient:
+    """Construct the HTTP client. Isolated so tests can inject a MockTransport."""
+    return httpx.AsyncClient(timeout=_HTTP_TIMEOUT)
+
+
+async def _get(path: str, params: Optional[dict] = None) -> Any:
+    """GET ``{API}{path}`` and return the parsed JSON body verbatim.
+
+    Pass-through by design: the returned object is exactly the API response, so
+    the MCP surface inherits the API's shapes with no second serialization to
+    drift. Errors are always RETURNED as a structured ``{"error", "status"}``
+    dict rather than raised, so the message reaches the calling agent: a 4xx/5xx
+    carries the API's detail (e.g. "Protein not found"); an unreachable API
+    returns ``status: null`` with a remediation hint (MCP would otherwise swallow
+    a raised exception into a generic "Error executing tool" message).
+    """
+    url = f"{_api_base()}{path}"
+    try:
+        async with _make_client() as client:
+            resp = await client.get(url, params=params)
+    except httpx.RequestError as exc:
+        return {
+            "error": (
+                f"Could not reach the ProPaths API at {_api_base()}. Set "
+                "PROPATHS_API_URL to a running API (e.g. http://localhost:8000), "
+                f"or start one with `uvicorn api.app:app`. ({exc!r})"
+            ),
+            "status": None,
+        }
+
+    if resp.status_code >= 400:
+        detail: Optional[str] = None
+        try:
+            detail = resp.json().get("detail")
+        except Exception:  # non-JSON error body
+            detail = resp.text[:200] or None
+        return {"error": detail or f"HTTP {resp.status_code}", "status": resp.status_code}
+
+    return resp.json()
+
+
+async def _get_text(path: str, params: Optional[dict] = None) -> str:
+    """GET ``{API}{path}`` and return the raw text body (for exports).
+
+    On an unreachable API or a 4xx/5xx it returns a short ``error: ...`` string
+    rather than a body (never raises), so the message reaches the agent.
+    """
+    url = f"{_api_base()}{path}"
+    try:
+        async with _make_client() as client:
+            resp = await client.get(url, params=params)
+    except httpx.RequestError as exc:
+        return (
+            f"error: could not reach the ProPaths API at {_api_base()}. Set "
+            f"PROPATHS_API_URL to a running API, or start one with "
+            f"`uvicorn api.app:app`. ({exc!r})"
+        )
+    if resp.status_code >= 400:
+        detail = None
+        try:
+            detail = resp.json().get("detail")
+        except Exception:
+            detail = None
+        return f"error: {detail or f'HTTP {resp.status_code}'}"
+    return resp.text
+
+
+def _summarize_protein_page(page: dict) -> dict:
+    """Project the full protein-page payload into an agent-sized overview.
+
+    The API's protein page is frontend-shaped: it bundles every interaction with
+    full mechanism/evidence prose (~700K tokens for a hub like ATXN3), which is
+    unusable as a single LLM tool result. This keeps one headline row per
+    interaction, resolves each edge's pathway ids to names from the page's own
+    pathway subtree, and drops the heavy prose. Depth is fetched on demand via
+    get_interaction.
+    """
+    id_to_name = {pw["id"]: pw["name"] for pw in page.get("pathways", [])}
+
+    def edge(i: dict) -> dict:
+        names: list[str] = []
+        for fn in i.get("functions", []):
+            name = id_to_name.get(fn.get("canonicalPathwayId"))
+            if name and name not in names:
+                names.append(name)
+        return {
+            "id": i["id"],
+            "source": i["source"],
+            "target": i["target"],
+            "kind": i.get("kind"),
+            "direction": i.get("direction"),
+            "type": i.get("type"),
+            "functionCount": i.get("functionCount", 0),
+            "evidenceCount": i.get("evidenceCount", 0),
+            "supportSummary": i.get("supportSummary", ""),
+            "pathways": names,
+        }
+
+    interactions = page.get("interactions", [])
+    pathways = page.get("pathways", [])
+    return {
+        "main": page.get("main"),
+        "protein": page.get("protein"),
+        "counts": {
+            "interactions": len(interactions),
+            "pathways": len(pathways),
+            "proteins": len(page.get("proteins", [])),
+        },
+        "pathwayRoots": sorted(
+            pw["name"] for pw in pathways if pw.get("hierarchyLevel") == 0
+        ),
+        "interactions": [edge(i) for i in interactions],
+        "note": (
+            "Overview only. For an edge's full mechanism/kinetics/evidence call "
+            "get_interaction(id)."
+        ),
+    }
+
+
+server = MCPServer(
+    name="propaths",
+    title="ProPaths Interactome",
+    version="0.1.0",
+    instructions=(
+        "Read-only access to the ProPaths verified interactome graph: typed, "
+        "directed, mechanistic protein interactions, per-edge kinetics, and a "
+        "pathway ontology, all built from primary literature. New here? Call "
+        "describe_schema (or read the propaths://schema resource) and "
+        "list_interaction_types to orient. Typical flow: search_proteins to resolve "
+        "a symbol, get_protein for a compact overview, then drill into an edge with "
+        "get_interaction(id). list_interactions filters/sorts a protein's edges; "
+        "get_interaction_between fetches a specific pair; get_pathway is pathway-first; "
+        "get_highlights returns the strongest specimens; export_network dumps to "
+        "Cytoscape/networkx. All tools are read-only and idempotent."
+    ),
+)
+
+
+@server.tool(annotations=_ann("Search proteins"))
+async def search_proteins(q: str, limit: int = 20) -> dict:
+    """Search proteins by symbol prefix (case-insensitive).
+
+    Returns matching symbols with HGNC id and description. Use this first to
+    resolve a protein of interest, then call get_protein.
+    """
+    return await _get("/api/search", {"q": q, "limit": limit})
+
+
+@server.tool(annotations=_ann("Get protein overview"))
+async def get_protein(symbol: str) -> dict:
+    """Overview map for one protein, the main entry point.
+
+    Returns a COMPACT overview sized for an agent: protein metadata, counts,
+    the top-level pathway roots, and one headline row per interaction (id,
+    oriented source/target, kind, direction, type, a one-line supportSummary,
+    resolved pathway names, and function/evidence counts). It deliberately omits
+    the heavy per-edge mechanism and evidence prose (the full protein page is
+    ~700K tokens for a hub protein).
+
+    Drill into any row by id for full depth: get_interaction(id) for an edge's
+    mechanism + kinetics + evidence.
+    """
+    page = await _get(f"/api/protein/{quote(symbol, safe='')}")
+    if isinstance(page, dict) and "error" in page:
+        return page
+    return _summarize_protein_page(page)
+
+
+@server.tool(annotations=_ann("Get interaction detail"))
+async def get_interaction(interaction_id: str, query: Optional[str] = None) -> dict:
+    """One interaction's full enriched record by id.
+
+    Includes mechanism prose, direction, per-function effects, kinetics, and
+    evidence. Pass `query` (a participating symbol) to orient source/target so
+    the query protein reads as the source.
+    """
+    params = {"query": query} if query else None
+    return await _get(f"/api/interaction/{quote(interaction_id, safe='')}", params)
+
+
+@server.tool(annotations=_ann("Get pathway tree"))
+async def get_pathway_tree() -> dict:
+    """The full pathway scaffold as a flat node list.
+
+    Assemble the tree client-side via each node's parentId. Use this to resolve
+    the canonicalPathwayId values returned on interactions into human-readable
+    pathway names.
+    """
+    return await _get("/api/pathways/tree")
+
+
+@server.tool(annotations=_ann("Interaction between two proteins"))
+async def get_interaction_between(a: str, b: str) -> dict:
+    """The interaction(s) between two named proteins, oriented from `a`.
+
+    Use this for "what does A do to B" in one call, instead of pulling
+    get_protein and scanning for the partner.
+    """
+    return await _get(f"/api/edge/{quote(a, safe='')}/{quote(b, safe='')}")
+
+
+@server.tool(annotations=_ann("List / filter interactions"))
+async def list_interactions(
+    symbol: str,
+    kind: Optional[str] = None,
+    type: Optional[str] = None,
+    pathway: Optional[str] = None,
+    min_evidence: int = 0,
+    sort: str = "evidence",
+    order: str = "desc",
+    limit: int = 50,
+) -> dict:
+    """Filtered, sorted, headline-only list of a protein's interactions.
+
+    kind = activates|inhibits|binds|regulates; type = direct|indirect;
+    pathway = a pathway-name substring; min_evidence = minimum supporting
+    papers; sort = evidence|functions|partner. Lighter than get_protein; use it
+    for targeted questions ("best-evidenced inhibitory edges in ERAD"), then
+    drill in with get_interaction(id).
+    """
+    params: dict = {"min_evidence": min_evidence, "sort": sort, "order": order, "limit": limit}
+    if kind:
+        params["kind"] = kind
+    if type:
+        params["type"] = type
+    if pathway:
+        params["pathway"] = pathway
+    return await _get(f"/api/protein/{quote(symbol, safe='')}/interactions", params)
+
+
+@server.tool(annotations=_ann("Vocabulary + counts"))
+async def list_interaction_types() -> dict:
+    """The controlled vocabulary with plain-language meanings and live counts:
+    edge kinds, interaction types, directions, and the mechanisms present in the
+    graph. Call this before filtering so you use valid values.
+    """
+    return await _get("/api/interaction-types")
+
+
+@server.tool(annotations=_ann("Get pathway"))
+async def get_pathway(pathway_id: str) -> dict:
+    """A single pathway by id: the node, its ancestors and children, and the
+    interactions placed in it. The pathway-first way into the graph.
+    """
+    return await _get(f"/api/pathway/{quote(pathway_id, safe='')}")
+
+
+@server.tool(annotations=_ann("Curated highlights"))
+async def get_highlights() -> dict:
+    """A curated entry point: the best-evidenced interactions, ranked by
+    supporting evidence. Good for a quick, strong overview.
+    """
+    return await _get("/api/highlights")
+
+
+@server.tool(annotations=_ann("Export network"))
+async def export_network(symbol: str, format: str = "tsv") -> str:
+    """Export a protein's interactome as text for external tools.
+
+    format = tsv (edge list / spreadsheet), sif or graphml (Cytoscape,
+    networkx, igraph, Gephi). Edges carry their biological orientation (an
+    upstream partner points into the protein), so the graph is directed.
+    """
+    return await _get_text(
+        f"/api/protein/{quote(symbol, safe='')}/network", {"format": format}
+    )
+
+
+# Static guidance (no HTTP): explains the vocabulary + how to drive the tools.
+_SCHEMA_GUIDE = {
+    "graph": (
+        "A verified protein-protein interactome built from primary literature. "
+        "Interactions are typed, directed, and mechanistic. One protein (ATXN3) "
+        "is fully mapped today."
+    ),
+    "edgeKinds": {
+        "activates": "source increases target activity/level",
+        "inhibits": "source decreases target activity/level",
+        "binds": "physical association, no signed effect",
+        "regulates": "modulates target, direction unspecified",
+    },
+    "interactionTypes": {
+        "direct": "physical / first-order interaction",
+        "indirect": "mediated through one or more intermediates",
+    },
+    "directions": {
+        "downstream": "query acts on the partner (query -> partner)",
+        "upstream": "partner acts on the query (partner -> query)",
+        "bidirectional": "mutual / no single causal direction",
+    },
+    "orientation": (
+        "Pass the query symbol to get_protein / get_interaction so source/target "
+        "read outward from it."
+    ),
+    "flow": (
+        "search_proteins -> get_protein (overview) -> get_interaction for depth. "
+        "list_interactions filters; get_interaction_between fetches a specific "
+        "pair; get_pathway is pathway-first; list_interaction_types shows the "
+        "vocabulary; export_network dumps to Cytoscape/networkx."
+    ),
+    "note": "canonicalPathwayId values resolve to names via get_pathway_tree.",
+}
+
+
+@server.tool(annotations=_ann("Describe the graph"))
+async def describe_schema() -> dict:
+    """Explain the graph's vocabulary and how to use these tools: edge kinds,
+    interaction types, direction semantics, orientation, and the recommended
+    call flow. Static guidance that works even if the API is unreachable.
+    """
+    return _SCHEMA_GUIDE
+
+
+# ---------------------------------------------------------------------------
+# Resources: readable context a client can attach without a tool call.
+# ---------------------------------------------------------------------------
+
+@server.resource("propaths://schema", name="schema",
+                 description="Graph vocabulary + tool-usage guide", mime_type="application/json")
+async def schema_resource() -> dict:
+    return _SCHEMA_GUIDE
+
+
+@server.resource("propaths://interaction-types", name="interaction-types",
+                 description="Controlled vocabulary + counts", mime_type="application/json")
+async def types_resource() -> dict:
+    return await _get("/api/interaction-types")
+
+
+@server.resource("propaths://pathways/tree", name="pathways-tree",
+                 description="Full pathway scaffold", mime_type="application/json")
+async def tree_resource() -> dict:
+    return await _get("/api/pathways/tree")
+
+
+@server.resource("propaths://protein/{symbol}", name="protein-overview",
+                 description="Compact interactome overview for one protein",
+                 mime_type="application/json")
+async def protein_resource(symbol: str) -> dict:
+    page = await _get(f"/api/protein/{quote(symbol, safe='')}")
+    if isinstance(page, dict) and "error" in page:
+        return page
+    return _summarize_protein_page(page)
+
+
+# ---------------------------------------------------------------------------
+# Prompts: reusable templates a client can surface to the user.
+# ---------------------------------------------------------------------------
+
+@server.prompt(name="profile-protein", title="Profile a protein",
+               description="Summarize a protein's interactome from the graph")
+def profile_protein(symbol: str) -> str:
+    return (
+        f'Use the ProPaths tools to profile {symbol}. Start with get_protein("{symbol}") '
+        "for the overview, note the interaction-kind mix and top pathways, then call "
+        "get_interaction(id) on the two or three best-evidenced edges to explain their "
+        "mechanism and direction. Finish with a concise, sourced summary."
+    )
+
+
+@server.prompt(name="strongest-evidence", title="Strongest-evidence interactions",
+               description="Find a protein's best-supported interactions")
+def strongest_evidence(symbol: str) -> str:
+    return (
+        f'Call list_interactions("{symbol}", sort="evidence", limit=5) for the best-'
+        "evidenced interactions, then get_interaction(id) on each to report the mechanism "
+        "and the supporting papers (PMIDs)."
+    )
+
+
+@server.prompt(name="explain-pathway", title="Explain a pathway",
+               description="Explain a pathway and what its members do")
+def explain_pathway(pathway: str) -> str:
+    return (
+        f'Find the pathway matching "{pathway}" (via get_pathway_tree, or '
+        'list_interactions(pathway=...)), then use get_pathway(id) to list the interactions '
+        "placed in it and explain the biology in plain language."
+    )
+
+
+# ---------------------------------------------------------------------------
+# Completion: autocomplete protein symbols for prompt args + the protein
+# resource template (propaths://protein/{symbol}).
+# ---------------------------------------------------------------------------
+
+@server.completion()
+async def complete(ref, argument, context) -> Optional[Completion]:
+    if argument.name in ("symbol", "protein") and (argument.value or "").strip():
+        try:
+            result = await _get("/api/search", {"q": argument.value, "limit": 15})
+        except Exception:
+            return None
+        if isinstance(result, dict) and result.get("results"):
+            return Completion(values=[r["symbol"] for r in result["results"]], has_more=False)
+    return None
+
+
+def main() -> None:
+    """Console entry point: run the MCP server over stdio."""
+    server.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

propaths_mcp-0.1.0/tests/test_tools.py

@@ -0,0 +1,318 @@
+"""Tests for the local/stdio MCP server (``mcp_server/server.py``).
+
+Deterministic and offline: the HTTP layer is stubbed with ``httpx.MockTransport``
+so no API, database, network, or LLM is touched. These lock the two things
+that make the MCP a faithful mirror of the read API:
+
+1. every tool hits the correct /api/* path and forwards its params, and
+2. the API JSON is passed through verbatim (so the tool output cannot drift
+   from the frozen API contract), with HTTP errors surfaced as usable messages.
+
+Run:
+    python -m pytest tests/ -q
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+import httpx
+import pytest
+
+from propaths_mcp import server as srv
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+def _install_mock(monkeypatch, handler):
+    """Point the server's client factory at a MockTransport driven by `handler`."""
+    monkeypatch.setattr(
+        srv, "_make_client",
+        lambda: httpx.AsyncClient(transport=httpx.MockTransport(handler)),
+    )
+
+
+def _recording_handler(recorded: list, payload, status: int = 200):
+    """A handler that records each request and returns a fixed JSON `payload`."""
+    def handler(request: httpx.Request) -> httpx.Response:
+        recorded.append(request)
+        return httpx.Response(status, json=payload)
+    return handler
+
+
+# ---------------------------------------------------------------------------
+# Registration
+# ---------------------------------------------------------------------------
+
+def test_all_tools_registered_and_annotated():
+    tools = _run(srv.server.list_tools())
+    names = {t.name for t in tools}
+    assert names == {
+        "search_proteins", "get_protein", "get_interaction",
+        "get_pathway_tree", "get_interaction_between",
+        "list_interactions", "list_interaction_types", "get_pathway",
+        "get_highlights", "export_network", "describe_schema",
+    }
+    # every tool advertises read-only + idempotent + closed-world
+    for t in tools:
+        assert t.annotations is not None
+        assert t.annotations.read_only_hint is True
+        assert t.annotations.idempotent_hint is True
+        assert t.annotations.open_world_hint is False
+
+
+def test_resources_prompts_and_templates_registered():
+    resources = {str(r.uri) for r in _run(srv.server.list_resources())}
+    assert resources == {
+        "propaths://schema",
+        "propaths://interaction-types", "propaths://pathways/tree",
+    }
+    templates = {t.uri_template for t in _run(srv.server.list_resource_templates())}
+    assert templates == {"propaths://protein/{symbol}"}
+    prompts = {p.name for p in _run(srv.server.list_prompts())}
+    assert prompts == {"profile-protein", "strongest-evidence", "explain-pathway"}
+
+
+def test_get_protein_tool_schema_exposes_symbol():
+    tools = {t.name: t for t in _run(srv.server.list_tools())}
+    props = tools["get_protein"].input_schema.get("properties", {})
+    assert "symbol" in props
+
+
+# ---------------------------------------------------------------------------
+# Path routing + pass-through
+# ---------------------------------------------------------------------------
+
+def test_get_protein_hits_path_and_returns_overview(monkeypatch):
+    rec: list = []
+    body = {"main": "ATXN3", "protein": {"symbol": "ATXN3"},
+            "proteins": ["ATXN3", "VCP"],
+            "interactions": [], "chains": [], "pathways": []}
+    _install_mock(monkeypatch, _recording_handler(rec, body))
+
+    result = _run(srv.get_protein("ATXN3"))
+
+    assert rec[0].url.path == "/api/protein/ATXN3"
+    # get_protein returns the compact overview, not the raw page
+    assert result["main"] == "ATXN3"
+    assert result["counts"] == {"interactions": 0, "pathways": 0, "proteins": 2}
+    assert "note" in result
+
+
+def test_get_interaction_is_verbatim_passthrough(monkeypatch):
+    # detail tools stay pure pass-through (only get_protein is projected)
+    rec: list = []
+    body = {"id": "i1", "source": "ATXN3", "target": "VCP",
+            "functions": [{"function": "x"}], "mechanism": "deep prose"}
+    _install_mock(monkeypatch, _recording_handler(rec, body))
+    assert _run(srv.get_interaction("i1")) == body
+
+
+def test_search_forwards_query_and_limit(monkeypatch):
+    rec: list = []
+    _install_mock(monkeypatch, _recording_handler(rec, {"query": "AT", "results": []}))
+
+    _run(srv.search_proteins("AT", limit=5))
+
+    assert rec[0].url.path == "/api/search"
+    assert dict(rec[0].url.params) == {"q": "AT", "limit": "5"}
+
+
+def test_interaction_orient_query_is_optional(monkeypatch):
+    rec: list = []
+    _install_mock(monkeypatch, _recording_handler(rec, {"id": "i1"}))
+
+    _run(srv.get_interaction("i1", query="ATXN3"))
+    assert rec[0].url.path == "/api/interaction/i1"
+    assert dict(rec[0].url.params) == {"query": "ATXN3"}
+
+    _run(srv.get_interaction("i1"))
+    assert dict(rec[1].url.params) == {}        # no query param when omitted
+
+
+def test_pathway_tree_path(monkeypatch):
+    rec: list = []
+    _install_mock(monkeypatch, _recording_handler(rec, {"pathways": [], "count": 0}))
+    _run(srv.get_pathway_tree())
+    assert rec[0].url.path == "/api/pathways/tree"
+
+
+def test_path_segment_is_url_encoded(monkeypatch):
+    rec: list = []
+    _install_mock(monkeypatch, _recording_handler(rec, {}))
+    _run(srv.get_protein("A/B"))
+    # a stray slash must stay percent-encoded on the wire so it cannot escape
+    # the path segment (`.path` decodes it back; the raw URL preserves it)
+    assert "/api/protein/A%2FB" in str(rec[0].url)
+
+
+def test_respects_PROPATHS_API_URL_env(monkeypatch):
+    rec: list = []
+    monkeypatch.setenv("PROPATHS_API_URL", "http://example.test:9000/")
+    _install_mock(monkeypatch, _recording_handler(rec, {"pathways": []}))
+    _run(srv.get_pathway_tree())
+    assert str(rec[0].url) == "http://example.test:9000/api/pathways/tree"
+
+
+# ---------------------------------------------------------------------------
+# Error handling
+# ---------------------------------------------------------------------------
+
+def test_http_404_becomes_structured_error(monkeypatch):
+    rec: list = []
+    _install_mock(
+        monkeypatch,
+        _recording_handler(rec, {"detail": "Protein not found: ZZZ"}, status=404),
+    )
+    result = _run(srv.get_protein("ZZZ"))
+    assert result == {"error": "Protein not found: ZZZ", "status": 404}
+
+
+def test_unreachable_api_returns_error_with_hint(monkeypatch):
+    # A raised exception would be swallowed by MCP into a generic "Error
+    # executing tool" message, so the tool RETURNS a structured error instead.
+    def boom(request: httpx.Request) -> httpx.Response:
+        raise httpx.ConnectError("connection refused", request=request)
+
+    _install_mock(monkeypatch, boom)
+    result = _run(srv.get_pathway_tree())
+    assert result["status"] is None
+    assert "Could not reach the ProPaths API" in result["error"]
+    assert "PROPATHS_API_URL" in result["error"]
+
+
+# ---------------------------------------------------------------------------
+# _summarize_protein_page — the agent-sized projection (pure)
+# ---------------------------------------------------------------------------
+
+def _full_page() -> dict:
+    return {
+        "main": "ATXN3",
+        "protein": {"symbol": "ATXN3", "hgncId": "HGNC:7106"},
+        "proteins": ["ATXN3", "VCP", "TP53"],
+        "pathways": [
+            {"id": "root1", "name": "Proteostasis", "hierarchyLevel": 0, "parentId": None},
+            {"id": "p2", "name": "ERAD", "hierarchyLevel": 2, "parentId": "root1"},
+        ],
+        "interactions": [{
+            "id": "i1", "source": "ATXN3", "target": "VCP", "kind": "binds",
+            "direction": "bidirectional", "type": "direct", "functionCount": 2,
+            "evidenceCount": 3, "supportSummary": "ATXN3 binds VCP",
+            "summary": "long...", "mechanism": "M" * 500, "effect": "e",
+            "functions": [{"function": "f1", "canonicalPathwayId": "p2",
+                           "effectDescription": "X" * 500}],
+            "evidence": [{"pmid": "1", "keyFinding": "K" * 500}], "pmids": ["1", "2"],
+        }],
+        "chains": [{
+            "id": "c1", "nodes": ["ATXN3", "VCP", "TP53"], "length": 2,
+            "netArrow": "activates", "netDirection": "query_to_terminal",
+            "terminalNode": "TP53", "terminalEffect": "te", "supportSummary": "chain s",
+            "cascadeNarrative": "N" * 500, "hops": [{"mechanism": "M" * 500}],
+        }],
+    }
+
+
+def test_summarize_drops_heavy_prose_keeps_headlines_and_resolves_pathways():
+    s = srv._summarize_protein_page(_full_page())
+    assert s["counts"] == {"interactions": 1, "pathways": 2, "proteins": 3}
+    assert s["pathwayRoots"] == ["Proteostasis"]
+
+    ix = s["interactions"][0]
+    assert ix["id"] == "i1" and ix["kind"] == "binds"
+    assert ix["supportSummary"] == "ATXN3 binds VCP"
+    assert ix["pathways"] == ["ERAD"]                 # id resolved to name
+    for heavy in ("functions", "evidence", "mechanism", "summary", "effect"):
+        assert heavy not in ix
+
+    # chains are SHELVED: the overview must not surface them even if present in the page
+    assert "chains" not in s and "chains" not in s["counts"]
+
+
+def test_summarize_is_smaller_than_raw_page():
+    page = _full_page()
+    assert len(json.dumps(srv._summarize_protein_page(page))) < len(json.dumps(page))
+
+
+def test_summarize_handles_edge_with_no_functions():
+    page = _full_page()
+    page["interactions"][0]["functions"] = []
+    s = srv._summarize_protein_page(page)
+    assert s["interactions"][0]["pathways"] == []
+
+
+# ---------------------------------------------------------------------------
+# New tools: path routing + pass-through
+# ---------------------------------------------------------------------------
+
+def test_types_and_highlights_paths(monkeypatch):
+    rec: list = []
+    _install_mock(monkeypatch, _recording_handler(rec, {"ok": True}))
+    _run(srv.list_interaction_types())
+    _run(srv.get_highlights())
+    assert [r.url.path for r in rec] == ["/api/interaction-types", "/api/highlights"]
+
+
+def test_interaction_between_path(monkeypatch):
+    rec: list = []
+    _install_mock(monkeypatch, _recording_handler(rec, {"source": "ATXN3", "target": "VCP"}))
+    out = _run(srv.get_interaction_between("ATXN3", "VCP"))
+    assert rec[0].url.path == "/api/edge/ATXN3/VCP"
+    assert out == {"source": "ATXN3", "target": "VCP"}          # pass-through
+
+
+def test_list_interactions_forwards_filters(monkeypatch):
+    rec: list = []
+    _install_mock(monkeypatch, _recording_handler(rec, {"interactions": []}))
+    _run(srv.list_interactions("ATXN3", kind="inhibits", min_evidence=3, sort="evidence", limit=10))
+    assert rec[0].url.path == "/api/protein/ATXN3/interactions"
+    assert dict(rec[0].url.params) == {
+        "min_evidence": "3", "sort": "evidence", "order": "desc",
+        "limit": "10", "kind": "inhibits"}
+
+
+def test_get_pathway_path(monkeypatch):
+    rec: list = []
+    _install_mock(monkeypatch, _recording_handler(rec, {"pathway": {}}))
+    _run(srv.get_pathway("abc-123"))
+    assert rec[0].url.path == "/api/pathway/abc-123"
+
+
+def test_export_network_returns_text(monkeypatch):
+    rec: list = []
+    def handler(request):
+        rec.append(request)
+        return httpx.Response(200, text="source\ttarget\nATXN3\tVCP\n")
+    _install_mock(monkeypatch, handler)
+    out = _run(srv.export_network("ATXN3", "tsv"))
+    assert rec[0].url.path == "/api/protein/ATXN3/network"
+    assert dict(rec[0].url.params) == {"format": "tsv"}
+    assert out.startswith("source\ttarget")                    # raw text, not JSON
+
+
+# ---------------------------------------------------------------------------
+# Static schema (no HTTP) + resources + completion
+# ---------------------------------------------------------------------------
+
+def test_describe_schema_is_static_and_offline():
+    guide = _run(srv.describe_schema())
+    assert {"edgeKinds", "interactionTypes", "directions", "flow"} <= set(guide)
+    assert guide["edgeKinds"]["activates"]
+    # schema resource returns the same static guide
+    assert _run(srv.schema_resource()) == guide
+
+
+def test_completion_suggests_symbols(monkeypatch):
+    from types import SimpleNamespace
+    _install_mock(monkeypatch, _recording_handler([], {"results": [{"symbol": "ATXN3"}, {"symbol": "ATXN2"}]}))
+    arg = SimpleNamespace(name="symbol", value="ATX")
+    result = _run(srv.complete(None, arg, None))
+    assert result is not None and result.values == ["ATXN3", "ATXN2"]
+
+
+def test_completion_ignores_unknown_argument():
+    from types import SimpleNamespace
+    result = _run(srv.complete(None, SimpleNamespace(name="color", value="red"), None))
+    assert result is None