MCP server¶

The whole encyclopedia — 1,524 prime abstractions, 11,102 domain-specific abstractions, 1,134 solution archetypes and 9,939 mechanisms, with the reference registry, the hierarchy and the diagnostic layer — as a set of tools an AI assistant can call. It runs on your machine, reads a downloaded snapshot, and needs no account, no key and no network once installed.

Current release: server 1.0.6, data edition 2026-10-07 (144 MB download, 526 MB on disk). Downloads are at the end of this page.

What it is¶

The Model Context Protocol is the open standard through which assistants such as Claude Desktop, Claude Code, Cursor, Cline, Zed and Continue call external tools. eoa-mcp is a small Python program that speaks that protocol over standard input and output. Your client starts it, the client's model sees the tools listed below, and when the model decides an encyclopedia lookup would help it calls one — the same way it would read a file or run a search.

It is read-only and local: nothing you ask reaches this site, and the server cannot edit the corpus. The data it reads is a packaged copy of exactly the files published on the Downloads page, laid out the way the build laid them out, with a manifest of SHA-256 checksums that the installer verifies file by file.

Why you would want it¶

The catalog is far too large to hand to a model as context. The server lets a model retrieve — the right entry, the right neighbours, the right evidence — instead of relying on what it half-remembers about a concept. Several of the tools also do things the website cannot:

Search by structure, not by words. search_prime embeds the meta-model of a problem — its domain-stripped structural signature — so a question about supply chains can land on an abstraction first named in ecology. search_plain_language is the everyday-English complement, over the ELI ladder.
Diagnose a problem. search_archetypes_by_problem and get_archetype_applicability work from a problem statement to the solution archetypes whose trigger conditions it meets, showing which conditions are grounded and which are still missing, rather than returning a keyword match.
Go from problem to implementation. find_mechanisms_for_problem traverses problem → archetype → mechanism and returns form-diverse candidates; browse_mechanisms pages the whole registry by controlled family.
Turn the bibliography inside out. get_reference returns a source's record together with every claim in the encyclopedia that rests on it; get_claim_support gives the source behind one sentence; find_related_by_sources finds entries that lean on the same literature — a relatedness signal from evidence rather than editorial judgement.
Measure distance. get_domain_distance scores how far an abstraction is from a target domain, with the nearest and farthest domains for context.
X-ray a document. Give xray_candidates a syllabus, a spec or a paper and it maps the abstractions the text is built on; xray_render draws the result.
Cite precisely. Every entity response carries its version and content hash, so an assistant can say which edition of an entry it is quoting.

A worked pattern: state the problem in your own words, ask the assistant to strip the domain vocabulary into a meta-model, run search_prime on that, then search_archetypes_by_problem on the original statement, and finally get_references on whatever it proposes. get_reasoning_pipeline_guide describes the full nine-step version of this.

What it provides¶

48 tools, grouped by what they answer. The one-line descriptions are the tools' own docstrings — what the model sees.

Search and lookup¶

Retrieval over the prime and domain-specific catalogs, plus direct fetches by slug or catalog id.

Tool	What it does
`search_prime`	Semantic search over prime abstractions, queried with the META-MODEL.
`get_prime`	Fetch a prime entry by slug.
`get_primes`	Batch-fetch several primes in one call (each slug alias-resolved).
`list_primes`	Browse the prime corpus by metadata (search_prime is semantic; this is the deterministic filter/census view).
`search_domain_specific`	Semantic search over the DOMAIN-SPECIFIC abstractions corpus — abstractions whose home-domain vocabulary does NOT travel, kept out of the main prime corpus (allais_paradox, allee_effect, accelerator_effect, ...).
`get_domain_specific`	Fetch a domain-specific abstraction by slug (a separate namespace from primes; this tool always selects the domain-specific namespace even if a future homonym exists).
`list_domain_specific`	Browse the domain-specific corpus by metadata.
`search_abstraction`	Search primes and domain-specific abstractions in one typed namespace.
`get_abstraction`	Fetch a prime or domain-specific record through typed graph identity.
`search_by_facets`	Facet-decomposition retrieval for oblique, multi-structure problems.
`get_catalog_entity`	Resolve a stable typed catalog ID such as P-1356 or M-9858.

Hierarchy and neighbourhood¶

Walks over the typed mixed DAG, the prime-only projection, and the bootstrapped catalog graph.

Tool	What it does
`get_abstraction_lineage`	Walk the canonical typed mixed DAG from either abstraction kind.
`get_abstraction_siblings`	List typed co-children under each shared mixed-DAG parent.
`get_prime_lineage`	Walk the CURATED prime-only compatibility DAG (dist/prime_dag.jsonl — the hand-adjudicated projection, not the auto-bootstrapped graph).
`get_prime_siblings`	List a prime's siblings in the prime-only DAG, grouped by shared parent.
`get_prime_neighborhood`	Return a prime's automatic compatibility-graph neighborhood.
`find_related_primes`	Find primes related to a given prime via the archetype catalog.

