How do I resolve scientific names to taxonomy IDs, get lineage, and find most recent common ancestors via Open Tree of Life MCP?

@pipeworx/mcp-opentreeoflife — phylogenetics via Open Tree of Life API

Package: npm install @pipeworx/mcp-opentreeoflife Transport: library-style (export { tools, callTool }) — import and call directly, no stdio server API: api.opentreeoflife.org/v3 (POST JSON-RPC, keyless) Auth: none required

Tools (3)

1. match_names {names: string[]} — Resolve scientific names to OTT taxon IDs. Returns ott_id, accepted name, rank, synonym/approximate flags, and match score. Max 20 names per call. Gracefully returns matched: null for unrecognized names.

1. taxon_info {ott_id: number} — Full taxon details: accepted name, rank, up to 15 synonyms, source taxonomy, and complete ancestry lineage from the taxon to the root of life. Returns 400 for invalid OTT IDs.

1. common_ancestor {ott_ids: number[]} — Most recent common ancestor (MRCA) of 2–10 taxa. Returns the MRCA taxon name, rank, and OTT ID. When the MRCA node is unnamed, falls back to the nearest named ancestor (flagged via nearest_named_fallback: true).

Execution pattern

npm install @pipeworx/mcp-opentreeoflife

const mod = await import("@pipeworx/mcp-opentreeoflife/src/index.ts");
const { callTool } = mod.default;

// Step 1: resolve names to OTT IDs
const r = await callTool("match_names", { names: ["Panthera leo", "Aquila chrysaetos"] });
// r.matches[0].matched.ott_id → 563151 (lion)
// r.matches[1].matched.ott_id → 263127 (golden eagle)

// Step 2: get lineage
const info = await callTool("taxon_info", { ott_id: 563151 });
// info.lineage → Panthera → Pantherinae → Felidae → Carnivora → Mammalia → ... → cellular organisms

// Step 3: find MRCA
const mrca = await callTool("common_ancestor", { ott_ids: [563151, 263127] });
// mrca.mrca.name → "Amniota" (the clade uniting mammals, reptiles, birds)

Requires node --experimental-strip-types for direct .ts execution.

Verified results (20 calls, 20/20 OK)

match_names (7 calls):

• Animals: Panthera leo → 563151, Aquila chrysaetos → 263127 (exact matches, score=1)
• Plants: Quercus alba → 791112, Rosa canina → 799768, Arabidopsis thaliana → 309263
• Primates: Homo sapiens → 770315, Pan troglodytes → 417950, Gorilla gorilla → 417969
• Microbes: E. coli → 474506, S. cerevisiae → 356221
• Error: typo "Panthra leo" → matched: null (graceful), nonexistent "Xyzabc foobar" → matched: null

taxon_info (4 calls):

• Lion (563151): lineage Panthera → Pantherinae → Felidae → Carnivora → Mammalia → Amniota → ... → cellular organisms. 3 synonyms (Felis imperialis, Felis leo, Leo leo)
• Human (770315): 15 synonyms. Full lineage through Homininae → Hominidae → Primates → Mammalia
• Oak (791112): lineage Quercus → Fagaceae → Fagales → rosids → eudicotyledons → Magnoliopsida. 15 synonyms (Quercus candida, Q. ramosa, etc.)
• Invalid OTT (999999999): 400 error "Unrecognized OTT ID" — handled gracefully

common_ancestor (5 calls):

• Human + chimp → Homininae (subfamily, nearestnamedfallback=true — MRCA is an unnamed internal node)
• Human + chimp + gorilla → Homininae (the named node itself, fallback=false)
• Lion + golden eagle → Amniota (correct: both amniotes)
• Human + oak → Eukaryota (domain-level: animal + plant)
• E. coli + yeast → cellular organisms (deepest split: bacteria + fungi)
• Single OTT ID → error "provide 2-10 numeric ott_ids"

Latency: p50 ~320ms per call

Gotchas

1. Always start with match_names — OTT IDs are internal to Open Tree and cannot be guessed. Using an incorrect OTT ID returns 400.
2. Unnamed MRCA nodes: when the true MRCA is an unnamed internal phylogenetic node, the API returns the nearest named ancestor. Check nearest_named_fallback to know which case you got.
3. Max 20 names per match_names call, max 10 OTT IDs per common_ancestor call.
4. Synonyms capped at 15 in taxon_info output (source has more for well-studied taxa).