swaggertools-mcp 1.0.0

package/.env.example

@@ -0,0 +1,3 @@
+OPENAPI_DEFAULT_URL=http://dev.manage.zw.uav.sczlcq.com/v3/api-docs
+ALLOW_PRIVATE_NETWORK=true
+# OPENAPI_DOC_TTL_MS=600000

package/README.md

@@ -0,0 +1,98 @@
+# swagger-mcp
+
+English | [中文](./README.zh-CN.md)
+
+MCP server for loading and querying OpenAPI/Swagger documents.
+It supports fuzzy operation matching when users provide incomplete paths or keywords.
+
+## Features
+
+- Load remote OpenAPI 3.x docs (JSON/YAML)
+- In-memory document caching with TTL
+- List/filter operations by method/tag/keyword
+- Fuzzy resolve operations from partial paths
+- Inspect full request/response details
+- Inspect `components.schemas` and where they are used
+
+## Tools
+
+- `openapi.load`
+- `openapi.list_operations`
+- `openapi.resolve_operation`
+- `openapi.get_operation`
+- `openapi.get_schema`
+
+## Requirements
+
+- Node.js 18+
+- pnpm 10+
+
+## Quick Start
+
+```bash
+pnpm install
+pnpm dev
+```
+
+Build and run:
+
+```bash
+pnpm build
+pnpm start
+```
+
+## Codex MCP Config Example
+
+```json
+{
+  "mcpServers": {
+    "swagger-mcp": {
+      "command": "node",
+      "args": ["D:\\workspace\\demo\\mcp\\swagger-mcp\\dist\\index.js"],
+      "cwd": "D:\\workspace\\demo\\mcp\\swagger-mcp"
+    }
+  }
+}
+```
+
+If you are actively developing this repo, you can also run with `pnpm dev`.
+
+## Environment Variables
+
+- `OPENAPI_DEFAULT_URL` or `OPENAPI_URL`
+  Default OpenAPI URL used when `openapi.load` is called without `url`.
+- `OPENAPI_DOC_TTL_MS` (default: `600000`)
+  Cache TTL in milliseconds.
+- `ALLOW_PRIVATE_NETWORK` (default: `false`)
+  Set to `true` if your OpenAPI endpoint is in private/internal network.
+- `OPENAPI_ENV_FILE`
+  Optional explicit `.env` file path (highest priority).
+- `OPENAPI_ENV_DIR`
+  Optional directory that contains `.env`.
+
+Env file load order:
+
+1. `OPENAPI_ENV_FILE`
+2. `OPENAPI_ENV_DIR/.env`
+3. `process.cwd()/.env`
+4. `INIT_CWD/.env` (if runtime provides it)
+
+## `docId: "default"` Behavior
+
+- If a document has already been loaded, `default` maps to the latest loaded `docId`.
+- If no document is loaded yet, server auto-loads from `OPENAPI_DEFAULT_URL` / `OPENAPI_URL`.
+
+## Example `.env`
+
+```env
+OPENAPI_DEFAULT_URL=http://dev.manage.zw.uav.sczlcq.com/v3/api-docs
+ALLOW_PRIVATE_NETWORK=true
+# OPENAPI_DOC_TTL_MS=600000
+```
+
+## Troubleshooting
+
+- Error: `Document not found: default`
+  - Ensure `.env` is readable from the server runtime working directory.
+  - Ensure `OPENAPI_DEFAULT_URL` or `OPENAPI_URL` is set.
+  - Restart MCP server after changing `.env`.

package/README.zh-CN.md