Solution archetypes and diagnosis¶

From a problem statement to the archetypes whose trigger conditions it meets — the diagnostic applicability graph, with AND/OR condition sets, groundings and residuals kept explicit.

Tool	What it does
`search_archetypes_by_problem`	Search archetype diagnostic heads and structural conditions.
`get_archetype_applicability`	Return the diagnostic logic that makes an archetype worth examining.
`find_archetypes_for_abstraction`	Find archetypes whose diagnostic logic is grounded by an abstraction.
`find_abstractions_for_archetype`	Return an archetype's trigger and supporting-context abstractions.
`search_archetype`	Semantic search over solution archetypes, queried with the META-MODEL.
`get_archetype`	Fetch the full archetype entry by slug.
`find_archetypes_for_prime`	List historical catalog references from a prime to archetypes.

Components and mechanisms¶

The implementation layer: recurring components and the mechanism registry, browsable by controlled families and reachable from a problem through its archetypes.

Tool	What it does
`browse_mechanisms`	Browse mechanisms through the reviewed discovery classifications.
`search_mechanism`	Hybrid semantic/lexical search for concrete implementation forms.
`get_mechanism`	Fetch a mechanism by slug (or case-insensitive name).
`find_mechanisms_for_archetype`	Return enriched mechanisms that implement one solution archetype.
`find_mechanisms_for_problem`	Traverse problem evidence -> candidate archetypes -> mechanisms.
`find_archetypes_using_mechanism`	List archetypes whose mechanisms include the given mechanism name.
`list_mechanisms`	List mechanisms that appear in at least `min_archetype_count` archetypes.
`list_components`	List components that appear in at least `min_archetype_count` archetypes.
`find_archetypes_using_component`	List archetypes whose components include the given component name.

Learnability (the ELI ladder)¶

Reviewed explanations at five registers and a teaching order over the primes; plain-language retrieval is the everyday-English complement to the structural search above.

Tool	What it does
`search_plain_language`	Find primes from an everyday-English description, not a meta-model.
`get_learning_path`	The reviewed teaching order over primes: where to start, what follows.

References¶

The reference registry as structured records: a source's record with every claim that rests on it, an entry's bibliography, the claim behind one FACT anchor, and bibliographic coupling between entries.

Tool	What it does
`get_reference`	A source's record plus every claim in the encyclopedia resting on it.
`get_references`	An entry's bibliography as structured records instead of markdown footnotes.
`get_claim_support`	The source behind one specific FACT anchor, or every anchored claim in an entry.
`search_references`	Search the registry by author, title, container and year, with facets.
`get_canon`	The works the encyclopedia leans on hardest, by distinct citing entries.
`find_shared_sources`	Which sources two entries have in common, rarest first.
`find_related_by_sources`	Entries leaning on the same literature — bibliographic coupling.
`reference_registry_stats`	Registry size and coverage: works, citations, links, and the facet census.

Domain distance and document x-ray¶

How far an abstraction is from a target domain, and which abstractions a document you supply is built on.

Tool	What it does
`get_domain_distance`	Quantitative distance from an abstraction's home domain to a target domain.
`xray_candidates`	Scan a document's text for candidate abstractions - the retrieval half of the document x-ray.
`xray_render`	Render adjudicated x-ray hits as an overlay on the Abstraction Atlas - the presentation half of the document x-ray.

Corpus and reasoning guide¶

What is loaded, how complete every index is, and the 9-step augmented abstract reasoning pipeline as a structured guide.

Tool	What it does
`corpus_stats`	Return high-level statistics about the loaded corpus.
`get_reasoning_pipeline_guide`	Return the 9-step Augmented Abstract Reasoning Pipeline as a structured guide.

The data it reads¶

The data bundle is the runtime slice of the Downloads page, in one archive:

the five catalog exports — primes, domain-specific abstractions, archetypes, components, mechanisms — with the corpus manifest;
the typed mixed DAG, the prime-only compatibility projection and the bootstrapped catalog graph;
the diagnostic applicability graph and its search documents;
the reference registry (works, citations, aliases);
the learnability export (ELI ladder and teaching order) and the entity version index;
the controlled family vocabularies the website joins at render time;
prebuilt embedding indexes for every semantic tool, so nothing is computed on install;
the Atlas node table used by the document x-ray.

The embedding model is not in the bundle. eoa-mcp fetch-model downloads the quantized ONNX port of BGE-small from its own repository (Qdrant/bge-small-en-v1.5-onnx-Q, Apache-2.0), pinned to a specific revision and verified by hash — it must be the exact model the shipped indexes were built with. Without it the server still runs; semantic tools fall back to lexical matching and say so in every response.

