Apidocs MCP Server

API文档MCP服务器

模型上下文协议（MCP）服务器，用于分析API文档并推荐前端实现方法。

🚀 主要功能

• 自动分析API文档：自动分析Swagger/OpenAPI JSON或HTML格式的API文档
• 前端推荐：推荐基于分析的API实现前端页面的方法
• 认证支持：还可以分析需要基于Cookie的身份验证的API文档
• 检查API状态：检查端点的状态和响应时间
• 生成代码示例：JavaScript/TypeScript，自动生成Python代码示例
• 端点搜索：基于关键字的API端点搜索
• 导出文档：以JSON、Markdown格式导出API文档
• 基于FastMCP：使用最新的FastMCP规格实现快速高效的服务器

📋 支持的API文档格式

• Swagger/OpenAPI JSON: /swagger.json, /api-docs, /openapi.json 灯
• HTML文档：包含Swagger UI等的HTML页面
• 需要认证的文档：支持基于Cookie的身份验证

🛠️ 安装和运行

本地开发环境

1. 依赖性安装

   pip install -e .

1. 运行服务器

   mcp run api_docs_mcp_server:server

使用Docker运行

1. 映像构建

   docker build -t api-docs-mcp-server .

1. 运行容器

   docker run -p 8080:8080 api-docs-mcp-server

Smithery部署

该项目配置为可在Smithery平台上部署：

1. 安装Smithery CLI

   npm install -g @smithery/cli

1. 部署

   smithery deploy

🔧 使用方法

用于MCP客户端

# MCP 클라이언트 예시
from mcp.client import ClientSession

async with ClientSession("http://localhost:8080") as session:
    # API 문서 분석
    result = await session.call_tool(
        "analyze_api_docs",
        {
            "url": "https://api.example.com/swagger.json",
            "cookies": {"_oauth2_proxy": "your-auth-token"}  # 선택사항
        }
    )
    print(result.content)
    
    # API 상태 확인
    health_result = await session.call_tool(
        "health_check_api",
        {
            "url": "https://api.example.com/swagger.json",
            "max_endpoints": 5
        }
    )
    print(health_result.content)
    
    # 코드 예시 생성
    code_result = await session.call_tool(
        "generate_code_examples",
        {
            "url": "https://api.example.com/swagger.json",
            "endpoint_path": "/api/users"
        }
    )
    print(code_result.content)

🛠️ 可用的工具

1. analyze_api_docs

分析API文档并推荐如何实现前端页面。

参数：

• url （必需）：要分析的API文档的URL
• cookies （可选）：认证所需的Cookie文档

2. get_api_endpoints

从API文档中获取所有端点列表。

参数：

• url （必需）：要分析的API文档的URL
• cookies （可选）：认证所需的Cookie文档

3. health_check_api

检查API端点的状态。

参数：

• url （必需）：API文档的URL
• cookies （可选）：认证所需的Cookie文档
• max_endpoints （可选）：要测试的最大端点数（默认值：10）

4. generate_code_examples

为特定API端点生成代码示例。

参数：

• url （必需）：API文档的URL
• endpoint_path （必需）：生成代码示例的端点路径
• cookies （可选）：认证所需的Cookie文档

5. search_endpoints

在API端点中搜索特定关键字。

参数：

• url （必需）：API文档的URL
• search_term （必需）：要搜索的关键字
• cookies （可选）：认证所需的Cookie文档

6. get_api_info

获取API文档的基本信息。

参数：

• url （必需）：API文档的URL
• cookies （可选）：认证所需的Cookie文档

7. export_api_docs

将API文档导出为多种格式。

参数：

• url （必需）：API文档的URL
• format （可选）：导出格式（json，markdown）（默认：json）
• cookies （可选）：认证所需的Cookie文档

📊 分析结果示例

✅ **API 문서 분석 완료: Example API (1.0.0)**

총 25개의 API 엔드포인트를 발견했습니다.

--- 📄 프론트엔드 페이지 구현 추천 ---

### 💡 사용자 관리 페이지
_사용자 관리 기능 구현을 위한 API들_
- `GET` /api/users (사용자 목록 조회)
- `POST` /api/users (새 사용자 생성)
- `PUT` /api/users/{id} (사용자 정보 수정)
- `DELETE` /api/users/{id} (사용자 삭제)

### 💡 인증/로그인 페이지
_인증/로그인 기능 구현을 위한 API들_
- `POST` /api/auth/login (로그인)
- `POST` /api/auth/logout (로그아웃)
- `GET` /api/auth/me (현재 사용자 정보)

### 💡 결제/결제 페이지
_결제/결제 기능 구현을 위한 API들_
- `POST` /api/payments (결제 생성)
- `GET` /api/payments/{id} (결제 정보 조회)
- `PUT` /api/payments/{id}/cancel (결제 취소)

🏗️ 项目结构

apidocs-mcp-server/
├── src/
│   └── api_docs_mcp_server/
│       └── __init__.py
├── server.py              # 메인 서버 파일
├── pyproject.toml         # 프로젝트 설정
├── Dockerfile            # Docker 설정
├── smithery.yaml         # Smithery 배포 설정
└── README.md             # 이 파일

🔍 主要类别和功能

APIDocs分析仪

• fetch_swagger_docs()：导入Swagger/OpenAPI JSON文档
• fetch_html_docs()：导入HTML格式的API文档
• analyze_swagger_docs()：分析和结构化API文档
• _generate_frontend_recommendations()：创建前端推荐
• health_check_endpoint()：检查各个端点的状态
• generate_code_examples()：生成代码示例

分析结果模型

• APIEndpoint：关于单个API端点
• FrontendRecommendation：推荐分页API
• AnalysisResult：完整分析结果
• APIHealthCheck：API状态检查结果
• CodeExample：代码示例模型

🎯 前端推荐逻辑

服务器建议按以下标准对API进行分组：

• 用户管理: user, member, customer 包括关键字
• 验证/登录: auth, login, token, oauth 包括关键字
• 付款/付款: payment, pay, billing, charge 包括关键字
• 上载文件: upload, file, image, media 包括关键字
• 搜索: search, find, query 包括关键字
• 统计/分析: stats, analytics, report, metric 包括关键字
• 通知/消息: notification, message, alert, push 包括关键字
• 设置/管理: config, setting, admin, management 包括关键字
• 查询数据：GET方法
• 创建/修改数据：POST、PUT、PATCH方法

🔧 设置开发环境

基本要求

• Python 3.10或更高版本
• 点

安装开发依赖性

# 가상환경 생성 (권장)
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -e .

测试

# 서버 실행 테스트
mcp run api_docs_mcp_server:server --host 0.0.0.0 --port 8080

📝 许可证

MIT许可证

🤝 贡献

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📞 支持

如果出现问题或有问题，请生成问题。

______________________________________________________________________

请参见：此服务器采用FastMCP规范实现，与Smithery平台兼容。