Hi MCP Filter

MCP响应筛选器代理

位于Azure API管理和模型上下文协议（MCP）服务器之间的代理服务器，用于过滤和修改MCP响应。

特性

• 响应过滤：基于模式匹配和删除/允许响应的声明性规则
• 响应转换：使用JSONata表达式修改响应内容
• 自定义插件：为特定领域的业务逻辑编写JavaScript插件
• 热重新加载：更新配置而不重新启动代理
• 容器原生：Docker/AKS/Azure容器应用程序就绪
• 生产就绪：健康检查、指标、日志记录、优雅关机
• 苏格兰和南方能源公司运输：返回服务器发送事件（SSE）的代理MCP服务器

快速开始

先决条件

• Node.js 20.x LTS
• npm或纱线

本地开发

# Install dependencies
npm install

# Run in development mode
npm run dev
# Test the server
curl http://localhost:8080/health
curl http://localhost:8080/metrics
curl http://localhost:8080/config

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

为生产而建

npm run build
npm start

码头工人

# Build Docker image
docker build -f docker/Dockerfile -t hi-mcp-filter:latest .

# Run locally with Docker Compose
docker-compose -f docker/docker-compose.yml up

配置

配置文件位于 config/ 目录：

• proxy.example.json -代理服务器设置
• filters.example.json -筛选规则
• transforms.example.json -转换规则

复制示例文件并根据需要进行修改：

cp config/proxy.example.json config/proxy.json
cp config/filters.example.json config/filters.json
cp config/transforms.example.json config/transforms.json

苏格兰和南方能源公司运输

代理可以自动检测SSE响应或强制每个后端进行SSE。看 docs/sse-transport.md 有关配置选项、示例和指标。

API终点

健康检查

GET /health

返回代理健康状态（活性检查）。

代理终结点

POST /proxy/:serverId
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "request-id",
  "method": "tool_call",
  "params": {}
}

将请求转发到指定的MCP服务器，并返回经过筛选/转换的响应。

当后端使用SSE时，代理提取JSON-RPC有效载荷并向客户端返回标准JSON。

建筑

src/
├── proxy/          # HTTP server and request routing
├── mcp/            # MCP protocol validation
├── filter/         # Declarative filter engine
├── transform/      # Response transformation engine
├── plugin/         # Custom plugin loader and execution
├── config/         # Configuration management and hot-reload
└── common/         # Shared utilities (logging, metrics, errors)

tests/
├── unit/           # Component-level tests
├── integration/    # End-to-end proxy flow tests
└── fixtures/       # Test data

开发指南

添加筛选规则

过滤规则使用JSONPath表达式来匹配响应模式。例子：

{
  "id": "block-dangerous-tool",
  "name": "Block dangerous_tool responses",
  "enabled": true,
  "condition": {
    "field": "$.result.content[0].name",
    "operator": "equals",
    "value": "dangerous_tool"
  },
  "action": "drop",
  "composition": "NONE",
  "priority": 1
}

编写自定义插件

插件是实现过滤或转换逻辑的JavaScript模块：

// plugins/my-plugin.js
module.exports = {
  name: 'my-plugin',
  version: '1.0.0',

  async filter(context) {
    const { request, response, logger } = context;
    
    // Custom filtering logic
    if (shouldBlock(response)) {
      return {
        action: 'drop',
        reason: 'Matched custom filter',
      };
    }

    return {
      action: 'allow',
      reason: 'Passed custom filter',
    };
  },

  async transform(context) {
    const { response, logger } = context;

    // Custom transformation logic
    return modifyResponse(response);
  },
};

测试

测试分为两类：

• 单元测试：过滤器、转换、插件和配置模块的组件级测试
• 集成测试：完整代理流的端到端测试

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run specific test file
npm test tests/unit/filter/rule-matcher.test.ts

# Watch mode
npm run test:watch

部署

Azure容器应用

# Create container registry
az acr create --resource-group mygroup --name myregistry --sku Basic

# Build and push image
docker build -f docker/Dockerfile -t myregistry.azurecr.io/hi-mcp-filter:latest .
docker push myregistry.azurecr.io/hi-mcp-filter:latest

# Deploy to Container Apps
az containerapp create \
  --resource-group mygroup \
  --name hi-mcp-filter \
  --image myregistry.azurecr.io/hi-mcp-filter:latest \
  --environment myenv \
  --ingress external \
  --target-port 8080

Azure Kubernetes服务（AKS）

看 quickstart.md 了解详细的AKS部署说明。

许可证

麻省理工学院

支持

对于问题或疑问，请在项目存储库上打开问题。