tc39-mcp

🤖

Spec lookup for AI agents

Any MCP client (Claude Code, Claude Desktop, Cursor, MCP Inspector) gets `clause.get`, `spec.search`, `spec.crossrefs`, and 16 more tools — structural JSON answers grounded on real spec text instead of grep'd HTML. Every citation resolves to a specific clause id at a specific SHA.

🎯

19 tools across 5 namespaces

clause.get / list / outline · spec.about / snapshots / search / global_search / crossrefs / diff / history / symbol_resolve / tables / grammar / sdo_index / well_known_intrinsics · test262.search / get · proposal.list / get

📦

Two specs, every released annual edition

ECMA-262 (es2016 → latest + main) and ECMA-402 (main + most recent candidate). Every clause carries its upstream SHA and fetched_at timestamp — full table on the Snapshots page.

✈️

Offline-first by default

The stdio transport (`npx tc39-mcp`) ships every parsed snapshot in the tarball. Once installed, every tool call is served from local disk — no network round-trip, no leakage of which clause you're reading, works on planes. The hosted Worker is the HTTP alternative.

🔌

Three ways to run it

Local stdio via `npx tc39-mcp` (the offline default), a global CLI, or the hosted Cloudflare Worker over HTTP. Same MCP protocol, three transports.

🔄

Auto-refreshing

A scheduled CI workflow checks upstream tc39/* mains every 4 hours, bumps PATCH + republishes whenever anything moved. Stay current without lifting a finger.

🧪

Deterministic over pinned data

Every response is a function of static parsed JSONs. Same inputs → same bytes out, reproducible across server versions.

🏗️

Production-shaped

LRU-bounded memory, tiered rate limiting (anonymous 30/60s/IP, sponsors 300/60s/key), structured per-request logging, post-deploy smoke testing, historical SHA addressing via `at:` on the hosted Worker.

Install + run

stdio (npx, recommended)global CLIhosted Worker

# Wire into Claude Code via .mcp.json:
{
  "mcpServers": {
    "tc39": { "command": "npx", "args": ["tc39-mcp"] }
  }
}

npm i -g tc39-mcp
tc39-mcp                     # reads stdio

# .mcp.json:
{
  "mcpServers": {
    "tc39": {
      "type": "http",
      "url": "https://tc39-mcp.<account>.workers.dev/mcp"
    }
  }
}

What it's for

Agents and tooling that need to consult the JS spec — clause.get + spec.search instead of grepping spec.html.

Reading the spec offline / in a tool — full structured access without scraping or hitting a 4 MB HTML file.

Cross-version analysis — spec.diff between any two editions back to ES2016; spec.history walks the upstream git log.

Cross-spec analysis — spec.crossrefs { include_cross_spec: true } resolves references that point from ECMA-262 into ECMA-402 (or vice versa). Useful for queries like "every 262 op that calls into Intl."

AOID → clause-id lookup — spec.search ranks aoid-exact matches first.

Scope

Deliberately narrow:

Read-only. No tool mutates anything. Every response is a deterministic function of pinned spec data.

No execution. No spec semantics evaluated; no JS run. Pure parsed-JSON lookup.

No auth. Read-only + no execution = safe to host publicly.

No corpus vendoring. test262 search works against an index built from a local checkout (~13 MB JSON).

These constraints are the design — they're what make the server small, fast, and trivially deployable behind a Cloudflare Worker without sandboxing concerns.

tc39-mcpStructured MCP for the TC39 specs