thatmgmt-mcp

thatmgmt-mcp

一个封装 ThatMgmt 域名 API 的 MCP（Model Context Protocol）服务。**可通过任意 MCP 客户端检查可用性、获取锁定价格报价并准备注册，无需为公共工具注册。**租户工具（投资组合、建议、试运行规划）需要 API 密钥才能使用。所有操作都不会盲目执行：API 不提供执行端点，因此此服务只负责规划和报价，绝不购买。

基础 API：https://api.thatmgmt.com 规范：openapi.json 机器文档：llms-full.txt

已验证的声明

下列每项声明都有 test/ 中的测试佐证——完全模拟，不访问网络、不需要密钥，也不会产生费用。欢迎自行运行：npm test（47/47 项通过）。

声明	佐证数据
共有 13 个 MCP 工具，其中恰好 4 个是公共工具	test/tools.test.js 中的 “exposes the expected tool set” 断言全部 13 个名称；“exactly the zero-signup tools are marked public” 指定 tmgmt_health、tmgmt_capabilities、domains_check_availability、domains_get_quote
没有 API 密钥时，租户工具会默认拒绝请求	test/server.test.js 中的 “refuses tenant tools without an API key”：isError 为 true，消息中包含 TMGMT_API_KEY
公共工具不会发送 Authorization 请求头	test/server.test.js 中的 “public reads work with no API key and send no Authorization header” 断言所有 4 个公共路由都没有此请求头
错误消息绝不会泄露 API 密钥	test/thatmgmt.test.js 中的 “never leaks the API key in error messages”：密钥会替换为 [REDACTED]
对可重试的 GET / 429 / 5xx 恰好重试一次；对 400 或不可重试的 503 不重试	test/thatmgmt.test.js：收到 429 后调用 2 次 fetch；收到 400 和标记为不可重试的 503 时各调用 1 次
未提供报价 ID、未设置 approved: true 或 ID 不匹配时，审批关卡都会拒绝	test/tools.test.js 中的审批关卡用例
无效域名会在任何网络调用前被拒绝	test/tools.test.js 中的 “callTool rejects an invalid domain before any network call”：fetch 调用次数为 0
对不可用域名报价时会明确说明，而不是只返回 {available:false}	test/tools.test.js 中的报价整形用例
转移试运行会传递 authCodePresent，绝不传递原始授权码	test/tools.test.js 中的 “passes authCodePresent (never the raw code)”

快速开始

git clone https://github.com/thingscorp/thatmgmt-mcp.git && cd thatmgmt-mcp
npm install
node demo-agent-run.mjs   # real server over stdio, stub API, zero signup

演示会在无网络、无密钥的情况下，通过 tmgmt_health → 可用性检查 → 锁定报价 → 准备注册，调用真实服务。实时模式（仅限公共工具，只读）：node demo-agent-run.mjs --live。

安装

从 npm 安装（无需克隆）：

npx -y @thatmgmt/mcp

从源码安装（Node 18+）：

git clone https://github.com/thingscorp/thatmgmt-mcp.git thatmgmt-mcp
cd thatmgmt-mcp
npm install
npm test

添加到 MCP 客户端（Claude Code .mcp.json、Cursor、Replit）：

{
  "mcpServers": {
    "thatmgmt": {
      "command": "npx",
      "args": ["-y", "@thatmgmt/mcp"],
      "env": { "TMGMT_API_KEY": "your-thatmgmt-api-key" }
    }
  }
}

只有租户工具需要密钥；公共读取无需密钥。

发布流程已自动化：推送版本标签（例如 v0.2.2）会运行 Publish to npm 工作流（通过 NPM_TOKEN 密钥执行 npm publish），以及 Publish to MCP Registry 工作流（验证 server.json，通过 GitHub OIDC 发布 io.github.thingscorp/thatmgmt-mcp）。标签必须与 package.json 和 server.json 中的 version 一致。

用法

每个工具描述中都写明了两步购买流程，确保 Agent 先向用户展示价格：

