Openapi To MCP Generator

OpenAPI到MCP生成器

根据OpenAPI 3.0/3.1规范自动生成MCP服务器（模型上下文协议）。允许LLMS以标准化的方式与您公司的微服务交互。

主要特征

核心功能

• 完整的 OpenAPI 解析器：支持OpenAPI 3.0.x和3.1.x，并进行严格验证
• 自动处理：将终结点转换为工具，将架构转换为资源
• 端点选择：通过CLI、交互模式或Web GUI选择要包括的端点
• 支持FASTMCP和MCP：使用FASTMCP（推荐）或标准MCP生成服务器
• 灵活认证：Soporta API密钥、承载令牌、基本身份验证和OAuth2
• 客户端HTTP弹性客户端：指数退货自动重试
• 绝望的Docker：图像Docker准备与Gunicorn一起制作

UI/UX功能✨

• 🌙 暗/亮模式：暗/亮主题，自动系统检测
• 📋 吐司通知：优雅而非侵入性的通知系统
• 📂 拖放：拖动OpenAPI文件以立即加载它们
• 🕒 最新规格：加载的最后10个规范的历史
• 💾 导出/导入配置：导出和导入端点选择配置
• 🔖 预设：保存并重复使用端点选择作为预设
• 📊 进度条：带有10个可见步骤的详细进度条
• ⚡ 自动清理：自动清理临时文件和过期会话
• 📚 规范库：带有版本控制的完整规范库
• 🔄 版本控制：带有视觉Timeline和Diff Viewer的版本历史
• ⭐ 收藏夹和标签：组织规格的收藏夹和标签系统
• 🔍 高级搜索：高级规格搜索和过滤
• 📈 生成跟踪：记录所有执行的MCP代
• ⚙️ 高级配置：按规格高级配置
• 📝 双模式编辑器：GUI表单和带有切换的Yaml/JSON编辑器
• 🎨 配置描述文件：可重复使用（开发、生产等）
• ✅ 实时验证：带有错误和警告的实时验证
• 💾 配置导入/导出：在YAML中导出和导入配置

企业功能

• 🔒 全面审计：45种严重程度为4级的事件
• 🔐 加密：AES-256，带有Fernet和用于敏感规范的PBKDF2推导
• 📊 仪表板管理员：使用指标，按团队划分的活动，世代
• 🚨 可配置警报：10种带有阈值和通知的警报
• 📋 自动报告：8种带有调度的JSON/CSV/HTML报告
• 🗃️ 数据保留：具有自动清理功能的9种数据类型的保留策略
• 🌐 多数据库：支持SQLite、PostgreSQL和MongoDB

人工智能和云功能

• 🤖 Olama集成：智能规范分析、文档生成、IA安全审计
• 📦 MinIO存储：S3存储-支持规范、MCP工件和报告
• 🔐 OAuth2管理：通过OIDC发现和自动刷新集中管理令牌
• ⚙️ 功能开关：独立启用/禁用模块（AI、存储、OAuth2）
• 🐳 开发基础设施：Docker-与PostgreSQL、Redis、Minio和Ollama一起创作

开发者体验

• 🎯 智能错误消息：上下文错误、解决方案建议和文档链接
• 🔍 从URL加载：从远程URL导入OpenAPI规范
• 📦 下载为zip：生成和下载压缩MCP服务器
• 🚀 实时预览：预览生成的代码而不保存它

______________________________________________________________________

目录

1. 安装
2. 快速启动
3. 使用方式

- CLI Básico - CLI控制台 - 交互式CLI - GUI Web - 独立模式

2. MCP框架
3. 配置
4. 批处理
5. 与Claude Desktop的集成
6. 企业功能

- 环境配置 - AI集成（Ollama） - 存储（Minio） - OAuth2身份验证 - 股票审计 - 规范加密 - 可配置警报 - 自动报告 - Metricas仪表板 - 保留策略 - 数据库配置

1. API 参考
2. 建筑
3. Mapeo OpenAPI→ MCP
4. 例子
5. 考虑因素
6. 争议

______________________________________________________________________

安装

要求

• Python>=3.10
• 点对点

基本设施

# Clonar el repositorio
git clone https://github.com/enterprise/openapi-to-mcp.git
cd openapi-to-mcp-generator

# Crear entorno virtual
python -m venv .venv

# Activar entorno virtual
# Linux/Mac:
source .venv/bin/activate
# Windows:
.\.venv\Scripts\activate

# Instalar el paquete
pip install -e .

具有可选功能的安装

# Instalar con modo interactivo CLI (questionary)
pip install -e ".[interactive]"

# Instalar con GUI web (Flask + requests + gunicorn)
pip install -e ".[gui]"

# Instalar con IA (Ollama integration)
pip install -e ".[ai]"

# Instalar con almacenamiento MinIO
pip install -e ".[storage]"

# Instalar con PostgreSQL
pip install -e ".[postgresql]"

