taxonomy-mcp

An MCP (Model Context Protocol) server that exposes Marble's open skill taxonomy (os-taxonomy) as queryable tools for AI agents. The taxonomy is a typed DAG of 1,590 micro-topics spanning ages 4-15, connected by 3,221 hard/soft prerequisite edges, each with a human-written reason, per-topic evidence criteria, a templated assessment prompt, and precomputed centrality.

This repository is kylelynch/taxonomy-mcp. The upstream dataset lives at withmarbleapp/os-taxonomy.

The server is stateless, read-only, and requires zero secrets. It holds no server-side accounts, mastery records, or database of any kind. Tools that need to know what a learner already knows (frontier_for, path_to) take a list of mastered topic ids as an argument, so the calling agent owns all state. The data is vendored into the repo and baked into the Docker image, so the server has no runtime network dependencies and every deploy is reproducible from the repo alone.

Tools

All nine tools are read-only and validated with zod.

Related MCP server: okfy

Resources

Two resource families are also exposed:

• taxonomy://clusters/{subject} - one resource per subject that has clusters, serving parent-friendly summaries of what children learn, grouped by domain and starting age.

• taxonomy://about - dataset provenance, taxonomy version, upstream commit, license, and attribution.

Local quickstart

Install dependencies once:

npm install

Run the server locally over stdio (useful for local MCP clients and manual testing):

npm run dev

To wire it into Claude Code instead, this repo already ships a .mcp.json pointing at the stdio entry, so Claude Code will pick it up automatically when you open the project.

To run the streamable-HTTP transport locally on port 3002:

npm run dev:http

GET /healthz returns {status, version, taxonomyVersion, topics, edges}. The MCP endpoint is POST /mcp.

Client configuration

Once the server is deployed (see Deployment below), point any MCP-capable client at the hosted endpoint. For Claude Code:

claude mcp add --transport http taxonomy https://taxonomy.kylelynch.us/mcp

Data provenance and license

The code in this repository is licensed under MIT; see LICENSE.

The curriculum data in data/ is not covered by that license. It is vendored, unmodified, from Marble's os-taxonomy project and remains the property of Marble (Generative Spark, Inc.). The database structure is licensed under the Open Database License (ODbL) 1.0, and the authored content within it is licensed under CC BY-SA 4.0. Full provenance details, including the upstream commit and vendoring date, live in data/UPSTREAM.md. Attribution to Marble also appears in the taxonomy://about MCP resource and in the taxonomy_overview tool output, so agents surfacing this data can pass attribution along.

Refreshing the data

The vendored data is not fetched at runtime. To pull a fresh copy from upstream, validate it, and rewrite data/ and data/UPSTREAM.md:

npm run update-data

The script fetches the latest files from the upstream GitHub repository, verifies each file's sha256 and byte count against the fetched manifest, validates every file against the vendored JSON Schemas, and runs the same referential-integrity checks the server uses at boot. Review the diff and commit the result; the server never talks to the network at boot or during a request.

Deployment

The server is designed to run as a Docker container, built from the multi-stage Dockerfile in this repo, with the taxonomy data baked into the image. It is deployed to Kyle's droplet behind nginx at https://taxonomy.kylelynch.us/mcp. For the full build, deploy, and rollback procedure, see docs/deploy-runbook.md.