Requirements¶

Python 3.10 or newer (the installer picks the newest 3.10+ it finds; the server is tested on 3.10, 3.13 and 3.14).
About 1 GB of disk: 526 MB of data, ~70 MB of model, and the Python dependencies (mcp, numpy, onnxruntime, tokenizers, PyYAML, jsonschema).
Memory: roughly 0.6 GB after start-up, rising to ~1.3 GB once every index has been touched (the graphs, the reference registry and the applicability layer load on first use).
No GPU. Embedding runs on the CPU through ONNX Runtime; a query takes a fraction of a second.
Network only to install and update — the site for the wheel and the data, Hugging Face for the model. Nothing at query time.
macOS or Linux for the one-line installer; Windows works with the manual steps below.
An MCP client. Any client that can launch a stdio server works; Claude Desktop and Claude Code are shown.

Install¶

One line (macOS, Linux)¶

curl -fsSL https://abstractopedia.org/downloads/eoa-mcp-install.sh | bash

The script asks where to install (default ~/.eoa-mcp), creates a virtual environment there, installs the server, downloads and verifies the data bundle and the model, runs eoa-mcp doctor and then the server's own test-suite against what it just installed, and finishes by printing the configuration to paste into your client. Re-run it any time to update. Read it first if you prefer — it is short.

By hand (any OS, including Windows)¶

python3 -m venv ~/.eoa-mcp/venv
~/.eoa-mcp/venv/bin/pip install https://abstractopedia.org/downloads/eoa_mcp-1.0.6-py3-none-any.whl
~/.eoa-mcp/venv/bin/eoa-mcp fetch-data     # data bundle → ~/.eoa-mcp/data, verified
~/.eoa-mcp/venv/bin/eoa-mcp fetch-model    # embedding model from Hugging Face, verified
~/.eoa-mcp/venv/bin/eoa-mcp doctor         # what is installed, what is missing
~/.eoa-mcp/venv/bin/eoa-mcp self-test      # the packaged test-suite against your install

On Windows use py -3 -m venv %USERPROFILE%\.eoa-mcp\venv and the Scripts\ directory in place of bin/.

Connect a client¶

eoa-mcp config claude-desktop and eoa-mcp config claude-code print these with your real paths filled in.

Claude Desktop — add to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "encyclopedia-of-abstractions": {
      "command": "/Users/you/.eoa-mcp/venv/bin/eoa-mcp",
      "args": [
        "serve"
      ],
      "env": {
        "EOA_DATA_DIR": "/Users/you/.eoa-mcp/data"
      }
    }
  }
}

Claude Code:

claude mcp add encyclopedia-of-abstractions -s user \
    -e EOA_DATA_DIR=$HOME/.eoa-mcp/data -- $HOME/.eoa-mcp/venv/bin/eoa-mcp serve

Any other client: a stdio server with command ~/.eoa-mcp/venv/bin/eoa-mcp, argument serve, and EOA_DATA_DIR in its environment. Restart the client; the tools appear in its tool list. corpus_stats is a good first call.

Updating¶

Data and server are versioned separately. eoa-mcp fetch-data reads eoa-mcp-latest.json, downloads the current edition if yours is older, verifies every file against the bundle's manifest, and swaps it into place atomically — your previous edition is kept beside it as data.previous until the next update. A new server version is a pip install --upgrade of the wheel, or simply re-running the installer. A data edition that needs a newer server says so before downloading anything.

Restart your client (or reconnect the server) after an update: the server loads its data at start-up.

Limits¶

Read-only, single-user, local. There are no editing tools and no hosted endpoint.
Responses are budgeted for a model's context, not for people: get_prime at full verbosity averages ~20 KB, so the tools default to summaries and the assistant should ask for full deliberately.
Semantic search represents negation poorly ("when everyone copies" still surfaces No Copies Allowed); search_plain_language reports this limit rather than hiding it.
Coverage is honest, not complete: corpus_stats reports every index's coverage of the loaded corpus, and a missing optional artifact degrades the tool that needs it with a message saying what to rebuild.
The counts on this page are those of the packaged edition; the live site may be ahead of it between releases.

Downloads¶

File	Size	SHA-256
`eoa_mcp-1.0.6-py3-none-any.whl` — the server	200 KB	`562e32eebec4777e123e517524775457eb5c27cf7b21cbadef817e9fbaa02c0d`
`eoa-mcp-data-2026-10-07.tar.gz` — data edition 2026-10-07, 44 files	144 MB	`ad38894b7cef09ff619b4904e2f2c658afab27d1829b8e60f198bc81baa77685`
`eoa-mcp-latest.json` — release pointer	—	see the Downloads checksum manifest
`eoa-mcp-install.sh` — installer	—	see the Downloads checksum manifest

The same files are listed, with their checksums, under MCP server on the Downloads page.