Skip to main content
Glama
deenesjakoruzh
breezykalama

MCPGen

by breezykalama
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

MCPGen

从 OpenAPI 规范生成安全且具备策略意识的 MCP 服务器。

MCPGen 是一个面向生产环境的 MVP Python 框架，它将 OpenAPI 规范转换为默认安全的工具服务器。它可以生成 FastAPI 演示服务器或 MCP 风格的 stdio 服务器，同时在未来的策略工作明确启用之前，保持写操作处于阻塞状态。

问题

AI 应用程序通常需要访问许多 API、数据库和内部系统。如果没有框架，团队往往会重复构建相同的集成，向模型暴露过多的工具，并跳过风险分类、审计日志和写操作护栏等安全控制。

MCP 服务器使 AI 系统能够使用工具，但快速原型可能会在未经审查的情况下意外暴露危险操作，如 DELETE、POST、PATCH 或 PUT。

Related MCP server: openapi-mcp

解决方案

MCPGen 读取 OpenAPI YAML 或 JSON 文件并生成：

  • 结构化的工具描述符

  • 安全暴露的工具列表

  • 被扣留的工具报告

  • 输入模式

  • 具备策略意识的 FastAPI 或 MCP 服务器

  • 试运行预览

  • 安全的 GET 执行

  • JSONL 审计日志

  • 带有关键字回退的语义工具路由

默认行为是有意保守的：仅暴露低风险的 GET 工具。

特性

  • OpenAPI YAML/JSON 解析

  • 从端点生成工具

  • 风险分类：

    • GET = 低

    • POST, PUT, PATCH = 中

    • DELETE = 高

  • 默认安全过滤

  • 从路径/查询参数和 JSON 请求体生成输入模式

  • 带有关键字回退的语义工具路由

  • FastAPI 模式

  • 带有 tools/list 和 tools/call 的 MCP stdio 模式

  • 试运行请求预览

  • 仅针对低风险 GET 工具的安全实际执行

  • 中央策略引擎

  • JSONL 审计日志

  • CLI 命令：generate, inspect

  • 通过 mcpgen.yaml 进行配置

架构流程

OpenAPI spec
  -> parser
  -> tool generator
  -> risk classifier
  -> safety filter
  -> tools.json / tools.all.json / tools.embeddings.json / safety_report.json
  -> generated FastAPI or MCP server
  -> policy engine
  -> semantic/keyword router
  -> dry-run or safe GET execution
  -> audit log

快速入门

本地安装：

pip install -e .[dev]

检查规范：

mcpgen inspect --from examples/jsonplaceholder.openapi.yaml

生成 FastAPI 服务器：

mcpgen generate --from examples/jsonplaceholder.openapi.yaml --mode fastapi --output generated_jsonplaceholder

运行它：

cd generated_jsonplaceholder
export API_BASE_URL=https://jsonplaceholder.typicode.com
uvicorn server:app --reload --port 8001

PowerShell：

cd generated_jsonplaceholder
$env:API_BASE_URL = "https://jsonplaceholder.typicode.com"
uvicorn server:app --reload --port 8001

打开：

http://127.0.0.1:8001/
http://127.0.0.1:8001/docs
http://127.0.0.1:8001/tools
http://127.0.0.1:8001/safety

OpenAPI 输入示例

演示规范：

examples/jsonplaceholder.openapi.yaml

它包括：

  • GET /users

  • GET /users/{id}

  • GET /posts

  • GET /posts/{id}

  • POST /posts

  • DELETE /posts/{id}

摘录：

paths:
  /users/{id}:
    get:
      operationId: getUserById
      summary: Get user by ID
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: integer

生成的工具示例

生成的安全工具：

{
  "name": "get_user_by_id",
  "description": "Get user by ID",
  "method": "GET",
  "path": "/users/{id}",
  "risk_level": "low",
  "enabled": true,
  "operation_id": "getUserById",
  "input_schema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "description": "User ID",
        "x-mcpgen-location": "path"
      }
    },
    "required": ["id"]
  }
}

被扣留的工具（如 create_post 和 delete_post）保留在 tools.all.json 中，并在 safety_report.json 中进行了解释。

FastAPI 演示命令

从项目根目录：

mcpgen generate --from examples/jsonplaceholder.openapi.yaml --mode fastapi --output generated_jsonplaceholder
cd generated_jsonplaceholder
export API_BASE_URL=https://jsonplaceholder.typicode.com
uvicorn server:app --reload --port 8001

PowerShell：

mcpgen generate --from examples/jsonplaceholder.openapi.yaml --mode fastapi --output generated_jsonplaceholder
cd generated_jsonplaceholder
$env:API_BASE_URL = "https://jsonplaceholder.typicode.com"
uvicorn server:app --reload --port 8001

列出暴露的安全工具：

curl http://127.0.0.1:8001/tools

按查询路由工具：

curl -X POST http://127.0.0.1:8001/tools \
  -H "Content-Type: application/json" \
  -d "{\"query\":\"get user by id\"}"

PowerShell 等效命令：

