audit-ledger-mcp

audit-ledger-mcp

将 Claude、Cursor、LangGraph 或你自己的 Agent 连接到 AI Audit Ledger。 这个 MCP 服务让 Agent 只需一行配置，就能使用工具在防篡改日志中记录、检查和列出决策。

它专为需要清晰记录 AI 决策的团队打造：满足《欧盟 AI 法案》第 12 条的日志记录要求、FCA SS1/23 模型风险证据要求，以及 GDPR 数据最小化要求。原始个人数据会先在本地进行哈希处理，然后才会发送，因此账本只能看到指纹。

AI Audit Ledger 系列。 这个 MCP 服务会将决策写入 账本，证明发生了什么 以及记录是否被更改。 AI Decision Evidence Hub 位于 账本之上，只读。它会将每条轻量级决策记录转化为 审计案例文件，展示已有的证据、仍缺少的内容、各项差距的负责人，以及当前准备度评分。系列项目： audit-ledger · audit-ledger-mcp · evidence-hub。

试用实时仪表板 →  ·  通过此 MCP 服务写入的 30 条合成决策，可供查询和验证。

LangGraph 工作流会在每个 Agent 步骤后调用 record_decision。三条审计事件已写入实时账本；每条都可以独立验证。

---

功能介绍

向任何兼容 MCP 的 Agent 提供四种工具：

工具	功能
record_decision	记录 AI 决策。在本地对输入进行哈希处理，然后写入账本。返回事件 ID。
verify_decision	将存储的记录与不可变的 S3 Object Lock 副本进行交叉核对。返回 integrity_verified: true/false。
verify_completeness	检测已删除或缺失的记录。将账本中每个租户的计数器与实际存在的行进行比较，并返回缺失的序列号。这回答了“你能证明日志完整吗？”
list_decisions	查询近期决策，可按时间范围筛选。按租户隔离，依据 API 密钥确定范围。

每次调用最终都会在你部署的账本中生成符合监管要求的审计记录——DynamoDB 用于查询，S3 Object Lock COMPLIANCE 模式用于保存不可变副本，默认保留 7 年。

---

快速开始 — 无需配置

npx -y audit-ledger-mcp

就是这样。未设置环境变量时，服务会以沙盒模式启动，并将记录写入托管账本上的共享公共租户。你无需配置任何内容，就能试用所有工具——record_decision、verify_decision、verify_completeness、list_decisions。

沙盒模式启用时，你会在 stderr 中看到横幅：

[audit-ledger-mcp] ─────────────── SANDBOX MODE ───────────────
[audit-ledger-mcp] No AUDIT_API_URL configured.
[audit-ledger-mcp] Using the public sandbox at sandbox-public.
[audit-ledger-mcp]   View: https://d2pfirb2397ixy.cloudfront.net
[audit-ledger-mcp] Do NOT write real personal data...

沙盒属性

托管方	github.com/shahidh68/audit-ledger（同一 AWS 部署）
租户	sandbox-public（共享、公开）
速率限制	每个 IP 每分钟 100 个请求
保留期限	7 年（记录无法删除）
适用对象	初步体验者、集成测试、框架演示
不适用场景	生产数据、客户 PII、真实合规记录

零配置接入 Claude Desktop

{
  "mcpServers": {
    "audit-ledger-sandbox": {
      "command": "npx",
      "args": ["-y", "audit-ledger-mcp"]
    }
  }
}

重启 Claude Desktop。四种工具会立即出现在 MCP 菜单中。试着让 Claude“记录此决策：X 是否应获批准？”，然后查看记录是否出现在沙盒仪表板中。

---

生产环境安装

对于实际工作负载，请部署自己的审计账本，并将 MCP 服务指向它：

npm install -g audit-ledger-mcp

使用 API URL 和租户密钥进行配置（设置其中任意一个都会关闭沙箱模式）。出于向后兼容考虑，AUDIT_HMAC_KEY 在技术上是可选的，但强烈建议设置——请参阅下方该值上方的说明：

export AUDIT_API_URL="https://<api-id>.execute-api.<region>.amazonaws.com/prod"
export AUDIT_WRITE_KEY="<your-tenant-write-key>"
export AUDIT_READ_KEY="<your-tenant-read-key>"

# Strongly recommended. Tenant-held secret used to HMAC PII and prompts
# locally before sending. Generate once, store next to AUDIT_WRITE_KEY:
#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
# If unset, the MCP falls back to plain SHA-256 and warns once (back-compat).
export AUDIT_HMAC_KEY="<your-tenant-hmac-secret>"

# Optional
export AUDIT_TIMEOUT_MS=5000        # default 5000
export AUDIT_RETRY_ATTEMPTS=3       # default 3

完整模板位于 .env.example。

---

