capiscio/capiscio-mcp-python
GitHub: capiscio/capiscio-mcp-python
为 Model Context Protocol 工具提供身份验证、授权控制和审计日志的安全框架。
Stars: 1 | Forks: 0
# CapiscIO MCP Guard
Model Context Protocol 服务器的工具级安全保护。
[](https://badge.fury.io/py/capiscio-mcp)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/Apache-2.0)
**MCP Guard** 为 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 工具调用提供信任徽章和身份验证。它实现了：
- **RFC-006**：MCP 工具授权与证据
- **RFC-007**：MCP 服务器身份披露与验证
## 安装
```
pip install capiscio-mcp
```
MCP SDK 集成（FastMCP 包装器）：
```
pip install capiscio-mcp[mcp]
```
## 为什么选择 MCP Guard？
MCP 服务器向自主代理暴露强大的工具——文件系统、数据库、API。但 MCP 本身没有定义如何：
- **认证**哪个代理在调用工具
- **授权**该代理是否有权访问
- **审计**发生了什么以供事后审查
MCP Guard 解决这一问题：
| 功能 | 描述 |
|---------|-------------|
| **@guard 装饰器** | 使用信任级别要求保护工具 |
| **证据日志** | 每次调用的加密审计追踪 |
| **服务器身份** | 连接前验证 MCP 服务器 |
| **服务器注册** | 生成密钥对并注册服务器 DID |
| **信任级别** | 0（自签名）→ 4（扩展验证） |
## 快速入门 1：服务端（工具保护）
使用信任级别要求保护您的 MCP 工具：
```
from capiscio_mcp import guard
@guard(min_trust_level=2)
async def read_database(query: str) -> list[dict]:
"""Only agents with Trust Level 2+ can execute this tool."""
# ... database query logic
pass
# 同步版本可用
from capiscio_mcp import guard_sync
@guard_sync(min_trust_level=2)
def read_database_sync(query: str) -> list[dict]:
pass
```
### 完整配置
```
from capiscio_mcp import guard, GuardConfig
config = GuardConfig(
min_trust_level=2,
trusted_issuers=["did:web:registry.capisc.io"],
allowed_tools=["read_*", "list_*"],
require_badge=True, # Deny anonymous access
)
@guard(config=config)
async def execute_query(sql: str) -> list[dict]:
pass
```
## 快速入门 2：客户端（服务器验证）
验证您连接的 MCP 服务器的身份：
```
from capiscio_mcp import verify_server, ServerState
result = await verify_server(
server_did="did:web:mcp.example.com",
server_badge="eyJhbGc...",
transport_origin="https://mcp.example.com",
)
if result.state == ServerState.VERIFIED_PRINCIPAL:
print(f"Trusted server at Level {result.trust_level}")
elif result.state == ServerState.DECLARED_PRINCIPAL:
print("Server identity declared but not verified")
elif result.state == ServerState.UNVERIFIED_ORIGIN:
print("Warning: Server did not disclose identity")
```
## 快速入门 3：服务器注册
在 CapiscIO 注册表中注册您的 MCP 服务器身份：
```
from capiscio_mcp import setup_server_identity
# 一步设置：生成密钥 + 注册到注册表
result = await setup_server_identity(
server_id="550e8400-e29b-41d4-a716-446655440000", # From dashboard
api_key="sk_live_...", # Registry API key
ca_url="https://registry.capisc.io", # Optional, defaults to production
output_dir="./keys",
)
print(f"Server DID: {result['did']}")
# did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
print(f"Private key saved to: {result['private_key_path']}")
```
### 分步注册
```
from capiscio_mcp import generate_server_keypair, register_server_identity
# 步骤 1：生成密钥对
keys = await generate_server_keypair(output_dir="./keys")
# 步骤 2：注册到注册表
await register_server_identity(
server_id="550e8400-e29b-41d4-a716-446655440000",
api_key="sk_live_...",
did=keys["did_key"],
public_key=keys["public_key_pem"],
ca_url="https://registry.capisc.io", # Optional, defaults to production
)
```
## MCP SDK 集成
要与官方 [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 无缝集成，请使用 `mcp` 扩展安装：
```
pip install capiscio-mcp[mcp]
```
### 使用 FastMCP 包装器的服务器
创建具有内置信任执行的 MCP 服务器：
```
from capiscio_mcp.integrations.mcp import CapiscioMCPServer
server = CapiscioMCPServer(
name="filesystem",
did="did:web:mcp.example.com:servers:filesystem",
badge="eyJhbGc...", # From CapiscIO registry
)
@server.tool(min_trust_level=2)
async def read_file(path: str) -> str:
"""Only agents with Trust Level 2+ can read files."""
with open(path) as f:
return f.read()
@server.tool(min_trust_level=0)
async def list_files(directory: str) -> list[str]:
"""Any authenticated agent can list files."""
import os
return os.listdir(directory)
# 运行服务器（stdio 传输）
server.run()
```
### 具有信任验证的客户端
通过 stdio 传输连接到 MCP 服务器：
```
from capiscio_mcp.integrations.mcp import CapiscioMCPClient
async with CapiscioMCPClient(
command="python",
args=["my_mcp_server.py"],
min_trust_level=1,
badge="eyJhbGc...", # Your client badge
) as client:
# List available tools
tools = await client.list_tools()
print(f"Available tools: {[t['name'] for t in tools]}")
# Call a tool
result = await client.call_tool("read_file", {"path": "/data/config.json"})
print(result)
```
## MCPServerIdentity.connect() — "Let's Encrypt" 风格设置
一次调用即可注册您的 MCP 服务器并获取徽章：
```
from capiscio_mcp import MCPServerIdentity
identity = await MCPServerIdentity.connect(
server_id="550e8400-...", # From the dashboard
api_key="sk_live_...",
)
print(identity.did) # did:web:registry.capisc.io:servers:550e8400-...
print(identity.badge) # Current badge JWS (auto-issued)
```
### 使用环境变量
```
identity = await MCPServerIdentity.from_env()
```
| 变量 | 必填 | 描述 |
|----------|----------|-------------|
| `CAPISCIO_SERVER_ID` | 是 | 仪表板中的服务器 UUID |
| `CAPISCIO_API_KEY` | 是 | 注册表 API 密钥 |
| `CAPISCIO_SERVER_URL` | 否 | 注册表 URL（默认：生产环境） |
| `CAPISCIO_SERVER_DOMAIN` | 否 | 徽章颁发的域名 |
| `CAPISCIO_SERVER_PRIVATE_KEY_PEM` | 否 | 临时环境的 PEM 编码 Ed25519 私钥 |
### 部署到容器/无服务器环境
在临时环境（Docker、Lambda、Cloud Run）中，本地 `~/.capiscio/` 目录
无法在重启后保留。首次运行时 SDK 会生成密钥对并记录捕获提示：
```
╔══════════════════════════════════════════════════════════╗
║ New server identity generated — save key for persistence ║
╚══════════════════════════════════════════════════════════╝
Add to your secrets manager / .env:
CAPISCIO_SERVER_PRIVATE_KEY_PEM='-----BEGIN PRIVATE KEY-----\nMC4C...\n-----END PRIVATE KEY-----\n'
```
将该值复制到您的密钥管理器并设置为环境变量。
后续启动时 SDK 将恢复相同的 DID，而不会生成新身份。
**密钥解析优先级：** 环境变量 → 本地文件 → 生成新密钥。
```
# docker-compose.yml
services:
mcp-server:
environment:
CAPISCIO_SERVER_ID: "550e8400-..."
CAPISCIO_API_KEY: "sk_live_..."
CAPISCIO_SERVER_PRIVATE_KEY_PEM: "${MCP_SERVER_KEY}" # from secrets
```
请参阅[部署指南](https://docs.capisc.io/mcp-guard/guides/deployment/)获取完整示例。
## 核心连接模式
MCP Guard 连接到 capiscio-core 进行加密操作：
### 嵌入式模式（默认）
SDK 自动下载并管理核心二进制文件：
```
pip install capiscio-mcp
# 直接可用！首次使用时下载二进制文件。
```
### 外部模式
连接到单独管理的核心服务：
```
# 在另一个终端启动 core
capiscio mcp serve --listen localhost:50051
# SDK 连接到外部 core
export CAPISCIO_CORE_ADDR="localhost:50051"
```
## 信任级别
根据 RFC-002 v1.4：
| 级别 | 名称 | 验证 | 使用场景 |
|-------|------|-------------|----------|
| 0 | 自签名 (SS) | 无，`did:key` 签发者 | 本地开发、测试、演示 |
| 1 | 已注册 (REG) | 账户注册 | 开发、内部代理 |
| 2 | 域名验证 (DV) | DNS/HTTP 挑战 | 生产环境、B2B 代理 |
| 3 | 组织验证 (OV) | DUNS/法律实体 | 高信任生产环境 |
| 4 | 扩展验证 (EV) | 人工审查 + 法律 | 受监管行业 |
## 证据日志
每个工具调用——允许或拒绝——都会产生一条证据记录：
```
from capiscio_mcp import guard, GuardError
@guard(min_trust_level=2)
async def sensitive_operation(data: dict) -> dict:
pass
try:
result = await sensitive_operation(data={"key": "value"})
except GuardError as e:
# Evidence logged even on denial
print(f"Denied: {e.reason}")
print(f"Evidence ID: {e.evidence_id}") # For audit trail
```
证据包括：
- 工具名称和参数哈希（不是原始参数——保护 PII）
- 调用者身份（代理 DID、徽章 JTI、认证级别）
- 决策和原因
- 时间戳和唯一证据 ID
## 配置参考
### GuardConfig
```
from capiscio_mcp import GuardConfig
config = GuardConfig(
min_trust_level=2, # Minimum trust level (0-4)
accept_level_zero=False, # Accept self-signed badges?
trusted_issuers=[ # List of trusted issuer DIDs
"did:web:registry.capisc.io",
],
allowed_tools=[ # Glob patterns for allowed tools
"read_*",
"list_*",
],
require_badge=True, # Deny anonymous/API key access
policy_version="v1.0", # Policy version for tracking
)
```
### VerifyConfig
```
from capiscio_mcp import VerifyConfig
config = VerifyConfig(
trusted_issuers=[...], # Trusted issuer DIDs
min_trust_level=2, # Minimum required level
accept_level_zero=False, # Accept self-signed servers?
offline_mode=False, # Skip revocation checks?
skip_origin_binding=False, # Skip host/path binding?
)
```
## 环境变量
| 变量 | 描述 | 默认值 |
|----------|-------------|---------|
| `CAPISCIO_SERVER_ID` | 服务器 UUID（用于 `MCPServerIdentity`） | — |
| `CAPISCIO_API_KEY` | 注册表 API 密钥（用于 `MCPServerIdentity`） | — |
| `CAPISCIO_SERVER_URL` | 注册表服务器 URL | `https://registry.capisc.io` |
| `CAPISCIO_SERVER_DOMAIN` | 徽章颁发的域名 |（从服务器 URL 派生）|
| `CAPISCIO_SERVER_PRIVATE_KEY_PEM` | PEM 编码的 Ed25519 私钥（临时环境） | — |
| `CAPISCIO_CORE_ADDR` | 外部核心地址 |（嵌入式模式）|
| `CAPISCIO_SERVER_ORIGIN` | guard 使用的服务器来源 |（自动检测）|
| `CAPISCIO_LOG_LEVEL` | 日志详细程度 | `info` |
## API 参考
### Guard (RFC-006)
- `guard(config=None, min_trust_level=None, tool_name=None)` — 异步装饰器
- `guard_sync(...)` — 同步装饰器
- `evaluate_tool_access(tool_name, params, credential, config)` — 底层 API
- `compute_params_hash(params)` — 确定性参数哈希
- `GuardConfig` — 配置数据类
- `GuardResult` — 评估结果数据类
- `GuardError` — 拒绝访问的异常
### 服务器 (RFC-007)
- `verify_server(server_did, server_badge, transport_origin, endpoint_path, config)` — 异步验证
- `verify_server_sync(...)` — 同步验证
- `verify_server_strict(...)` — 任何验证失败时抛出 ServerVerifyError
- `parse_http_headers(headers)` — 从 HTTP 头提取身份
- `parse_jsonrpc_meta(meta)` — 从 MCP _meta 提取身份
- `VerifyConfig` — 配置数据类
- `VerifyResult` — 验证结果数据类
- `ServerVerifyError` — 验证失败的异常
### 注册（服务器身份）
- `generate_server_keypair(key_id, output_dir)` — 生成 Ed25519 密钥对
- `generate_server_keypair_sync(...)` — 同步版本
- `register_server_identity(server_id, api_key, did, public_key, ca_url)` — 向注册表注册 DID
- `register_server_identity_sync(...)` — 同步版本
- `setup_server_identity(server_id, api_key, ca_url, output_dir, key_id)` — 组合设置
- `setup_server_identity_sync(...)` — 同步版本
- `RegistrationError` — 注册失败的异常
- `KeyGenerationError` — 密钥生成失败的异常
### 类型
- `Decision` — ALLOW / DENY
- `AuthLevel` — ANONYMOUS / API_KEY / BADGE
- `DenyReason` — 拒绝原因枚举
- `TrustLevel` — RFC-002 规定的信任级别 0-4
- `ServerState` — VERIFIED_PRINCIPAL / DECLARED_PRINCIPAL / UNVERIFIED_ORIGIN
- `ServerErrorCode` — 验证错误代码枚举
### MCP SDK 集成（可选）
需要 `pip install capiscio-mcp[mcp]`：
- `CapiscioMCPServer(name, did, badge,)` — 具有信任执行的 FastMCP 包装器
- `CapiscioMCPServer.tool(min_trust_level=...)` — 受保护工具的装饰器
- `CapiscioMCPServer.run(transport="stdio")` — 运行服务器
- `CapiscioMCPClient(command, args, ...)` — 用于 stdio 传输的客户端*
- `CapiscioMCPClient.call_tool(name, args)` — 在服务器上调用工具
- `CapiscioMCPClient.list_tools()` — 列出可用工具
*注意：`CapiscioMCPClient` 中的服务器身份验证需要 MCP SDK 支持在 initialize 响应中传递 `_meta`。目前尚不可用，因此 `min_trust_level` 和 `fail_on_unverified` 参数目前不生效。通过 `@server.tool(min_trust_level=...)` 的服务端信任执行完全可用。
## 文档
- [RFC-006：MCP 工具授权与证据](https://docs.capisc.io/rfcs/006)
- [RFC-007：MCP 服务器身份披露](https://docs.capisc.io/rfcs/007)
- [服务器注册指南](https://docs.capisc.io/mcp-guard/guides/server-registration)
- [服务端指南](https://docs.capisc.io/mcp-guard/guides/server-side)
- [客户端指南](https://docs.capisc.io/mcp-guard/guides/client-side)
- [证据日志指南](https://docs.capisc.io/mcp-guard/guides/evidence)
## 开发
```
# 克隆仓库
git clone https://github.com/capiscio/capiscio-mcp-python.git
cd capiscio-mcp-python
# 安装开发依赖
pip install -e ".[dev]"
# 运行测试
pytest -v
# 运行带覆盖率的测试
pytest --cov=capiscio_mcp --cov-report=html
# 类型检查
mypy capiscio_mcp
# 代码检查
ruff check capiscio_mcp
```
## 许可证
Apache License 2.0
## 贡献
请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
标签：API安全, DID, FastMCP, JSONLines, JSON输出, MCP, Model Context Protocol, Python, RFC-006, RFC-007, 代理安全, 信任等级, 加密审计, 去中心化标识符, 审计日志, 密钥对, 工具安全, 工具级别安全, 授权, 无后门, 无线安全, 服务器注册, 服务器身份, 网络安全, 自主代理安全, 证据日志, 隐私保护, 零信任