openapi-docs-mcp 0.1.6 → 0.1.7
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.
- package/README.md +5 -5
- package/dist/mcp/server.d.ts.map +1 -1
- package/dist/mcp/server.js +11 -5
- package/dist/mcp/server.js.map +1 -1
- package/package.json +41 -41
package/README.md
CHANGED
|
@@ -180,7 +180,7 @@ mise exec node@24 -- npx --yes openapi-docs-mcp \
|
|
|
180
180
|
| :------- | :--: | :----------------------------------------------- |
|
|
181
181
|
| `query` | 否 | 搜索关键词，例如 `异常分页列表` 或 `create user` |
|
|
182
182
|
| `method` | 否 | HTTP 方法过滤条件，例如 `GET`、`POST` |
|
|
183
|
-
| `tag` | 否 |
|
|
183
|
+
| `tag` | 否 | 忽略大小写、完整匹配 OpenAPI Tag |
|
|
184
184
|
| `limit` | 否 | 返回数量，默认 10，最大 50 |
|
|
185
185
|
|
|
186
186
|
搜索依次侧重 `summary`、`tags`、`path`、`description` 和 `operationId`。中文搜索不依赖空格分词，会结合标准化、包含匹配和字符片段进行评分。
|
|
@@ -189,7 +189,7 @@ mise exec node@24 -- npx --yes openapi-docs-mcp \
|
|
|
189
189
|
|
|
190
190
|
获取单个接口的完整上下文，包括 HTTP 方法、路径、参数、请求体、响应、Tags、Security、Deprecated 元数据和展开后的 Schema。
|
|
191
191
|
|
|
192
|
-
优先传入 `search_api` 返回的 `id
|
|
192
|
+
优先传入 `search_api` 返回的 `id`。如果用户已经提供精确的 `path` 和 `method`，可以直接查询；如果只提供 `path`，应先用 `search_api` 确认对应的 HTTP 方法。精确查询失败时，不应静默替换成猜测的接口。`maxDepth` 控制 Schema 最大展开深度，默认 5，范围为 1–12。
|
|
193
193
|
|
|
194
194
|
### `get_schema`
|
|
195
195
|
|
|
@@ -206,9 +206,9 @@ mise exec node@24 -- npx --yes openapi-docs-mcp \
|
|
|
206
206
|
## 推荐调用流程
|
|
207
207
|
|
|
208
208
|
```text
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
search_api 搜索候选接口
|
|
209
|
+
用户提供精确 path + method ──────────→ get_api 直接查询
|
|
210
|
+
│
|
|
211
|
+
└─ 否：用简短关键词调用 search_api 搜索候选接口
|
|
212
212
|
↓
|
|
213
213
|
根据 summary、tag、path 选择接口
|
|
214
214
|
↓
|
package/dist/mcp/server.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAc/C,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,
|
|
1
|
+
{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAEzD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAc/C,wBAAgB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,CAwIlE"}
|
package/dist/mcp/server.js
CHANGED
|
@@ -14,11 +14,17 @@ export function createMcpServer(service) {
|
|
|
14
14
|
});
|
|
15
15
|
server.registerTool("search_api", {
|
|
16
16
|
title: "Search OpenAPI operations",
|
|
17
|
-
description: "Search API operations by
|
|
17
|
+
description: "Search API operations by keywords, path, tag, description, or operationId. Preserve exact identifiers from the user instead of rewriting them. For colloquial, synonymous, or cross-language requests, make separate calls with multiple short query variants, then call get_api to verify candidates. Do not include conversational filler or negated alternatives in the query.",
|
|
18
18
|
inputSchema: z.object({
|
|
19
|
-
query: z
|
|
19
|
+
query: z
|
|
20
|
+
.string()
|
|
21
|
+
.default("")
|
|
22
|
+
.describe("Concise OpenAPI-style keywords: 1–4 entity/action terms, not the full user sentence. Preserve exact paths and operationIds. Examples: 用户 停用, 支付 退款, task exception."),
|
|
20
23
|
method: z.string().optional().describe("Optional HTTP method filter"),
|
|
21
|
-
tag: z
|
|
24
|
+
tag: z
|
|
25
|
+
.string()
|
|
26
|
+
.optional()
|
|
27
|
+
.describe("Optional case-insensitive full tag filter"),
|
|
22
28
|
limit: z.number().int().min(1).max(50).default(10),
|
|
23
29
|
}),
|
|
24
30
|
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
@@ -33,7 +39,7 @@ export function createMcpServer(service) {
|
|
|
33
39
|
}));
|
|
34
40
|
server.registerTool("get_api", {
|
|
35
41
|
title: "Get one OpenAPI operation",
|
|
36
|
-
description: "Get the request parameters, expanded request body, responses, tags, and metadata for one operation.
|
|
42
|
+
description: "Get the request parameters, expanded request body, responses, tags, and metadata for one operation. Call directly when the user provides an exact path and method, or an id returned by search_api. For a path without a method, call search_api first with the exact path to discover method-specific candidates. If an exact lookup fails, never silently replace it with a guessed candidate; report the failure and clearly label any separately searched alternatives.",
|
|
37
43
|
inputSchema: z
|
|
38
44
|
.object({
|
|
39
45
|
id: z.string().optional().describe("Stable id returned by search_api"),
|
|
@@ -73,7 +79,7 @@ export function createMcpServer(service) {
|
|
|
73
79
|
});
|
|
74
80
|
server.registerTool("list_groups", {
|
|
75
81
|
title: "List OpenAPI groups",
|
|
76
|
-
description: "List tags with their operation counts.",
|
|
82
|
+
description: "List tags with their operation counts. Use this before search_api when the document's business terminology is unclear, then pass the most relevant exact tag as a filter. Skip this discovery step when the user already provides an exact id or path.",
|
|
77
83
|
inputSchema: z.object({}),
|
|
78
84
|
annotations: { readOnlyHint: true, idempotentHint: true },
|
|
79
85
|
}, async () => success({ groups: service.listGroups() }));
|
package/dist/mcp/server.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AACzD,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAC/D,MAAM,WAAW,GAAG,aAAa,CAAC,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,oBAAoB,CAEtE,CAAC;AAEF,IAAI,OAAO,WAAW,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;IAC5C,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;AAC7D,CAAC;AAED,MAAM,aAAa,GAAG,WAAW,CAAC,OAAO,CAAC;AAE1C,MAAM,UAAU,eAAe,CAAC,OAAuB;IACrD,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,aAAa;KACvB,CAAC,CAAC;IAEH,MAAM,CAAC,YAAY,CACjB,YAAY,EACZ;QACE,KAAK,EAAE,2BAA2B;QAClC,WAAW,EACT,
|
|
1
|
+
{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,41 +1,41 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "openapi-docs-mcp",
|
|
3
|
-
"version": "0.1.
|
|
4
|
-
"description": "A vendor-neutral MCP server for searching and understanding OpenAPI documents.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"openapi-docs-mcp": "dist/cli.js"
|
|
8
|
-
},
|
|
9
|
-
"exports": {
|
|
10
|
-
".": "./dist/index.js"
|
|
11
|
-
},
|
|
12
|
-
"files": [
|
|
13
|
-
"dist",
|
|
14
|
-
"README.md",
|
|
15
|
-
"LICENSE"
|
|
16
|
-
],
|
|
17
|
-
"scripts": {
|
|
18
|
-
"build": "tsc -p tsconfig.build.json",
|
|
19
|
-
"dev": "tsx src/cli.ts",
|
|
20
|
-
"test": "vitest run",
|
|
21
|
-
"test:watch": "vitest",
|
|
22
|
-
"typecheck": "tsc --noEmit"
|
|
23
|
-
},
|
|
24
|
-
"engines": {
|
|
25
|
-
"node": ">=20"
|
|
26
|
-
},
|
|
27
|
-
"license": "MIT",
|
|
28
|
-
"dependencies": {
|
|
29
|
-
"@modelcontextprotocol/server": "^2.0.0",
|
|
30
|
-
"@scalar/openapi-parser": "^0.28.12",
|
|
31
|
-
"@scalar/openapi-types": "^0.9.4",
|
|
32
|
-
"zod": "^4.4.3"
|
|
33
|
-
},
|
|
34
|
-
"devDependencies": {
|
|
35
|
-
"@modelcontextprotocol/client": "^2.0.0",
|
|
36
|
-
"@types/node": "^26.2.0",
|
|
37
|
-
"tsx": "^4.23.12",
|
|
38
|
-
"typescript": "^7.0.2",
|
|
39
|
-
"vitest": "^4.1.10"
|
|
40
|
-
}
|
|
41
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "openapi-docs-mcp",
|
|
3
|
+
"version": "0.1.7",
|
|
4
|
+
"description": "A vendor-neutral MCP server for searching and understanding OpenAPI documents.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"openapi-docs-mcp": "dist/cli.js"
|
|
8
|
+
},
|
|
9
|
+
"exports": {
|
|
10
|
+
".": "./dist/index.js"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"dist",
|
|
14
|
+
"README.md",
|
|
15
|
+
"LICENSE"
|
|
16
|
+
],
|
|
17
|
+
"scripts": {
|
|
18
|
+
"build": "tsc -p tsconfig.build.json",
|
|
19
|
+
"dev": "tsx src/cli.ts",
|
|
20
|
+
"test": "vitest run",
|
|
21
|
+
"test:watch": "vitest",
|
|
22
|
+
"typecheck": "tsc --noEmit"
|
|
23
|
+
},
|
|
24
|
+
"engines": {
|
|
25
|
+
"node": ">=20"
|
|
26
|
+
},
|
|
27
|
+
"license": "MIT",
|
|
28
|
+
"dependencies": {
|
|
29
|
+
"@modelcontextprotocol/server": "^2.0.0",
|
|
30
|
+
"@scalar/openapi-parser": "^0.28.12",
|
|
31
|
+
"@scalar/openapi-types": "^0.9.4",
|
|
32
|
+
"zod": "^4.4.3"
|
|
33
|
+
},
|
|
34
|
+
"devDependencies": {
|
|
35
|
+
"@modelcontextprotocol/client": "^2.0.0",
|
|
36
|
+
"@types/node": "^26.2.0",
|
|
37
|
+
"tsx": "^4.23.12",
|
|
38
|
+
"typescript": "^7.0.2",
|
|
39
|
+
"vitest": "^4.1.10"
|
|
40
|
+
}
|
|
41
|
+
}
|