# Instalar con Redis (cache, token store, message broker)
pip install -e ".[redis]"

# Instalar con OAuth2
pip install -e ".[oauth2]"

# Instalar todas las características
pip install -e ".[all]"

# Instalar con herramientas de desarrollo
pip install -e ".[dev]"

验证安装

openapi-to-mcp --version
# Output: openapi-to-mcp, version 1.0.0

openapi-to-mcp --help

______________________________________________________________________

快速启动

1.准备您的OpenAPI规范

确保您有有效的OpenAPI文件（Yaml或JSON）：

# mi-api.yaml
openapi: "3.0.3"
info:
  title: Mi API
  version: "1.0.0"
paths:
  /users:
    get:
      summary: Listar usuarios
      responses:
        "200":
          description: Lista de usuarios

2.生成MCP服务器

openapi-to-mcp generate mi-api.yaml --service-name mi_api

3.运行生成的服务器

cd output/mcp_server_mi_api
pip install -r requirements.txt
python -m src.server

替代方案：使用GUI Web

# Opción 1: Con archivo local
openapi-to-mcp gui mi-api.yaml

# Opción 2: Modo standalone (subir archivo o cargar desde URL)
openapi-to-mcp gui
# o
openapi-to-mcp serve

______________________________________________________________________

使用方式

模式1：基本CLI

生成具有所有端点的MCP服务器的最简单方式：

openapi-to-mcp generate  --service-name  [opciones]

主要选择：

完整示例：

openapi-to-mcp generate ./specs/users-api.yaml \
    --service-name user_management \
    --service-prefix users \
    --base-url https://api.example.com/v2 \
    --environment production \
    --mcp-framework fastmcp \
    --output ./servers

______________________________________________________________________

模式2：带有端点过滤器的CLI

使用全局模式过滤要包括的端点：

# Incluir solo endpoints que coincidan con patrones
openapi-to-mcp generate api.yaml -n myservice \
    --include-endpoints "/v1/api/users*" \
    --include-endpoints "/v1/api/orders*"

# Excluir endpoints específicos
openapi-to-mcp generate api.yaml -n myservice \
    --exclude-endpoints "/internal/*" \
    --exclude-endpoints "*/admin/*"

# Combinar inclusión y exclusión
openapi-to-mcp generate api.yaml -n myservice \
    -i "/api/*" \
    -x "/api/internal/*" \
    -x "/api/debug/*"

支持的模式：

______________________________________________________________________

模式3：交互式CLI

在终端上交互式选择端点：

# Requiere: pip install questionary
openapi-to-mcp generate api.yaml -n myservice --interactive

互动流程：

┌─────────────────────────────────────────────────────────────┐
│ ¿Cómo deseas seleccionar los endpoints?                    │
│                                                             │
│ > Selección manual (checkboxes)                            │
│   Por patrones (glob)                                      │
│   Por tags (grupos)                                        │
│   Todos los endpoints                                      │
└─────────────────────────────────────────────────────────────┘

选择选项：

1. 手动选择：列出marcar/desmarcar中的复选框
2. 按模式：交互式输入全球模式
3. 按标签：通过其OpenAPI标记选择端点组
4. 待办事项：包括所有没有过滤器的端点

______________________________________________________________________

Modo4:GUI Web

带有预加载文件的可视化端点选择Web图形界面：

# Requiere: pip install flask
openapi-to-mcp gui api.yaml

选项：

openapi-to-mcp gui  [opciones]

# Opciones disponibles:
  --port, -p      Puerto del servidor web (default: 5000)
  --no-browser    No abrir el navegador automáticamente
  --output, -o    Directorio de salida (default: ./output)

示例：

openapi-to-mcp gui ./specs/large-api.yaml --port 8080

______________________________________________________________________

模式 5: 独立模式 （Web）

在不需要预加载文件的情况下运行GUI。允许：

• 上传文件：拖放或从资源管理器中选择
• 从URL加载：输入OpenAPI规范的直接URL
• 下载为zip：生成服务器并下载压缩

# Opción 1: Comando gui sin argumentos
openapi-to-mcp gui

# Opción 2: Comando serve dedicado
openapi-to-mcp serve --port 5000 --output ./output

上传接口：

