OmniAudit MCP

所有审计MCP

单个自托管MCP连接器，附带三个生产模块：

• AuditLens (auditlens.*)：GitHub PR/运行证据分类和问题起草。
• SiteLint (sitelint.*)：实时URL审核和报告生成。
• Release Butler (releasebutler.*)：发布资产校验和和发布注释工作流。

它在以下位置暴露了一个MCP端点 POST /mcp 并包括一个轻量级的仪表板 GET /ui.

已实现的功能

• 跨所有必需命名空间的MCP工具(auditlens, sitelint, releasebutler, core).
• 向后兼容 releasebutler.generate_notes 扩展名：

- 可选的 from_tag - 可选的 to_tag - 可选的 fallback_window

• releasebutler.create_release 本地文件资产上传(assets[])每个文件的结果元数据：

- uploaded_assets[] - failed_assets[]

• 物体储存硬化：

- local 后端 - s3 具有双读行为的后端（对S3的新写入，遗留的本地引用仍然可读）

• 策略控制：

- 回购写满列表 - URL分配列表/域名列表 - 写入操作确认令牌门 - 扫描提交和GitHub写入的速率限制

• 具有不可变输出引用的接收优先写入操作。
• 仅使用哈希工具输入附加审计日志存储。
• 可观察性基线：

- 结构化日志(LOG_FORMAT=json|plain) - 可选OTLP轨迹(OTEL_ENABLED=true) - 普罗米修斯 /metrics 端点(PROMETHEUS_ENABLED=true)

• GitHub身份验证提供者：

- 细粒PAT - GitHub App安装令牌流

• S3/MinIO兼容对象存储支持工件和报告。
• 用于作业、收据、审计日志和秘密记录的SQL存储。

存储库布局

• apps/mcp_server -FastAPI MCP服务器和仪表板端点
• packages/omniaudit -域模块、运行时、安全、存储
• services/worker -Celery worker和异步SiteLint任务
• tests -单元+集成测试
• infra -Dockerfiles

架构图

flowchart LR
  ChatGPT -->|MCP JSON-RPC| API["FastAPI /mcp"]
  API --> Runtime["MCP Runtime"]
  Runtime --> AuditLens["AuditLens"]
  Runtime --> SiteLint["SiteLint"]
  Runtime --> ReleaseButler["Release Butler"]
  Runtime --> Policy["Policy + Risk Gate + Rate Limits"]
  Runtime --> Receipts["Receipts + Audit Logs"]
  Runtime --> ObjectStore["ObjectStore (Local or S3 Dual-Read)"]
  Runtime --> Jobs["JobStore"]
  Worker["Celery Worker"] --> SiteLint
  SiteLint --> Reports["Reports + Evidence"]
  ReleaseButler --> GitHub["GitHub API"]
  AuditLens --> GitHub
  API --> Metrics["/metrics"]

支持矩阵

快速入门（本地）

1. 创建环境变量并安装依赖项：

uv venv .venv
uv pip install --python .venv/bin/python -e '.[test]'

1. 配置环境：

cp .env.example .env

1. Bootstrap本地数据文件夹和密钥：

./scripts/bootstrap.sh

1. 运行API：

PYTHONPATH=packages:apps:services .venv/bin/uvicorn mcp_server.main:app --host 0.0.0.0 --port 8080

可选的SiteLint浏览器堆栈：

./scripts/install_sitelint_toolchain.sh

1. 健康检查：

curl -s http://localhost:8080/healthz

快速入门（Docker Compose）

cp .env.example .env
./scripts/bootstrap.sh
docker compose up --build

API终点： http://localhost:8080/mcp 指标端点： http://localhost:8080/metrics

ChatGPT连接器设置

在ChatGPT开发者模式连接器模式中：

• 姓名： OmniAudit MCP
• MCP服务器URL: https:///mcp
• 身份验证：

- 着手 None 如果 MCP_AUTH_MODE=none - 如果启用，则设置为API密钥流 MCP_AUTH_MODE=api_key

存储后端模式

默认模式为本地模式：

OBJECT_STORE_BACKEND=local

S3/MinIO模式，双读，S3写：

OBJECT_STORE_BACKEND=s3
OBJECT_STORE_BUCKET=omniaudit
OBJECT_STORE_PREFIX=omniaudit
S3_ENDPOINT_URL=http://minio:9000
S3_FORCE_PATH_STYLE=true
S3_ACCESS_KEY_ID=minioadmin
S3_SECRET_ACCESS_KEY=minioadmin

行为 s3 模式：

• 新的不可变对象被写入 `s3:///

/...`

• 现有的本地文件引用继续通过回退读取进行解析
• 现有收据不需要迁移 result_ref 价值观

MCP示例

列出工具：

curl -s http://localhost:8080/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc":"2.0",
  "id":1,
  "method":"tools/list",
  "params":{}
}'

开始站点扫描：

curl -s http://localhost:8080/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc":"2.0",
  "id":2,
  "method":"tools/call",
  "params":{
    "name":"sitelint.start_scan",
    "arguments":{
      "url":"https://example.com",
      "profile":"standard",
      "viewport_set":"desktop_mobile"
    }
  }
}'

写入操作风险闸门流程(auditlens.create_issue):

1. 不打电话 confirmation_token 并阅读 structuredContent.confirmation_token.
2. 使用该令牌重复调用以执行写入和接收 receipt_id.

生成标签到标签注释：

curl -s http://localhost:8080/mcp -H 'Content-Type: application/json' -d '{
  "jsonrpc":"2.0",
  "id":3,
  "method":"tools/call",
  "params":{
    "name":"releasebutler.generate_notes",
    "arguments":{
      "repo":"Prekzursil/AdrianaArt",
      "from_tag":"v1.0.0",
      "to_tag":"v2.0.0",
      "fallback_window":25
    }
  }
}'

使用本地资产创建发布（确认流程）：

1. 第一个电话 releasebutler.create_release 没有 confirmation_token.
2. 重新呼叫并返回 confirmation_token 以及中的本地文件路径 assets[].
3. 检查 uploaded_assets 和 failed_assets 在 structuredContent.

活烟工作流程

在本地运行生产风格的双读/S3写烟雾检查：

./scripts/smoke_hardening_pass2.sh

输出：

• artifacts/smoke//summary.json
• artifacts/smoke//responses/*.json

关键断言：

• 切换到S3后端后，传统本地引用仍然可读
• 新的写作成为 s3://...
• 本地资产发布上传确认流程成功
• 度量端点暴露硬化计数器

可观测性

结构化日志记录：

LOG_FORMAT=json

可选OTLP跟踪：

OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces

普罗米修斯指标：

PROMETHEUS_ENABLED=true

外露系列包括：

• omniaudit_tool_calls_total{tool,status}
• omniaudit_tool_latency_seconds{tool}
• omniaudit_write_gate_denied_total{tool}
• omniaudit_rate_limit_denied_total{bucket}

测试

TMPDIR=/tmp TEMP=/tmp TMP=/tmp .venv/bin/pytest -q -s

备注

• sitelint.start_scan 默认情况下，内联运行以实现确定性单用户行为。
• 集 SITELINT_ASYNC_MODE=true 然后跑 worker 通过Celery处理扫描作业的服务。
• GitHub API操作需要中的有效凭据 .env.
• 在Docker+MinIO设置中，保持 S3_FORCE_PATH_STYLE=true 为了兼容性。
• 有关路线图和发行说明策略，请参阅 docs/ROADMAP.md 和 docs/CHANGELOG_POLICY.md.

看 docs/ARCHITECTURE.md 和 docs/OPERATIONS.md 了解详情。