@pipeworx/herb-tcm

HERB 2.0's Traditional Chinese Medicine knowledge base — herbs, ingredients, gene targets, diseases, PubMed-cited papers and GEO transcriptomic experiments — proxied live from herb.ac.cn, with every relationship row tagged an evidence_tier so a statistical prediction is never mistaken for proof of efficacy.

Part of Pipeworx — an MCP gateway connecting AI agents to 1865+ live data sources. This is an independent, unofficial integration — not affiliated with, endorsed by, or published by the upstream provider.

Tools

• herb_search(keyword, category?) — resolve a name to an id. Accepts Chinese characters, pinyin, English/Latin names, gene names/aliases, disease names, or a HERB id itself. category is one of herb / ingredient / target / disease (default herb).
• herb_browse(category, page?, page_size?) — page through the full herb/ingredient/target/disease list (7,263 / 49,258 / 12,933 / 28,212 rows respectively).
• herb_detail(id, category, limit?, offset?, sections?) — the full record for one id: composition, traditional-use summary, and every predicted or literature-backed target/disease relationship, each carrying its evidence_tier. Relationship tables are paged (fleet #1399 — an unpaged well-studied herb ran to 806 KB): each comes back as {total, offset, limit, returned, truncated, rows} where total is the TRUE upstream row count and truncated: true says more rows exist — so a 25-row slice can never be mistaken for 25 rows existing. limit defaults to 25 (the pack's precedent, set by herb_papers), max 200; offset pages; sections (e.g. ["summary","herb_ingredient"]) fetches composition without pulling thousands of predicted disease rows, and an unknown section name errors loudly rather than silently returning nothing. We chose client-side slicing over a sections-only design because detail_api has no server-side paging (one upstream call returns everything regardless), so the slice costs nothing extra and the envelope keeps the caller honest. ingredient_alias (a small synonym list) is never paged.
• herb_papers(drug_type?, experiment_type?, sort_by?, limit?, offset?) — list PubMed-cited references, each tagged human_clinical or laboratory.
• herb_paper_detail(paper_id) — one reference's bibliographic record plus the specific targets/diseases it reports.
• herb_experiments(drug_type?, species?, experiment_type?, limit?, offset?) — list GEO-deposited herb/ingredient-vs-control transcriptomic experiments.
• herb_experiment_detail(experiment_id) — differential-expression results for one experiment: top up/down genes, enriched GO/KEGG terms, connectivity-map hit counts. Always evidence_tier: computational_prediction.

Evidence tiers

Every relationship row carries one of:

| Tier | Meaning | |---|---| | traditional_use | From the herb's Pharmacopoeia-style summary (Function/Indication/Meridians). Historical use, not a trial. | | human_clinical | A PubMed-cited paper whose HERB-assigned "Experiment type" includes "Clinical Experiment" — it studied humans. | | laboratory | A PubMed-cited paper studying cells or animals only. | | computational_prediction | A statistical enrichment or database cross-reference with no clinical or experimental confirmation. This is a hypothesis, not evidence the herb/ingredient treats anything. | | compositional_fact | "This ingredient occurs in this herb" — a composition fact, not an efficacy claim at all. |

herb_target / herb_disease (statistical enrichment, p-value + FDR_BH columns), ingredient_target / ingredient_disease / target_disease (curated cross-references with no clinical backing) and every herb_experiment_detail row are computational_prediction. drug_paper_target / drug_paper_disease (PubMed-cited) are split into human_clinical or laboratory by resolving each cited paper's own "Experiment type" — see Data sources below for how.

Auth

Keyless. herb.ac.cn requires no account, token or payment — it is public data served to anyone.

Data sources

• http://herb.ac.cn/chedi/api/ — herb.ac.cn is a umi single-page app with no REST surface (every path returns the same ~900-byte shell). The real API is this one POST endpoint, dispatching on a func_name body field, found in the site's own JS bundle (http://herb.ac.cn/static/umi.js). Seven verbs, confirmed live 2026-09-08: search_api, detail_api, browse_api, paper_api, paper_detail_api, experiment_api, experiment_detail_api.

Notes for the next person:

• http only, and Chinese-hosted — measured 200ms-1.5s per call from this session but expect latency and occasional unreachability; several .cn sources are known-flaky from our vantage. This is a known class, not a bug — report it rather than retrying hard.
• Every response is served as text/html, including successful ones — do not branch on Content-Type. The only reliable signal for "no such id" is the HTTP status: a bad key_id/label/paper_key_id/drug_GSE_id returns HTTP 500 with an HTML "Internal Server Error" page; an unknown func_name returns HTTP 200 with the literal body null. parseJson/httpError from @pipeworx/shared handle both shapes.
• Cells in every table are either a plain value or {link, title} / {style, title} — even header cells in the differential-expression tables come this way ({filterable, sortable, title}). tableToRows in src/index.ts unwraps every shape to a plain string/number.
• detail_api needs three params, not just the id: key_id, label (must match the id's category — HERB… ids need label: "Herb", etc.) and v (the site's own UI passes the id again under this name; omitting it was not tested and isn't worth risking).
• drug_paper_target/drug_paper_disease rows (inside herb_detail) carry a Paper id but not that paper's own experiment type, and a cited herb can reference 20-100+ papers. Rather than firing one paper_detail_api call per paper (impolite fan-out against a slow host), herb_detail makes ONE extra call to paper_api unfiltered — which returns HERB's entire ~2,000-row reference index including "Experiment type" per id — and resolves the tier from that in-memory lookup. Nothing from it is cached across tool calls; it is refetched live every time herb_detail needs it.
• Ingredient_alias (inside an ingredient's detail_api response) is not a table — it's a one-element array holding one semicolon-joined string of synonyms. Treating it as a table throws (table[0].map is not a function); split on ; instead.
• experiment_detail_api's Experiment_detail field nests everything one level deeper than expected: it's an object with exactly one key, named "HBEXP000001 Data Detail" (the experiment id plus a fixed suffix), whose value is { data: {...} }. The differential-expression/GO/KEGG/CMAP tables live under that single value's data field — src/index.ts grabs it with Object.values(...)[0]?.data rather than building the key string, since the exact suffix isn't documented anywhere.
• paper_api and experiment_api have no server-side pagination — each call returns the FULL filtered list (~2,000 papers / ~1,000 experiments unfiltered) in one response. herb_papers/herb_experiments slice client-side with limit/offset; a tighter drug_type/experiment_type filter reduces what herb.ac.cn itself has to compute and send.
• Licensing: settled by Bruce, fleet #1389 (2026-09-08) — a live per-request proxy call is a client, not a publisher, so it needs no explicit reuse grant the way bulk-copying the dataset would. This pack must stay a proxy: no bulk download, no full local mirror, no cached complete copy of herb.ac.cn's data.

Quick Start

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

{
  "mcpServers": {
    "herb-tcm": {
      "url": "https://gateway.pipeworx.io/herb-tcm/mcp"
    }
  }
}

What this endpoint actually serves

tools/list at https://gateway.pipeworx.io/herb-tcm/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:

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

Both URLs reach the same gateway and the same 1865+ 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

curl -X POST https://gateway.pipeworx.io/v1/tools/herb_tcm_herb_search \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"banlangen","category":"herb"}'

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

Run it from npm

@pipeworx/mcp-herb-tcm is a local stdio bridge to the Pipeworx gateway: your MCP client starts it with npx, and it forwards every call to the same https://gateway.pipeworx.io/herb-tcm/mcp endpoint shown above. It needs network access; there is no offline mode.

{
  "mcpServers": {
    "herb-tcm": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-herb-tcm"]
    }
  }
}

Without a key it calls anonymously, capped at 50 calls a day. A free account raises that to 200 a day: get a key at https://pipeworx.io/signup and add "env": { "PIPEWORX_API_KEY": "<your key>" } to the server entry. The key is sent as a Bearer token, the same way a hosted connection sends it, so calls are metered and billed exactly as they are there.

It lists only this pack's tools by default. Set PIPEWORX_META_TOOLS=1 to also list ask_pipeworx and the other gateway-wide tools.

Behind an HTTPS proxy: Node's built-in fetch does not read HTTPS_PROXY by default. Newer Node releases honour it when NODE_USE_ENV_PROXY=1 is set; check your Node version's documentation.

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 Herb Tcm data" })

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

More

• Docs and guides
• pipeworx.io

License

MIT