openapi-docs-mcp 0.1.0 → 0.1.3

package/README.md

@@ -17,41 +17,84 @@
 - Node.js 20 或更高版本
 - 开发时建议使用 pnpm 11 或更高版本
 
-## 安装与构建
+## 快速开始
+
+包已经发布到 npm：[openapi-docs-mcp](https://www.npmjs.com/package/openapi-docs-mcp)。
+
+### 使用 npx（推荐）
+
+不需要安装，直接下载并运行指定版本：
 
 ```bash
-pnpm install
-pnpm build
+npx -y openapi-docs-mcp@0.1.3 \
+  --source https://api.example.com/v3/api-docs \
+  --timeout 30000
+```
+
+建议在 MCP 配置中固定版本，例如 `openapi-docs-mcp@0.1.3`，避免新版本自动升级后改变行为。
+
+如果希望始终使用最新版本：
+
+```bash
+npx -y openapi-docs-mcp@latest \
+  --source https://api.example.com/v3/api-docs
 ```
 
-构建产物位于 `dist/`。
+### 使用 pnpm dlx
 
-## 启动服务
+```bash
+pnpm dlx openapi-docs-mcp@0.1.3 \
+  --source https://api.example.com/v3/api-docs \
+  --timeout 30000
+```
+
+### 全局安装
+
+```bash
+npm install --global openapi-docs-mcp@0.1.3
+```
+
+安装后可以直接执行：
+
+```bash
+openapi-docs-mcp \
+  --source https://api.example.com/v3/api-docs \
+  --timeout 30000
+```
+
+升级全局版本：
+
+```bash
+npm install --global openapi-docs-mcp@latest
+```
+
+## 启动参数示例
 
 ### 加载本地文档
 
 支持 OpenAPI/Swagger JSON 和 YAML 文件：
 
 ```bash
-node dist/cli.js --source ./openapi.json
+npx -y openapi-docs-mcp@0.1.3 --source ./openapi.json
 ```
 
 也可以直接使用位置参数：
 
 ```bash
-node dist/cli.js ./openapi.yaml
+npx -y openapi-docs-mcp@0.1.3 ./openapi.yaml
 ```
 
 ### 加载远程文档
 
 ```bash
-node dist/cli.js --source https://api.example.com/v3/api-docs
+npx -y openapi-docs-mcp@0.1.3 \
+  --source https://api.example.com/v3/api-docs
 ```
 
 默认远程加载超时时间为 10 秒，可以通过 `--timeout` 修改：
 
 ```bash
-node dist/cli.js \
+npx -y openapi-docs-mcp@0.1.3 \
   --source https://api.example.com/v3/api-docs \
   --timeout 20000
 ```
@@ -61,7 +104,7 @@ node dist/cli.js \
 可以重复使用 `--header`，格式为 `NAME=VALUE`：
 
 ```bash
-node dist/cli.js \
+npx -y openapi-docs-mcp@0.1.3 \
   --source https://api.example.com/v3/api-docs \
   --header Authorization="Bearer token" \
   --header X-Tenant-Id=tenant-1
@@ -84,14 +127,113 @@ node dist/cli.js \
 
 ## MCP Client 配置
 
-构建完成后，可以在任意支持 stdio MCP Server 的 Client 中添加配置。
-
-路径建议使用绝对路径：
+可以在任意支持 stdio MCP Server 的 Client 中通过 `npx` 启动，无需克隆或构建本项目：
 
 ```json
 {
   "mcpServers": {
     "project-api-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "openapi-docs-mcp@0.1.3",
+        "--source",
+        "https://api.example.com/v3/api-docs",
+        "--timeout",
+        "30000"
+      ]
+    }
+  }
+}
+```
+
+### VS Code + mise 兼容配置
+
+VS Code 使用顶层字段 `servers`。如果 VS Code 扩展宿主误用了旧版 Node.js 或旧版 `npx`，可能出现 `ERROR: You must supply a command.`。此时可以让 VS Code 通过 `mise` 固定使用 Node.js 24，再启动本包：
+
+```json
+{
+  "servers": {
+    "project-api-docs": {
+      "type": "stdio",
+      "command": "mise",
+      "args": [
+        "exec",
+        "node@24",
+        "--",
+        "npx",
+        "--yes",
+        "openapi-docs-mcp@0.1.3",
+        "--source",
+        "https://api.example.com/v3/api-docs",
+        "--timeout",
+        "30000"
+      ]
+    }
+  }
+}
+```
+
+在终端执行 `where.exe mise` 可以查看本机 `mise.exe` 的实际路径，并替换示例中的 `command`。配置步骤：
+
+1. 在 VS Code 中按 `Ctrl + Shift + P`；
+2. 执行 `MCP: Open User Configuration`；
+3. 写入上述配置并替换 OpenAPI 地址；
+4. 执行 `MCP: List Servers`，启动或重启 `project-api-docs`。
+
+推荐将包含内部 OpenAPI 地址或鉴权信息的配置放在 VS Code 用户配置中，不要提交到项目仓库。MCP 使用 stdio 通信，由 VS Code 负责启动进程，不需要提前在终端中常驻运行命令。
+
+同一个 npm 包可以使用不同 OpenAPI 文档启动多个实例，因此不同项目之间不会冲突。
+
+### 同时配置多个实例
+
+每个实例使用不同的 MCP Server 名称和 `--source`：
+
+```json
+{
+  "mcpServers": {
+    "safety-api-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "openapi-docs-mcp@0.1.3",
+        "--source",
+        "https://safety.example.com/v3/api-docs",
+        "--timeout",
+        "30000"
+      ]
+    },
+    "mall-api-docs": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "openapi-docs-mcp@0.1.3",
+        "--source",
+        "https://mall.example.com/v3/api-docs",
+        "--timeout",
+        "30000"
+      ]
+    }
+  }
+}
+```
+
+### 使用本地源码构建
+
+参与开发时才需要克隆源码并构建：
+
+```bash
+pnpm install
+pnpm build
+node dist/cli.js --source ./openapi.json
+```
+
+本地 MCP 配置需要使用 `dist/cli.js` 的绝对路径：
+
+```json
+{
+  "mcpServers": {
+    "local-api-docs": {
       "command": "node",
       "args": [
         "C:/absolute/path/openapi-docs-mcp/dist/cli.js",
@@ -103,8 +245,6 @@ node dist/cli.js \
 }
 ```
 
-同一个 npm 包可以使用不同 OpenAPI 文档启动多个实例，因此不同项目之间不会冲突。
-
 ## MCP 工具
 
 ### `search_api`
@@ -115,22 +255,22 @@ node dist/cli.js \
 
 输入参数：
 
-| 参数 | 必填 | 说明 |
-|---|---:|---|
-| `query` | 否 | 搜索关键词，例如 `异常分页列表` 或 `create user` |
-| `method` | 否 | HTTP 方法过滤条件，例如 `GET`、`POST` |
-| `tag` | 否 | 精确匹配 OpenAPI Tag |
-| `limit` | 否 | 返回数量，默认 10，最大 50 |
+| 参数     | 必填 | 说明                                             |
+| -------- | ---: | ------------------------------------------------ |
+| `query`  |   否 | 搜索关键词，例如 `异常分页列表` 或 `create user` |
+| `method` |   否 | HTTP 方法过滤条件，例如 `GET`、`POST`            |
+| `tag`    |   否 | 精确匹配 OpenAPI Tag                             |
+| `limit`  |   否 | 返回数量，默认 10，最大 50                       |
 
 搜索字段权重：
 
-| 字段 | 权重 |
-|---|---:|
-| `summary` | 10 |
-| `tags` | 8 |
-| `path` | 6 |
-| `description` | 4 |
-| `operationId` | 2 |
+| 字段          | 权重 |
+| ------------- | ---: |
+| `summary`     |   10 |
+| `tags`        |    8 |
+| `path`        |    6 |
+| `description` |    4 |
+| `operationId` |    2 |
 
 中文搜索不依赖空格分词，会使用标准化、包含匹配以及二元/三元字符片段进行评分。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openapi-docs-mcp",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "A vendor-neutral MCP server for searching and understanding OpenAPI documents.",
   "type": "module",
   "bin": {