tc39-mcp

tc39-mcp

📖 文档：mcp.xyzzylabs.ai/tc39 — 快速入门 · 工具 · 操作手册 · 版本 · 架构 · 托管

独立项目——并非 Ecma International 或 TC39 的官方出版物。读取公开发布的 ECMAScript 规范（ECMA-262 + ECMA-402）。

为支持 MCP 的 AI Agent 提供对 JS 规范的结构化访问。 任何支持 Model Context Protocol 的客户端都可以调用 clause.get sec-tonumber，并获取解析后的 JSON（算法 步骤以独立数组表示，交叉引用以 ID 表示，签名以类型化值 表示），而不是拿到一个 4 MB 的 spec.html 再用 grep 搜索。工具涵盖 ECMA-262 （核心语言）和 ECMA-402 （Intl API）：条款、算法步骤、双向交叉引用、版本差异、 上游 git 历史、test262 搜索、提案查询。每个响应都固定到 特定上游提交的 SHA，因此 Agent 引用的内容都可复现。

快照通过本地缓存 → 托管 Worker → 内置备用数据链进行解析。stdio 传输（npx tc39-mcp） 在缓存未命中时会从托管的 Cloudflare Worker 获取每个快照， 将其写入 ~/.cache/tc39-mcp/，之后从磁盘提供服务——只有当 本地副本的存放时间超过约 4 小时，才会重新验证（发送带条件的 If-None-Match 请求）。npm 包还内置了这两份规范的最新稳定版 + main 版本，以及 test262 和提案索引；当 Worker 无法访问时，会直接从软件包提供这些内容（离线备用数据——不会写入缓存）。托管的 Worker 也是一种 HTTP 替代方案，适用于需要共享网络 端点的场景；其 R2 数据每隔约 4 小时从上游刷新。

安装并首次调用

将其接入任意 MCP 客户端——stdio 启动命令在所有客户端中都相同， 区别仅在于配置文件：

{
  "mcpServers": {
    "tc39": { "command": "npx", "args": ["tc39-mcp"] }
  }
}

也可以全局安装——运行 npm i -g tc39-mcp，然后运行 tc39-mcp。

首次运行会下载 npm 包（其中内置了最新稳定版 + main 版本，以及提案和 test262 索引）。首次调用某个快照时，会从托管的 Worker 获取该快照并将其缓存到本地；后续调用从磁盘提供服务， 只有超过约 4 小时的新鲜度窗口后才会向 Worker 重新验证。 如果 Worker 无法访问，内置版本仍可离线响应。然后在客户端中输入：

使用 clause.get 读取 sec-tonumber 并向我展示步骤

你应该会看到结构化 JSON 响应：

{
  "meta": {
    "id": "sec-tonumber",
    "aoid": "ToNumber",
    "title": "ToNumber ( argument )",
    "number": "7.1.4",
    "kind": "op"
  },
  "signatureRaw": "ToNumber ( _argument_: an ECMAScript language value, ): either a normal completion containing a Number or a throw completion",
  "algorithms": [
    { "steps": [
        { "text": "If _argument_ is a Number, return _argument_." },
        { "text": "If _argument_ is either *undefined* or a Symbol, throw a *TypeError* exception." },
        { "text": "If _argument_ is *null*, return *+0*<sub>𝔽</sub>." },
        "..."
    ]}
  ],
  "crossrefs": ["sec-tonumber-applied-to-the-string-type", "..."]
}

五分钟快速演练：docs/getting-started.md。

托管 HTTP

让客户端连接到托管的 Cloudflare Worker，而不必运行 本地子进程——使用相同的 MCP 协议，无需安装：

{
  "mcpServers": {
    "tc39": {
      "type": "http",
      "url": "https://mcp.xyzzylabs.ai/tc39/mcp"
    }
  }
}

每个 IP 的流量限制为 30 req/min。

擅长之处

• 让 Agent 在不产生幻觉的情况下推理规范。 结构化 JSON 答案以真实规范文本为依据： 步骤编号、交叉引用目标、签名形式、版本差异、一致性测试。任何引用都能解析到特定 SHA 上的具体条款 ID，便于验证和复现。
• 根据提示找到所需条款。 spec.search 会优先排列 AOID 完全匹配项；spec.symbol_resolve 可解码 [[Prototype]] / %Object.prototype% / ~enumerate~。
• 双向追踪引用。 spec.crossrefs 会返回某条款引用的内容，以及引用该条款的内容。通过 AOID 增强处理，步骤文本中的普通提及也会计入，而不只是 <emu-xref> href。 include_cross_spec 可解析 262 ↔ 402 之间的跳转。 （Cookbook 配方 1。）
• 比较版本并追踪文本变更。 spec.diff 可比较 ES2016 以来的任意两个版本；spec.history 可通过 pickaxe 搜索遍历上游 git 日志。 （Cookbook 配方 2。）
• 查找条款对应的 test262 覆盖情况。 test262.search 使用前缀匹配的 esid:，一次调用即可找到 sec-tonumber 和 sec-tonumber-applied-to-the-string-type。
• 将提案映射到规范。 proposal.list / proposal.get 基于 tc39/proposals 的结构化索引，涵盖 ECMA-262 和 ECMA-402（Intl）提案，可按 spec 筛选。与规范保持相同的 4 小时刷新周期。
• 本地缓存，内置回退（stdio）。 快照缓存到 ~/.cache/tc39-mcp/ 后，工具调用会从磁盘提供，仅在约 4 小时的新鲜度窗口过后才会向托管 Worker 重新验证（使用携带 R2 对象键而非条款 ID 的条件请求 If-None-Match）。当 Worker 无法访问时，内置版本仍可离线响应。托管 Worker 则是适用于共享／多租户场景的 HTTP 替代方案。

