# @pipeworx/symmap

SymMap v2 (symmap.org, Beijing University of Chinese Medicine) — the Traditional
Chinese Medicine association graph: 698 herbs, ~26k ingredients, ~21k protein
targets, TCM symptoms, TCM syndromes, modern medical symptoms and ~14k diseases,
connected by curated and predicted associations. Every relationship payload
carries an explicit `evidence_tier` (`traditional_use` | `human_clinical` |
`laboratory` | `computational_prediction`) and an `evidence_basis` sentence,
because SymMap records associations, not efficacy — nothing in it is clinical
proof that a herb treats anything.

Part of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1683+ live data sources.

## Tools

- `symmap_search(query, entity)` — resolve a name (Chinese, pinyin, Latin,
  English, gene symbol, disease name) to SymMap ids across any of the seven
  entity classes.
- `symmap_herb(herb)` — full bilingual herb record: TCM properties, meridians,
  drug class, used part, all name forms.
- `symmap_herb_ingredients(herb)` — molecules identified in a herb, with
  PubChem CID, CAS and oral-bioavailability score.
- `symmap_herb_symptoms(herb)` — the herb's traditional indications: TCM
  symptoms (SMTS) and TCM syndromes (SMSY), kept separate from the modern
  vocabulary.
- `symmap_symptom_herbs(symptom, system)` — herbs for a symptom; `system:"tcm"`
  is a direct lookup, `system:"modern"` goes through SymMap's curated
  modern→TCM symptom crosswalk with both hops explicit.
- `symmap_ingredient(ingredient)` — an ingredient's protein targets
  (PubMed-cited edges are tier `laboratory`, uncited ones
  `computational_prediction`) and the herbs it occurs in.
- `symmap_target_diseases(target)` — diseases associated with a gene;
  OMIM/Orphanet-backed edges are tier `human_clinical`, the rest
  `computational_prediction`.

## Auth

Keyless.

## Data sources

- <http://www.symmap.org/related_components/> — form-POST JSON: association
  edges for one entity (`rrid`, `table_name`, `filter`).
- <http://www.symmap.org/search/> — form-POST JSON: entity search by name
  (`table_name`, `key`).
- `src/herbs.ts` — the herb entity table, generated by `scripts/bake-herbs.py`
  from the SMHB file on SymMap's download page, so herb lookup never depends on
  the upstream server.

Things the next person would rediscover the hard way:

- **The site is plain HTTP only** — `https://www.symmap.org` does not answer.
- **The downloadable "key files" are NOT relation edges.** They are long-format
  (id, Field_name, Field_context) dumps of the same entity tables. The actual
  graph edges are only served by `/related_components/`.
- **Some join directions 502 by design of their backend**: herb→Gene,
  herb→Disease, herb→MM_symptom and MM_symptom→Herb all return 502 every time,
  while herb→Mol, herb→TCM_symptom, herb→Syndrome, Mol→Gene, Mol→Herb,
  TCM_symptom↔MM_symptom, TCM_symptom→Herb, Syndrome→Herb, Gene→Disease and
  Disease→Gene answer reliably. The tools compose only the reliable directions;
  a herb's targets are reached herb→ingredients→targets, one hop at a time.
- `rrid` accepts both `SMHB1` and `SMHB00001` forms.
- In v2.0, `SMTS` is TCM symptoms, `SMSY` is TCM **syndromes** (new in v2),
  `SMMS` is modern-medicine symptoms. The v1 downloads reuse `SMTS` differently;
  don't mix versions.
- Ingredient→target literature evidence arrives as an HTML snippet with the
  same sentence twice (short + long variants) plus a Fold button; the pack
  extracts the long variant and the PMIDs.

## Licence / attribution

SymMap is a free-to-access academic database; its site states the download
files are free to download and carries no further reuse terms. Cite the paper
when publishing results: Wu et al., *SymMap: an integrative database of
traditional Chinese medicine enhanced by symptom mapping*, Nucleic Acids
Research 2019, doi:10.1093/nar/gky1021.

## Quick Start

Add to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "symmap": {
      "url": "https://gateway.pipeworx.io/symmap/mcp"
    }
  }
}
```

### What this endpoint actually serves

`tools/list` at `https://gateway.pipeworx.io/symmap/mcp` returns the tools in the table
above **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,
`discover_tools`, `search_within`, `remember`/`recall` and the rest of the
gateway-wide set. So the tool count you see is larger than this table: a
single-pack endpoint currently lists roughly 30 shared tools alongside the
pack's own. The connection's `initialize` response states its exact scope, and
is the authoritative answer for a given day.

This is deliberate, not multiplexing by accident. The meta-tools are what let a
scoped connection answer a question this pack does not cover — via
`ask_pipeworx`, which routes across the whole catalog — without you adding a
second MCP server. There is currently no way to mount a pack endpoint without
them; if the extra schemas cost you more context than the routing is worth,
connect to the full gateway once rather than to several pack endpoints.

Or connect to the full Pipeworx gateway to get every pack's tools listed
directly, instead of just this one's:

```json
{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}
```

Both URLs reach the same gateway and the same 1683+ data sources. The
only difference is which pack's tools are listed **directly**; `ask_pipeworx`
reaches all of them from either one.

## No MCP client? Call it over HTTP

```bash
curl -X POST https://gateway.pipeworx.io/v1/tools/symmap_search \
  -H 'Content-Type: application/json' \
  -d '{"query":"insomnia","entity":"mm_symptom"}'
```

No account needed for the first calls. Inspect any tool: `GET https://gateway.pipeworx.io/v1/tools/symmap_search`. Find one: `POST https://gateway.pipeworx.io/v1/tools/search_packs` with `{"query":"..."}`.

## Standalone (no gateway account)

This package also runs as a local stdio MCP server — no Pipeworx account, no
gateway round-trip:

```json
{
  "mcpServers": {
    "symmap": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-symmap"]
    }
  }
}
```

Or run it directly to confirm it starts:

```bash
npx -y @pipeworx/mcp-symmap
```

It speaks MCP over stdin/stdout and answers `initialize`/`tools/list`/`tools/call`
for **only** this pack's tools — none of the shared meta-tools the gateway
connection above adds. Same source, same tools, no ask_pipeworx routing.

## Using with ask_pipeworx

Instead of calling tools directly, you can ask questions in plain English —
this works on the pack endpoint above as well as on the full gateway:

```
ask_pipeworx({ question: "your question about Symmap data" })
```

The gateway picks the right tool and fills the arguments automatically.

## More

- [Docs and guides](https://pipeworx.io/docs)
- [pipeworx.io](https://pipeworx.io)

## License

MIT