api2mcp 0.3.1 → 0.4.0-beta.0

package/README.md

@@ -8,11 +8,28 @@
 - 📝 **完整支持**: 支持 OpenAPI 3.x 规范，包括路径参数、查询参数、请求体等
 - 🚀 **简单易用**: 通过 CLI 或配置文件快速启动
 - 🔌 **MCP 兼容**: 完全兼容 MCP 协议，可在 Claude Desktop 等 MCP 客户端中使用
+- 🎯 **按需模式**: 针对大型 OpenAPI 文档，提供按需发现和调用 API 的模式
 
 ## 安装
 
 ```bash
-# 使用 pnpm
+# 推荐使用 npx，无需安装
+npx api2mcp --url https://petstore3.swagger.io/api/v3/openapi.json
+
+# 或全局安装
+npm install -g api2mcp
+# 或
+pnpm add -g api2mcp
+```
+
+## 从源码构建
+
+```bash
+# 克隆仓库
+git clone https://github.com/shenjingnan/api2mcp.git
+cd api2mcp
+
+# 安装依赖
 pnpm install
 
 # 构建
@@ -21,23 +38,40 @@ pnpm build
 
 ## 使用方法
 
-### CLI
+### npx 快速使用（推荐）
+
+无需安装，直接使用 npx 运行：
 
 ```bash
 # 基本使用
-api2mcp --url https://petstore3.swagger.io/api/v3/openapi.json
+npx api2mcp --url https://petstore3.swagger.io/api/v3/openapi.json
 
 # 指定基础 URL
-api2mcp --url ./openapi.json --base-url https://api.example.com
+npx api2mcp --url ./openapi.json --base-url https://api.example.com
 
 # 带认证头
-api2mcp --url https://api.example.com/openapi.json --headers '{"Authorization":"Bearer xxx"}'
+npx api2mcp --url https://api.example.com/openapi.json --headers '{"Authorization":"Bearer xxx"}'
 
 # 带工具前缀
-api2mcp --url https://api.example.com/openapi.json --prefix myapi
+npx api2mcp --url https://api.example.com/openapi.json --prefix myapi
 
 # 调试模式
-api2mcp --url https://api.example.com/openapi.json --debug
+npx api2mcp --url https://api.example.com/openapi.json --debug
+```
+
+### CLI
+
+如果需要全局安装：
+
+```bash
+# 使用 pnpm 全局安装
+pnpm add -g api2mcp
+
+# 或使用 npm 全局安装
+npm install -g api2mcp
+
+# 然后直接运行
+api2mcp --url https://petstore3.swagger.io/api/v3/openapi.json
 ```
 
 ### CLI 参数
@@ -49,6 +83,7 @@ api2mcp --url https://api.example.com/openapi.json --debug
 | `--timeout` | `-t` | 请求超时时间 (毫秒) |
 | `--headers` | `-h` | 自定义请求头 (JSON 字符串) |
 | `--prefix` | `-p` | 工具名前缀 |
+| `--mode` | `-m` | 工作模式：`default`（默认）或 `ondemand`（按需） |
 | `--debug` | `-d` | 启用调试模式 |
 
 ### 配置文件
@@ -68,10 +103,61 @@ api2mcp --url https://api.example.com/openapi.json --debug
   "headers": {
     "Authorization": "Bearer your-token"
   },
-  "toolPrefix": "myapi"
+  "toolPrefix": "myapi",
+  "mode": "default"
 }
 ```
 
+## 工作模式
+
+api2mcp 支持两种工作模式：
+
+### 默认模式 (default)
+
+将所有 API 直接转换为 MCP 工具。适合 API 数量较少的场景。
+
+```bash
+npx api2mcp --url https://api.example.com/openapi.json --mode default
+```
+
+### 按需模式 (ondemand)
+
+当 OpenAPI 文档包含大量端点（如数百或数千个）时，按需模式提供更好的体验：
+
+- **减少上下文占用**: 不会预先注册所有工具，节省 LLM 上下文空间
+- **按需发现**: LLM 可以搜索和浏览可用的 API
+- **直接执行**: 找到需要的 API 后直接调用
+
+```bash
+npx api2mcp --url https://api.example.com/openapi.json --mode ondemand
+```
+
+#### 按需模式提供的工具
+
+| 工具名 | 功能 |
+|--------|------|
+| `api_list` | 分页浏览所有 API，支持按标签过滤 |
+| `api_search` | 模糊搜索 API（名称、摘要、描述、路径） |
+| `api_detail` | 获取 API 的详细信息和参数 Schema |
+| `api_execute` | 直接执行 API 调用 |
+
+#### 使用示例
+
+```
+用户: 我需要查询用户信息
+
+LLM 调用流程:
+1. api_search(query="user") → 找到相关 API
+2. api_detail(id="get_user") → 查看参数要求
+3. api_execute(operationId="get_user", parameters={userId: 123}) → 执行调用
+```
+
+#### 推荐场景
+
+- OpenAPI 文档包含 100+ 个端点
+- API 数量众多但通常只需要少数几个
+- 希望减少 MCP 客户端的加载时间
+
 ### 环境变量
 
 | 环境变量 | 说明 |
@@ -84,7 +170,7 @@ api2mcp --url https://api.example.com/openapi.json --debug
 
 ### 在 Claude Desktop 中使用
 
-在 Claude Desktop 配置文件中添加:
+在 Claude Desktop 配置文件中添加：
 
 **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
 **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
@@ -93,13 +179,15 @@ api2mcp --url https://api.example.com/openapi.json --debug
 {
   "mcpServers": {
     "api2mcp": {
-      "command": "node",
-      "args": ["/path/to/api2mcp/bin/api2mcp.js", "--url", "https://api.example.com/openapi.json"]
+      "command": "npx",
+      "args": ["-y", "api2mcp", "--url", "https://api.example.com/openapi.json"]
     }
   }
 }
 ```
 
+> **注意**: 使用 `-y` 参数可以自动确认 npx 的安装提示，避免交互式确认。
+
 ## 配置优先级
 
 配置加载优先级 (从高到低):