@@ -0,0 +1,98 @@
+# swagger-mcp
+
+[English](./README.md) | 中文
+
+用于加载和查询 OpenAPI/Swagger 文档的 MCP 服务。
+支持在用户只提供部分路径或关键词时进行接口模糊匹配。
+
+## 功能特性
+
+- 加载远程 OpenAPI 3.x 文档（JSON/YAML）
+- 基于内存的文档缓存（TTL）
+- 按 method/tag/关键词筛选接口
+- 通过不完整路径进行接口模糊解析
+- 查看接口完整请求/响应结构
+- 查看 `components.schemas` 以及被哪些接口引用
+
+## 工具列表
+
+- `openapi.load`
+- `openapi.list_operations`
+- `openapi.resolve_operation`
+- `openapi.get_operation`
+- `openapi.get_schema`
+
+## 环境要求
+
+- Node.js 18+
+- pnpm 10+
+
+## 快速开始
+
+```bash
+pnpm install
+pnpm dev
+```
+
+构建并运行：
+
+```bash
+pnpm build
+pnpm start
+```
+
+## Codex MCP 配置示例
+
+```json
+{
+  "mcpServers": {
+    "swagger-mcp": {
+      "command": "node",
+      "args": ["D:\\workspace\\demo\\mcp\\swagger-mcp\\dist\\index.js"],
+      "cwd": "D:\\workspace\\demo\\mcp\\swagger-mcp"
+    }
+  }
+}
+```
+
+如果你在本仓库内联调，也可以用 `pnpm dev` 启动。
+
+## 环境变量
+
+- `OPENAPI_DEFAULT_URL` 或 `OPENAPI_URL`
+  当 `openapi.load` 未传 `url` 时，使用该默认地址。
+- `OPENAPI_DOC_TTL_MS`（默认：`600000`）
+  文档缓存时长（毫秒）。
+- `ALLOW_PRIVATE_NETWORK`（默认：`false`）
+  如果 OpenAPI 地址是内网地址，需设为 `true`。
+- `OPENAPI_ENV_FILE`
+  可选，显式指定 `.env` 文件路径（最高优先级）。
+- `OPENAPI_ENV_DIR`
+  可选，指定包含 `.env` 的目录。
+
+`.env` 加载顺序：
+
+1. `OPENAPI_ENV_FILE`
+2. `OPENAPI_ENV_DIR/.env`
+3. `process.cwd()/.env`
+4. `INIT_CWD/.env`（如果运行时提供）
+
+## `docId: "default"` 行为
+
+- 如果服务中已加载过文档，`default` 会映射到最近一次加载的 `docId`。
+- 如果尚未加载文档，服务会尝试使用 `OPENAPI_DEFAULT_URL` / `OPENAPI_URL` 自动加载。
+
+## `.env` 示例
+
+```env
+OPENAPI_DEFAULT_URL=http://dev.manage.zw.uav.sczlcq.com/v3/api-docs
+ALLOW_PRIVATE_NETWORK=true
+# OPENAPI_DOC_TTL_MS=600000
+```
+
+## 常见问题
+
+- 错误：`Document not found: default`
+  - 确认服务运行目录可读取到 `.env`
+  - 确认已设置 `OPENAPI_DEFAULT_URL` 或 `OPENAPI_URL`
+  - 修改 `.env` 后重启 MCP 服务

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { config as dotenvConfig } from 'dotenv';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as z from 'zod/v4';
+import { OpenApiRegistry } from './openapi-service.js';
+const loadedEnvFiles = loadEnvFiles();
+const server = new McpServer({
+    name: 'swagger-mcp',
+    version: '1.0.0',
+});
+const registry = new OpenApiRegistry();
+server.registerTool('openapi.load', {
+    description: 'Load and index a remote OpenAPI document URL.',
+    inputSchema: {
+        url: z.string().url().optional().describe('OpenAPI JSON/YAML URL. If omitted, read from .env'),
+        headers: z.record(z.string(), z.string()).optional().describe('Optional HTTP headers'),
+        forceRefresh: z.boolean().optional().describe('Bypass cache and reload'),
+    },
+}, async ({ url, headers, forceRefresh }) => {
+    try {
+        const finalUrl = url ?? getDefaultOpenApiUrl();
+        if (!finalUrl) {
+            return failure({
+                code: 'VALIDATION_ERROR',
+                message: `Missing OpenAPI URL. Provide url input or set OPENAPI_DEFAULT_URL/OPENAPI_URL in .env (searched: ${loadedEnvFiles.join(', ') || 'none'})`,
+            });
+        }
+        const result = await registry.load(finalUrl, headers, forceRefresh ?? false);
+        return success({
+            docId: result.docId,
+            title: result.title,
+            version: result.version,
+            servers: result.servers,
+            stats: {
+                operationCount: result.operationCount,
+                schemaCount: result.schemaCount,
+            },
+        }, {
+            docId: result.docId,
+            cached: result.cached,
+        });
+    }
+    catch (error) {
+        return failure(mapError(error));
+    }
+});
+server.registerTool('openapi.list_operations', {
+    description: 'List operations in a loaded OpenAPI document with basic filters.',
+    inputSchema: {
+        docId: z.string(),
+        tag: z.string().optional(),
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']).optional(),
+        keyword: z.string().optional(),
+        page: z.number().int().positive().optional(),
+        pageSize: z.number().int().positive().max(200).optional(),
+    },
+}, async ({ docId, tag, method, keyword, page, pageSize }) => {
+    try {
+        const resolvedDocId = await resolveDocId(docId);
+        const result = registry.listOperations({ docId: resolvedDocId, tag, method, keyword, page, pageSize });
+        return success(result, { docId: resolvedDocId, requestedDocId: docId });
+    }
+    catch (error) {
+        return failure(mapError(error), { docId });
+    }
+});
+server.registerTool('openapi.resolve_operation', {
+    description: 'Resolve incomplete path/keyword into operation candidates.',
+    inputSchema: {
+        docId: z.string(),
+        query: z.string().min(1),
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']).optional(),
+        tag: z.string().optional(),
+        topK: z.number().int().min(1).max(20).optional(),
+    },
+}, async ({ docId, query, method, tag, topK }) => {
+    try {
+        const resolvedDocId = await resolveDocId(docId);
+        const result = registry.resolveOperation(resolvedDocId, query, { method, tag, topK });
+        return success(result, { docId: resolvedDocId, requestedDocId: docId });
+    }
+    catch (error) {
+        return failure(mapError(error), { docId });
+    }
+});
+server.registerTool('openapi.get_operation', {
+    description: 'Get operation details by exact or fuzzy mode, including parameters and responses.',
+    inputSchema: {
+        docId: z.string(),
+        operationId: z.string().optional(),
+        method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']).optional(),
+        path: z.string().optional(),
+        matchMode: z.enum(['exact', 'fuzzy']).optional(),
+        query: z.string().optional(),
+        topK: z.number().int().min(1).max(20).optional(),
+        minScore: z.number().min(0).max(1).optional(),
+        resolveRefs: z.boolean().optional(),
+    },
+}, async (args) => {
+    try {
+        const resolvedDocId = await resolveDocId(args.docId);
+        const result = registry.getOperation({ ...args, docId: resolvedDocId });
+        const matchMode = args.matchMode ?? 'exact';
+        if (!result.operation) {
+            return failure({
+                code: 'OPERATION_NOT_FOUND',
+                message: 'No operation matched the input',
+                details: { candidates: result.candidates ?? [] },
+            }, { docId: resolvedDocId, requestedDocId: args.docId, matchMode });
+        }
+        return success({
+            matchMode,
+            matched: result.matched,
+            candidates: result.candidates,
+            operation: result.operation,
+        }, { docId: resolvedDocId, requestedDocId: args.docId, matchMode });
+    }
+    catch (error) {
+        return failure(mapError(error), { docId: args.docId });
+    }
+});
+server.registerTool('openapi.get_schema', {
+    description: 'Get a schema from components.schemas by schemaName.',
+    inputSchema: {
+        docId: z.string(),
+        schemaName: z.string().min(1),
+        resolveRefs: z.boolean().optional(),
+    },
+}, async ({ docId, schemaName, resolveRefs }) => {
+    try {
+        const resolvedDocId = await resolveDocId(docId);
+        const result = registry.getSchema(resolvedDocId, schemaName, resolveRefs ?? true);
+        return success(result, { docId: resolvedDocId, requestedDocId: docId });
+    }
+    catch (error) {
+        return failure(mapError(error), { docId, schemaName });
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('swagger-mcp server running on stdio');
+}
+main().catch((error) => {
+    console.error('swagger-mcp fatal error:', error);
+    process.exit(1);
+});
+async function resolveDocId(docId) {
+    if (docId !== 'default') {
+        return docId;
+    }
+    const latest = registry.getLatestDocId();
+    if (latest) {
+        return latest;
+    }
+    const defaultUrl = getDefaultOpenApiUrl();
+    if (!defaultUrl) {
+        throw new Error(`Document not found: default. Set OPENAPI_DEFAULT_URL/OPENAPI_URL in AI workspace .env or pass explicit docId from openapi.load`);
+    }
+    const loaded = await registry.load(defaultUrl);
+    return loaded.docId;
+}
+function getDefaultOpenApiUrl() {
+    const raw = process.env.OPENAPI_DEFAULT_URL ?? process.env.OPENAPI_URL;
+    const normalized = raw?.trim();
+    return normalized ? normalized : undefined;
+}
+function loadEnvFiles() {
+    const found = [];
+    const candidates = new Set();
+    const explicitFile = process.env.OPENAPI_ENV_FILE?.trim();
+    const explicitDir = process.env.OPENAPI_ENV_DIR?.trim();
+    if (explicitFile) {
+        candidates.add(path.resolve(explicitFile));
+    }
+    if (explicitDir) {
+        candidates.add(path.resolve(explicitDir, '.env'));
+    }
+    candidates.add(path.resolve(process.cwd(), '.env'));
+    const initCwd = process.env.INIT_CWD?.trim();
+    if (initCwd) {
+        candidates.add(path.resolve(initCwd, '.env'));
+    }
+    for (const envFile of candidates) {
+        if (!existsSync(envFile))
+            continue;
+        dotenvConfig({ path: envFile, override: false });
+        found.push(envFile);
+    }
+    return found;
+}
+function success(data, meta = {}) {
+    const envelope = { ok: true, data, meta, error: null };
+    return {
+        content: [{ type: 'text', text: safeJson(envelope) }],
+        structuredContent: envelope,
+    };
+}
+function failure(error, meta = {}) {
+    const envelope = { ok: false, data: null, meta, error };
+    return {
+        content: [{ type: 'text', text: safeJson(envelope) }],
+        structuredContent: envelope,
+        isError: true,
+    };
+}
+function mapError(raw) {
+    const message = raw instanceof Error ? raw.message : String(raw);
+    if (message.includes('Document not found')) {
+        return { code: 'DOC_NOT_FOUND', message };
+    }
+    if (message.includes('Schema not found')) {
+        return { code: 'SCHEMA_NOT_FOUND', message };
+    }
+    if (message.includes('Operation not found') || message.includes('exact mode requires') || message.includes('query is required')) {
+        return { code: 'OPERATION_NOT_FOUND', message };
+    }
+    if (message.includes('Only http/https') || message.includes('Invalid URL') || message.includes('blocked')) {
+        return { code: 'VALIDATION_ERROR', message };
+    }
+    if (message.toLowerCase().includes('parse')) {
+        return { code: 'OPENAPI_PARSE_ERROR', message };
+    }
+    if (message.toLowerCase().includes('fetch') || message.toLowerCase().includes('network') || message.toLowerCase().includes('timeout')) {
+        return { code: 'OPENAPI_FETCH_ERROR', message };
+    }
+    return { code: 'VALIDATION_ERROR', message };
+}
+function safeJson(value) {
+    const seen = new WeakSet();
+    return JSON.stringify(value, (_, currentValue) => {
+        if (currentValue && typeof currentValue === 'object') {
+            if (seen.has(currentValue)) {
+                return '[Circular]';
+            }
+            seen.add(currentValue);
+        }
+        return currentValue;
+    }, 2);
+}

package/dist/openapi-service.d.ts

@@ -0,0 +1,62 @@
+import type { HttpMethod, OperationCandidate, OperationDetail, OperationSummary, ToolGetOperationInput } from './tool-types.js';
+type JsonMap = Record<string, unknown>;
+interface ResolveOptions {
+    method?: HttpMethod;
+    tag?: string;
+    topK?: number;
+    minScore?: number;
+}
+export interface LoadResult {
+    docId: string;
+    title?: string;
+    version?: string;
+    servers: string[];
+    operationCount: number;
+    schemaCount: number;
+    cached: boolean;
+}
+export interface ResolveResult {
+    bestMatch?: OperationCandidate;
+    candidates: OperationCandidate[];
+}
+export interface GetOperationResolved {
+    matched?: OperationCandidate;
+    operation?: OperationDetail;
+    candidates?: OperationCandidate[];
+}
+export interface GetSchemaResolved {
+    schemaName: string;
+    schema: JsonMap;
+    usedByOperations: Array<Pick<OperationSummary, 'operationId' | 'method' | 'path'>>;
+}
+export declare class OpenApiRegistry {
+    private readonly docs;
+    private readonly keyToDocId;
+    private readonly ttlMs;
+    private latestDocId?;
+    constructor(ttlMs?: number);
+    load(url: string, headers?: Record<string, string>, forceRefresh?: boolean): Promise<LoadResult>;
+    listOperations(input: {
+        docId: string;
+        tag?: string;
+        method?: HttpMethod;
+        keyword?: string;
+        page?: number;
+        pageSize?: number;
+    }): {
+        items: OperationSummary[];
+        page: number;
+        pageSize: number;
+        total: number;
+    };
+    resolveOperation(docId: string, query: string, options?: ResolveOptions): ResolveResult;
+    getOperation(input: ToolGetOperationInput): GetOperationResolved;
+    getSchema(docId: string, schemaName: string, resolveRefs?: boolean): GetSchemaResolved;
+    getLatestDocId(): string | undefined;
+    private getDoc;
+    private toLoadResult;
+    private cleanupExpired;
+    private assertSupportedUrl;
+    private requireOperationByMethodPath;
+}
+export {};