1. 报价。 调用 domains_get_quote。它会返回锁定价格：wholesaleCents、按项列出的 1% 抽成（platformCutCents、platformCutBasisPoints）和 totalCents。无需密钥。向用户展示这些信息。
2. 制定计划。 调用 domains_prepare_registration（需要 TMGMT_API_KEY）。它会返回经过安全检查的计划，但绝不会执行任何操作。

报价包含批发价、固定 1% 平台抽成和总价——没有订阅，也没有分级套餐。模拟测试装置中的数据格式如下：wholesaleCents: 1299、platformCutCents: 13、platformCutBasisPoints: 100、totalCents: 1312。

此服务无法执行的操作

ThatMgmt API 不提供任何执行端点。购买、续订、转移和 DNS 变更都不会由 API 执行；API 只会返回经过验证的计划和预检结果。因此，此服务无法注册、续订或转移域名，也绝不会声称已执行这些操作。src/approval.js 中包含审批关卡，供未来的执行工具使用（传回报价 ID，并明确设置 approved: true，否则会拒绝调用）——该功能现已实现并经过测试，确保执行路由上线时安全设计已准备就绪。

当前版本：0.2.2（只读公共工具及经过验证的计划）。执行工具计划在 0.3.0 版本中推出。

配置

仅使用环境变量——没有标志，也没有配置文件：

变量	必需	默认值	用途
TMGMT_API_KEY	仅租户工具需要	—	租户 API 密钥，以 Bearer 令牌形式发送。绝不记录日志；错误信息中会脱敏。
TMGMT_BASE_URL	否	https://api.thatmgmt.com	覆盖 API 基础 URL。
TMGMT_TIMEOUT_MS	否	30000	每个请求的超时时间，单位为毫秒。

对于瞬时故障（网络错误、超时、429、可重试的 5xx），无副作用的调用会重试一次；服务绝不会重试任何可能导致资金变动的操作。

API 参考

此服务通过 MCP stdio 暴露的 13 个工具，均严格按照 src/tools.js 中的定义。每个工具都对应 在线 OpenAPI 规范中的实际路由；没有虚构的端点。

工具	功能	API 路由	是否需要密钥
tmgmt_health	存活状态检查	GET /health/live	否
tmgmt_capabilities	发现无需身份验证的公共功能	GET /v1/public/capabilities	否
domains_check_availability	检查域名是否可用	GET /v1/public/availability	否
domains_get_quote	锁定价格报价：批发价 + 按项列出的 1% 抽成 + 总价（第 1 步）	GET /v1/public/quote	否
domains_suggest	推荐替代名称	GET /v1/domains/suggestions	是
domains_prepare_registration	经过安全检查的计划，不会执行操作（第 2 步）	GET /v1/domains/prepare-registration	是
domains_list	列出组合中的域名	GET /v1/domains	是
domains_dns	查看域名的 DNS 记录	GET /v1/domains/{resourceId}/dns	是
portfolio_health	组合健康状况摘要	GET /v1/portfolio/health	是
portfolio_renewal_risk	续订风险视图	GET /v1/portfolio/renewal-risk	是
portfolio_exceptions	按优先级排列的异常队列	GET /v1/portfolio/exceptions	是
orders_dry_run	包含按项定价的完整订单计划，不会导致资金变动	POST /v1/orders/dry-run	是
offerings	服务项目覆盖矩阵	GET /v1/offerings	是

公共工具绝不会发送 Authorization 标头，也不会索要密钥。没有密钥时，租户工具会返回类似 401 的拒绝响应；服务会提示你设置 TMGMT_API_KEY。

面向 Agent

skills/thatmgmt/SKILL.md 是此服务的 Agent 技能文件，其中介绍了何时使用、工具列表和两步购买流程。将它提供给你的 Agent，即可快速上手。

参与贡献

请参阅 CONTRIBUTING.md。

许可证

MIT。请参阅 LICENSE。