┌─────────────────────────────────────────────────────────────────┐
│            OpenAPI to MCP Generator                              │
│                                                                  │
│     ┌─────────────────────────────────────────────────────┐     │
│     │              Carga tu especificación                 │     │
│     │                                                      │     │
│     │    [  Archivo  ]  [    URL    ]                     │     │
│     │                                                      │     │
│     │    ┌────────────────────────────────────────────┐   │     │
│     │    │                                            │   │     │
│     │    │       Arrastra tu archivo aquí             │   │     │
│     │    │                  o                         │   │     │
│     │    │      [ Seleccionar Archivo ]               │   │     │
│     │    │                                            │   │     │
│     │    │  Formatos: .yaml, .yml, .json              │   │     │
│     │    └────────────────────────────────────────────┘   │     │
│     │                                                      │     │
│     │    ─── O cargar desde URL ───                       │     │
│     │                                                      │     │
│     │    [ https://api.example.com/openapi.json ] [Cargar]│     │
│     │                                                      │     │
│     │    Ejemplos: [Petstore API] [GitHub API]            │     │
│     └─────────────────────────────────────────────────────┘     │
│                                                                  │
│     ┌─────────┐  ┌─────────┐  ┌─────────┐                       │
│     │Selección│  │ FastMCP │  │Descarga │                       │
│     │ Visual  │  │  / MCP  │  │  ZIP    │                       │
│     └─────────┘  └─────────┘  └─────────┘                       │
└─────────────────────────────────────────────────────────────────┘

端点选择接口：

┌─────────────────────────────────────────────────────────────────────────┐
│  OpenAPI to MCP Generator                    API: Petstore v1.0        │
├─────────────────────────────────────────────────────────────────────────┤
│  [Vista: Lista ▼] [Buscar: ____________] [Patrón: /users/*] [Agregar]  │
├─────────────────────────────────────────────────────────────────────────┤
│  ┌─── Disponibles (15) ────┐         ┌─── Seleccionados (5) ───┐       │
│  │ □ [GET] /users          │   >>    │ ☑ [GET] /orders         │       │
│  │ □ [POST] /users         │         │ ☑ [POST] /orders        │       │
│  │ □ [GET] /users/{id}     │    str:
    response = await http_client.request(
        method="GET",
        path="/users",
        params={"page": page, "limit": limit}
    )
    return json.dumps(response)

if __name__ == "__main__":
    mcp.run()

MCP标准

具有更多控制的低级别API。对于晚期病例。

openapi-to-mcp generate api.yaml -n myservice --mcp-framework mcp

比较：

______________________________________________________________________

配置

生成的服务器配置文件

# config/config.yaml
service_name: user_management
base_url: https://api.enterprise.com/v2
timeout: 30
environment: production
log_level: INFO

retry:
  max_retries: 3
  backoff_factor: 0.5
  retry_statuses:
    - 429
    - 500
    - 502
    - 503
    - 504

auth:
  type: bearer  # none, api_key, bearer, basic, oauth2

环境变量

# .env
BASE_URL=https://api.enterprise.com/v2
TIMEOUT=30
LOG_LEVEL=INFO
ENVIRONMENT=production

# Autenticación
API_KEY=your_api_key
AUTH_TOKEN=your_bearer_token

______________________________________________________________________

批处理

为多个微服务生成服务器：

# batch-config.yaml
output_dir: ./output

services:
  - name: users
    spec: ./specs/users-api.yaml
    base_url: https://users.api.com

  - name: orders
    spec: ./specs/orders-api.yaml
    base_url: https://orders.api.com

openapi-to-mcp batch ./batch-config.yaml

______________________________________________________________________

与Claude Desktop的集成

基本配置

{
  "mcpServers": {
    "user_management": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp_server_user_management",
      "env": {
        "BASE_URL": "https://api.enterprise.com/v2",
        "AUTH_TOKEN": "your_token"
      }
    }
  }
}

______________________________________________________________________

企业功能

环境配置

系统使用pydantic设置进行集中配置。复制 .env.example 一 .env:

cp .env.example .env

功能开关 -只激活您需要的模块：

ENABLE_AI=true       # Integración Ollama (análisis IA)
ENABLE_STORAGE=true  # MinIO (almacenamiento S3)
ENABLE_OAUTH2=true   # OAuth2 token management
ENABLE_AGENTS=true   # Multi-agent architecture (futuro)

电梯开发服务：

# Inicia PostgreSQL, Redis, MinIO y Ollama
docker-compose -f docker-compose.dev.yml up -d

# Verificar estado
curl http://localhost:5000/api/features

回应 /api/features:

{
  "ai": {"enabled": true, "ollama_url": "http://localhost:11434"},
  "storage": {"enabled": true, "endpoint": "localhost:9000"},
  "oauth2": {"enabled": false, "configured": false},
  "agents": {"enabled": false},
  "database": {"type": "sqlite"}
}

AI集成（Ollama）

通过Ollama使用本地LLM模型执行6种任务：

示例-使用IA分析规范：

curl -X POST http://localhost:5000/api/ai/analyze-spec \
  -H "Content-Type: application/json" \
  -d '{"spec_content": "openapi: 3.0.3\ninfo:\n  title: My API..."}'

回答：

{
  "analysis": {
    "quality_score": 78,
    "summary": "REST API with user management endpoints",
    "total_endpoints": 12,
    "issues": [
      {"severity": "warning", "path": "/users", "message": "Missing pagination"}
    ],
    "mcp_recommendations": {
      "priority_endpoints": ["/users", "/orders"],
      "suggested_tools": ["list_users", "create_order"]
    }
  },
  "model": "llama3.2:3b",
  "tokens_used": 1250,
  "duration_ms": 3400
}

配置模型：

OLLAMA_HOST=localhost
OLLAMA_PORT=11434
OLLAMA_MODEL_SPEC_ANALYSIS=llama3.2:3b
OLLAMA_MODEL_CODE_GENERATION=codellama:7b
OLLAMA_MODEL_DOCUMENTATION=llama3.2:3b
OLLAMA_MODEL_VALIDATION=llama3.2:1b
OLLAMA_RATE_LIMIT_RPM=30

存储（Minio）

S3存储-支持带有4个专用桶的工件：

示例-上传文件：

curl -X POST http://localhost:5000/api/storage/upload \
  -F "file=@mi-api.yaml" \
  -F "bucket=openapi-specs" \
  -F "key=project1/v1/api.yaml"

示例-列出对象：

curl http://localhost:5000/api/storage/objects/openapi-specs?prefix=project1/

当地撤退：如果Minio不可用或 ENABLE_STORAGE=false，系统自动使用本地文件系统中的存储(output/storage/).

配置：

MINIO_ENDPOINT=localhost:9000
MINIO_ACCESS_KEY=minioadmin
MINIO_SECRET_KEY=minioadmin
MINIO_SECURE=false

OAuth2身份验证

集中管理OAuth2令牌，将身份验证传播到生成的MCP服务器。

流量：

1. Registrar proveedor → GET /api/auth/oauth2/authorize/{provider}
2. Usuario autoriza     → Redirect a authorization_url
3. Callback con code    → GET /api/auth/oauth2/callback?code=...
4. Token almacenado     → Auto-refresh antes de expiración
5. MCP Context          → GET /api/auth/oauth2/mcp-context/{provider}/{user}

特点：

• 自动发现(.well-known/openid-configuration)
• 令牌存储：内存（默认）或Redis（生产）
• 带可配置缓冲区的自动刷新（到期前300s）
• 生成的MCP服务器上的身份验证注入上下文

配置：

OAUTH2_ISSUER=https://your-domain.auth0.com
OAUTH2_CLIENT_ID=your-client-id
OAUTH2_CLIENT_SECRET=your-client-secret
OAUTH2_REDIRECT_URI=http://localhost:5000/api/auth/oauth2/callback
OAUTH2_TOKEN_STORE=redis
OAUTH2_REFRESH_BUFFER=300

股票审计

完整的审计日志记录系统，有26种事件类型和4种严重程度。

审核事件类型：

示例-查询审核日志：

# Obtener logs filtrados por severidad y rango de fechas
curl "http://localhost:5000/api/audit/logs?severity=HIGH&days=7&limit=50"

# Exportar logs en CSV
curl "http://localhost:5000/api/audit/export?format=csv&start_date=2025-01-01"

# Resumen de auditoría (estadísticas)
curl "http://localhost:5000/api/audit/summary?workspace_id=1"

回应 /api/audit/summary:

{
  "total_events": 1523,
  "by_severity": {"LOW": 890, "MEDIUM": 412, "HIGH": 198, "CRITICAL": 23},
  "top_actions": [
    {"action": "SPEC_UPLOADED", "count": 342},
    {"action": "MCP_GENERATED", "count": 289}
  ],
  "active_users": 12
}

每个记录包括：用户、工作空间、IP、用户代理、请求路径和其他元数据。

规范加密

AES-256加密以保护敏感的OpenAPI规范。

# Encriptar una spec
curl -X POST http://localhost:5000/api/encryption/encrypt \
  -H "Content-Type: application/json" \
  -d '{"spec_id": 1, "password": "mi-clave-segura"}'

# Desencriptar
curl -X POST http://localhost:5000/api/encryption/decrypt \
  -H "Content-Type: application/json" \
  -d '{"spec_id": 1, "password": "mi-clave-segura"}'

# Rotar clave
curl -X POST http://localhost:5000/api/encryption/rotate \
  -H "Content-Type: application/json" \
  -d '{"spec_id": 1, "old_password": "clave-vieja", "new_password": "clave-nueva"}'

可配置警报

具有10种类型、可配置阈值和多通道通知的警报系统。

可用的警报类型：

生命周期： 主动->确认->决议（非临时）

# Crear regla de alerta
curl -X POST http://localhost:5000/api/alerts/rules \
  -H "Content-Type: application/json" \
  -d '{
    "alert_type": "FAILED_LOGINS",
    "severity": "HIGH",
    "threshold": 5,
    "period_minutes": 15,
    "channels": ["email", "webhook"],
    "cooldown_minutes": 60,
    "workspace_id": 1
  }'

# Listar alertas activas
curl "http://localhost:5000/api/alerts?status=ACTIVE&severity=HIGH"

# Reconocer una alerta
curl -X POST http://localhost:5000/api/alerts/42/acknowledge

# Resolver una alerta
curl -X POST http://localhost:5000/api/alerts/42/resolve

自动报告

8种报告类型，有3种格式，可自动安排。

报告类型：

行程安排： 每天、每周或每月通过电子邮件或网络挂钩交付。

# Generar reporte manualmente
curl -X POST http://localhost:5000/api/reports/generate \
  -H "Content-Type: application/json" \
  -d '{"report_type": "SECURITY_AUDIT", "period_days": 30, "workspace_id": 1}'

# Programar reporte automático
curl -X POST http://localhost:5000/api/reports/scheduled \
  -H "Content-Type: application/json" \
  -d '{
    "report_type": "USAGE_SUMMARY",
    "format": "HTML",
    "schedule": "WEEKLY",
    "workspace_id": 1,
    "delivery_email": "admin@empresa.com"
  }'

# Exportar reporte en formato específico
curl "http://localhost:5000/api/reports/generated/15/export?format=csv"

# Listar reportes generados
curl "http://localhost:5000/api/reports/generated?workspace_id=1&limit=20"

Metricas仪表板

具有实时度量的管理仪表板。

指标类别：

# Dashboard completo
curl http://localhost:5000/api/metrics/dashboard

# Métricas de seguridad
curl http://localhost:5000/api/metrics/security

回应 /api/metrics/security:

{
  "failed_logins_24h": 3,
  "successful_logins_24h": 47,
  "high_severity_events": 5,
  "critical_events": 0,
  "suspicious_ips": ["192.168.1.100"],
  "by_severity": {"LOW": 120, "MEDIUM": 34, "HIGH": 5, "CRITICAL": 0}
}

数据保留策略

可配置的保留系统，用于9种数据类型，并具有自动清理功能。

默认保留：

# Configurar política de retención
curl -X POST http://localhost:5000/api/retention/policies \
  -H "Content-Type: application/json" \
  -d '{
    "data_type": "AUDIT_LOGS",
    "retention_days": 180,
    "action": "ARCHIVE",
    "workspace_id": 1
  }'

# Ejecutar cleanup (dry-run primero)
curl -X POST http://localhost:5000/api/retention/execute \
  -H "Content-Type: application/json" \
  -d '{"workspace_id": 1, "dry_run": true}'

# Ver estadísticas de retención
curl "http://localhost:5000/api/retention/stats?workspace_id=1"

# Historial de ejecuciones
curl "http://localhost:5000/api/retention/history?workspace_id=1"

数据库配置

通过环境变量配置支持3种数据库类型。

SQLite（默认）：

DATABASE_TYPE=sqlite
# Usa archivo local en output/instance/app.db

PostgreSQL：

DATABASE_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_NAME=openapi_mcp
DB_USER=postgres
DB_PASSWORD=your-password
# O usando URL directa:
# DATABASE_URL=postgresql://user:pass@localhost:5432/openapi_mcp

MongoDB：

DATABASE_TYPE=mongodb
DATABASE_URL=mongodb://user:pass@localhost:27017/openapi_mcp

# Verificar salud de la base de datos
curl http://localhost:5000/api/health

# Información detallada
curl http://localhost:5000/api/database/info

回应 /api/database/info:

{
  "type": "postgresql",
  "url_masked": "postgresql://***@localhost:5432/openapi_mcp",
  "healthy": true,
  "server_version": "16.1",
  "database_size": "24 MB"
}

______________________________________________________________________

API 参考

每个模块的端点

核心（始终可用）

AI(ENABLE_AI=true)

存储(ENABLE_STORAGE=true)

OAuth2(ENABLE_OAUTH2=true)

审计

警报

报告

Metricas

保留

加密

______________________________________________________________________

建筑

流量产生

┌─────────────────────────────────────────────────────────────────┐
│                    OpenAPI Specification                         │
│                    (YAML/JSON 3.0/3.1)                          │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      OpenAPI Parser                              │
│  - Validación de spec                                           │
│  - Resolución de $refs                                          │
│  - Extracción de paths, schemas, security                       │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Endpoint Selector                             │
│  - Filtrado por patrones CLI                                    │
│  - Selección interactiva                                        │
│  - Selección via GUI web                                        │
│  - Carga desde archivo o URL                                    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
              ┌───────────────┴───────────────┐
              │                               │
              ▼                               ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│    Tool Transformer     │     │  Resource Transformer   │
└─────────────────────────┘     └─────────────────────────┘
              │                               │
              └───────────────┬───────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    MCP Server Generator                          │
│  - Genera código server.py (FastMCP o MCP)                      │
│  - Crea http_client.py, auth.py, config.py                      │
│  - Genera requirements.txt, Dockerfile, README                  │
│  - Opcionalmente crea ZIP para descarga                         │
└─────────────────────────────────────────────────────────────────┘

项目结构

openapi-to-mcp-generator/
├── src/
│   └── openapi_to_mcp/
│       ├── models.py              # Modelos de datos
│       ├── cli.py                 # Interfaz de comandos
│       ├── endpoint_selector.py   # Selector de endpoints
│       ├── config/                # ⚙️ Configuración centralizada
│       │   ├── __init__.py
│       │   └── settings.py        # Pydantic Settings (Ollama, MinIO, OAuth2)
│       ├── ai/                    # 🤖 Integración IA
│       │   ├── __init__.py
│       │   └── ollama_client.py   # Cliente Ollama (6 tareas IA)
│       ├── auth/                  # 🔐 Autenticación
│       │   ├── __init__.py
│       │   └── oauth2.py          # OAuth2 Manager + Token Stores
│       ├── storage/               # 📦 Almacenamiento
│       │   ├── __init__.py
│       │   └── adapters/
│       │       ├── base.py        # Interfaz StorageAdapter
│       │       ├── local_adapter.py
│       │       └── minio_adapter.py
│       ├── parsers/
│       │   └── openapi_parser.py
│       ├── transformers/
│       │   ├── tool_transformer.py
│       │   └── resource_transformer.py
│       ├── generators/
│       │   └── server_generator.py
│       └── gui/                   # Interfaz web
│           ├── web_app.py         # 80+ API endpoints
│           ├── db_config.py       # Multi-database config
│           ├── database.py        # SQLAlchemy models
│           ├── audit.py           # Audit logging
│           ├── encryption.py      # AES-256 encryption
│           ├── retention.py       # Data retention
│           ├── metrics.py         # Usage metrics
│           ├── alerts.py          # Configurable alerts
│           ├── reports.py         # Automatic reports
│           ├── templates/
│           │   ├── index.html     # Selector de endpoints
│           │   ├── upload.html    # Página de carga
│           │   ├── admin.html     # Dashboard admin
│           │   └── login.html     # Autenticación
│           └── static/
│               ├── style.css
│               └── app.js
├── .env.example                   # Variables de entorno
├── Dockerfile
├── docker-compose.yml             # Producción
├── docker-compose.dev.yml         # Desarrollo (PostgreSQL, Redis, MinIO, Ollama)
├── docker-entrypoint.sh
├── examples/
├── tests/
└── pyproject.toml

______________________________________________________________________

Mapeo OpenAPI→ MCP

操作→工具

参数→JSON模式

______________________________________________________________________

例子

编程使用

from openapi_to_mcp import (
    OpenAPIParser,
    ToolTransformer,
    ResourceTransformer,
    MCPServerGenerator,
    MCPServerConfig,
    MCPFramework,
    EndpointFilter,
)

# 1. Parsear especificación
parser = OpenAPIParser()
spec = parser.parse("api.yaml")

# 2. Filtrar endpoints
endpoint_filter = EndpointFilter(
    include_patterns=["/users/*", "/orders/*"],
    exclude_patterns=["/internal/*"]
)

# 3. Transformar y generar
transformer = ToolTransformer(service_prefix="myapi")
tools = transformer.transform(spec, endpoint_filter=endpoint_filter)

config = MCPServerConfig(
    service_name="my_service",
    mcp_framework=MCPFramework.FASTMCP,
)

generator = MCPServerGenerator(output_dir="./output")
result = generator.generate(spec, tools, resources, config)

有用的CLI命令

# Validar especificación OpenAPI
openapi-to-mcp validate ./api.yaml

# Vista previa de tools y resources
openapi-to-mcp preview ./api.yaml --service-prefix myapi

# Modo verbose para debugging
openapi-to-mcp -v generate ./api.yaml -n myservice

# Iniciar servidor web standalone
openapi-to-mcp serve --port 8080

______________________________________________________________________

考虑因素

已知限制

1. WebSockets/SSE：当前不支持流媒体
2. 文件上传：Multipart Form-数据需要特殊处理
3. 图查询语言：不支持，仅限REST
4. 需要Ollama：AI功能需要在本地运行Ollama
5. SAML/LDAP：仅当前支持的OAuth2/OIDC（备份中的SAML）

良好做法

1. 美国操作ID：定义 operationId 在您的OpenAPI中，用于更可读的工具名称
2. 卡塞尔文献展：包括 summary y description 在每个操作中
3. 版本a：使用版本前缀(users_v2_*)当API进化时
4. Filtra：不要将内部或调试终结点暴露给LLMS
5. 功能开关：仅激活您在中需要的模块 .env
6. 令牌安全：在生产中，使用Redis作为令牌存储(OAUTH2_TOKEN_STORE=redis)
7. 生产中的迷你：配置 MINIO_SECURE=true 和安全凭证

______________________________________________________________________

🗺️ 路线图

第一阶段：用户体验改进（V1.1）✅ 完成

🌙 暗/亮模式✅

• \[x\] 在Web界面上切换主题
• \[x\] 局部存储中的偏好持久性
• \[x\] 自动偏好检测系统

✅ 实时验证✅

• \[x\] 加载时验证OpenAPI规范
• \[x\] 错误和警告的视觉指标
• \[x\] 自动更正建议
• \[x\] 带有问题详细信息的诊断面板

👁️ 预览en Vivo✅

• \[x\] 下载前生成的MCP代码预览
• \[x\] Python语法高亮显示
• \[x\] 按生成的文件导航
• \[x\] 比较版本的Diff Viewer

📊 高级统计✅

• \[x\] 带有使用指标的仪表板
• \[x\] 最常用的端点图
• \[x\] 最近规格历史（最后10个）
• \[x\] 平均发电时间

🎯 性能和DX✅ 湾仔

• \[x\] 自动清理临时文件
• \[x\] 清理过期会话（>2小时）
• \[x\] 详细的进度条（10步）
• \[x\] 带有上下文和建议的改进错误消息
• \[x\] 错误中的文档链接

🎨 UI/UX改进✅ 湾仔

• \[x\] Toast通知（成功、错误、警告、信息）
• \[x\] 文件上传的拖放
• \[x\] 快速重新加载的最新规范列表
• \[x\] 导出/导入选择设置
• \[x\] 预置管理（保存/加载选择）
• \[x\] 移动响应式设计

______________________________________________________________________

第二阶段：规范管理（V1.2）✅ 完成

📁 OpenAPI规范管理器✅

• \[x\] 加载的规范库
• \[x\] 按项目/文件夹组织
• \[x\] 搜索和过滤规范
• \[x\] 标签和分类
• \[x\] 收藏夹和快捷方式

🔄 规范版本✅

OpenAPI规范的完整版本控制系统：

┌─────────────────────────────────────────────────────────────────┐
│  📋 Petstore API - Historial de Versiones                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ●───●───●───●───◉  (Timeline)                                  │
│  v1  v2  v3  v4  v5                                             │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ v5 (actual) - 2024-01-15 14:32                          │   │
│  │ ├─ 🔧 MCP generado: 2024-01-15 14:35                    │   │
│  │ ├─ Endpoints: 24 (+3 desde v4)                          │   │
│  │ └─ Nota: "Agregados endpoints de autenticación OAuth"   │   │
│  ├─────────────────────────────────────────────────────────┤   │
│  │ v4 - 2024-01-10 09:15                                   │   │
│  │ ├─ 🔧 MCP generado: 2024-01-10 09:20                    │   │
│  │ ├─ 🔧 MCP generado: 2024-01-12 16:45                    │   │
│  │ ├─ Endpoints: 21                                        │   │
│  │ └─ Nota: "Refactoring de rutas de usuarios"             │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  [Ver Diff v4 ↔ v5]  [Restaurar v4]  [Exportar Historial]      │
└─────────────────────────────────────────────────────────────────┘

🔧 MCP世代记录✅

• \[x\] 生成MCP的版本视觉指示器
• \[x\] 每一代人的确切日期和时间
• \[x\] 每一代使用的配置
• \[x\] 生成的zip下载链接（如果可用）
• \[x\] 生成统计数据（工具、资源、时间）

______________________________________________________________________

第三阶段：MCP高级配置（V1.3）✅ 完成

⚙️ 按规格配置的区域✅

每个规范都有自己的MCP输出配置：

Modo编辑器（yaml/JSON）：

# Configuración directa en formato YAML
service_name: "petstore_api"
mcp_framework: "fastmcp"
output_format: "python"
service_prefix: "petstore"
generate_resources: true
auth_config:
  type: "bearer"
  token_env: "PETSTORE_API_KEY"
endpoint_filters:
  include: ["/pets/*", "/store/*"]
  exclude: ["/internal/*"]

图形用户界面模式（视觉形式）：

┌─────────────────────────────────────────────────────────────────┐
│  ⚙️ Configuración MCP - Petstore API                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Información General                                            │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Nombre del servicio: [petstore_api_________]            │   │
│  │ Prefijo:             [petstore_____________]            │   │
│  │ Framework:           [FastMCP ▼]                        │   │
│  │ Formato salida:      ○ Python  ○ TypeScript (futuro)    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Autenticación                                                  │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ Tipo:     [Bearer Token ▼]                              │   │
│  │ Variable: [PETSTORE_API_KEY___]                         │   │
│  │ □ Requerido para todos los endpoints                    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  Generación                                                     │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │ ☑ Generar Resources                                     │   │
│  │ ☑ Incluir validación de parámetros                      │   │
│  │ ☑ Generar documentación inline                          │   │
│  │ □ Modo estricto (fallar en warnings)                    │   │
│  └─────────────────────────────────────────────────────────┘   │
│                                                                 │
│  [Modo Editor YAML]  [Guardar Config]  [Restaurar Defaults]    │
└─────────────────────────────────────────────────────────────────┘

• \[x\] 在编辑器模式和GUI模式之间切换
• \[x\] 实时配置验证
• \[x\] 可重复使用的配置文件（默认为4个配置文件）
• \[x\] 导入/导出配置（YAML/JSON）
• \[x\] 将配置文件应用于现有规范

______________________________________________________________________

第四阶段：合作与团队（V2.0）✅

👥 用户管理

• \[x\] 认证系统（本地/OAUTH）
• \[x\] 角色和权限（管理员、编辑、查看器）
• \[x\] 共享工作空间
• \[x\] 实时团队活动

🔗 整合

• \[x\] 用于CI/CD的webhooks
• \[x\] API REST自动化
• \[x\] 与GitHub/Gitlab的集成
• \[x\] 与规范存储库同步
• \[x\] 通知（Slack，Discord，电子邮件）

📤 高级出口

• \[x\] 生成TypeScript代码（官方MCP SDK）
• \[x\] 个性化模板（Jinja2）
• \[\]导出插件
• \[x\] 多规格批量生成

______________________________________________________________________

Fase 5：企业功能（v3.0）✅

🔒 高级安全

• \[x\] 行动审计（45种事件，4种严重程度）
• \[x\] 敏感规范加密（AES-256 with Fernet，PBKDF2）
• \[x\] OAuth2/OIDC集成（OIDC发现、令牌管理、刷新自动）
• \[x\] 数据保留策略（9种数据类型，自动清理）

📈 分析和监测

• \[x\] 管理仪表板（完整指标）
• \[x\] 团队使用指标（用户、活动、工作空间）
• \[x\] 可配置警报（10种类型、阈值、通知）
• \[x\] 自动报告（8种类型，3种格式，时间表）

🌐 逃逸

• \[\]Soporte多租户
• \[\]负载平衡
• \[x\] 分布式缓存（Redis作为缓存和令牌存储的后端）
• \[x\] 持久数据库（postgresql/mongodb通过db_config）

______________________________________________________________________

Fase 6:人工智能和云基础设施（v4.0）✅

🤖 Ollama整合（当地LLM）

• \[x\] 具有速率限制和错误处理的Ollama客户端
• \[x\] OpenAPI规范的智能分析（质量分数、问题、MCP建议）
• \[x\] MCP文档的自动生成
• \[x\] 人工智能辅助安全审计（OWASP合规性）
• \[x\] 生成的MCP代码验证
• \[x\] 规范优化（分页、缓存、批处理）
• \[x\] 对MCP服务器的改进建议
• \[x\] 按任务类型配置的模型（规范分析、代码生成、文档、验证）
• \[x\] IA的7个端点(/api/ai/*)

📦 Minio存储（S3兼容）

• \[x\] 带有存储抽象的Minio适配器
• \[x\] 本地适配器（文件系统）作为备份
• \[x\] Buckets dedicados：规格、工件、报告、备份
• \[x\] 安全下载的预签名URL
• \[x\] 辅助工具：store_spec、store_mcp_artifact、store_report
• \[x\] 7个端点去存储(/api/storage/*)

🔐 OAuth2令牌管理

• \[x\] 集中令牌管理器OAuth2
• \[x\] 自动发现
• \[x\] 令牌存储：内存y Redis
• \[x\] 自动刷新令牌
• \[x\] 将身份验证上下文传播到MCP服务器
• \[x\] 5个端点OAuth2(/api/auth/oauth2/*)

⚙️ 基础设施

• \[x\] 使用pydantic设置进行集中配置
• \[x\] 功能切换： ENABLE_AI, ENABLE_STORAGE, ENABLE_OAUTH2, ENABLE_AGENTS
• \[x\] .env.example 所有环境变量
• \[x\] docker-compose.dev.yml （PostgreSQL、Redis、MinIO、Ollama）
• \[x\] 功能状态终结点(/api/features)

______________________________________________________________________

积压（Sin priorizar）

______________________________________________________________________

为 Roadmap 贡献

你有新功能的想法吗？

1. 打开一个 问题 带有标签 enhancement
2. 描述用例和好处
3. 如果可能，包括Mockup或图表
4. 投票👍 在现有功能中优先考虑

______________________________________________________________________

争议

1. 叉库
2. 创建分支（git checkout -b feature/nueva-funcionalidad)
3. 安装开发依赖项： pip install -e ".[dev]"
4. 运行测试： pytest
5. 提交更改(git commit -am 'Agregar funcionalidad')
6. 推拉拉马(git push origin feature/nueva-funcionalidad)
7. 打开拉动请求

______________________________________________________________________

许可证

MIT许可证-版本 许可证 关于细节。

______________________________________________________________________

开发用于通过MCP自动化企业微服务与LLMS的集成。

技术堆栈： Python 3.10+| Flask | SQLAlchemy | Pydantic | Ollama | MinIO | Redis | OAuth2/OIDC