工具（5 个命名空间，共 19 个）

目标	工具
验证当前提供的内容	spec.about · spec.snapshots
阅读特定条款	clause.get
根据名称／现象查找条款	spec.search · spec.global_search
解析 [[X]] / %X% / ~X~ 表示法	spec.symbol_resolve
浏览／查看大纲	clause.list · clause.outline
比较版本／提交历史	spec.diff · spec.history
遍历引用（入向和出向）	spec.crossrefs
阅读结构化表格	spec.tables
检查语法	spec.grammar · spec.sdo_index
枚举众所周知的内置对象	spec.well_known_intrinsics
查找一致性测试	test262.search · test262.get
查询提案	proposal.list · proposal.get

完整参考（输入架构、输出类型、每个工具的调用示例）：docs/tools.md — 自动根据架构生成，确保内容始终与之同步。

规范与版本

每个规范读取工具都接受 spec（"262" 或 "402"，默认为 "262"）和 edition（默认为 "latest"）。

• ECMA-262：es2016 – es2026、main。（ES5 / ES5.1 / ES6 没有上游标签，因此不受支持。）
• ECMA-402：es2016 – es2026、main。（402 将每个年度版本发布为 esYYYY 分支，而非标签；获取步骤会以相同方式解析分支或标签。）
• 别名：latest 会根据规范确定版本（每个规范对应当前稳定版本，当前为 es2026）。draft / next 在两者中都指向 main。

完整表格及添加新版本的说明：docs/editions.md。

自托管快照

stdio 服务会从公开托管的 Worker 获取快照 （缓存 → Worker → 内置回退），在严格限制出站流量的网络上，它会 回退到内置版本，无法访问其他版本。通过 TC39_MCP_BASE_URL 覆盖 基础 URL，将其指向私有镜像 ——适用于严格限制出站流量的网络、隔离环境，或 使用自托管 Worker 运行：

TC39_MCP_BASE_URL=https://my-mirror.example.com npx tc39-mcp

端点只需提供相同的键结构 （spec-<spec>-<edition>.json、test262-index.json、 proposals-index.json）——普通静态文件服务器即可。如果端点 返回 ETag，服务会使用 If-None-Match 重新验证 （开销很低的 304）；如果没有，缓存副本过期时就会重新获取完整对象。 要填充镜像，请针对本地检出版本运行 npm run parse（见下文），并将 build/*.json 上传到任意存储桶。

缓存位于 $XDG_CACHE_HOME/tc39-mcp（如果未设置 XDG_CACHE_HOME，则位于 ~/.cache/tc39-mcp）。

从源代码构建（贡献者）

最终用户无需执行此操作——npm 包和上文介绍的托管 Worker 是受支持的使用方式。本节适用于开发服务本身。

git clone https://github.com/xyzzylabs/tc39-mcp
cd tc39-mcp
npm install
npm run fetch-spec               # ~2 min, ~150 MB — both specs at every supported edition
npm run parse                    # spec.html → build/spec-<spec>-<edition>.json
npm run fetch-test262            # optional, enables test262.* (~300 MB)
npm run build-test262-index
npm run fetch-proposals          # optional, enables proposal.* (~50 MB)
npm run build-proposals-index
npm run mcp                      # start the stdio MCP server against your source

将 MCP 客户端指向本地源代码，而不是已发布的二进制文件：

{
  "mcpServers": {
    "tc39": {
      "type": "stdio",
      "command": "npm",
      "args": ["run", "--silent", "mcp"],
      "cwd": "/abs/path/to/tc39-mcp"
    }
  }
}

--silent 会阻止 npm 的生命周期横幅输出到 stdout，确保 MCP 客户端收到干净的 JSON-RPC 数据流。

文档

托管于 mcp.xyzzylabs.ai/tc39 ——支持搜索、适合暗色模式，并在每次刷新时自动重建，因此 /snapshots 始终反映最新的 SHA。

仓库内文档（也可在 GitHub 上浏览）：

• docs/getting-started.md — 安装 → 配置 → 首次调用 → 验证。五分钟即可完成。
• docs/tools.md — 每个工具、每个字段、每个 示例。根据源代码自动生成。
• docs/cookbook.md — 多工具使用方案： 跨规范查询、文本漂移跟踪、语法/SDO 交叉引用、test262 覆盖率、提案到条款的映射。
• docs/editions.md — 支持的版本 + 别名解析。
• docs/architecture.md — 数据管道、 解析器、缓存、内存模型。
• docs/deployment.md — 本地 stdio、npm CLI、托管 Cloudflare Worker、刷新模型、可观测性。
• CONTRIBUTING.md — 哪些类型的更改 容易合并，哪些不会。
• SECURITY.md — 威胁模型 + 负责任的 漏洞披露。
• CHANGELOG.md — 版本历史 + 自动刷新 约定。

隐私政策

tc39-mcp 是只读的规范查询服务。stdio 传输 （npx tc39-mcp）不会发送遥测数据，也不会传输你的 查询内容——缓存未命中或过期时会从托管 Worker 获取快照， 其他情况下则从本地磁盘提供；这些获取请求 携带的是 R2 对象键，绝不会携带条款 ID 或工具参数。托管的 Cloudflare Worker 只会收集标准 请求元数据（用于速率限制的 IP、时间戳、请求 标头）；它不会记录请求正文、设置 Cookie，也不会与第三方共享 数据。

完整政策：mcp.xyzzylabs.ai/tc39/privacy

如有隐私相关问题，请在 GitHub 上创建带有 privacy 标签的问题。

许可证

MIT