将其接入 Agent

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "audit-ledger": {
      "command": "npx",
      "args": ["-y", "audit-ledger-mcp"],
      "env": {
        "AUDIT_API_URL": "https://<api-id>.execute-api.<region>.amazonaws.com/prod",
        "AUDIT_WRITE_KEY": "<your-tenant-write-key>",
        "AUDIT_READ_KEY": "<your-tenant-read-key>",
        "AUDIT_HMAC_KEY": "<your-tenant-hmac-secret>"
      }
    }
  }
}

AUDIT_HMAC_KEY 是租户密钥，用于在任何负载离开 MCP 服务进程之前，在本地对 PII 进行密钥哈希。使用 node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" 生成一次，并将结果存储在上方的 env 块中。MCP 不会传输此值，只会读取它。

重启 Claude Desktop。你会在 MCP 工具菜单中看到“audit-ledger”。向 Claude 提出类似 “记录此决定：我拒绝了该申请，因为……” 的请求，然后观察它自动调用 record_decision。

Cursor

在 Cursor 设置 → MCP → 添加服务：

{
  "mcpServers": {
    "audit-ledger": {
      "command": "npx",
      "args": ["-y", "audit-ledger-mcp"],
      "env": {
        "AUDIT_API_URL": "https://<api-id>.execute-api.<region>.amazonaws.com/prod",
        "AUDIT_WRITE_KEY": "<your-tenant-write-key>",
        "AUDIT_READ_KEY": "<your-tenant-read-key>",
        "AUDIT_HMAC_KEY": "<your-tenant-hmac-secret>"
      }
    }
  }
}

LangGraph（Python）

使用 langchain-mcp-adapters：

from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langchain_anthropic import ChatAnthropic
import os

client = MultiServerMCPClient({
    "audit-ledger": {
        "command": "npx",
        "args": ["-y", "audit-ledger-mcp"],
        "transport": "stdio",
        "env": {
            "AUDIT_API_URL":   os.environ["AUDIT_API_URL"],
            "AUDIT_WRITE_KEY": os.environ["AUDIT_WRITE_KEY"],
            "AUDIT_READ_KEY":  os.environ["AUDIT_READ_KEY"],
            "AUDIT_HMAC_KEY":  os.environ["AUDIT_HMAC_KEY"],
        },
    }
})

tools = await client.get_tools()
agent = create_react_agent(
    ChatAnthropic(model="claude-sonnet-4-7-20251022"),
    tools,
)

# The agent can now call record_decision, verify_decision, verify_completeness, list_decisions
result = await agent.ainvoke({
    "messages": [{"role": "user", "content": "Triage this loan application…"}]
})

自定义客户端（原始 MCP）

AUDIT_API_URL=... AUDIT_WRITE_KEY=... AUDIT_READ_KEY=... AUDIT_HMAC_KEY=... npx -y audit-ledger-mcp

该服务通过 stdio 使用 MCP 通信。请按照 MCP 规范发送 initialize、tools/list 和 tools/call 请求。

---

record_decision 调用流程

Agent                  audit-ledger-mcp                  AWS (your ledger)
  |                          |                                 |
  |--- record_decision ----->|                                 |
  |   raw_user_input         | (hash locally — no PII over     |
  |   raw_system_prompt      |  the wire from this point)      |
  |   decision_output        |                                 |
  |   human_in_loop          |                                 |
  |                          |--- HTTPS POST /audit/events --->|
  |                          |    {hashes + decision +         |
  |                          |     x-api-key}                  |
  |                          |                                 |
  |                          |<--- 202 Accepted ---------------|
  |                          |    { event_id, ... }            |
  |<--- event_id ------------|                                 |
  |     recorded_at          |                                 |
  |     note                 |                                 |

AWS 侧的存储通过 SQS → Processor Lambda → DynamoDB + S3 Object Lock 异步完成。完整流程请参阅主仓库的 ARCHITECTURE.md。

---

工具参考

record_decision

将 AI 决策记录到账本中。

参数	类型	必填	备注
model_version	string	是	例如 "claude-sonnet-4-7-20251022"
raw_system_prompt	string	是	在本地进行哈希处理
raw_user_input	string	是	在本地进行哈希处理
ai_decision_output	object	是	按原样存储——不得包含原始 PII
human_in_loop	boolean	是	对《欧盟 AI 法案》第 14 条至关重要
event_id	uuid v4	否	如未提供则自动生成
timestamp	ISO 8601	否	默认为当前时间

verify_decision

检查存储记录是否遭到篡改。

参数	类型	必填	备注
event_id	uuid v4	是	要验证的记录 ID

返回 DynamoDB 记录、S3 记录，以及 integrity_verified: true/false。

verify_completeness

检测缺失的记录。它是 verify_decision 的配套工具：前者证明一条现存记录未被篡改；此工具则证明没有记录被删除。

