MCP Facade

MCP Facade

强大的 Facade 服务，提供统一接口，用于管理和交互多个 MCP（Machine Conversation Protocol）服务。它作为 Agent 与各种 MCP 服务通信的单一入口，同时提供可靠的身份验证和访问控制。

目录

• 功能
• 安装
• 配置
• API 文档
  • 服务管理
  • 工具管理
  • 访问控制
  • MCP 协议
• 身份验证
• 示例

功能

• 统一访问入口：为多个 MCP 服务提供单一接口
• 服务管理：注册、更新和管理多个 MCP 服务
• 工具管理：发现并使用所有已注册服务中的工具
• 身份验证：基于 JWT 的身份验证，支持细粒度访问控制
• 访问规则：可在工具级别配置访问规则
• 运行状况监控：内置运行状况检查端点
• 数据库后端：使用 PostgreSQL 存储服务配置和访问规则

在本地运行

运行 MCP 服务（示例）

注意：如果已有 MCP 服务，可跳过此步骤。

cd mcp-facade/mcp-servers

uv sync
source .venv/bin/activate
uv pip install -e .

# start mcp servers
uv run src/mcp_servers/main.py

运行 MCP facade

# Clone the repository
git clone https://github.com/yourusername/mcp-facade.git
cd mcp-facade/mcp-facade

# Install dependencies
pnpm i

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Start the service
pnpm dev

添加配置

# add echo 
curl -X POST http://localhost:3001/api/mcp/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "echo",
    "url": "http://127.0.0.1:3003/echo/mcp"
  }'

# add math
curl -X POST http://localhost:3001/api/mcp/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "math",
    "url": "http://127.0.0.1:3003/math/mcp"
  }'

与 oap-langgraph-tools-agent 搭配使用

# clone fork (with disabled auth)
git clone [email protected]:DmitryBe/oap-langgraph-tools-agent.git
cd oap-langgraph-tools-agent

# install deps 
uv sync
source .venv/bin/activate

# run langfraph server locally
langgraph dev

# open url
open https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024

# create assistant with configuration
MCPConfig
    url: http://localhost:3000/api
    tools: echo, add, subtract, multiply, divide

# start a thread by asking somehting like: compute 2 * 5 - 3

API 文档

服务管理

通过以下端点管理 MCP 服务：

列出所有服务

curl http://localhost:3001/api/mcp/servers | jq .

按名称获取服务

curl http://localhost:3001/api/mcp/servers/echo | jq .

创建服务

curl -X POST http://localhost:3001/api/mcp/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "echo",
    "url": "http://127.0.0.1:3003/echo/mcp"
  }'

更新服务

curl -X PUT http://localhost:3001/api/mcp/servers/echo \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://127.0.0.1:3003/echo/mcp"
  }'

删除服务

curl -X DELETE http://localhost:3001/api/mcp/servers/echo

工具管理

列出可用工具

curl http://localhost:3000/api/mcp/tools | jq .

调用工具

curl -N -X POST http://localhost:3000/api/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "tools/call",
    "params": {
      "name": "echo",
      "arguments": {
        "message": "Hello, world!"
      }
    }
  }'

访问控制

该服务支持在工具级别进行细粒度访问控制。可使用不同的规则类型配置访问规则：

• WILDCARD：允许所有人访问
• SCOPE：要求具备特定的 OAuth 作用域
• USER_ID：限制为特定用户 ID

列出所有访问规则

curl http://localhost:3001/api/access-rules | jq .

获取工具的规则

curl http://localhost:3001/api/access-rules/by-tool/echo | jq .

创建访问规则

# Allow everyone
curl -X POST http://localhost:3001/api/access-rules/by-tool/echo \
  -H "Content-Type: application/json" \
  -d '{"ruleType": "WILDCARD", "value": null}'

# Require specific scope
curl -X POST http://localhost:3001/api/access-rules/by-tool/add \
  -H "Content-Type: application/json" \
  -d '{"ruleType": "SCOPE", "value": "openid"}'

更新访问规则

curl -X PUT http://localhost:3001/api/access-rules/2 \
  -H "Content-Type: application/json" \
  -d '{"ruleType": "USER_ID", "value": "1,2,3"}'

删除访问规则

curl -X DELETE http://localhost:3001/api/access-rules/3

MCP 协议

该服务实现了用于工具交互的 MCP 协议。以下是一些常见操作：

初始化连接

curl -N -X POST http://localhost:3001/api/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      }
    }
  }'

列出工具

curl -N -X POST http://localhost:3000/api/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }' | jq -R 'select(startswith("data: ")) | .[6:] | fromjson'

Ping 服务

curl -N -X POST http://localhost:3001/api/mcp \
  -H "Accept: application/json, text/event-stream" \
  -H "Connection: keep-alive" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "ping"
  }' | jq -R 'select(startswith("data: ")) | .[6:] | fromjson'

身份验证

该服务使用 JWT（JSON Web Tokens）进行身份验证。对于需要身份验证的请求，请在 Authorization 标头中包含 JWT 令牌：

curl -H "Authorization: Bearer your.jwt.token" http://localhost:3001/api/mcp/tools

贡献

欢迎贡献！请随时提交 Pull Request。