openapi-docs-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# OpenAPI Docs MCP
+
+一个厂商无关的 MCP Server，帮助编码 Agent 搜索和理解 OpenAPI/Swagger 文档，且不会调用文档中描述的真实后端接口。
+
+第一版重点保证结果确定、准确和稳定：
+
+- 启动时加载并校验本地或远程 OpenAPI 文档；
+- 启动完成后，所有工具调用都直接读取内存；
+- 使用明确的字段权重搜索中英文接口元数据；
+- 只在查询接口或 Schema 时按需展开本地 `$ref`；
+- 限制 Schema 展开深度，并检测循环引用；
+- 通过 stdio 暴露 4 个只读 MCP 工具；
+- 不绑定 OpenAI、Claude 或其他模型厂商。
+
+## 环境要求
+
+- Node.js 20 或更高版本
+- 开发时建议使用 pnpm 11 或更高版本
+
+## 安装与构建
+
+```bash
+pnpm install
+pnpm build
+```
+
+构建产物位于 `dist/`。
+
+## 启动服务
+
+### 加载本地文档
+
+支持 OpenAPI/Swagger JSON 和 YAML 文件：
+
+```bash
+node dist/cli.js --source ./openapi.json
+```
+
+也可以直接使用位置参数：
+
+```bash
+node dist/cli.js ./openapi.yaml
+```
+
+### 加载远程文档
+
+```bash
+node dist/cli.js --source https://api.example.com/v3/api-docs
+```
+
+默认远程加载超时时间为 10 秒，可以通过 `--timeout` 修改：
+
+```bash
+node dist/cli.js \
+  --source https://api.example.com/v3/api-docs \
+  --timeout 20000
+```
+
+### 加载需要鉴权的文档
+
+可以重复使用 `--header`，格式为 `NAME=VALUE`：
+
+```bash
+node dist/cli.js \
+  --source https://api.example.com/v3/api-docs \
+  --header Authorization="Bearer token" \
+  --header X-Tenant-Id=tenant-1
+```
+
+日志和错误信息只会写入 stderr，stdout 专门用于传输 MCP 消息。
+
+## CLI 参数
+
+```text
+用法：openapi-docs-mcp --source <文件或URL> [选项]
+
+选项：
+  -s, --source <value>    OpenAPI JSON/YAML 文件或 HTTP(S) URL
+      --header NAME=VALUE 加载远程文档时使用的请求头，可重复传入
+      --timeout <ms>      远程加载超时时间，默认 10000 毫秒
+      --strict-validation 严格模式：任何 OpenAPI 校验警告都会阻止启动
+  -h, --help              显示帮助信息
+```
+
+## MCP Client 配置
+
+构建完成后，可以在任意支持 stdio MCP Server 的 Client 中添加配置。
+
+路径建议使用绝对路径：
+
+```json
+{
+  "mcpServers": {
+    "project-api-docs": {
+      "command": "node",
+      "args": [
+        "C:/absolute/path/openapi-docs-mcp/dist/cli.js",
+        "--source",
+        "C:/absolute/path/openapi.json"
+      ]
+    }
+  }
+}
+```
+
+同一个 npm 包可以使用不同 OpenAPI 文档启动多个实例，因此不同项目之间不会冲突。
+
+## MCP 工具
+
+### `search_api`
+
+根据自然语言关键词、路径、标签、描述或 `operationId` 搜索接口，返回经过排序的轻量候选结果。
+
+正常工作流是先调用 `search_api` 找到接口，再把结果中的 `id` 传给 `get_api`。
+
+输入参数：
+
+| 参数 | 必填 | 说明 |
+|---|---:|---|
+| `query` | 否 | 搜索关键词，例如 `异常分页列表` 或 `create user` |
+| `method` | 否 | HTTP 方法过滤条件，例如 `GET`、`POST` |
+| `tag` | 否 | 精确匹配 OpenAPI Tag |
+| `limit` | 否 | 返回数量，默认 10，最大 50 |
+
+搜索字段权重：
+
+| 字段 | 权重 |
+|---|---:|
+| `summary` | 10 |
+| `tags` | 8 |
+| `path` | 6 |
+| `description` | 4 |
+| `operationId` | 2 |
+
+中文搜索不依赖空格分词，会使用标准化、包含匹配以及二元/三元字符片段进行评分。
+
+### `get_api`
+
+获取单个接口的完整上下文，包括：
+
+- HTTP 方法和路径；
+- Summary、Description 和 Tags；
+- Path、Query、Header、Cookie 参数；
+- Request Body 和 Content-Type；
+- Responses；
+- Security 和 Deprecated 元数据；
+- 按需展开后的 Schema。
+
+优先传入 `search_api` 返回的 `id`，也可以传入精确的 `path` 和可选的 `method`。
+
+`maxDepth` 用于控制 Schema 最大展开深度，默认值为 5，允许范围为 1 到 12。
+
+### `get_schema`
+
+根据精确名称读取 `components.schemas` 中的 Schema。
+
+本地 `$ref` 会按需展开，同时具有：
+
+- 最大深度限制；
+- 最大属性数量限制；
+- 循环引用检测；
+- 无法解析的引用标记。
+
+### `list_groups`
+
+列出 OpenAPI Tags 及每个 Tag 下的接口数量。
+
+没有 Tag 的接口会归入 `untagged`。
+
+## 推荐调用流程
+
+```text
+用户描述需要实现的功能
+        ↓
+search_api 搜索候选接口
+        ↓
+根据 summary、tag、path 选择接口
+        ↓
+get_api 一次获取请求和响应结构
+        ↓
+必要时再调用 get_schema
+        ↓
+生成 TypeScript 类型、API 方法和页面调用代码
+```
+
+## 开发与测试
+
+```bash
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+当前测试覆盖：
+
+- OpenAPI 3.0 文档加载；
+- OpenAPI 3.1 YAML 文档加载；
+- Swagger 2.0 文档加载；
+- 无效文档错误处理；
+- 中文加权搜索；
+- Method 和 Tag 过滤；
+- 接口请求与响应 Schema 展开；
+- 循环引用保护；
+- MCP 工具发现与调用。
+
+## 当前版本边界
+
+第一版有意保持较小的功能范围。
+
+已经支持：
+
+- OpenAPI 3.0、3.1；
+- Swagger 2.0；
+- JSON 和 YAML；
+- 本地文件和 HTTP(S) URL；
+- 本地 `$ref` 按需展开；
+- stdio MCP 传输。
+
+暂不支持：
+
+- 调用真实后端 API；
+- 保存或管理后端鉴权凭证；
+- 展开其他文件或 URL 中的外部 `$ref`；
+- 向量数据库或 Embedding 搜索；
+- Streamable HTTP MCP 部署；
+- OpenAPI 文档自动刷新；
+- 模型厂商私有能力。
+
+当 OpenAPI 文档发生变化时，重启 MCP Server 即可重新加载和建立索引。
+
+## 设计原则
+
+```text
+OpenAPI / Swagger
+        ↓
+加载与校验
+        ↓
+标准 OpenAPI Document
+        ↓
+内存 Operation 索引
+        ↓
+Search + Formatter
+        ↓
+标准 MCP Tools
+        ↓
+任意支持 MCP 的 Agent 或 IDE
+```
+
+项目不会把 OpenAPI 数据重新转换成一套重复的核心模型。OpenAPI Document 始终是事实来源，自定义类型只用于搜索结果和 MCP 输出。
+
+Formatter 也不会擅自修复后端文档中的可疑定义，而是忠实返回 OpenAPI 声明的内容，避免工具本身成为新的错误来源。
+
+默认使用兼容校验模式。部分 Springdoc 文档会生成包含中文名称的本地 `$ref`；严格的 URI 校验器可能拒绝这类引用。只要引用目标真实存在，本项目会保留警告并继续加载。需要完全遵循严格校验结果时，可以添加 `--strict-validation`。

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+interface CliOptions {
+    source: string;
+    timeoutMs?: number;
+    headers: Record<string, string>;
+    strictValidation: boolean;
+}
+export declare function parseArgs(args: string[]): CliOptions;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAMA,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAsBD,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CA2CpD"}

package/dist/cli.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { loadOpenApi } from "./openapi/loader.js";
+import { createMcpServer } from "./mcp/server.js";
+import { OpenApiService } from "./service.js";
+async function main() {
+    const options = parseArgs(process.argv.slice(2));
+    const context = await loadOpenApi(options.source, {
+        ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
+        ...(Object.keys(options.headers).length ? { headers: options.headers } : {}),
+        validationMode: options.strictValidation ? "strict" : "compatible",
+    });
+    const service = new OpenApiService(context);
+    console.error(`Loaded ${context.operations.length} operations from ${context.source} (OpenAPI ${context.version})`);
+    for (const warning of context.validationWarnings) {
+        console.error(`Validation warning (${warning.count}): ${warning.message}`);
+    }
+    serveStdio(() => createMcpServer(service), {
+        onerror: (error) => console.error(error),
+    });
+}
+export function parseArgs(args) {
+    let source;
+    let timeoutMs;
+    let strictValidation = false;
+    const headers = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--source" || argument === "-s") {
+            source = requireValue(args, ++index, argument);
+        }
+        else if (argument === "--timeout") {
+            const raw = requireValue(args, ++index, argument);
+            timeoutMs = Number(raw);
+            if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+                throw new Error("--timeout must be a positive number in milliseconds");
+            }
+        }
+        else if (argument === "--header") {
+            const raw = requireValue(args, ++index, argument);
+            const separator = raw.indexOf("=");
+            if (separator <= 0)
+                throw new Error("--header must use NAME=VALUE");
+            headers[raw.slice(0, separator)] = raw.slice(separator + 1);
+        }
+        else if (argument === "--strict-validation") {
+            strictValidation = true;
+        }
+        else if (argument === "--help" || argument === "-h") {
+            printHelp();
+            process.exit(0);
+        }
+        else if (argument?.startsWith("-")) {
+            throw new Error(`Unknown option: ${argument}`);
+        }
+        else if (argument) {
+            if (source)
+                throw new Error("Only one OpenAPI source may be provided");
+            source = argument;
+        }
+    }
+    if (!source) {
+        throw new Error("Missing OpenAPI source. Pass --source <file-or-url>.");
+    }
+    return {
+        source,
+        headers,
+        strictValidation,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    };
+}
+function requireValue(args, index, option) {
+    const value = args[index];
+    if (!value)
+        throw new Error(`Missing value for ${option}`);
+    return value;
+}
+function printHelp() {
+    console.error(`Usage: openapi-docs-mcp --source <file-or-url> [options]
+
+Options:
+  -s, --source <value>   OpenAPI JSON/YAML file or HTTP(S) URL
+      --header NAME=VALUE  Header used when loading a remote document (repeatable)
+      --timeout <ms>       Remote loading timeout (default: 10000)
+      --strict-validation  Reject every OpenAPI validation warning
+  -h, --help             Show this help`);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/formatter/operation.d.ts

@@ -0,0 +1,4 @@
+import type { OpenAPI } from "@scalar/openapi-types";
+import type { JsonObject, OperationEntry, SchemaFormatOptions } from "../types.js";
+export declare function formatOperation(document: OpenAPI.Document, entry: OperationEntry, options?: SchemaFormatOptions): JsonObject;
+//# sourceMappingURL=operation.d.ts.map

package/dist/formatter/operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.d.ts","sourceRoot":"","sources":["../../src/formatter/operation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAInF,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAC1B,KAAK,EAAE,cAAc,EACrB,OAAO,GAAE,mBAAwB,GAChC,UAAU,CAyBZ"}

package/dist/formatter/operation.js

@@ -0,0 +1,135 @@
+import { asObject, asString } from "../openapi/operations.js";
+import { formatSchema, resolveLocalReference } from "./schema.js";
+export function formatOperation(document, entry, options = {}) {
+    const operation = entry.operation;
+    const parameters = [
+        ...asArray(entry.pathItem.parameters),
+        ...asArray(operation.parameters),
+    ].map((parameter) => formatParameter(document, parameter, options));
+    const result = {
+        id: entry.id,
+        method: entry.method.toUpperCase(),
+        path: entry.path,
+        tags: entry.tags,
+        parameters,
+        responses: formatResponses(document, operation.responses, options),
+    };
+    copyIfDefined(result, "summary", entry.summary);
+    copyIfDefined(result, "description", entry.description);
+    copyIfDefined(result, "operationId", entry.operationId);
+    copyIfDefined(result, "deprecated", operation.deprecated);
+    copyIfDefined(result, "security", operation.security);
+    const requestBody = asObject(operation.requestBody);
+    if (requestBody)
+        result.requestBody = formatRequestBody(document, requestBody, options);
+    return result;
+}
+function formatParameter(document, rawParameter, options) {
+    const parameter = asObject(rawParameter);
+    if (!parameter)
+        return rawParameter;
+    const ref = asString(parameter.$ref);
+    if (ref) {
+        const resolved = resolveLocalReference(document, ref);
+        return referenceEnvelope(ref, resolved === undefined
+            ? undefined
+            : formatParameter(document, withoutSameReference(resolved, ref), options), "parameter");
+    }
+    const result = {};
+    for (const key of ["name", "in", "required", "description", "deprecated", "style", "explode"]) {
+        copyIfDefined(result, key, parameter[key]);
+    }
+    if (parameter.schema !== undefined) {
+        result.schema = formatSchema(document, parameter.schema, options);
+    }
+    if (parameter.content !== undefined) {
+        result.content = formatContent(document, parameter.content, options);
+    }
+    return result;
+}
+function formatRequestBody(document, requestBody, options) {
+    const ref = asString(requestBody.$ref);
+    if (ref) {
+        const resolved = resolveLocalReference(document, ref);
+        const body = asObject(withoutSameReference(resolved, ref));
+        return referenceEnvelope(ref, body ? formatRequestBody(document, body, options) : undefined, "requestBody");
+    }
+    const result = {
+        required: requestBody.required === true,
+        content: formatContent(document, requestBody.content, options),
+    };
+    copyIfDefined(result, "description", requestBody.description);
+    return result;
+}
+function formatResponses(document, rawResponses, options) {
+    const responses = asObject(rawResponses);
+    if (!responses)
+        return {};
+    return Object.fromEntries(Object.entries(responses).map(([status, rawResponse]) => {
+        const response = asObject(rawResponse);
+        if (!response)
+            return [status, rawResponse];
+        const ref = asString(response.$ref);
+        if (ref) {
+            const resolved = asObject(withoutSameReference(resolveLocalReference(document, ref), ref));
+            return [
+                status,
+                referenceEnvelope(ref, resolved
+                    ? formatResponses(document, { resolved }, options).resolved
+                    : undefined, "response"),
+            ];
+        }
+        const formatted = {};
+        copyIfDefined(formatted, "description", response.description);
+        if (response.headers !== undefined)
+            formatted.headers = response.headers;
+        if (response.content !== undefined) {
+            formatted.content = formatContent(document, response.content, options);
+        }
+        if (response.schema !== undefined) {
+            formatted.schema = formatSchema(document, response.schema, options);
+        }
+        return [status, formatted];
+    }));
+}
+function formatContent(document, rawContent, options) {
+    const content = asObject(rawContent);
+    if (!content)
+        return {};
+    return Object.fromEntries(Object.entries(content).map(([mediaType, rawMedia]) => {
+        const media = asObject(rawMedia);
+        if (!media)
+            return [mediaType, rawMedia];
+        const formatted = {};
+        if (media.schema !== undefined) {
+            formatted.schema = formatSchema(document, media.schema, options);
+        }
+        copyIfDefined(formatted, "example", media.example);
+        copyIfDefined(formatted, "examples", media.examples);
+        copyIfDefined(formatted, "encoding", media.encoding);
+        return [mediaType, formatted];
+    }));
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function copyIfDefined(target, key, value) {
+    if (value !== undefined)
+        target[key] = value;
+}
+function referenceEnvelope(ref, value, key) {
+    const result = {
+        $ref: ref,
+        name: decodeURIComponent(ref.split("/").at(-1) ?? ref),
+    };
+    if (value === undefined)
+        result.unresolved = true;
+    else
+        result[key] = value;
+    return result;
+}
+function withoutSameReference(value, ref) {
+    const object = asObject(value);
+    return object?.$ref === ref ? undefined : value;
+}
+//# sourceMappingURL=operation.js.map

package/dist/formatter/operation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"operation.js","sourceRoot":"","sources":["../../src/formatter/operation.ts"],"names":[],"mappings":"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"}

package/dist/formatter/schema.d.ts

@@ -0,0 +1,7 @@
+import type { OpenAPI } from "@scalar/openapi-types";
+import type { SchemaFormatOptions } from "../types.js";
+export declare function formatSchema(document: OpenAPI.Document, schema: unknown, options?: SchemaFormatOptions): unknown;
+export declare function listSchemaNames(document: OpenAPI.Document): string[];
+export declare function findSchema(document: OpenAPI.Document, name: string): unknown;
+export declare function resolveLocalReference(document: OpenAPI.Document, ref: string): unknown;
+//# sourceMappingURL=schema.d.ts.map

package/dist/formatter/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../src/formatter/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAc,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQnE,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAC1B,MAAM,EAAE,OAAO,EACf,OAAO,GAAE,mBAAwB,GAChC,OAAO,CAKT;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,GAAG,MAAM,EAAE,CAKpE;AAED,wBAAgB,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAK5E;AAwHD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAYtF"}