atlas-mcp

atlas-mcp

作为 MCP 服务，为 AI Agent 提供操作前授权。

Agent 删除数据、部署或花钱之前，会先询问 Atlas。Atlas 会根据签名委托链检查请求，并通过回执返回 permit、deny 或 escalate。操作完成后，Agent 会通过 atlas_commit_effect 报告实际发生的情况。每一步都会写入采用哈希链并由 ML-DSA-65 签名的审计日志。

$ npx -y @corpussanctum/atlas-mcp demo

  You (alice) delegate to claude: database work in STAGING only.

  Claude: delete rows in staging
    -> PERMIT    rcpt_ec14…  authorized by 1-link delegation chain from user:alice

  Claude: delete rows in PRODUCTION
    -> DENY      rcpt_876f…  effect targets environment 'production';
                             delegated authority (grant grt_c9c8…) only permits staging

  Claude: write to staging (grant says writes need a human)
    -> ESCALATE  rcpt_a8d7…  action 'db.write' requires human approval

快速入门（5 分钟）

1. 注册服务。

Claude Code：

claude mcp add atlas -- npx -y @corpussanctum/atlas-mcp

Claude Desktop（claude_desktop_config.json）或任何 MCP 客户端：

{ "mcpServers": { "atlas": { "command": "npx", "args": ["-y", "@corpussanctum/atlas-mcp"] } } }

Codex（~/.codex/config.toml）：

[mcp_servers.atlas]
command = "npx"
args = ["-y", "@corpussanctum/atlas-mcp"]

2. 委托权限。 你作为主体，向 Agent 授予权限：

npx -y @corpussanctum/atlas-mcp grant --principal user:alice --subject agent:claude \
  --allow 'db.*' --env staging --escalate db.write --ttl-hours 8
# prints the grant JSON; note its "id" (grt_…)

3. 告知 Agent 规则。 将以下内容添加到 CLAUDE.md / AGENTS.md（参见 examples/CLAUDE.md.snippet）：

在执行任何破坏性操作、生产环境操作、部署或支出操作之前，调用 atlas_authorize，并传入 Agent agent:claude、主体 user:alice、delegation_chain ["grt_…"]、操作及所有影响。只有获得 permit 后才能继续。之后调用 atlas_commit_effect。

4. 以人工身份批准升级请求。 批准操作特意没有做成 MCP 工具，因此 Agent 无法自行批准：

npx -y @corpussanctum/atlas-mcp resolve rcpt_a8d7… approve
npx -y @corpussanctum/atlas-mcp verify            # check the audit chain and signatures

工具

工具	用途
atlas_authorize	{agent, principal, requested_action, effects[], delegation_chain[]} → {decision, reason, scope, receipt_id}
atlas_commit_effect	报告回执对应的实际情况。每张回执只能提交一次。未被回执涵盖的影响会标记为 violation。
atlas_receipt_status	ready、pending_approval、rejected、denied、committed、expired
atlas_verify_audit	验证 SHA3-256 哈希链和每个 ML-DSA-65 签名

决策机制

• 授权规定：授权者 → 被授权者可以执行 allow 操作（排除 deny），且仅限指定的 environments 和 resources；需要人工处理的 escalate 操作除外。授权由本地签发者密钥签名，并记录在审计日志中。
• 授权链从主体 → Agent → 子 Agent 延伸。链条必须完整、未过期且未撤销，并且权限只能逐级收窄。扩大父级权限范围的子授权会被拒绝。
• 交集语义： 每个链路都必须独立允许该操作和每项影响。撤销任一链路都会使其下所有授权失效。
• 默认拒绝： 未知授权、签名无效、受环境限制的授权未指定环境，以及格式错误的请求都会被拒绝。服务信任自己记录的授权副本，而不信任调用方提供的副本。
• 回执在 15 分钟后过期。许可或批准仅涵盖明确列出的影响。

强制执行：Claude Code hook

MCP 工具只是由 Agent 主动选择调用的关卡。hook 则让 Claude Code 中的检查无法跳过：每次调用受控工具时，它都会在模型外部运行，因此 Agent 不会忘记检查，也无法通过说辞绕过 deny。

npm i -g @corpussanctum/atlas-mcp       # a global install avoids npx startup cost on every tool call
atlas-mcp hook init --principal user:alice

hook init 会写入 ~/.atlas-mcp/hook.json，签发一份初始授权（有效期 30 天；环境为 dev 和 staging；shell.deploy 和 shell.delete 需要先询问），并输出要粘贴到 ~/.claude/settings.json 的 settings.json 配置块。

