内容
# Argo — MCP 审计代理
Argo 是一个[模型上下文协议（MCP）](https://modelcontextprotocol.io)服务器，暴露了三个用于人工智能治理和安全合规工作的特定审计工具。它在本地运行，并连接到 Claude Code、Claude Desktop 或任何兼容 MCP 的客户端。
每个工具都封装了 `claude-sonnet-4-6`，并带有审计级别的提示，返回**结构化 JSON**，旨在模仿四大会计师事务所审计师阅读 SOC 2 报告、草拟 ISO 42001 适用性声明以及评估控制证据的方式。
> **注意：** Argo 是一个投资组合制品，展示了 GRC 工程在四大会计师事务所审计经验和人工智能治理框架交叉点的成果。其输出是人工智能生成的草稿，旨在加速合格专业人员的工作 — 而不是取代专业判断。参见[限制](#限制)。
## 三个工具
| 工具 | 输入 | 输出 |
| --- | --- | --- |
| `summarize_soc2_report` | SOC 2 报告文本 | 报告的结构化摘要 |
| `draft_iso42001_soa_section` | 人工智能系统描述 + ISO 42001 控制列表 | 起草的适用性声明条目 |
| `evaluate_control_evidence` | 控制声明 + 证据描述 | 证据充分性评估，带有跨框架映射 |
### 1. `summarize_soc2_report`
读取 SOC 2 报告的文本，模仿审计师在供应商尽职调查过程中的做法，提取影响依赖决策的事实。
**输入：** `report_text`（字符串）— 报告全文。
**输出（JSON）：**
- `service_organization_name`
- `audit_period`
- `opinion_type` — `无条件` / `有条件` / `不利` / `免责声明`
- `trust_services_criteria` — 适用的 TSC 类别
- `key_exceptions` — 测试异常和发现，以及管理层回应
- `cuecs` — 补充用户实体控制
- `subservice_organizations` — 名称、服务和包含/排除处理
- `risk_flags` — 审计师风格的标志，涉及依赖
### 2. `draft_iso42001_soa_section`
为特定人工智能系统的一组 ISO/IEC 42001:2023 附件 A 控制草拟适用性声明（SoA）条目。
**输入：** `ai_system_description`（字符串）和 `controls`（字符串列表 — 附件 A 控制引用或名称）。
**输出（JSON）：** 一个 `soa_sections` 数组，每个控制一个条目，包含：
- `control_reference` 和 `control_title`
- `applicability_decision` — `适用` / `不适用`
- `justification` — 与特定系统相关的叙述
- `implementation_status` — `已实施` / `部分实施` / `计划中` / `未实施` / `不适用`
- `evidence_pointer` — 证明控制的文件类型
### 3. `evaluate_control_evidence`
评估证据是否足以支持控制，应用标准审计证据方法（充分性与适当性、可靠性层次、设计与运行有效性以及时间覆盖）。
**输入：** `control_statement`（字符串）和 `evidence_description`（字符串）。
**输出（JSON）：**
- `sufficiency_rating` — `足够` / `部分足够` / `不足`
- `coverage_assessment` — 证据表明和未表明的内容
- `gaps_identified`
- `recommended_additional_evidence`
- `framework_mapping` — 最相关的 SOC 2、ISO 42001 和 NIST AI RMF 参考（或 `无直接映射`）
## 涵盖的框架
Argo 建立在三个框架之上，共同涵盖安全保障和人工智能治理：
- **SOC 2（AICPA 信托服务标准）。** 服务组织安全保障的事实标准。`summarize_soc2_report` 读取 I 型和 II 型报告；`evaluate_control_evidence` 将控制映射到相关的信托服务标准（例如 `CC6.x` 逻辑访问）。
- **ISO/IEC 42001:2023.** 首个国际人工智能管理系统标准。`draft_iso42001_soa_section` 遵循附件 A 控制结构（目标 A.2–A.10）草拟适用性声明条目。
- **NIST AI RMF.** NIST 人工智能风险管理框架（治理 / 映射 / 衡量 / 管理）。`evaluate_control_evidence` 将控制映射到相关的 RMF 功能和类别，提供控制的跨框架视图。
## 工作原理
Argo 是一个**无状态、本地 MCP 服务器** — 没有数据库，没有向量存储，没有 Web 框架。架构故意保持简单：
```
MCP 客户端（Claude Code / Desktop）
│ JSON-RPC via stdio
▼
server.py ← 注册 3 个工具，路由调用
│
▼
tools/*.py ← 验证输入，调用 claude-sonnet-4-6，解析 JSON
│
▼
prompts/*.txt ← 审计逻辑位于此处，不在代码中
```
- **`server.py`** 广告宣传三个工具（名称、描述、输入模式）并将每个调用路由到 `tools/` 中的处理程序。
- 每个**工具模块**验证其输入，加载其提示，调用 Claude，并将响应解析为 Python 字典。
- 每个工具的**提示**位于 `prompts/` 中为纯文本，因此审计逻辑可以独立于运行它的代码进行审查和改进。
## 项目结构
```
argo-mcp/
├── server.py # MCP 服务器入口点
├── requirements.txt
├── tools/
│ ├── soc2_summarizer.py # 工具 1
│ ├── iso42001_soa.py # 工具 2
│ └── evidence_evaluator.py # 工具 3
├── prompts/ # 每个工具一个提示（纯文本）
├── schemas/ # JSON 输出模式（每个工具）
└── tests/ # 每个工具的测试
```
## 要求
- Python 3.11 或更高版本
- [Anthropic API 密钥](https://console.anthropic.com/)
运行时依赖项（参见 `requirements.txt`）：
- `mcp` — 模型上下文协议 SDK
- `anthropic` — Anthropic SDK（调用 `claude-sonnet-4-6`）
- `python-dotenv` — 在开发过程中加载 API 密钥的便利设施
## 安装
```bash
# 克隆，然后创建并激活虚拟环境
python -m venv venv
# Windows（PowerShell）
venv\Scripts\Activate.ps1
# macOS / Linux
source venv/bin/activate
# 安装依赖项
pip install -r requirements.txt
```
## 配置
Argo 从 `ANTHROPIC_API_KEY` 环境变量中读取 Anthropic API 密钥。
在 shell 中设置：
```powershell
# Windows（PowerShell）
$env:ANTHROPIC_API_KEY = "sk-ant-..."
```
```bash
# macOS / Linux
export ANTHROPIC_API_KEY="sk-ant-..."
```
对于本地开发，您可以将密钥保存在 `.env` 文件中（在项目根目录下忽略 git）：
```
ANTHROPIC_API_KEY=sk-ant-...
```
向桌面 MCP 客户端提供密钥的推荐方式是客户端配置的 `env` 块（如下所示），它直接为服务器进程设置变量。
## 运行
Argo 通过 **stdio** 使用 MCP，因此它由 MCP 客户端启动，而不是单独运行。通过将命令指向虚拟环境的 Python 和 `server.py` 来在客户端注册它。
客户端配置示例（Claude Desktop / Claude Code `mcpServers` 块）：
```json
{
"mcpServers": {
"argo": {
"command": "C:\\path\\to\\argo-mcp\\venv\\Scripts\\python.exe",
"args": ["C:\\path\\to\\argo-mcp\\server.py"],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-..."
}
}
}
}
```
在 macOS / Linux 上，请使用匹配的路径（`venv/bin/python` 和 `/path/to/argo-mcp/server.py`）。
客户端重启后，三个 Argo 工具可供助手使用，助手可以在对话过程中调用它们。
### Claude Code（项目范围内的 `.mcp.json`）
Claude Code 还从存储库根目录的 `.mcp.json` 文件中读取项目范围内的 MCP 配置。存储库中附带了一个模板 `.mcp.json.example`：
```bash
# 从项目根目录复制模板并编辑路径
cp .mcp.json.example .mcp.json
```
然后编辑 `.mcp.json`，使两个路径均为**绝对路径**，并指向此克隆 — 虚拟环境的 Python 作为 `command`，`server.py` 作为参数：
```json
{
"mcpServers": {
"argo": {
"command": "/absolute/path/to/argo-mcp/venv/Scripts/python.exe",
"args": ["/absolute/path/to/argo-mcp/server.py"]
}
}
}
```
注意：
- **`.mcp.json` 被 git 忽略**，因为路径是特定于机器的；请提交 `.mcp.json.example` 的更改。每个开发人员从模板创建自己的 `.mcp.json`。
- **此处不需要 `env` 块**。`server.py` 从项目的 `.env` 文件中自动加载 `ANTHROPIC_API_KEY`。
- **在 Windows 上**，请保持正斜杠（Python 接受它们）或将反斜杠转义为 `\\` — 单个 `\` 不是有效的 JSON 转义。
启动（或重启）Claude Code 进入项目目录后，它将提示您在第一次批准项目的 MCP 服务器。运行 `/mcp` 以确认 `argo` 已连接；然后三个工具作为 `mcp__argo__summarize_soc2_report`、`mcp__argo__draft_iso42001_soa_section` 和 `mcp__argo__evaluate_control_evidence` 显示。
## 示例
调用 `summarize_soc2_report` 获取包含测试异常的 II 型报告，返回（缩略）：
```json
{
"service_organization_name": "Northwind Cloud Services, Inc.",
"audit_period": "2024 年 1 月 1 日至 2024 年 12 月 31 日",
"opinion_type": "有条件",
"trust_services_criteria": ["安全", "可用性"],
"key_exceptions": [
{
"control_area": "CC6.2 – 访问取消",
"description": "对于抽样的 25 名已终止员工中的 2 名，未在要求的 24 小时内取消生产访问。",
"management_response": "管理层已实施自动取消工作流。"
}
],
"subservice_organizations": [
{
"name": "Amazon Web Services (AWS)",
"service_provided": "数据中心托管",
"treatment": "排除"
}
],
"risk_flags": [
"意见是有条件的，而不是无条件的 — CC6.2 例外修改了审计师的意见。",
"AWS 被视为排除项；获取单独的 AWS SOC 2 报告以涵盖基础设施层。"
]
}
```
## 设计原则
- **清晰胜过聪明。** 每个函数都有文档字符串；每个文件都有模块注释。目标是任何一行代码都可以被用简单的语言解释。
- **提示位于 `prompts/`。** 审计逻辑是文本，可以独立于运行它的代码进行审查和改进。
- **显式错误处理。** 空输入、API 失败和模型输出格式错误都会引发不同的、描述性的错误 — 没有无声失败。
## 限制
- 输出是**人工智能生成的草稿**，不是保证意见或法律建议。每个结果都应由合格的专业人员审查后才影响决策。
- 每个工具都会向 Anthropic API 发送实时调用，并受模型变化的影响；结果不是确定性的。
- Argo 仅汇总和评估它给出的文本。它不获取、验证或独立验证底层证据。
## 状态和路线图
已实施并针对实时 API 进行端到端验证：
- ✅ 具有所有三个工具注册和路由的 MCP 服务器
- ✅ 所有三个工具处理程序和提示
计划中：
- `schemas/` 中的 JSON 输出模式连接到工具（结构化输出）
以保证模式有效的响应
- `tests/` 中的每个工具的测试
- `summarize_soc2_report` 的可选文件路径输入
