内容
# MCPShield
模型上下文协议（MCP）的安全代理。位于您的AI代理和MCP工具服务器之间，实时检查每个工具调用是否存在秘密和策略违规。
## 工作原理
```
AI 代理 → MCPShield (:4444) → MCP 服务器
↓
秘密检测
策略执行
审计日志
```
请求 **和** 响应都会被扫描。违规行为会在到达上游服务器之前被阻止。
## 检测内容
| 模式 | 示例 |
|---------|---------|
| 已知凭证 | AWS 密钥、GitHub令牌、OpenAI/Anthropic 密钥、GCP API 密钥、Stripe 直播密钥 |
| 私钥 | RSA、EC、OpenSSH PEM 块 |
|令牌 | JWT |
| 未知秘密 | 通过香农熵评分的高熵字符串 |
## 操作
| 规则匹配 | 操作 |
|------------|--------|
| 已知凭证 | 阻止 — 返回 JSON-RPC 错误，上游从未调用 |
| JWT / 高熵 | 标记 — 允许通过，记录为警告 |
## 快速入门
**1. 克隆和安装**
```bash
git clone https://github.com/yourhandle/mcpshield
cd mcpshield
pip install -e .
```
**2. 配置上游 MCP 服务器**
```yaml
# config.yaml
proxy:
host: "127.0.0.1"
port: 4444
upstream:
url: "http://localhost:3000" # 您的 MCP 服务器
```
**3. 从项目根目录运行**
```bash
# 必须从存储库根目录运行，config.yaml 位于此处
python -m mcpshield
```
代理在 `http://127.0.0.1:4444` 处运行。指向您的 AI 代理或 Claude Desktop 这里，而不是直接指向您的 MCP 服务器。
## 测试
**阻止的秘密：**
```bash
curl -s -X POST http://127.0.0.1:4444 \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "write_file",
"arguments": {"content": "key=AKIAIOSFODNN7EXAMPLE"}
}
}' | jq
```
预期响应：
```json
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32600,
"message": "Detected 'aws_access_key' in method=tools/call. Request blocked."
}
}
```
**干净的请求（代理通过）：**
```bash
curl -s -X POST http://127.0.0.1:4444 \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | jq
```
## 运行测试
```bash
pip install -e ".[dev]"
pytest tests/ -v
```
## 架构
参见 [ARCHITECTURE.md](ARCHITECTURE.md) 了解传输（HTTP + stdio）、策略管道和会话污染。
**stdio 模式**（Claude Desktop / Cursor）：
```bash
cp config.yaml.example config.yaml
# 设置 upstream.command / upstream.args 和 taint.enabled
python -m mcpshield stdio
```
## 路线图
- [x] 第 1 周：具有实时秘密检测的透明代理
- [x] 第 2 周：策略即配置、PII 检测、编辑
- [x] 第 3 周：会话级污染传播（v1，内存中）
- [ ] 第 4 周：审计仪表盘
## 贡献
欢迎模式贡献 — 将检测规则添加到 `mcpshield/detectors/secrets.py` 并打开一个 PR。