每次工具调用时会发生什么

Claude Code 工具调用	Atlas 操作	结果
在 dev 中运行 npm test	shell.exec	不作判断：适用 Claude Code 的常规权限
psql … production	shell.exec @ production	拒绝：委托权限仅允许 dev、staging
rm -rf dist、git push --force、drop table	shell.delete	询问：Claude Code 会提示你；接受操作会被记录为批准
kubectl apply、terraform apply、npm publish	shell.deploy	询问
Write / Edit / MultiEdit	file.write	根据授权处理
mcp__server__tool	mcp.server.tool	根据授权处理
Read、Grep、Glob、Atlas 自身的工具	不受控制

随后，PostToolUse hook 会将回执（成功或失败）提交到签名审计日志。可随时通过 atlas-mcp verify 检查。

调优

编辑 ~/.atlas-mcp/hook.json：

{
  "agent": "agent:claude-code",
  "principal": "user:alice",
  "delegation_chain": ["grt_…"],
  "default_environment": "dev",
  "environments": [{ "match": "\\b(prod|production|live)\\b", "environment": "production" }],
  "rules": [{ "tool": "^Bash$", "match": "^make release", "action": "shell.deploy", "effect_type": "deploy" }],
  "on_permit": "defer"
}

on_permit: "allow" 可让 Atlas 的许可跳过 Claude Code 自己的提示。默认值 defer 会将 Claude Code 的提示保留为第二层防护。

它不会做什么（请阅读）

• 分类采用模式匹配。 Atlas 无法识别的命令会被视为普通的 shell.exec，环境则根据命令中的词语（prod、production、staging）推断。没有环境词语的 ./deploy.sh 或连接字符串会被视为 dev。请为自己的工具添加 rules 和 environments。这只是防止失误的缓冲措施，也是审计记录，并不能防范主动隐藏意图的 Agent。
• 效果是分类结果，并非实际观察所得。 审计日志记录的是 Atlas 对调用效果的判断，而非进程实际执行的操作。
• 钩子故障。 钩子能够捕获自身错误（配置缺失、授权无效）时，会返回 deny。除非你的版本支持在钩子处理程序上设置 "onFailure": "block"（近期版本的文档中有说明），否则 Claude Code 不会阻止严重崩溃或超时；如果你的版本支持，请将其添加到两个钩子条目中。
• 权限模式。 Claude Code 的文档没有说明钩子的 deny 是否能在 --permission-mode bypassPermissions 下生效。我们在 Claude Code 2.1.296（Claude Code）上进行了测试：在 bypassPermissions 模式下，被拒绝的命令没有运行（控制命令运行并已提交）。升级 Claude Code 后请重新测试。
• 自我保护并不完善。 对 ~/.atlas-mcp 的编辑以及指定该路径的命令都会被拒绝，但 shell 可以通过多种途径访问文件。如果这对你很重要，请使用与数据目录所有者不同的 OS 用户运行 Agent。
• 仅支持 Claude Code。其他客户端需要自己的执行控制点。

依赖它之前请先阅读

• 这是 Agent 会查询的关卡，不是沙箱。 MCP 工具本身无法阻止决定不调用它的 Agent，也无法阻止谎报操作效果的 Agent。v0.1 会提供经过签名且可验证的记录，以及可供强制执行的决策：对于 Claude Code，请使用上面的钩子使其具有约束力；在其他环境中，请将其与工具代理或网络／凭据隔离搭配使用。atlas_commit_effect 会捕获并记录已告知它的不一致情况。
• 签发密钥以未加密形式存储在 ~/.atlas-mcp/issuer.json（权限模式 0600）中。请像保护 SSH 密钥一样保护该目录。任何能够读取该文件的人都能伪造授权。
• 本地操作员审批 = 本地 shell 访问权限。v0.1 不提供远程审批通道。
• 这不是合规认证。加密方案遵循父项目的假设；尚未进行外部审计。

数据和配置

ATLAS_MCP_DATA_DIR（默认为 ~/.atlas-mcp）存放 issuer.json 和 audit.jsonl。所有数据都不会离开本机。

Docker

docker build -t atlas-mcp .
docker run -i --rm -v atlas-data:/data atlas-mcp

与 Atlas Protocol 的关系

atlas-protocol 是完整的治理守护程序（Telegram 操作员中继、96 条规则的策略引擎、Agent 身份注册表、行为基线、邻近度）。atlas-mcp 是其中最精简且实用的部分，单独提取出来，让你只需一行即可安装。

开发

npm install && npm test

Apache-2.0。