openapi-docs-mcp 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +61 -25
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -26,12 +26,12 @@
26
26
  不需要安装，直接下载并运行指定版本：
27
27
 
28
28
  ```bash
29
- npx -y openapi-docs-mcp@0.1.2 \
29
+ npx -y openapi-docs-mcp@0.1.3 \
30
30
  --source https://api.example.com/v3/api-docs \
31
31
  --timeout 30000
32
32
  ```
33
33
 
34
- 建议在 MCP 配置中固定版本，例如 `openapi-docs-mcp@0.1.2`，避免新版本自动升级后改变行为。
34
+ 建议在 MCP 配置中固定版本，例如 `openapi-docs-mcp@0.1.3`，避免新版本自动升级后改变行为。
35
35
 
36
36
  如果希望始终使用最新版本：
37
37
 
@@ -43,7 +43,7 @@ npx -y openapi-docs-mcp@latest \
43
43
  ### 使用 pnpm dlx
44
44
 
45
45
  ```bash
46
- pnpm dlx openapi-docs-mcp@0.1.2 \
46
+ pnpm dlx openapi-docs-mcp@0.1.3 \
47
47
  --source https://api.example.com/v3/api-docs \
48
48
  --timeout 30000
49
49
  ```
@@ -51,7 +51,7 @@ pnpm dlx openapi-docs-mcp@0.1.2 \
51
51
  ### 全局安装
52
52
 
53
53
  ```bash
54
- npm install --global openapi-docs-mcp@0.1.2
54
+ npm install --global openapi-docs-mcp@0.1.3
55
55
  ```
56
56
 
57
57
  安装后可以直接执行：
@@ -75,26 +75,26 @@ npm install --global openapi-docs-mcp@latest
75
75
  支持 OpenAPI/Swagger JSON 和 YAML 文件：
76
76
 
77
77
  ```bash
78
- npx -y openapi-docs-mcp@0.1.2 --source ./openapi.json
78
+ npx -y openapi-docs-mcp@0.1.3 --source ./openapi.json
79
79
  ```
80
80
 
81
81
  也可以直接使用位置参数：
82
82
 
83
83
  ```bash
84
- npx -y openapi-docs-mcp@0.1.2 ./openapi.yaml
84
+ npx -y openapi-docs-mcp@0.1.3 ./openapi.yaml
85
85
  ```
86
86
 
87
87
  ### 加载远程文档
88
88
 
89
89
  ```bash
90
- npx -y openapi-docs-mcp@0.1.2 \
90
+ npx -y openapi-docs-mcp@0.1.3 \
91
91
  --source https://api.example.com/v3/api-docs
92
92
  ```
93
93
 
94
94
  默认远程加载超时时间为 10 秒，可以通过 `--timeout` 修改：
95
95
 
96
96
  ```bash
97
- npx -y openapi-docs-mcp@0.1.2 \
97
+ npx -y openapi-docs-mcp@0.1.3 \
98
98
  --source https://api.example.com/v3/api-docs \
99
99
  --timeout 20000
100
100
  ```
@@ -104,7 +104,7 @@ npx -y openapi-docs-mcp@0.1.2 \
104
104
  可以重复使用 `--header`，格式为 `NAME=VALUE`：
105
105
 
106
106
  ```bash
107
- npx -y openapi-docs-mcp@0.1.2 \
107
+ npx -y openapi-docs-mcp@0.1.3 \
108
108
  --source https://api.example.com/v3/api-docs \
109
109
  --header Authorization="Bearer token" \
110
110
  --header X-Tenant-Id=tenant-1
@@ -136,7 +136,7 @@ npx -y openapi-docs-mcp@0.1.2 \
136
136
  "command": "npx",
137
137
  "args": [
138
138
  "-y",
139
- "openapi-docs-mcp@0.1.2",
139
+ "openapi-docs-mcp@0.1.3",
140
140
  "--source",
141
141
  "https://api.example.com/v3/api-docs",
142
142
  "--timeout",
@@ -147,6 +147,42 @@ npx -y openapi-docs-mcp@0.1.2 \
147
147
  }
148
148
  ```
149
149
 
