bounded-tools-mcp

@bounded-systems/bounded-tools-mcp

一个本地、只读的 MCP 服务（以及与之配套的 CLI），用于访问 bounded.tools 的已签名静态 API。

它向任何 MCP 客户端（Claude Desktop、Claude Code 等）公开网站以可验证、内容寻址的 JSON形式提供的部分内容——Web-Build Conformance 报告和 SPDX SBOM——并在返回前，针对网站经 Sigstore 签名的 sha256 清单逐字节验证每个响应。如果客户端将收到的字节与已签名清单不匹配，它就会拒绝返回这些内容。

它通过 stdio 在本地运行——客户端以子进程形式启动它。它没有托管服务，也没有网络监听器，因此保留了网站的静态 / 无攻击面的特性。

通用核心的精简实现

这个包十分精简。所有可复用的机制——验证型 fetch 客户端、sha256 清单与 Sigstore 检查，以及 VerbSpec → MCP（工具 + 资源） / VerbSpec → CLI 投影——都位于 @bounded-systems/static-mcp 中。bounded-tools-mcp 仅提供：

• 动词（src/verbs.ts）——get_conformance、get_sbom，各自只需编写一次，作为 @bounded-systems/verbspec VerbSpec；
• 资源目录（src/catalog.ts）——tools://… 资源；
• 配置值（src/config.ts）——源站和预期的签名者身份；以及
• 入口（src/index.ts）——用于选择接口并将规范交给核心。

src/verbs.ts ─┐
src/catalog.ts ├─▶ buildToolsSpec(config) ─▶ @bounded-systems/static-mcp
src/config.ts ─┘        serveVerifiedStaticMcp(spec, config)   (MCP, stdio)
                        runStaticCli(spec, config, argv)        (CLI)

两种接口，一个定义。 verbspec 会将每个动词投影为一个 MCP 工具和一个 CLI 子命令。MCP 工具和 CLI 命令由完全相同的一组动词提供支持——无需重复定义，也不会产生偏差。

公开的内容（以及未公开的内容）

bounded.tools 是一个静态网站，其可验证接口有意保持精简。这里仅公开网站以已签名、内容寻址的 JSON形式提供的内容——每项内容都会被获取，并针对已签名清单逐字节验证：

