金大哥 - openapi-mcp MCP 详情

article

README

🚀 OpenAPI智能代理工具使用说明

OpenAPI智能代理工具 openapi-mcp 是一个基于OpenAPI规范生成智能代理工具的脚手架。它能依据给定的OpenAPI/Swagger规范自动生成强大的工具，可有效提升API调用的效率和稳定性。

🚀 快速开始

直接运行镜像

# 示例：使用Weatherbit API示例
docker run --rm -it \
  --mount type=bind,source="$(pwd)/example/weather",target=/app/example/weather \
  ckan tong/openapi-mcp:latest \
    --spec /app/example/weather/swagger.yaml \
    --api-key-env API_KEY \
    --api-key-name key \
    --api-key-loc query

使用Docker Compose启动示例项目

# 在example目录下运行以下命令
docker-compose up --build

✨ 主要特性

openapi-mcp 具备以下强大功能：

自动发现能力：识别目标API的所有端点和参数
请求重试机制：支持失败重试和熔断策略
性能优化：内置结果缓存和链路监控
扩展插件系统：支持自定义中间件和后处理逻辑

📦 安装指南

使用预构建镜像

Docker Hub 镜像：ckan tong/openapi-mcp:latest
特性：
- 已配置默认日志记录级别为 info
- 已安装 python3.8, pip, setuptools

本地构建镜像

# 在项目根目录下运行以下命令
docker build . --tag openapi-mcp:latest

💻 使用示例

基础用法

# 示例：使用Weatherbit API示例
docker run --rm -it \
  --mount type=bind,source="$(pwd)/example/weather",target=/app/example/weather \
  ckan tong/openapi-mcp:latest \
    --spec /app/example/weather/swagger.yaml \
    --api-key-env API_KEY \
    --api-key-name key \
    --api-key-loc query

高级用法

# 在example目录下运行以下命令，使用Docker Compose启动示例项目
docker-compose up --build

📚 详细文档

必要参数

| 参数名 | 类型 | 作用描述 | |-------------------|--------|------------------------------------------------------------------------------------------------| | --spec | string | 指定OpenAPI规范文件路径或URL，必填项 | | --port | int | 设置MCP服务器运行端口，默认为8080 | | --api-key-env | string | 指定包含API密钥的环境变量名称 | | --api-key-name | string | API密钥参数名称，如Header、Query等 | | --api-key-loc | string | 设置密钥传递位置：header, query, path, cookie |

可选参数

| 参数名 | 类型 | 作用描述 | |------------------|-------------|------------------------------------------------------------------------------------------| | --include-tag | string slice| 指定要包含的标签（可重复使用） | | --exclude-tag | string slice| 指定要排除的标签（可重复使用） | | --include-op | string slice| 指定要包含的操作ID（可重复使用） | | --exclude-op | string slice| 指定要排除的操作ID（可重复使用） | | --log-level | log level | 设置日志记录级别，默认为info |

示例项目结构

# 项目根目录结构示例：
.
├── requirements.txt       # 依赖管理文件
├── example/
│   └── weather/
│       ├── swagger.yaml  # OpenAPI规范文件
│       └── README.md     # 示例说明文档
└── main.py                # 主程序入口文件

🔧 技术细节

核心功能模块

代理服务器（MCP）

自动发现API端点
智能路由请求
请求增强与重试

日志与跟踪

分布式链路追踪：集成Jaeger或SkyWalking
实时日志查询：支持ELK Stack

高级功能

熔断降级：保护API调用失败情况
限流策略：防止系统过载
结果缓存：提升响应速度和可用性

高级配置

自定义插件开发

# 示例中间件插件
class MyMiddleware:
    def __init__(self, app):
        self.app = app

    async def __call__(self, request):
        # 在请求前执行自定义逻辑
        print("Custom middleware executed")
        return await self.app(request)

自定义结果处理

def custom_response_handler(response):
    # 在响应处理中添加自定义逻辑
    pass

📚 常见问题

如何设置日志级别？

修改配置文件 config/logging.yml 或在命令行中指定 --log-level=debug

环境变量如何生效？

将环境变量通过 -e 参数传递到Docker容器中：

docker run --rm -it -e API_KEY=your_key ...

📚 相关文档

📞 联系我们

如需反馈或技术支持，请联系：

邮箱：support@ckan-tong.com
微信：CKAN-Tong

openapi-mcp