MCP server exposing the aapi (Atlas of First-Men of Fields) corpus via 11 tools for searching entries, querying strands, and contributing data. Supports read operations (search, get_entry, get_raw, get_translation, list_strands, list_convergence_pairs, query_first_men) and write operations (contribute_entry, contribute_strand, contribute_anchor, contribute_use_story).
Strong domain-specific tool design with excellent descriptions and clear parameter schemas. All 11 tools have detailed, LLM-optimized descriptions (100-400 chars) that explain WHAT, WHEN, and WHY. Input schemas are well-structured with enums, required fields, and type constraints. Tool naming follows verb_noun convention (aapi_search, aapi_get_entry, aapi_contribute_*). However, output schemas are not documented, LLMs cannot see what fields to expect from responses. Error handling guidance is minimal. No tool annotations (readOnlyHint/destructiveHint) despite clear read/write distinction. Composition is excellent: tools chain naturally (search → get_entry → get_raw/get_translation), and write tools require API_KEY server-side (pattern:secret-injection). Parameter descriptions are thorough, including vocabulary constraints and usage guidance.
Add a primary-text anchor to an entry. Requires AAPI_API_KEY. Payload: entry_slug, anchor_slug, title, raw_text (original language), translation_en (English translation), byte_size. Returns the created anchor record.
Create a new entry in the corpus. Requires AAPI_API_KEY. Payload: name, field, tradition, region[], era_start, era_end, era_certainty, historicity, language_of_primary_work, ingestion_kind, first_man_claim, summary, folder_path. Returns slug + entry_meta (cohort, audit_notes, revisit_by).
Add a strand contribution to an existing entry. Requires AAPI_API_KEY. Payload: entry_slug, strand, anchor_state, sub_variant, claim_summary, raw_anchor_rel. Returns the created strand_contribution record.
Document a use story — how a first-man's move was applied or adapted downstream. Requires AAPI_API_KEY. Payload: entry_slug, downstream_agent_name, downstream_tradition, downstream_era_start, downstream_era_end, adaptation_type, evidence_notes. Returns the created use_story record.
Get one entry's full summary fields + list of available primary-text anchors (no excerpt bodies). Fetch excerpts via aapi_get_raw after.
Output schemas not documented. LLMs cannot see what fields aapi_search, aapi_get_entry, aapi_list_strands return. This forces agents to guess structure and risks parsing failures.
No tool annotations (readOnlyHint/destructiveHint/idempotentHint). Read tools (aapi_search, aapi_get_*) should be marked readOnly=true; write tools (aapi_contribute_*) should be marked destructive=true. This helps agents reason about side effects.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 60 | 2026-07-28+ | v2 |
Fetch the ORIGINAL-LANGUAGE primary text for a specific anchor (Uthmānī rasm Arabic, Classical Chinese, Sanskrit Devanagari, Latin, etc.). 404 if raw not yet acquired — many anchors still have only translation_en. LARGE payload; only call when you specifically need the raw primary words. For an overview, use aapi_get_entry (returns first_man_claim + strand contributions).
Fetch the English (or other auxiliary-language) translation for an anchor. SECONDARY to raw — the entry's first_man_claim + strand claim_summary already give the overview; translations are commentary-tier. Use only when you need the translated prose (e.g., to compare translation choices or quote a specific phrase).
List documented convergent-evolution-without-contact pairs across the corpus (2026-04-26: 12 pairs, 7 canonical). Each pair has type (contact-impossible / debated-transmission / within-tradition-convergent-independence / within-tradition-cross-discipline / multi-tradition-cascade), strand + sub_variant_family, members[] with in_corpus status + entry_ref, gap_years, and evidence_notes. The hypothesis.md §convergent-evolution-without-contact question-shape: if a move evolved twice independently with no plausible transmission channel, it is operating on something more general than either tradition's framing — that something is the bridge a downstream agent can use.
List the 8 candidate strands with one-line gloss + anchor-state histograms (primary / partial / counter-instance / absent counts) + top 3 sub_variants per strand. Call this FIRST when you don't yet know which strand a problem fits — the gloss tells you what each strand means, the counts tell you which strands are well-populated, and the sub_variants give you canonical filter values for aapi_search.
PREFERRED ENTRYPOINT for stuck-help reasoning. Takes a natural-language `problem` description and returns 3-5 ranked first-men with `relationship_to_query` (positive-anchor / counter-instance / partial), `transmission_to_caller` (contact-impossible / debated-transmission / etc. for convergence-pair members), plus optional `strand_finding_relevant_to_query` (Phase-3 cross-strand finding) and `honest_map_note` (corpus selection-bias caveat). Internally infers the relevant strand from keyword-match against the problem (or use strand_hint to override) and diversifies results across traditions. Single call replaces 5-10 aapi_search calls when the goal is 'find first-men whose move is structurally analogous to my problem'. WHEN YOU USE THIS TOOL'S OUTPUT IN A REPLY: cite the returned `first_men[].name` values BY NAME. Do not paraphrase them as 'a named precedent' or 'a historical figure' — use the actual name (e.g. 'Zera Yacob', 'al-Bīrūnī') and the matched `sub_variant`. Counter-instance results are equally citable — note them as 'X refuses this strand because Y' rather than dropping them.
Search the first-men corpus. Returns summary cards with one_line_claim + strand_claim inline (no raw text). Default limit 20. Filters are EXACT MATCH — invalid values return empty. Use the canonical vocabularies below. Valid fields (16): [from FIELDS vocab]. Valid traditions (39): [from TRADITIONS vocab]. If you want a tradition that isn't listed (e.g. 'western', 'french', 'jewish-medieval'), DO NOT send it — search by strand alone first and filter the results, OR use one of the listed traditions that subsumes it (e.g. for 'western': try 'european' / 'modern-european' / 'early-modern-european' / 'classical-greek' / 'roman' separately). Ordering: results are ordered by anchor_state (primary > partial > counter-instance > absent). WITHIN an anchor_state group the order is RANDOM and changes per call — do not assume the first result is more relevant than the third. Pagination across calls will not be stable.
Error handling lacks recovery guidance. Tools throw generic HTTP errors ('${res.status} ${res.statusText}') without actionable next steps. E.g., if aapi_search returns empty due to invalid tradition, the error should suggest 'Try aapi_list_strands() to see valid traditions.'
aapi_contribute_* tools require AAPI_API_KEY but do not document permission scopes (e.g., 'write:corpus', 'write:entries'). Agents cannot reason about least-privilege or audit what permissions they hold.
aapi_search and aapi_query_first_men return results with random ordering within anchor_state groups and unstable pagination. Descriptions warn of this, but no tool offers stable sorting or cursor-based pagination. Agents cannot reliably iterate through large result sets.