# 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://www.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://www.propaths.net/api/protein/ATXN3
curl 'https://www.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://www.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://www.propaths.net/quick-start> · License: MIT