Invoke-RestMethod -Method Post http://127.0.0.1:8001/tools `
  -ContentType "application/json" `
  -Body '{"query":"get user by id"}'

试运行安全工具：

curl -X POST http://127.0.0.1:8001/tools/get_user_by_id/dry-run \
  -H "Content-Type: application/json" \
  -d "{\"inputs\":{\"id\":1}}"

执行安全 GET 工具：

curl -X POST http://127.0.0.1:8001/execute \
  -H "Content-Type: application/json" \
  -d "{\"tool_name\":\"get_user_by_id\",\"params\":{\"id\":1}}"

PowerShell 等效命令：

Invoke-RestMethod -Method Post http://127.0.0.1:8001/execute `
  -ContentType "application/json" `
  -Body '{"tool_name":"get_user_by_id","params":{"id":1}}'

显示被阻止的 POST 行为：

curl -X POST http://127.0.0.1:8001/tools/create_post/dry-run \
  -H "Content-Type: application/json" \
  -d "{\"inputs\":{\"title\":\"Hello\",\"body\":\"Demo\",\"userId\":1}}"

显示被阻止的 DELETE 行为：

curl -X POST http://127.0.0.1:8001/tools/delete_post/dry-run \
  -H "Content-Type: application/json" \
  -d "{\"inputs\":{\"id\":1}}"

显示审计日志：

cat logs/audit.log

PowerShell 等效命令：

Get-Content logs\audit.log

MCP 模式

生成 MCP 风格的 stdio 服务器：

mcpgen generate --from examples/jsonplaceholder.openapi.yaml --mode mcp --output generated_jsonplaceholder_mcp

运行：

cd generated_jsonplaceholder_mcp
export API_BASE_URL=https://jsonplaceholder.typicode.com
python server.py

PowerShell：

cd generated_jsonplaceholder_mcp
$env:API_BASE_URL = "https://jsonplaceholder.typicode.com"
python server.py

示例 tools/list JSON-RPC 输入：

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

示例 tools/call 试运行输入：

{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_user_by_id","arguments":{"id":1}}}

MCP 模式使用与 FastAPI 模式相同的 tools.json、策略引擎和审计日志。在当前的 MVP 中，tools/call 默认进行试运行。通过 execution_mode: safe-execute，它只能执行低风险的 GET 工具。

语义工具路由

MCPGen 在生成过程中写入 tools.embeddings.json，并在以下情况下使用它：

routing_mode: semantic

如果嵌入不可用或语义排名失败，MCPGen 会自动回退到关键字路由。你可以通过以下方式强制使用关键字路由：

routing_mode: keyword

工具文本结合了工具名称、描述和可选标签。示例：

create_invoice create invoice for customer billing payments

默认情况下，MCPGen 使用确定性的本地嵌入回退，因此演示和测试无需下载模型即可工作。要使用 sentence-transformers，请设置：

export MCPGEN_EMBEDDING_BACKEND=sentence-transformers

PowerShell：

$env:MCPGEN_EMBEDDING_BACKEND = "sentence-transformers"

通过更改 mcpgen.yaml 中的 routing_mode 并重新生成服务器来比较路由模式。语义模式按向量相似度排名；关键字模式按归一化标记重叠度排名，并包含匹配的术语。

安全模型

MCPGen 默认是安全的：

  • 只有低风险的 GET 工具才会暴露在 tools.json 中。

  • 中等风险的写工具会被扣留，除非未来的配置明确启用它们。

  • 高风险的 DELETE 工具始终被阻止。

  • 实际执行仅限于低风险的 GET 工具。

  • 未实现写执行。

  • 未实现身份验证。

策略决策返回：

{
  "allowed": false,
  "status": "blocked",
  "reason": "Medium-risk tool is not listed in enabled_tools.",
  "risk_level": "medium",
  "tool_name": "create_post"
}

审计日志

审计日志是写入以下位置的 JSONL 记录：

logs/audit.log

配置：

audit_enabled: true
audit_log_path: logs/audit.log
routing_mode: semantic

每个事件包括：

  • 时间戳

  • 工具名称

  • 方法

  • 路径

  • 风险级别

  • 模式

  • 状态

  • 是否允许

  • 原因

  • 来源

  • 操作

操作包括：

  • policy_evaluation

  • dry_run

  • execution_started

  • execution_success

  • execution_error

  • execution_blocked

配置

默认配置：

max_tools: 5
allowed_methods:
  - GET
output_dir: generated_mcp_server
api_base_url: https://api.example.com
enabled_tools: []
execution_mode: dry-run
audit_enabled: true
audit_log_path: logs/audit.log

对于 JSONPlaceholder 演示，请设置：

api_base_url: https://jsonplaceholder.typicode.com

当前限制

  • 这是一个面向生产环境的 MVP，而不是生产就绪的框架。

  • 除了环境变量准备之外，没有身份验证或密钥处理。

  • 没有写执行。

  • 没有确认工作流 UI。

  • 没有向量数据库或嵌入缓存优化。

  • 没有速率限制。

  • 没有数据库支持的审计接收器。

  • 如果官方 Python MCP SDK 不可用，MCP 模式使用最小的 stdio 脚手架。

路线图

  • 官方 MCP SDK 集成

  • 身份验证和密钥管理

  • 已启用中等风险工具的确认工作流

  • 速率限制

  • 请求/响应验证

  • 更好的 OpenAPI 模式支持

  • 可插拔的审计接收器

  • 更好的语义路由模型和嵌入缓存优化

  • 部署模板

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • openapi-mcp

    wate
    A
    license
    Not graded
    quality
    D
    maintenance
    Automatically generates MCP server tools from OpenAPI specifications, enabling LLMs to interact with any API defined by an OpenAPI spec through natural language.
    29 npm
    MIT