AI导哈

OpenAPI协议服务器

一个为AI助手提供OpenAPI规范访问的模型上下文协议服务器，支持OAuth 2.0认证流程。

  • by HaoYan-A
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 HaoYan-A/open-api-mcp

使用说明

开放API MCP服务器

一个模型上下文协议（MCP）服务器，为人工智能助手提供访问OpenAPI规范的途径，并支持OAuth 2.0认证流程。

特性/功能

  • 📖 书籍 OpenAPI 支持加载并解析OpenAPI 2.0、3.0和3.1规范
  • 🔐 OAuth 2.0 认证全面支持密码模式、客户端凭证模式和授权码模式
  • 🔑 翻译成中文是：钥匙 多种认证方法API密钥、Bearer令牌、基本认证和OAuth 2.0
  • 🔍 翻译为中文是：放大镜（或“放大查看”） 智能搜索根据路径、方法、标签或关键词搜索和筛选API端点
  • 📝 翻译成中文是：📝（这个符号本身没有特定的中文翻译，它通常表示“待办事项”或“笔记”的意思，可以理解为“待办事项”或“笔记”）。 详细模式/详细架构获取任意端点的完整请求/响应模式
  • 🚀 表情符号“🚀”通常表示火箭、快速上升或飞速发展，也可以用来形容事情进展迅速或充满活力。在中文中，可以直接用“🚀”这个符号来传达同样的意思，或者根据上下文用相应的文字描述，比如“火箭”、“飞速上升”、“快速发展”等。 API执行直接调用API，自动进行身份验证
  • 📊（表格/数据图表） 请求记录跟踪所有API调用并记录详细日志

安装

选项1：使用npx（推荐）

无需安装！使用 npx 直接运行：

npx @yanhao-an/open-api-mcp

选项2：全局安装

npm install -g @yanhao-an/open-api-mcp
open-api-mcp

选项3：来自源（开发）

git clone https://github.com/HaoYan-A/open-api-mcp.git
cd open-api-mcp
npm install
npm run build
npm start

配置

创建一个 .env 项目根目录中的文件：

# Required: OpenAPI Specification URL
OPENAPI_SPEC_URL=http://127.0.0.1/v3/api-docs

# Authentication Mode
# Options: none, apiKey, bearer, basic, oauth2
AUTH_MODE=oauth2

# OAuth 2.0 Configuration (if AUTH_MODE=oauth2)
OAUTH_FLOW=clientCredentials
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_TOKEN_URL=https://auth.example.com/oauth/token
OAUTH_SCOPE=read write

# Logging
LOG_LEVEL=info
LOG_REQUESTS=true
LOG_RESPONSES=true

认证模式

1. OAuth 2.0 - 客户端凭据流程

最适合机器对机器通信：

AUTH_MODE=oauth2
OAUTH_FLOW=clientCredentials
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_TOKEN_URL=https://auth.example.com/oauth/token
OAUTH_SCOPE=api.access

2. OAuth 2.0 - 密码模式（或密码授权流程）

对于用户名/密码认证：

AUTH_MODE=oauth2
OAUTH_FLOW=password
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_USERNAME=user@example.com
OAUTH_PASSWORD=your-password
OAUTH_TOKEN_URL=https://auth.example.com/oauth/token
OAUTH_SCOPE=read write

3. OAuth 2.0 - 授权码流程

对于带重定向的用户授权：

AUTH_MODE=oauth2
OAUTH_FLOW=authorizationCode
OAUTH_CLIENT_ID=your-client-id
OAUTH_CLIENT_SECRET=your-client-secret
OAUTH_AUTH_URL=https://auth.example.com/oauth/authorize
OAUTH_TOKEN_URL=https://auth.example.com/oauth/token
OAUTH_REDIRECT_URI=http://localhost:3000/callback
OAUTH_CODE=<authorization-code-from-redirect>

4. API密钥认证

AUTH_MODE=apiKey
API_KEY=your-api-key
API_KEY_HEADER=Authorization
API_KEY_PREFIX=Bearer

5. 持有者令牌（或访问令牌）

AUTH_MODE=bearer
BEARER_TOKEN=your-bearer-token

6. 基本认证

AUTH_MODE=basic
BASIC_AUTH_USER=username
BASIC_AUTH_PASS=password

使用

运行服务器

# Development mode
npm run dev

# Production mode
npm start

# Test with MCP Inspector
npm run inspect

与Claude桌面版一起使用

添加到您的Claude桌面配置中（~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：