150
+ ### VS Code + mise 兼容配置
151
+
152
+ VS Code 使用顶层字段 `servers`。如果 VS Code 扩展宿主误用了旧版 Node.js 或旧版 `npx`，可能出现 `ERROR: You must supply a command.`。此时可以让 VS Code 通过 `mise` 固定使用 Node.js 24，再启动本包：
153
+
154
+ ```json
155
+ {
156
+ "servers": {
157
+ "project-api-docs": {
158
+ "type": "stdio",
159
+ "command": "mise",
160
+ "args": [
161
+ "exec",
162
+ "node@24",
163
+ "--",
164
+ "npx",
165
+ "--yes",
166
+ "openapi-docs-mcp@0.1.3",
167
+ "--source",
168
+ "https://api.example.com/v3/api-docs",
169
+ "--timeout",
170
+ "30000"
171
+ ]
172
+ }
173
+ }
174
+ }
175
+ ```
176
+
177
+ 在终端执行 `where.exe mise` 可以查看本机 `mise.exe` 的实际路径，并替换示例中的 `command`。配置步骤：
178
+
179
+ 1. 在 VS Code 中按 `Ctrl + Shift + P`；
180
+ 2. 执行 `MCP: Open User Configuration`；
181
+ 3. 写入上述配置并替换 OpenAPI 地址；
182
+ 4. 执行 `MCP: List Servers`，启动或重启 `project-api-docs`。
183
+
184
+ 推荐将包含内部 OpenAPI 地址或鉴权信息的配置放在 VS Code 用户配置中，不要提交到项目仓库。MCP 使用 stdio 通信，由 VS Code 负责启动进程，不需要提前在终端中常驻运行命令。
185
+
150
186
  同一个 npm 包可以使用不同 OpenAPI 文档启动多个实例，因此不同项目之间不会冲突。
151
187
 
152
188
  ### 同时配置多个实例
@@ -160,7 +196,7 @@ npx -y openapi-docs-mcp@0.1.2 \
160
196
  "command": "npx",
161
197
  "args": [
162
198
  "-y",
163
- "openapi-docs-mcp@0.1.2",
199
+ "openapi-docs-mcp@0.1.3",
164
200
  "--source",
165
201
  "https://safety.example.com/v3/api-docs",
166
202
  "--timeout",
@@ -171,7 +207,7 @@ npx -y openapi-docs-mcp@0.1.2 \
171
207
  "command": "npx",
172
208
  "args": [
173
209
  "-y",
174
- "openapi-docs-mcp@0.1.2",
210
+ "openapi-docs-mcp@0.1.3",
175
211
  "--source",
176
212
  "https://mall.example.com/v3/api-docs",
177
213
  "--timeout",
@@ -219,22 +255,22 @@ node dist/cli.js --source ./openapi.json
219
255
 
220
256
  输入参数：
221
257
 
222
- | 参数 | 必填 | 说明 |
223
- |---|---:|---|
224
- | `query` | 否 | 搜索关键词，例如 `异常分页列表` 或 `create user` |
225
- | `method` | 否 | HTTP 方法过滤条件，例如 `GET`、`POST` |
226
- | `tag` | 否 | 精确匹配 OpenAPI Tag |
227
- | `limit` | 否 | 返回数量，默认 10，最大 50 |
258
+ | 参数 | 必填 | 说明 |
259
+ | -------- | ---: | ------------------------------------------------ |
260
+ | `query` | 否 | 搜索关键词，例如 `异常分页列表` 或 `create user` |
261
+ | `method` | 否 | HTTP 方法过滤条件，例如 `GET`、`POST` |
262
+ | `tag` | 否 | 精确匹配 OpenAPI Tag |
263
+ | `limit` | 否 | 返回数量，默认 10，最大 50 |
228
264
 
229
265
  搜索字段权重：
230
266
 
231
- | 字段 | 权重 |
232
- |---|---:|
233
- | `summary` | 10 |
234
- | `tags` | 8 |
235
- | `path` | 6 |
236
- | `description` | 4 |
237
- | `operationId` | 2 |
267
+ | 字段 | 权重 |
268
+ | ------------- | ---: |
269
+ | `summary` | 10 |
270
+ | `tags` | 8 |
271
+ | `path` | 6 |
272
+ | `description` | 4 |
273
+ | `operationId` | 2 |
238
274
 
239
275
  中文搜索不依赖空格分词，会使用标准化、包含匹配以及二元/三元字符片段进行评分。
240
276
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openapi-docs-mcp",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "A vendor-neutral MCP server for searching and understanding OpenAPI documents.",
5
5
  "type": "module",
6
6
  "bin": {