CHA2A MCP API 文档

CHA2A MCP API 文档（mcp-api.md）

> 版本：v0.1 ｜ 2026-08-28 ｜面向开发者/AI agent

> MCP server：@wwumit/cha2a-mcp（npm）｜ Base：https://compliancehub.cn

> 本页是 MCP 工具契约；完整 REST 参考见 api-docs.html

---

一、接入（30 秒）

任意 MCP 客户端（Claude Desktop / Cursor / WorkBuddy 等）配置：

{
  "mcpServers": {
    "cha2a": {
      "command": "npx",
      "args": ["-y", "@wwumit/cha2a-mcp"],
      "env": { "CHA2A_BASE": "https://compliancehub.cn" }
    }
  }
}

连接后即获得 6 个只读工具：resolve_number / query_trust / verify_credential / verify_agent_sig / lookup / verify_artifact。

二、工具一览

工具	用途	只读
`resolve_number`	号码 → agent DID + 信任等级（寻址/门禁）	✅
`query_trust`	DID → 等级/状态/撤销（通信前验证）	✅
`verify_credential`	凭证/证据查询（可追溯审计）	✅
`verify_agent_sig`	出站签名验签（防冒充）	✅
`lookup`	DID → 名下号码（名片）	✅
`verify_artifact`	AI 资产内容完整性验证（指纹+背书+等级+撤销，v0.3）	✅

> 全部工具只读——本 MCP server 不提供任何写操作（注册/撤销/入账请走 REST + admin key）。

三、工具详细

1. resolve_number

参数：number（string，E.164 号码，+ 可省略，如 86951230001）
返回：

{
  "registered": true,
  "number": "+86951230001",
  "agentDid": "did:cha2a:agent:dshlib",
  "level": 2,
  "levelName": "L2 source",
  "name": "dshlib",
  "revoked": false
}

未注册返回：{"registered": false, "number": "...", "suspicious": true}

2. query_trust

参数：did（string，did:cha2a:* 格式）
返回：

{
  "registered": true,
  "active": true,
  "level": 2,
  "levelName": "L2 source",
  "revoked": false,
  "metadata": { "name": "dshlib", "author": "演示操作员" }
}

3. verify_credential

参数：did（string）；可选 predicateType（string，按类型过滤）
返回：

{
  "subject": "did:cha2a:agent:dshlib",
  "count": 1,
  "credentials": [
    {
      "id": "cred-...",
      "predicateType": "https://in-toto.io/attestation/test-result/v0.1",
      "verifier": "did:cha2a:verifier:dshlib",
      "result": "passed",
      "checkedAt": "2026-08-20T..."
    }
  ]
}

4. verify_agent_sig

调用：POST（body JSON，非 GET）
参数：did（string）、signature（string，base64）、payload（string）；可选 timestamp（string）
返回：{"ok": true, "did": "did:cha2a:agent:xxx"}（验签失败 ok: false）

5. verify_artifact（v0.3 内容完整性验证）

调用：POST（body JSON）
参数：subject（string，did:cha2a:package:* 或 did:cha2a:skill:*）、contentHash（string，SHA-256/SHA-512，hex 或 base64 integrity 格式）
返回：{ subject, registered, matches, attested, level, levelName, revoked, verdict: PASS/FAIL, basis: [...] }
判定（对齐规范 §4.6）：内容指纹（L1）匹配 + 发行背书（L3，content-integrity 凭证）+ 等级≥1 + 未撤销（fail-closed）

6. lookup

参数：did（string）
返回：{"did": "did:cha2a:agent:dshlib", "numbers": ["+86951230001", "+86951230002"]}

四、错误处理

情形	行为
参数非法（number/did 格式错误）	返回工具错误（`isError: true` + 错误信息）
registry 不可达	返回错误（不静默）——调用方可重试
未注册/不在簿	返回 `registered: false`（非错误，属正常结果）

五、使用示例（agent 视角）

场景：通信前门禁验证

1. resolve_number("86951230001")
   → { registered: true, agentDid: "did:cha2a:agent:dshlib", level: 2, revoked: false }
2. query_trust("did:cha2a:agent:dshlib")
   → { level: 2, levelName: "L2 source", revoked: false }
3. （可选）verify_credential("did:cha2a:agent:dshlib")
   → 查看验证证据
⇒ level ≥ 2 且未撤销 → 放行；否则拒绝

六、信任等级（L0-L4）

等级	名称	语义
L0	未认证	未声明
L1	integrity	身份锚定密钥验签（#agent-key，出站签名可验）
L2	source	归属绑定（owner-binding + 号段授权）
L3	issuance	背书链（发行方/验证方签发）
L4	ecosystem	多方独立验证（预留）

---

*开放契约，欢迎任何平台接入。REST 全端点参考：https://compliancehub.cn/api-docs.html*