内容
# 代理卫士 MCP - AI 代理权限与审计平台
代理卫士 MCP 是一个围绕 **模型上下文协议（MCP）** 构建的 AI 代理治理平台。
它作为 AI 代理与它们想要使用的工具之间的控制层，强制执行 **每个代理的权限、基于风险的策略、人工审批关口和审计日志记录**，在工具调用执行之前。
该项目演示了如何启用 MCP 的代理可以安全地与工作区工具（如 GitHub）交互，同时对高影响力操作保持人工监督。
---
## 概述
当 AI 代理被允许与外部工具交互时，它们会变得更加有用，但给予代理无限制的工具访问权限会带来安全和治理风险。
代理卫士 MCP 通过在执行前评估每个受管辖的工具调用来解决这个问题。
对于每个请求，代理卫士确定：
1. 哪个代理正在发出请求
2. 请求的工具是否存在且已启用
3. 代理是否具有使用该工具的权限
4. 工具执行的操作类型
5. 工具的配置风险级别
6. 是否需要人工审批
7. 请求是应该被允许、阻止还是等待审批
然后，每个决定都会被记录在审计日志中。
---
## 功能
### MCP 工具治理
代理卫士通过 MCP 服务器公开受管辖的工具，并通过中央策略层路由工具调用，在执行前。
该平台支持：
- 代理注册
- 工具注册
- 每个代理的工具权限
- 工具启用/禁用控制
- 风险分类
- 人工审批要求
- 受管辖的工具执行
- 工具调用审计日志记录
---
### 基于风险的策略引擎
策略引擎根据以下因素评估 AI 工具调用：
- 代理权限
- 工具可用性
- 工具风险级别
- 操作类型
- 审批要求
请求可以导致三种主要结果之一：
```text
允许
阻止
待审批
```
低风险操作可以立即执行。
高影响力操作（如写操作）可以路由到人工审批队列，在执行前。
---
### 人工审批关口
高风险操作可以在执行底层工具之前需要人工审批。
例如：
```text
AI 代理
|
v
创建 GitHub 问题
|
v
策略引擎
|
v
高风险写操作
|
v
待审批
|
+------ 拒绝
|
v
审批并执行
|
v
GitHub API
```
这允许系统对修改外部系统的操作保持人工监督。
---
### 审计日志记录
代理卫士记录受管辖的工具活动，以便管理员审查代理尝试执行的操作。
审计记录包括以下信息：
- 代理
- 工具
- 时间戳
- 风险级别
- 决策状态
- 审批状态
- 工具结果或失败信息
这提供了 AI 代理活动和治理决策的历史记录。
---
## 受管辖的工具
当前项目包括针对几种不同类型的代理操作的 MCP 工具。
### GitHub 问题读取
使用 GitHub REST API 读取现有的 GitHub 问题。
示例输入：
```json
{
"owner": "facebook",
"repo": "react",
"issue_number": 123
}
```
由于这是只读操作，因此可以将其配置为低风险工具，无需人工审批即可执行。
---
### GitHub 拉取请求摘要
检索 GitHub 拉取请求元数据和更改的文件，然后生成结构化摘要。
示例输入：
```json
{
"owner": "facebook",
"repo": "react",
"pull_number": 123
}
```
工具可以返回以下信息：
```text
摘要
关键更改
测试影响
风险级别
风险原因
推荐检查
```
当配置了 Gemini API 密钥时，可以使用 Gemini 生成结构化分析。
如果 Gemini 不可用，项目支持确定性备用行为，以便其余治理系统可以继续运行。
---
### 测试计划生成
代理卫士包括用于创建结构化 QA 测试计划的 AI 辅助工具。
生成的测试计划可以包括：
- 测试场景
- 预期行为
- 边缘情况
- 验证建议
- 风险考虑
---
### 审批关口的 GitHub 问题创建
代理可以请求创建 GitHub 问题。
示例输入：
```json
{
"owner": "OWNER",
"repo": "REPOSITORY",
"title": "示例问题",
"body": "通过 AgentGuard 创建的问题",
"labels": []
}
```
由于创建问题会修改外部系统，因此被视为高风险写操作。
在立即调用 GitHub 之前：
```text
代理请求
|
v
策略引擎
|
v
待审批
|
v
人工审查
/ \
拒绝 审批
|
v
执行 GitHub 操作
|
v
审计日志
```
---
## MCP 安全检查
代理卫士还包括安全检查，旨在识别潜在的不安全 MCP 工具行为和可疑的工具描述。
扫描器检查涉及以下模式：
- 忽略前面规则的指令
- 提示注入样式的指令
- 未授权的写行为
- 破坏性操作
- 任意命令执行
- 请求凭据、令牌或机密
- 过度宽泛的权限
- 可疑的权限提升
- 描述的行为与其预期权限不匹配的工具
这些检查有助于演示如何将 MCP 工具定义本身作为 AI 代理安全边界的一部分。
---
## 治理仪表盘
代理卫士包括一个 React 仪表盘，用于查看和管理治理系统。
仪表盘包含以下部分。
### 概述
显示高级别的治理信息，包括：
- 已注册的代理
- 已启用的工具
- 待审批的请求
- 审计事件
- 最近的工具活动
---
### 代理
查看已注册的 AI 代理，并管理每个代理允许使用的工具。
这实现了每个代理的最小权限工具访问。
---
### 工具
查看受管辖的工具及其配置，包括：
- 工具名称
- 类别
- 风险级别
- 操作类型
- 审批要求
- 已启用/禁用状态
---
### 审批队列
审查等待人工授权的高风险请求。
管理员可以：
```text
审批并执行
```
或：
```text
拒绝
```
已批准的请求将传递到工具执行层。
已拒绝的请求将阻止执行。
---
### 审计日志
查看受管辖的 AI 活动历史记录。
审计界面显示以下信息：
```text
时间戳
代理
工具
状态
风险
审批状态
执行结果
```
---
### 受管辖的工具运行器
仪表盘还包含一个工具运行器，可用于手动演示 AgentGuard 的治理流程。
用户可以选择：
```text
代理
工具
输入
```
并通过与 MCP 工具调用相同的治理层提交请求。
这使得演示以下内容变得容易：
```text
低风险请求
|
v
策略允许
|
v
执行
|
v
审计
```
和：
```text
高风险请求
|
v
策略需要审批
|
v
审批队列
```
---
## 架构
```text
AI 代理 / MCP 客户端
|
v
+----------------------+
| 代理卫士 MCP |
| 服务器 |
+----------+-----------+
|
v
+----------------------+
| 受管辖的执行器 |
+----------+-----------+
|
v
+----------------------+
| 策略引擎 |
+----------+-----------+
|
+--------------+--------------+
| |
v v
允许的请求 需要审批
| |
v v
工具执行 审批队列
| / \
| 拒绝 审批
| |
+----------------------------------+
|
v
外部工具/API
|
v
审计日志
```
React 仪表盘与 FastAPI 后端通信，以管理代理、权限、工具、审批、受管辖的执行和审计历史。
---
## 技术栈
### 后端
- Python
- FastAPI
- SQLAlchemy
- SQLite
- MCP Python SDK / FastMCP
- Pytest
- Requests
- GitHub REST API
- Google Gemini API
### 前端
- React
- TypeScript
- Vite
- Tailwind CSS
### 基础设施
- Docker
- Docker Compose
---
## 项目结构
```text
agentguard-mcp/
├── 后端/
│ ├── 应用/
│ │ ├── mcp_server/
│ │ ├── 策略/
│ │ ├── 路由/
│ │ ├── 服务/
│ │ ├── 工具服务器/
│ │ ├── main.py
│ │ ├── models.py
│ │ ├── schemas.py
│ │ └── seed.py
│ │
│ ├── 测试/
│ │ ├── test_ai_tools.py
│ │ ├── test_github_pr_tool.py
│ │ ├── test_github_tools.py
│ │ ├── test_policy_engine.py
│ │ └── test_tool_runner.py
│ │
│ ├── .env 示例
│ ├── Dockerfile
│ └── requirements.txt
│
├── 前端/
│ ├── public/
│ ├── src/
│ │ ├── App.tsx
│ │ ├── main.tsx
│ │ └── index.css
│ ├── Dockerfile
│ ├── package.json
│ └── package-lock.json
│
├── 文档/
├── mcp-server/
├── .gitignore
├── docker-compose.yml
└── README.md
```
---
# 快速入门
## 先决条件
确保已安装以下内容：
- Python 3
- Node.js
- npm
- Git
可选集成需要：
- GitHub 个人访问令牌
- Google Gemini API 密钥
---
## 后端设置
从项目根目录：
```bash
cd 后端
```
创建 Python 虚拟环境：
```bash
python3 -m venv .venv
```
在 macOS/Linux 上激活它：
```bash
source .venv/bin/activate
```
安装依赖项：
```bash
pip install -r requirements.txt
```
创建本地环境文件：
```bash
cp .env 示例 .env
```
启动后端：
```bash
uvicorn 应用.main:应用 --reload
```
API 将在以下位置可用：
```text
http://127.0.0.1:8000
```
FastAPI 文档可在以下位置访问：
```text
http://127.0.0.1:8000/docs
```
本地 SQLite 数据库将在后端启动时自动创建和初始化。
---
## 前端设置
打开另一个终端并导航到前端：
```bash
cd 前端
```
安装依赖项：
```bash
npm install
```
启动开发服务器：
```bash
npm run dev
```
仪表盘将在以下位置可用：
```text
http://localhost:5173
```
---
## MCP 服务器
要运行 MCP 服务器，请激活后端环境：
```bash
cd 后端
source .venv/bin/activate
```
然后运行：
```bash
python -m 应用.mcp_server.server
```
MCP 端点单独运行，与主 FastAPI 应用程序分开。
---
# 环境变量
本地环境配置存储在：
```text
后端/.env
```
示例：
```env
ENVIRONMENT=开发
DATABASE_URL=sqlite:///./agentguard.db
GITHUB_TOKEN=
GEMINI_API_KEY=
GEMINI_MODEL=gemini-2.5-flash
```
## GitHub 令牌
GitHub 令牌对于身份验证的 GitHub 操作是必需的，特别是对于诸如创建问题之类的写操作。
请勿将您的真实令牌提交到 GitHub。
---
## Gemini
Gemini 是可选的。
配置后，它可用于诸如拉取请求摘要和测试计划生成之类的 AI 驱动工具。
应用程序在未配置或无法使用 Gemini 时包含备用行为。
---
# 测试
后端包含一个自动化的 Pytest 测试套件。
当前测试文件包括：
```text
test_ai_tools.py
test_github_pr_tool.py
test_github_tools.py
test_policy_engine.py
test_tool_runner.py
```
测试涵盖的领域包括：
- 策略引擎决策
- 代理权限
- 工具授权
- 受管辖的工具执行
- GitHub 问题工具
- GitHub 拉取请求摘要
- AI 工具行为和备用行为
从后端目录运行测试：
```bash
cd 后端
source .venv/bin/activate
pytest -v
```
当前套件包含：
```text
22 个通过的测试
```
---
# 示例治理演示
一种有用的演示 AgentGuard 的方法是比较只读请求和写请求。
## 低风险示例
运行：
```text
read_github_issue
```
预期治理流程：
```text
代理请求
|
v
权限检查
|
v
策略允许
|
v
GitHub 读取
|
v
审计日志
```
---
## 高风险示例
运行：
```text
create_github_issue
```
预期治理流程：
```text
代理请求
|
v
权限检查
|
v
策略引擎
|
v
需要审批
|
v
审批队列
```
此时尚未发生 GitHub 写操作。
在人类选择：
```text
审批并执行
```
后，操作继续：
```text
审批
|
v
GitHub 问题创建
|
v
审计日志
```
这演示了 AgentGuard 的核心目的：允许 AI 代理使用实用工具，而不自动给予它们无限制的权限。
---
# 当前范围
AgentGuard MCP 是一个 **产品质量的治理 MVP**，旨在演示 AI 代理安全性和 MCP 治理概念。
当前实现演示了：
- 模型上下文协议工具暴露
- 特定于代理的权限
- 最小权限访问
- 基于风险的策略决策
- 人工审批
- GitHub 工具集成
- AI 辅助分析
- 安全扫描
- 工具调用审计
- 基于 React 的治理管理
- 自动后端测试
---
## 未来的生产改进
生产部署可以通过以下方式扩展平台：
- 用户身份验证
- 基于角色的访问控制
- 多租户组织支持
- PostgreSQL
- 数据库迁移
- 加密的秘密存储
- GitHub 应用程序或 OAuth 身份验证
- 不变审计存储
- 速率限制
- 分布式跟踪
- 指标和可观察性
- 生产部署配置
- 更全面的集成测试
- 前端组件测试
---
## 为什么选择 AgentGuard？
当 AI 代理可以与真实系统交互时，它们会变得更加强大。
这也意味着他们的行为需要治理。
AgentGuard 探索一个简单的原则：
> **代理应该只拥有他们需要的权限，高风险操作应该需要监督，并且每个工具调用都应该可审计。**
该项目演示了如何将 MCP 与传统的最小特权、安全策略、人工审批和审计日志等安全概念相结合，以构建更安全的 AI 代理工作流。