参数	类型	必填	备注
from	integer	否	sequence_no 的包含式下限。默认为 1。
to	integer	否	sequence_no 的包含式上限。默认为租户当前计数器的值。
tenant_id	string	否	仅使用管理员读取密钥时才需要；否则会忽略。

返回请求的范围、预期与找到的记录数、缺失序列号列表，以及易于理解的说明。

{
  "tenant_id": "acme-prod",
  "range": { "from": 1, "to": 142 },
  "expected_count": 142,
  "found_count": 140,
  "missing": [47, 91],
  "note": "Found 2 missing sequence number(s) in range. Each gap represents a deleted, lost, or never-written record. Cross-check against burned_sequence log entries before treating as a deletion."
}

list_decisions

列出调用方租户的近期决策。

参数	类型	必填	备注
from	ISO 8601	否	默认为 7 天前
to	ISO 8601	否	默认为当前时间
limit	integer 1–500	否	默认为 100

---

安全

• PII 哈希在此进程中计算，而非在账本中计算。 使用 UTF-8 编码和由你在环境中设置的 AUDIT_HMAC_KEY 作为密钥进行 HMAC-SHA256。密钥不会离开你的进程；只有 64 位十六进制摘要会被发送。对低熵值（姓名、电子邮件）使用普通 SHA-256，几秒内就能通过暴力破解；根据 ICO/EDPB 指南，这些值仍被视为个人数据，因此新安装默认使用带密钥的版本。为保持向后兼容，如果未设置 AUDIT_HMAC_KEY，MCP 会回退到普通 SHA-256，并在 stderr 上记录一次弃用警告；现有配置将继续照常运行。
• 绝不记录 API 密钥。 API 密钥来自环境变量，通过 x-api-key 标头传递，绝不会回传给 Agent 或写入磁盘。
• 两类密钥命名空间。 写入密钥不能读取；读取密钥不能写入。写入密钥泄露不会导致数据外泄；读取密钥泄露也无法植入伪造记录。
• 错误会原样传递 HTTP 状态码。 速率限制、无效密钥和验证错误都会传递给 Agent，使其能够妥善应对，而不是盲目重试。

---

本项目不是什么

• 不是法律建议。 这是用于生成审计证据的基础设施。这些证据是否满足任何特定监管义务，应由你的法律团队判断。
• 不能替代模型风险审计。 它记录 AI 做了什么，而不判断其是否正确。
• 不是偏差或公平性测试工具。 它是你现有测试之下的审计层。

---

配套项目：AI Decision Evidence Hub

此 MCP 服务会将决策写入账本——即记录发生了什么的不可变记录。AI Decision Evidence Hub 是账本之上的只读工作台。它回答审计员接下来会提出的问题：决策已记录，但证据是否足够完整，可以进行审查？

对于每项已记录的决策，它会生成：

• 跨九类证据（模型、数据、政策、人工审核、监控、提示词、完整性、保留、决策）的审计就绪度评分（0–100）；
• 具体列出已有和缺失的证据，以及每项预期缺口的负责人；
• 每项决策对应的审计资料包，可打印、保存为 PDF 或下载为 JSON；
• 一个仪表板（与账本仪表板交叉链接），以及一个基于清单的解析器，可自动填充静态证据。

存在未解决的缺口很正常。账本会保持决策记录精简且可防篡改；Evidence Hub 则会展示使该决策达到审计就绪状态所需的后续证据。它通过 API 读取账本，绝不修改记录。基于 AWS 构建的无服务器架构（Lambda + DynamoDB）。请参阅其 客户指南 和管理员操作手册。

项目家族： audit-ledger（发生了什么） · audit-ledger-mcp（此服务——Agent 如何写入决策） · evidence-hub（审计就绪度）。

---

开发

git clone https://github.com/shahidh68/audit-ledger-mcp.git
cd audit-ledger-mcp
npm install
npm run build
npm test

该服务使用 TypeScript 编写，运行于 Node 20+，采用 ESM 和 stdio 传输，并使用 @modelcontextprotocol/sdk。

---

相关项目

• shahidh68/audit-ledger — 此服务连接的 AWS 基础设施。包含 CDK 堆栈、Python 和 Node SDK、合规性仪表板以及完整的架构文档。
• shahidh68/evidence-hub — 账本之上的审计工作台。它会为每项决策的证据评分，将未解决的缺口视为预期的后续工作，并生成可打印或下载的审计资料包。（客户指南 · 管理员操作手册）

---

许可证

Apache License 2.0 — 详见 LICENSE。

专利授权条款是有意设置的。合规基础设施与企业法务审查密切相关，因此明确的授权条款至关重要。

---

作者

由 Shahid 构建。在英国受监管的金融科技领域，现寻求 Principal AI Engineering 和 Head of AI Engineering 职位，以及兼职顾问合作机会。