{
  "mcpServers": {
    "open-api": {
      "command": "npx",
      "args": ["-y", "@yanhao-an/open-api-mcp"],
      "env": {
        "OPENAPI_SPEC_URL": "http://127.0.0.1/v3/api-docs",
        "AUTH_MODE": "oauth2",
        "OAUTH_FLOW": "clientCredentials",
        "OAUTH_CLIENT_ID": "your-client-id",
        "OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTH_TOKEN_URL": "https://auth.example.com/oauth/token"
      }
    }
  }
}

或者如果你已全局安装它：

{
  "mcpServers": {
    "open-api": {
      "command": "open-api-mcp",
      "args": [],
      "env": {
        "OPENAPI_SPEC_URL": "http://127.0.0.1/v3/api-docs",
        "AUTH_MODE": "oauth2",
        "OAUTH_FLOW": "clientCredentials",
        "OAUTH_CLIENT_ID": "your-client-id",
        "OAUTH_CLIENT_SECRET": "your-client-secret",
        "OAUTH_TOKEN_URL": "https://auth.example.com/oauth/token"
      }
    }
  }
}

MCP 工具

1. listApi

列出所有可用的API端点，并可选择性地进行过滤。

参数：

  • tag （可选）：按标签名称筛选
  • limit （可选）：最大结果数（默认：50）
  • offset （可选）：跳过结果（默认：0）

示例：

{
  "tag": "users",
  "limit": 20
}

2. searchApi

根据上面的信息，执行如下指令：。

参数：

  • query （必填）：搜索查询
  • method （可选）：HTTP 方法过滤器
  • tag （可选）：标签过滤器

示例：

{
  "query": "user",
  "method": "GET"
}

3. getApiSchema

获取特定端点的详细模式。

参数：

  • path （必需）：API路径（例如。， /users/{id})
  • method （必填）：HTTP方法

示例：

{
  "path": "/api/users/{id}",
  "method": "GET"
}

4. callApi

执行带有认证的API请求。

参数：

  • path （必填）：API路径
  • method （必填）：HTTP方法
  • params （可选）：查询参数
  • body （可选）：请求体
  • headers （可选）：额外的头部信息

示例：

{
  "path": "/api/users",
  "method": "POST",
  "body": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

5. getAuthStatus

获取当前的认证状态和配置。

6. getApiInfo

获取OpenAPI文档信息（标题、版本、基础URL、标签）。

项目结构

open-api-mcp/
├── src/
│   ├── auth/                 # Authentication management
│   │   ├── auth-manager.ts   # Main auth manager
│   │   ├── oauth2-handler.ts # OAuth 2.0 orchestrator
│   │   ├── token-manager.ts  # Token storage
│   │   └── flows/            # OAuth 2.0 flow implementations
│   ├── openapi/              # OpenAPI document handling
│   │   ├── loader.ts         # Load from URL
│   │   ├── parser.ts         # Parse and index
│   │   └── cache.ts          # Document caching
│   ├── api/                  # API execution
│   │   └── caller.ts         # HTTP client with auth
│   ├── tools/                # MCP tools
│   │   └── index.ts          # Tool registration
│   ├── logger.ts             # Logging utility
│   ├── types.ts              # TypeScript types
│   └── index.ts              # Main entry point
├── package.json
├── tsconfig.json
└── .env

发展

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode
npm run watch

# Test with inspector
npm run inspect

OAuth 2.0 流程详情

令牌管理

  • 自动刷新令牌过期时会自动刷新
  • 令牌缓存有效的令牌会被缓存以减少认证请求
  • 到期缓冲区代币在到期前60秒刷新

流量选择指南

  • 客户端凭据最适合服务器到服务器的通信，不涉及用户上下文
  • 密码流对于使用用户名/密码的受信任应用程序
  • 授权码对于用户授权访问的重定向流程

记录日志

服务器提供详细的日志记录以供调试：

# Log levels: debug, info, warn, error
LOG_LEVEL=debug

# Enable/disable request logging
LOG_REQUESTS=true

# Enable/disable response logging
LOG_RESPONSES=true

请求日志包括：

  • 时间戳
  • HTTP方法和URL
  • 认证模式
  • 请求参数和请求体
  • 响应状态和数据
  • 请求持续时间

故障排除

“无法加载OpenAPI文档”

  • 验证 OPENAPI_SPEC_URL 是正确且可访问的
  • 检查网络连接
  • 确保URL返回有效的OpenAPI JSON/YAML

"OAuth 2.0 流程失败"

  • 验证OAuth凭据（客户端ID、密钥）
  • 检查令牌URL是否正确
  • 确保所需范围可用
  • 检查服务器日志以查找特定错误信息

“令牌刷新失败”

  • 验证刷新令牌是否有效
  • 检查认证服务器是否支持刷新令牌
  • 尝试重新认证以获取新的令牌

许可证

麻省理工学院（MIT）

做出贡献

欢迎贡献！请随时提交问题或拉取请求。

相关 MCP