OpenAPI 智能代理工具使用说明

安装指南

使用预构建镜像

• 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

使用Docker Compose启动示例项目

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

功能概述

openapi-mcp 是一个基于OpenAPI规范生成智能代理工具的脚手架。它能够根据给定的OpenAPI/Swagger规范自动生成一组功能强大的工具，包括：

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

核心功能模块

代理服务器（MCP）

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

日志与跟踪

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

高级功能

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

使用说明

必要参数

可选参数

示例项目结构

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

常见问题

如何设置日志级别？

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

环境变量如何生效？

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

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

高级配置

自定义插件开发

# 示例中间件插件
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

相关文档

• OpenAPI官方文档
• Docker最佳实践

联系我们

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

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