提供形式	内容	是否公开
已签名 JSON	api/v1/conformance.json	✅ get_conformance · tools://conformance
已签名 JSON	sbom.spdx.json	✅ get_sbom · tools://sbom
已签名 JSON	site.webmanifest	✅ tools://webmanifest（仅资源）
已签名的 HTML + Markdown	博客（blog/*.html、blog/*.md）	❌ 不是 JSON — 见下文

诚实优先，不盲目扩大接口。 博客确实包含在已签名清单中，但它以 HTML + Markdown 形式提供，而非 JSON 订阅源或单篇文章的 JSON 文档。经过验证的静态核心会获取每项内容并将其解析为 JSON，因此将博客公开为“工具”就意味着要捏造网站实际上并未提供的 JSON 结构。因此，我们选择不公开，而不是伪造。如果 bounded.tools 日后发布已签名的 posts.json（以及每篇文章的 JSON），就能直接加入 list_posts / get_post 动词，方式与 site-mcp 完全相同。

安装 / 运行

需要 Node ≥ 18.17。verbspec 依赖发布在 JSR 上，因此安装时会通过 JSR 的 npm 桥接服务解析该依赖——随附的 .npmrc 设置了 @jsr:registry=https://npm.jsr.io。（在全新的环境中使用时，请将这一行添加到 npm 配置中。）

# MCP server over stdio (what an MCP client launches):
npx -y @bounded-systems/bounded-tools-mcp

# CLI — the SAME verbs, printing the verified JSON:
npx -y @bounded-systems/bounded-tools-mcp get_conformance
npx -y @bounded-systems/bounded-tools-mcp get_sbom

MCP 服务会将就绪信息输出到 stderr（stdout 是 MCP 通道）：

bounded-tools-mcp ready (stdio) → https://bounded.tools; signature mode=off

MCP 客户端配置

{
  "mcpServers": {
    "bounded-tools": {
      "command": "npx",
      "args": ["-y", "@bounded-systems/bounded-tools-mcp"],
      "env": { "BOUNDED_TOOLS_MCP_SIGNATURE_MODE": "warn" }
    }
  }
}

资源

资源 URI	端点	内容
tools://conformance	api/v1/conformance.json	Web-Build 一致性标准报告（HTML / WCAG 2.2 / ARIA）
tools://sbom	sbom.spdx.json	SPDX 软件物料清单
tools://webmanifest	site.webmanifest	W3C Web 应用清单（PWA 站点元数据）

工具 / 命令行命令（只读）

两种界面使用相同的两个动词：

工具 / 命令	参数	返回值
get_conformance	—	Web-Build 一致性报告
get_sbom	—	SPDX 软件物料清单

资源读取和工具结果均包含 _meta.verification 块（相对于清单的路径、源 URL、已验证的 sha256，以及清单签名状态）。CLI 会输出已验证的 JSON；验证失败时会以非零状态退出，且不向 stdout 输出任何内容。

验证 / 信任模型

该站点发布一个签名清单 https://bounded.tools/site.sha256（sha256sum 格式），以及该清单的 Sigstore bundle：site.sha256.sigstore.json。核心会强制执行以下规则：

1. 逐文件哈希检查（始终启用）。 每个进程仅获取一次清单；对于每项资源，获取该资源，对收到的字节计算 SHA-256，并要求摘要与清单条目一致。文件被篡改、CDN 边缘节点数据过期或遭遇 MITM，都会导致摘要不匹配，进而返回 VerificationError，而非响应。清单中不存在的路径同样会被拒绝。
2. 清单签名检查（可选）。 BOUNDED_TOOLS_MCP_SIGNATURE_MODE=warn|require 会根据部署工作流身份（…/bounded-systems/site/.github/workflows/deploy.yml@refs/heads/main，OIDC 发行者为 https://token.actions.githubusercontent.com）验证 Sigstore bundle。这与 https://bounded.tools/provenance.json 中发布的无密钥身份相同。

配置

变量	默认值	含义
BOUNDED_TOOLS_MCP_BASE_URL	https://bounded.tools	提供站点 + API + 清单的源
BOUNDED_TOOLS_MCP_SIGNATURE_MODE	off	off | warn | require
BOUNDED_TOOLS_MCP_SIGNER_IDENTITY	deploy workflow SAN	预期的 Sigstore 证书身份
BOUNDED_TOOLS_MCP_SIGNER_ISSUER	GitHub Actions OIDC	预期的 Sigstore OIDC 发行者
BOUNDED_TOOLS_MCP_FETCH_TIMEOUT_MS	15000	每次请求的获取超时时间

开发

npm install         # resolves @bounded-systems/static-mcp (npm) + verbspec (JSR bridge)
npm run build       # tsc → dist/
npm test            # node --test via tsx (server + CLI; no network)
npm run typecheck
node scripts/headless-check.mjs   # live end-to-end against bounded.tools

发布

一个标签即可将同一版本镜像发布到三个注册表。 推送 v* 标签会运行 publish.yml，并行发布到：

#	注册表	标识符	身份验证
1	npm	@bounded-systems/bounded-tools-mcp	可信发布（OIDC）+ 来源证明
2	JSR（镜像）	@bounded-systems/bounded-tools-mcp	无令牌 OIDC（npx jsr publish）
3	MCP Registry	io.github.bounded-systems/bounded-tools-mcp	GitHub-OIDC 命名空间身份验证（mcp-publisher）

没有长期有效的密钥——每个注册表都使用作业的短期 GitHub Actions OIDC 令牌（id-token: write）进行身份验证。npm 需要 npm ≥ 11.5（工作流会升级 npm 以确保满足这一要求）。mcp-registry 作业与 npm 作业相互独立（依赖项为 needs: verify，而非 needs: npm）：注册表通过读取已发布 npm 包中的 mcpName 字段来证明包的所有权，因此可以独立运行或重试。

重要

版本必须保持一致。 发布版本号需在四处保持一致：package.json、deno.json、server.json 和 v<version> git 标签。工作流的 verify 作业会在发现任何不一致时直接中止整个发布，因此 npm 和 JSR 的版本绝不会出现偏差。MCP Registry 还要求 package.json 包含 "mcpName": "io.github.bounded-systems/bounded-tools-mcp"（它会读取已发布 npm 包中的此字段来证明所有权）。

一次性设置（维护者）——请在首个标签发布前完成

(a) npm — 可信发布方（在 npmjs.com 上）

1. 以 @bounded-systems 作用域所有者的身份登录。
2. 打开 @bounded-systems/bounded-tools-mcp 包页面 → Settings → Trusted Publisher。对于全新包，可能需要先手动发布一次 0.1.0（或创建该包），然后再切换到可信发布。
3. 选择 GitHub Actions，并填写：
   • 组织 / 用户： bounded-systems
   • 仓库： bounded-tools-mcp
   • 工作流文件名： publish.yml
   • 环境： （留空）
4. 保存。不会生成或存储任何令牌。

(b) JSR — 创建并关联包（在 jsr.io 上）

1. 使用 GitHub 登录 jsr.io，并在 @bounded-systems 作用域下创建包 @bounded-systems/bounded-tools-mcp。
2. 打开该包的 Settings 选项卡 → 在 GitHub Repository 下输入 bounded-systems/bounded-tools-mcp，然后点击 Link。关联仓库后，此工作流即可进行无令牌 OIDC 发布。

(c) MCP Registry — 无需预先授权

io.github.bounded-systems/* 命名空间会通过 GitHub OIDC 自动授权：由于此仓库位于 github.com/bounded-systems 下，mcp-publisher login github-oidc 会通过 Actions 运行本身证明所有权。

发布版本（单条命令）

# 1. Bump the version in ALL of: package.json, deno.json, server.json. Commit.
# 2. Tag with the SAME version and push — this is the only command:
git tag v0.1.0 && git push origin v0.1.0

本地试运行（验证但不发布）

npm pack --dry-run                                   # npm tarball contents
npx --yes jsr publish --dry-run --allow-slow-types   # JSR (or: deno publish --dry-run --allow-slow-types)
mcp-publisher validate ./server.json                 # MCP Registry schema check

bounded-tools-mcp 依赖 @bounded-systems/static-mcp；该核心包独立发布（通过其自身的 v* 标签发布到 JSR + npm），并需在发布此标签前完成。

许可证

MIT — 参见 LICENSE。