@agent-audit/mcp-server
This MCP server enables structured auditing of AI agent fix tasks by providing tools to start, record, query, and export audit trails as JSONL logs, with optional SDK-based auto-instrumentation and silent degradation.
Start a trace:
audit_start_traceinitiates an audit session, specifying agent name, task intent, and optional context; returns atraceId.Record events:
audit_record_eventlogs granular events with phases (INPUT_SNAPSHOT,REASONING,DECISION,EXECUTION,VERIFICATION), log levels (debugtoerror), and rich metadata (tool name, file path, status, duration, before/after states, error details).End a trace:
audit_end_tracecloses a session ascompletedorfailedand returns summary stats (event count, duration).Query trails:
audit_get_trailretrieves events bytraceId, with optional filtering by phase, level, and a limit up to 1000 events; backed by an in-memory ring buffer for real-time access.Export reports:
audit_export_reportgenerates a human-readable Markdown report for a single event or an entire trace.Persist logs: Events are stored in daily-rotated JSONL files, automatically cleaned after 7 days.
SDK integration: The client SDK allows programmatic control (
createAuditClient/wrapAgent) for manual auditing or automatic tool-call instrumentation, with silent fallback if the server is unavailable.Real-time notifications: Optionally triggers MCP notifications or stderr alerts for important events.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@@agent-audit/mcp-server 开始审计,任务:修复登录接口400错误"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@xueca/agent-audit-mcp
Agent 修复任务的行为审计 MCP Server:让 AI Agent 从输入、推理、决策到执行、验证的全过程留下结构化审计日志。
目录
Related MCP server: mcp-audit
项目简介
AI Agent 在自动修复代码时往往像"黑盒":改了什么、为什么改、验证结果如何,事后难以追溯。@xueca/agent-audit-mcp 以 MCP 工具 + JSONL 落盘 + SDK 自动注入的方式,把 Agent 的修复任务记录为结构化事件流(trace + event),提供全程清晰日志:何时开始、每个阶段发生了什么、最终结果如何,均可查询与回放。
前置要求
Node.js >= 21.0.0(
npm test依赖 Node >= 21 的测试运行器 glob 支持)支持 MCP 的 AI 编码助手客户端(Claude Code / Trae / Cursor / Windsurf / Codex 等),或 Node.js 环境直接以 CLI/SDK 方式运行
安装
方式一:从 npm 安装(推荐)
npm install @xueca/agent-audit-mcp --save-dev方式二:本地构建
git clone https://github.com/xueca/agent-audit-mcp.git
cd agent-audit-mcp
npm install
npm run build构建产物位于 dist/,可用 node dist/src/cli.js 启动 MCP Server。
快速开始
1. 注册 MCP Server
在支持 MCP 的客户端中注册本服务:
{
"mcpServers": {
"agent-audit": {
"command": "npx",
"args": ["-y", "@xueca/agent-audit-mcp"]
}
}
}启动后即暴露 5 个审计工具,事件默认落盘到 ./audit-events.jsonl/ 目录(按天生成 audit-YYYY-MM-DD.jsonl)。
本项目已通过 .trae/mcp.json 预配置 agent-audit,Trae 打开项目后 Agent 自动可用,无需手动注册。
2. 使用
在 AI 对话中直接调用 Tool,或对 Agent 说人话让它自动调用(见 路径 A 的对话示例):
开始审计,任务:修复登录接口 400 错误路径 A:Agent 直接调用 MCP 工具
这是推荐的使用方式:Agent(包括子 Agent)直接把审计工具当作普通 MCP 工具调用,在任务的不同阶段记录事件,形成完整审计闭环。
完整审计闭环(5 步)
audit_start_trace → 拿到 traceId
↓
audit_record_event → 按阶段记录 INPUT_SNAPSHOT / REASONING / DECISION / EXECUTION / VERIFICATION
↓
audit_end_trace → 标记 outcome(completed / failed),得到事件汇总
↓
audit_get_trail → (任意时刻)查询轨迹,核对过程
audit_export_report → 导出人类可读的 Markdown 报告工具调用示例
第 1 步:开始追踪
{
"agentName": "fix-agent-01",
"taskIntent": "修复 code-guardian 入口失效问题",
"context": "用户反馈 MCP 入口指向已删除的 index.js"
}返回 { "ok": true, "traceId": "019f...", "agentName": "fix-agent-01", "status": "active", "startTime": "..." }。保存 traceId,后续所有调用都需要它。
第 2 步:按阶段记录事件
{
"traceId": "019f...",
"phase": "DECISION",
"level": "info",
"message": "确定将入口从 index.js 改为 dist/index.js",
"metadata": {
"toolName": "apply_patch",
"filePath": ".trae/mcp.json",
"status": "success"
}
}第 3 步:结束追踪
{ "traceId": "019f...", "outcome": "completed" }返回 { "ok": true, "traceId": "019f...", "status": "completed", "eventCount": 12, "endTime": "...", "durationMs": 18340 }。
第 4 步:查询轨迹(任意时刻可查)
{ "traceId": "019f...", "phase": "EXECUTION", "limit": 100 }第 5 步:导出报告
{ "traceId": "019f..." }也可按单个事件导出:{ "eventId": "019f..." }(两者至少提供一个)。
阶段与时机对照
phase | 记录时机 | 建议 message 内容 |
| 任务开始 | 任务输入、上下文、目标文件与基线状态 |
| 调研 / 分析 | 关键分析结论、候选方案、风险点 |
| 确定方案 | 方案选择与理由(触发 MCP 通知) |
| 执行改动 | 改动的文件、调用的工具、执行结果 |
| 验证阶段 | 测试 / 检查结果,成功或失败原因 |
level 可选 debug / info / warn / error;metadata 建议携带 toolName、filePath、layer、durationMs、status(success / error / skipped)、before / after,便于报告还原细节。
对话示例
你想做的事 | 对 Agent 说 |
开始一次带审计的修复任务 |
|
中途记录关键决策 |
|
查看这次任务的过程 |
|
导出报告 |
|
导出单个事件 |
|
可用性说明
路径 A 生效的前提是客户端向 Agent(含子 Agent)暴露 MCP 工具集。部分平台的子 Agent 环境默认不注入 MCP 工具,此时需要主线程编排调用,或改用 路径 B(SDK 直连,不受工具集暴露限制)。
路径 B:SDK 自动注入
SDK 通过包的 ./sdk 子路径导出(package.json exports ./sdk),提供 createAuditClient / wrapAgent,包装结果附 closeAudit。
手动埋点:createAuditClient
import { createAuditClient } from '@xueca/agent-audit-mcp/sdk'
const client = createAuditClient({
agentName: 'demo-agent',
taskIntent: '修复 D1 路径穿越',
command: 'npx',
args: ['-y', '@xueca/agent-audit-mcp']
})
const traceId = await client.startTrace()
await client.record({
phase: 'DECISION',
level: 'info',
message: '提交修复方案',
metadata: { toolName: 'record_blueprint' }
})
await client.endTrace({ traceId, outcome: 'completed' })
await client.close()startTrace 未传 traceId 的 record 会懒启动追踪;timeoutMs 默认 2000 毫秒,超时按失败处理。
自动注入:wrapAgent
import { wrapAgent } from '@xueca/agent-audit-mcp/sdk'
const wrapped = wrapAgent(agent, {
agentName: 'demo-agent',
taskIntent: '演示独立接入',
command: 'npx',
args: ['-y', '@xueca/agent-audit-mcp']
})
// 工具调用后自动记录 EXECUTION 事件(成功 info / 失败 error)
const result = await wrapped.tools.fix({ file: 'src/a.ts' })
// 退出前释放子进程句柄(幂等,失败静默)
await wrapped.closeAudit?.()wrapAgent 返回原 Agent 的浅拷贝:tools 全部替换为带审计上报的包装函数,并新增 closeAudit;传入已创建的 client 时复用该客户端,否则内部自动创建。
静默降级
审计 Server 不可用时,startTrace / record / endTrace 返回 null、不抛异常;首次失败向 stderr 输出一行提示,此后完全静默(no-op),不影响业务调用。
工作原理
trace + event 模型:一次修复任务是一个
trace(会话),阶段行为是若干条event(事件),事件通过traceId关联成轨迹。三通道输出:JSONL 文件持久化(按天分片、10MB 轮转、7 天保留)、MCP
notifications/message通知(DECISION 阶段或 warn 及以上级别)、stderr 告警(warn 及以上级别)。内存实时查询:事件同时写入内存 RingBuffer(默认 1000 条,
drop-oldest),通过audit_get_trail实时查询最近轨迹。SDK 自动注入:
wrapAgent一行包装 Agent 的全部工具调用,成功后自动记录EXECUTION/info事件,失败记录EXECUTION/error事件后原样抛出。
5 个审计工具
工具名 | 用途 | 关键入参 | 返回 |
| 开始一次新的审计追踪 |
|
|
| 记录一条行为事件 |
|
|
| 结束追踪并返回汇总 |
|
|
| 查询追踪会话的事件轨迹 |
|
|
| 导出人类可读 Markdown 报告 |
|
|
事件阶段 phase:INPUT_SNAPSHOT / REASONING / DECISION / EXECUTION / VERIFICATION;日志级别 level:debug / info / warn / error。
配置参考
配置按四级来源合并(优先级从低到高):默认值 → .agent-audit.json → 环境变量 AGENT_AUDIT_* → CLI 参数,合并后经 zod schema 校验,非法配置直接报错退出。
CLI 参数
agent-audit [选项]
选项:
--log-level <debug|info|warn|error> 设置服务日志级别
--config <path> 配置文件路径(JSON)
-h, --help 显示本帮助并退出环境变量
变量 | 作用 |
| 传输方式,仅支持 |
| 日志级别 |
| 内存缓冲大小(正整数) |
| 写入器配置(JSON 数组,如 |
| 通知开关, |
| 定时落盘间隔(毫秒) |
| 批量落盘条数阈值 |
配置文件(.agent-audit.json)
默认读取工作目录下的 .agent-audit.json,也可用 --config 指定路径:
{
"logLevel": "info",
"buffer": { "maxSize": 1000, "overflowStrategy": "drop-oldest" },
"flush": { "intervalMs": 5000, "sizeThreshold": 100 },
"writers": [{ "type": "jsonl", "filePath": "./audit-events.jsonl" }],
"notifications": { "enabled": true, "minLevel": "warn" },
"storage": "jsonl"
}Code Guardian 集成
面向 Code Guardian 的接入说明(事件映射、编排流程、wrapAgent 接入、手动埋点)见 docs/cg-integration.md。独立使用示例见 examples/standalone-usage.ts,构建后运行 node dist/examples/standalone-usage.js。
运行测试
npm run build # tsc 编译到 dist/
npm run lint # ESLint 检查(src/tests/sdk/examples)
npm run typecheck # tsc --noEmit 类型检查
npm test # 编译后运行 node:test,全部测试
npm run clean # 删除 dist/项目结构
src/
buffer/ RingBuffer 有界环形缓冲
config/ 配置 schema / 默认值 / 环境变量解析 / 加载器
core/ AuditService 审计服务
errors/ AuditError 与错误码
models/ 事件 / 会话 / Blueprint 模型(zod)
notifications/ McpNotifier MCP 通知
storage/ TraceStore 追踪存储
tools/ 5 个 MCP 工具
writers/ JsonlWriter / CompositeWriter
cli.ts CLI 入口(bin: agent-audit)
server.ts MCP Server 装配
index.ts 公共 API 出口
sdk/ 客户端 SDK(client / instrumentation / types)
examples/ 使用示例
tests/ node:test 测试
docs/ 文档已知限制
运行环境要求 Node.js ≥ 21(
engines与npm test的测试运行器 glob 支持对齐)。当前构建产物为 CommonJS(tsconfig
module: NodeNext,未声明"type": "module"),ESM / 双格式发布留待后续版本。存储仅支持 JSONL(
storage固定为jsonl);writers[].filePath为目录而非单文件,内部按天分片并自动清理 7 天前的文件。redaction 配置字段当前仅解析、尚未生效(事件仍明文落盘)。
路径 A(Agent 直接调用 MCP 工具)依赖客户端向 Agent 暴露 MCP 工具集,部分平台子 Agent 环境默认不可用。
常见问题
Q: 路径 A 和路径 B 有什么区别?
A: 路径 A 是 Agent 把 audit_* 当作普通 MCP 工具直接调用,零代码、对模型透明,但依赖客户端暴露工具集;路径 B 用 SDK(wrapAgent / createAuditClient)在代码层注入,不依赖工具集暴露,适合需要保证一定埋点的场景。两者可混用。
Q: 为什么事件既要落盘又要进内存?
A: 落盘保证持久化与报告导出,内存 RingBuffer 保证 audit_get_trail 的实时查询,互不阻塞。
Q: 审计 Server 挂了会影响业务吗?
A: 不会。客户端调用失败时 SDK 返回 null 并静默降级为 no-op,业务调用不受影响。
Q: 如何清理审计日志?
A: 无需手动清理。JSONL 按天分片(audit-YYYY-MM-DD.jsonl),自动轮转并删除 7 天前的文件。
Q: 为什么选择 MCP 协议而不是直接作为 CLI 工具?
A: MCP 是 AI 编码助手的标准协议。通过 MCP Server,Agent 可以在修复过程中主动调用审计工具,无需人工干预;CLI 只能事后执行,无法覆盖过程行为。
贡献指南
欢迎贡献!请遵循以下流程:
Fork 本仓库
创建分支:
git checkout -b feat/your-feature编写代码:确保通过所有现有测试
添加测试:新功能或 bug 修复需要添加对应测试用例
运行测试:
npm run test提交 PR:提交前请确保:
所有测试通过
代码符合项目编码规范(文件头注释、函数注释)
新工具或配置变更需要更新 README.md
License
Available Tools
5 toolsaudit_end_traceB
结束指定追踪会话并返回事件汇总
Inputs: traceId (required), outcome.
audit_export_reportB
按需导出审计事件或追踪时间线为 Markdown 报告
Inputs: eventId, traceId.
audit_get_trailB
查询指定追踪会话的审计事件列表
Inputs: traceId (required), level, limit, phase.
audit_record_eventC
向指定追踪会话记录一条行为事件
Inputs: phase (required), message (required), traceId (required), error, +2 more.
audit_start_traceC
开始一次新的审计追踪,返回追踪会话信息
Inputs: agentName (required), taskIntent (required), context.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a uniquely identifiable role in the audit lifecycle: starting traces, recording events, ending traces, querying trails, and exporting reports. There is no overlap in their purposes.
All tool names follow the consistent pattern 'audit_<verb>_<noun>' (e.g., audit_start_trace, audit_record_event). The naming is uniform and predictable.
With 5 tools, the server is well-scoped for audit management. Each tool is necessary and sufficient, covering the lifecycle without unnecessary additions.
The tool surface fully covers the core audit workflow: start, record, end, retrieve, and export. Since audit trails are typically immutable, the absence of update/delete operations is appropriate and not a gap.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Hash-chained HMAC-signed audit log MCP for A2A (agent-to-agent) calls. Every tool-call, agent-ha...
MCP server for building and testing AI agents with multi-model experimentation and insights.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceAn MCP server that validates tool calls against JSON Schema, performs deterministic repair, redacts secrets, and maintains a hash-chained audit ledger.-
- AlicenseNot gradedqualityCmaintenanceAn MCP server that gives AI agents observability over their own tool calls, enabling auditing, cost tracking, latency analysis, and alerting.MIT
- AlicenseAqualityDmaintenanceAn MCP server that gives AI assistants the ability to inspect, normalize, diff, and validate agent tool-call traces.342 npmMIT
- AlicenseAqualityDmaintenanceMCP server for measuring, tracking, scoring, and improving AI agent reliability with tools for recording interactions, scoring reliability, analyzing failures, recommending improvements, generating audit reports, and checking MCP health.8MIT