APort策略门示例-MCP服务器
示例MCP服务器，演示了使用以下命令对AI代理工具调用执行APort策略 简单模式 （护照检查+保单验证）。
备注：此示例使用简单模式，适用于内部工具和开发环境。第2个月将为企业/外部工具添加安全模式（具有SCA要求）。
特性
- 🔐 在工具执行之前使用APort执行策略（简单模式）
- 🛠️ 两个示例工具：
merge_pull_request和process_refund - ✅ 延迟\>MCP Server: merge_pull_request(agent_id, repo, pr_number)
Note over MCP Server: Extract agent_id from request MCP Server->>APort: POST /api/verify/policy/code.repository.merge.v1 Note over APort: 1. Verify passport exists Note over APort: 2. Evaluate policy locally APort-->>MCP Server: { allow: true, decision_id: "dec_..." } MCP Server->>Tool: Execute merge (policy approved) Tool-->>MCP Server: Success MCP Server-->>Claude: ✅ PR merged (decision_id: dec_...)
## 策略执行（简单模式）
每个工具调用都受到使用简单模式的APort策略的保护：
**端点**: `/api/verify/policy/{pack_id}`
**安全流程**:
1. 提取 `agent_id` 从请求上下文
1. 验证护照是否存在并且处于活动状态
1. 在本地评估策略（\<20ms）
1. 返回允许/拒绝决定
**用例**：内部工具、开发环境、CI/CD管道、可信代理
### `merge_pull_request` → `code.repository.merge.v1`
- 需要能力： `code.repository.merge` 或 `repo.pr.create` + `repo.merge`
- 最低保证等级：L2
- 验证：存储库访问、分支保护、PR大小限制
### `process_refund` → `finance.payment.refund.v1`
- 需要能力： `finance.payment.refund`
- 最低保证等级：L2
- 验证：金额限制、货币支持、每日上限、原因代码
**何时升级到安全模式** （第2个月）：
- 外部MCP服务器（来自组织外部的工具）
- 需要加密证明的支付处理器
- 带有PII/敏感数据的数据导出
- 具有监管要求的企业API
## 示例：策略拒绝
User: Process a $100,000 refund for order 123
Claude: I'll process that refund... [Policy check fails] ❌ Policy denied: Amount exceeds daily cap of $50,000 Decision ID: dec_0987654321
## 环境变量
- `APORT_BASE_URL`：A端口注册表URL（默认值： `https://api.aport.io`)
- `APORT_TIMEOUT_MS`：请求超时（毫秒）（默认值： `5000`)
## 本地开发
Clone repo
git clone https://github.com/aporthq/mcp-policy-gate-example.git cd mcp-policy-gate-example
Install dependencies
npm install
Build TypeScript
npm run build
Run locally
npm start
Or run in dev mode with auto-reload
npm run dev
## 带护照的MCP客户端（US-1.2.2）
这个例子包括 **客户端** 展示如何将代理护照附加到MCP工具调用的示例。这是向MCP服务器进行工具调用的代理。
### 主要特点
- ✅ **行动前政策验证**：在使用调用MCP工具之前验证策略 `verifyPolicy()`
- ✅ **自动护照附件**：代理ID会自动添加到工具调用参数中
- ✅ **策略拒绝处理**：调整参数或升级后的优雅重试
- ✅ **错误处理**：使用审计跟踪进行全面的错误处理
- ✅ **框架集成**：OpenAI、Anthropic和自定义MCP客户端的示例
- ✅ **已发布SDK**：用途 `@aporthq/sdk-node` （npm）和 `aporthq-sdk-python` （PyPI）
### 快速入门（TypeScript）
**安装依赖项：**
npm install @aporthq/sdk-node @modelcontextprotocol/sdk
**用途：**
import { MCPClientWithPassport } from './src/client-example'; import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'; import { APortClient } from '@aporthq/sdk-node';
// Initialize APort client (uses published SDK) const aportClient = new APortClient({ baseUrl: 'https://api.aport.io', });
const transport = new StdioClientTransport({ command: 'npx', args: ['@aporthq/mcp-policy-gate-example'], });
const client = new MCPClientWithPassport('ap_your_agent_id', transport); await client.connect(transport);
// Call tool - policy is verified FIRST, then tool executes const result = await client.callTool( 'merge_pull_request', { repository: 'my-org/my-repo', pr_number: 123, base_branch: 'main', }, { retryOnDenial: false, maxRetries: 3, } );
console.log(result); // Policy verification happens automatically before tool execution
### 快速入门（Python）
**安装依赖项：**
pip install aporthq-sdk-python
**用途：**
from client_example import MCPClientWithPassport from aporthq_sdk_python import APortClient, APortClientOptions
Initialize APort client (uses published SDK)
aport_client = APortClient(APortClientOptions( base_url='https://api.aport.io', ))
async with MCPClientWithPassport('ap_your_agent_id') as client: # Call tool - policy is verified FIRST, then tool executes result = await client.call_tool( 'merge_pull_request', { 'repository': 'my-org/my-repo', 'pr_number': 123, 'base_branch': 'main', }, retry_on_denial=False, max_retries=3, )
print(result) # Policy verification happens automatically before tool execution
### 策略验证流程
客户端在每次工具调用之前验证策略：
// Each call verifies policy first, then executes tool await client.callTool('merge_pull_request', { repository: 'my-org/my-repo', pr_number: 123, }); // Flow: 1. Verify policy (code.repository.merge.v1) // 2. If allowed, call MCP tool with agent_id // 3. Return result with decision_id
### 策略拒绝处理
客户端可以使用调整后的参数自动重试：
// Automatic retry with reduced amount await client.callTool( 'process_refund', { amount: 1000000 }, // $10,000 { retryOnDenial: true, // Retry if denied maxRetries: 3, } ); // If denied, automatically retries with amount: 500000, then 250000
### 集成示例
#### OpenAI函数调用
看 [`openai-integration-example.py`](./openai-integration-example.py) 一个完整的例子展示了如何将MCP客户端与OpenAI的函数调用API集成。
from openai_integration_example import OpenAIWithMCPPassport
wrapper = OpenAIWithMCPPassport('ap_your_agent_id')
OpenAI function calls are automatically routed to MCP tools with passport
response = await wrapper.chat_completion_with_tools( messages=[{"role": "user", "content": "Refund $50 to customer_123"}], functions=[...], )
#### 人工工具使用
看 [`anthropic-integration-example.py`](./anthropic-integration-example.py) 一个完整的例子显示如何集成MCP客户端与Anthropic的工具使用API。
from anthropic_integration_example import AnthropicWithMCPPassport
wrapper = AnthropicWithMCPPassport('ap_your_agent_id')
Anthropic tool use is automatically routed to MCP tools with passport
response = await wrapper.messages_with_tools( messages=[{"role": "user", "content": "Merge PR #123"}], tools=[...], )
### 运行客户端示例
#### TypeScript
Run client examples
npm run build node dist/client-example.js
Or with tsx
npx tsx src/client-example.ts
#### python
Install dependencies
pip install aporthq-sdk-python mcp
Run client examples
python client_example.py
Run OpenAI integration example
python openai-integration-example.py
Run Anthropic integration example
python anthropic-integration-example.py
### 最佳实践
1. **始终附加agent_id**：客户端自动连接 `agent_id` 所有工具调用
1. **处理政策拒绝**：使用 `retryOnDenial` 对于可以使用调整后的参数重试的操作
1. **缓存护照**：客户端缓存护照以减少API调用
1. **记录决策**：始终记录审核跟踪的决策ID
1. **错误处理**：对网络错误实施优雅降级
### 错误处理
try { const result = await client.callTool('process_refund', {...}); } catch (error) { if (error instanceof PolicyDeniedError) { // Policy denied - escalate to human or retry with lower amount console.error('Policy denied:', error.message); console.error('Decision ID:', error.result.decision_id); } else { // Network or other error console.error('Error:', error); } }
## 与其他MCP客户端集成
### VS代码（临床扩展）
添加到settings.json：
{ "cline.mcpServers": { "aport-protected-tools": { "command": "npx", "args": ["@aporthq/mcp-policy-gate-example"] } } }
### 自定义MCP客户端
import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const transport = new StdioClientTransport({ command: 'npx', args: ['@aporthq/mcp-policy-gate-example'], });
const client = new Client({ name: 'my-client', version: '1.0.0', }, { capabilities: {}, });
await client.connect(transport);
// Call tool (agent_id required) const result = await client.request({ method: 'tools/call', params: { name: 'merge_pull_request', arguments: { agent_id: 'ap_a2d10232c6534523812423eec8a1425c', repository: 'my-org/my-repo', pr_number: 123, base_branch: 'main', }, }, });
console.log(result);
## 文件结构
mcp-policy-gate-example/ ├── src/ │ ├── index.ts # MCP server (policy enforcement) │ └── client-example.ts # MCP client (passport attachment) ├── client_example.py # Python MCP client ├── openai-integration-example.py # OpenAI integration ├── anthropic-integration-example.py # Anthropic integration ├── README.md # This file └── package.json
## 许可证
麻省理工学院