内容
# AuditHub MCP 服务器
此存储库包含 `audithub-mcp` 的源代码，这是一个用于 [AuditHub](https://audithub.veridise.com) 的 MCP 服务器。
`audithub-mcp` 允许基于 LLM 的代理访问以下功能：
* 发现有关 AuditHub 组织和项目的信息
* 启动和监控 AuditHub 工具任务
* 访问 AuditHub 问题和发现
按照设计，MCP 服务器限制功能为只读且非破坏性的。
可以通过配置文件启用其他功能。
> **警告：** LLM 可能会出错。在执行操作之前，请手动验证所有工具输出。
## 前置条件
- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
## 安装
`audithub-mcp` 作为 Python 包实现，但它尚未在 PyPI 上可用。
您必须直接从此存储库安装它。
### 全局安装
如果您正在使用 `uv` 包管理器，可以使用 `uv` 安装 `audithub-mcp`：
```bash
uv tool install 'git+https://github.com/Veridise/audithub-mcp'
audithub-mcp --help
```
### 本地克隆
从存储库根目录：
```bash
uv venv
uv sync --active
```
如果您的虚拟环境已经激活，并且您只想运行服务器入口点，请使用：
```bash
uv run audithub-mcp --help
```
## 使用 `audithub-mcp`
要使用 `audithub-mcp`，您需要配置两个部分：您的代理和 `audithub-mcp` 配置文件。
一旦两者都配置好了，代理应该会自动启动 MCP 服务器并使用其工具。
### 代理配置
要在您的代理中启用 `audithub-mcp`，您必须将其添加到您的代理的 MCP 服务器配置中。
以下示例假设 `audithub-mcp` 可在 `PATH` 上，并且您的配置文件位于 `~/.config/audithub-mcp/config.yaml`。
* Codex CLI
* 对于交互式设置，请使用 `codex mcp add audithub-mcp`
* 如果您想使用配置文件进行设置，请在您的 `.codex/config.toml` 中添加以下内容：
```toml
[mcp_servers.audithub-mcp]
command = "audithub-mcp"
args = ["--config", "~/.config/audithub-mcp/config.yaml"]
```
* Claude Code
* 对于交互式设置，请使用 `claude mcp add audithub-mcp audithub-mcp`
* 如果您想使用配置文件进行设置，请在您的 `.claude/mcp.json` 中添加以下内容：
```json
{
"mcpServers": {
"audithub-mcp": {
"command": "audithub-mcp",
"args": [
"--config",
"~/.config/audithub-mcp/config.yaml"
]
}
}
}
```
### MCP 服务器配置
您需要创建一个包含 `audithub-mcp` 服务器创建的 YAML 文件，并确保代理配置调用 `audithub-mcp` 时带有 `--config <path>` 参数。
如果您不确定配置文件应该放在哪里，一个好的默认位置是在 `~/.config/audithub-mcp/config.yaml`。
文件权限应设置为 `400`（所有者只读），因为它包含凭据。
有关如何创建配置文件的详细信息，请参见 [配置文档](./docs/configuration.md)。
## 可用的 MCP 工具
| 工具 | 描述 |
|---|---|
| `get_organizations` | 列出允许的组织；传递 `details=true` 以获取完整的组织记录，传递 `filter_id` 以缩小结果范围 |
| `get_defi_vanguard_detectors` | 列出某个组织的所有 DeFi Vanguard 检测器，使用 Vanguard 列表块格式 |
| `get_projects` | 列出允许的项目；传递 `details=true` 以获取完整的项目记录，传递 `filter_id` 以缩小结果范围 |
| `get_versions` | 列出某个项目的版本；传递 `details=true` 以获取完整的版本记录，传递 `filter_id` 以缩小结果范围，传递 `latest_only=true` 以获取最新的版本 |
| `get_task_info` | 获取 AuditHub 任务的状态和详细信息 |
| `get_task_artifacts` | 列出 AuditHub 任务的净化后工件元数据 |
| `get_task_artifact` | 以 base64 编码的内容获取任务工件 |
| `get_task_logs` | 获取一个或多个任务步骤的日志，并将每个结果写入本地输出文件 |
| `get_task_findings` | 获取任务的发现结果，并将它们写入本地输出文件 |
| `wait_for_task_completion` | 轮询任务直到没有待处理步骤或达到超时时间，然后返回最新的任务快照和完成状态；如果没有超时时间，具有任务能力的客户端可以将其作为任务调用 |
| `parse_findings_from_task_log` | 将一个或多个任务日志文件解析为包含发现结果和计数信息的 JSON，并写入本地绝对输出路径 |
| `get_version_comments` | 获取特定项目版本的评论 |
| `get_version_comment_threads` | 获取特定项目版本的评论线程 |
| `get_thread_comments` | 获取特定项目版本中特定线程的评论 |
| `get_project_issues` | 获取项目的所有问题 |
| `get_project_issue` | 获取项目中的特定问题 |
| `get_project_comments` | 获取项目在所有版本中的所有评论 |
| `run_orca_task` | 为项目版本启动 OrCa 任务；仅在显式启用任务运行时注册 |
| `run_defi_vanguard_task` | 为项目版本启动 DeFi Vanguard 任务；仅在显式启用任务运行时注册 |
| `create_version_from_file` | 通过上传本地 `.zip` 存档来创建项目版本；仅在显式启用版本创建时注册 |
| `create_version_from_url` | 从 git 仓库或存档 URL 创建项目版本；仅在显式启用版本创建时注册 |
所有工具都返回由 `audithub-sdk` 模型支持的类型化 Python 对象。
`get_organizations`、`get_projects` 和 `get_versions` 返回的对象仅公开属于已配置的允许列表中的组织/项目的项目。
## 安全模型
- **默认只读。** 默认工具名为 `get_*`，仅调用生成的 `audithub-sdk` GET 端点。
- **任务完成轮询。** `wait_for_task_completion` 反复获取任务详细信息，直到没有待处理步骤或达到超时时间，然后返回最新的净化 `Task` 快照和布尔完成状态。当具有任务能力的客户端以无超时时间调用时，它可以作为任务运行而不是阻塞请求。
- **按需 OrCa 任务执行。** `run_orca_task` 变异工具仅在设置了 `AH_ENABLE_TASK_RUNS=1` 或 `--enable-task-runs` 时注册。它通过 `audithub-sdk` 调用生成的 OrCa POST 端点。
- **按需 DeFi Vanguard 任务执行。** `run_defi_vanguard_task` 变异工具在相同的任务运行按需门控下注册。其输入在顶级展平：`organization_id`、`project_id`、`version_id`、检测器选择和运行时选项。以两个项目的 JSON 数组 `[type, id]` 传递检测器选择，其中内置选择器使用 `get_defi_vanguard_detectors` 中的内置检测器代码，而自定义选择器使用相同工具显示的目录 ID。服务器在调用生成的 DeFi Vanguard v2 POST 端点之前，通过后端检测器目录解析这些选择。
- **链上 OrCa 模式。** 在针对已部署的合约启动 OrCa 时，传递 `deployment_info_file` 作为以 `.deployment.json` 结尾的路径。服务器将其标准化为 `on_chain=True`，并在调用者意外启动本地 Foundry 样式运行之前拒绝不匹配的路径。
- **按需版本创建。** `create_version_from_url` 变异工具仅在设置了 `AH_ENABLE_VERSION_CREATION=1` 或 `--enable-version-creation` 时注册。它通过 `audithub-sdk` 调用生成的项目版本 URL POST 端点。
- **本地发现结果解析。** `parse_findings_from_task_log` 实用工具读取一个或多个本地任务日志文件，使用共享的日志解析器提取发现结果，并写入一个包含解析的发现结果和总发现结果数以及每个日志的计数的 JSON 文件。它不调用 AuditHub API。
- **检测器目录缓存。** DeFi Vanguard v2 内置检测器列表在启动时从 AuditHub 配置端点懒加载并缓存一天。自定义检测器在每次请求时从组织库和标准库中实时获取。
- **检测器列表格式。** `get_defi_vanguard_detectors` 返回每个检测器的一个块。每个块以 `detector: <json>` 开头，其中 `<json>` 是与 `DefiVanguardV2DetectorSelectionInput` 匹配的 JSON 值，然后是 `title:`。标准库自定义检测器还包括从检测器有效载荷加载的 `description:`。每个块以 `------` 结尾。
- **凭证隔离。** OIDC 凭证在启动时从环境中读取一次，并传递给 `audithub_sdk_ext.AuthenticatedApiClient`。它们从不作为工具参数接受，也不显示在工具输出或净化错误消息中。
- **ID 允许列表。** 服务器拒绝访问任何未在 `AH_ALLOWED_ORG_IDS` / `AH_ALLOWED_PROJECT_IDS` 中显式包含的组织或项目。在网络请求之前运行检查。
- **仅限 SDK 传输。** 所有的 AuditHub 交互都通过 `audithub-sdk` 和 `audithub_sdk_ext` 进行；MCP 服务器中没有原始 HTTP 帮助程序。
## 开发工作流程
- 运行测试：`uv run pytest`
- 类型检查：`uv run mypy`
- 整理代码：`uv run ruff check`
- 格式化代码：`uv run ruff format`
### 在本地覆盖 `audithub-sdk`
要在本地克隆的 `audithub-sdk` 上测试 `audithub-mcp`，请在根目录的 [`pyproject.toml`](./pyproject.toml) 中添加路径源覆盖，然后重新同步环境。
根目录 `pyproject.toml` 覆盖示例：
```toml
[tool.uv.sources]
audithub-sdk = { path = "/absolute/path/to/audithub-sdk", editable = true }
```
然后运行：
```bash
uv sync --active
```
要返回到固定的版本，请从 `[tool.uv.sources]` 中删除 `audithub-sdk` 条目，然后再次运行 `uv sync --active`。
## 许可证
[Apache 2.0](./LICENSE)
