swaggertools-mcp 1.0.0

package/dist/tool-types.d.ts

@@ -0,0 +1,143 @@
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS';
+export type MatchMode = 'exact' | 'fuzzy';
+export interface ApiError {
+    code: 'OPENAPI_FETCH_ERROR' | 'OPENAPI_PARSE_ERROR' | 'DOC_NOT_FOUND' | 'OPERATION_NOT_FOUND' | 'SCHEMA_NOT_FOUND' | 'VALIDATION_ERROR';
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface ApiEnvelope<T> {
+    ok: boolean;
+    data: T | null;
+    meta?: Record<string, unknown>;
+    error: ApiError | null;
+}
+export interface OperationSummary {
+    operationId?: string;
+    method: HttpMethod;
+    path: string;
+    summary?: string;
+    tags?: string[];
+}
+export interface ParameterItem {
+    name: string;
+    in: 'path' | 'query' | 'header' | 'cookie';
+    required?: boolean;
+    description?: string;
+    schema?: Record<string, unknown>;
+    example?: unknown;
+}
+export interface MediaTypeObject {
+    schema?: Record<string, unknown>;
+    example?: unknown;
+    examples?: Record<string, unknown>;
+}
+export interface RequestBodyItem {
+    required?: boolean;
+    description?: string;
+    content: Record<string, MediaTypeObject>;
+}
+export interface ResponseItem {
+    statusCode: string;
+    description?: string;
+    content?: Record<string, MediaTypeObject>;
+}
+export interface OperationDetail extends OperationSummary {
+    description?: string;
+    parameters: ParameterItem[];
+    requestBody?: RequestBodyItem;
+    responses: ResponseItem[];
+    security?: Array<Record<string, string[]>>;
+}
+export interface OperationCandidate extends OperationSummary {
+    score: number;
+    matchedBy: string[];
+}
+export interface ToolOpenApiLoadInput {
+    url: string;
+    headers?: Record<string, string>;
+    forceRefresh?: boolean;
+}
+export interface ToolOpenApiLoadOutput {
+    docId: string;
+    title?: string;
+    version?: string;
+    servers?: string[];
+    stats: {
+        operationCount: number;
+        schemaCount: number;
+    };
+}
+export interface ToolListOperationsInput {
+    docId: string;
+    tag?: string;
+    method?: HttpMethod;
+    keyword?: string;
+    page?: number;
+    pageSize?: number;
+}
+export interface ToolListOperationsOutput {
+    items: OperationSummary[];
+    page: number;
+    pageSize: number;
+    total: number;
+}
+export interface ToolResolveOperationInput {
+    docId: string;
+    query: string;
+    method?: HttpMethod;
+    tag?: string;
+    topK?: number;
+}
+export interface ToolResolveOperationOutput {
+    bestMatch?: OperationCandidate;
+    candidates: OperationCandidate[];
+}
+export interface ToolGetOperationInput {
+    docId: string;
+    operationId?: string;
+    method?: HttpMethod;
+    path?: string;
+    matchMode?: MatchMode;
+    query?: string;
+    topK?: number;
+    minScore?: number;
+    resolveRefs?: boolean;
+}
+export interface ToolGetOperationOutput {
+    matchMode: MatchMode;
+    matched?: OperationCandidate;
+    operation?: OperationDetail;
+    candidates?: OperationCandidate[];
+}
+export interface ToolGetSchemaInput {
+    docId: string;
+    schemaName: string;
+    resolveRefs?: boolean;
+}
+export interface ToolGetSchemaOutput {
+    schemaName: string;
+    schema: Record<string, unknown>;
+    usedByOperations?: Array<Pick<OperationSummary, 'operationId' | 'method' | 'path'>>;
+}
+export interface SwaggerMcpTools {
+    'openapi.load': {
+        input: ToolOpenApiLoadInput;
+        output: ApiEnvelope<ToolOpenApiLoadOutput>;
+    };
+    'openapi.list_operations': {
+        input: ToolListOperationsInput;
+        output: ApiEnvelope<ToolListOperationsOutput>;
+    };
+    'openapi.resolve_operation': {
+        input: ToolResolveOperationInput;
+        output: ApiEnvelope<ToolResolveOperationOutput>;
+    };
+    'openapi.get_operation': {
+        input: ToolGetOperationInput;
+        output: ApiEnvelope<ToolGetOperationOutput>;
+    };
+    'openapi.get_schema': {
+        input: ToolGetSchemaInput;
+        output: ApiEnvelope<ToolGetSchemaOutput>;
+    };
+}

package/dist/tool-types.js

@@ -0,0 +1 @@
+export {};

package/docs/swagger-mcp-design.md

@@ -0,0 +1,243 @@
+# Swagger MCP Design (V1)
+
+## 1. Goal
+
+Build an MCP server that accepts a user-provided OpenAPI URL (for example `http://dev.manage.zw.uav.sczlcq.com/v3/api-docs`) and exposes stable tools for:
+
+- loading OpenAPI docs
+- browsing operations
+- inspecting request/response schemas
+- resolving incomplete or fuzzy operation input
+
+## 2. Scope
+
+### P0 (must-have)
+
+1. `openapi.load`
+2. `openapi.list_operations`
+3. `openapi.get_operation` (exact + fuzzy modes)
+4. `openapi.resolve_operation` (candidate resolver for incomplete paths)
+5. `openapi.get_schema`
+
+### P1 (nice-to-have)
+
+1. `openapi.search` (cross-field keyword search)
+2. `openapi.validate_request_example`
+3. `openapi.mock_response_example`
+
+## 3. Core Concepts
+
+### 3.1 Document Session
+
+- Each loaded OpenAPI file is assigned a `docId`.
+- A process can hold multiple documents.
+- In-memory cache with TTL (default: 10 minutes).
+- Optional `forceRefresh` to bypass cache.
+
+### 3.2 Indexing
+
+Build indexes during load:
+
+- `operationId -> operation`
+- `METHOD + path -> operation`
+- `tag -> operations[]`
+- `schemaName -> schema`
+
+### 3.3 Normalized Operation Output
+
+All operation details should be normalized into:
+
+- `parameters`: path/query/header/cookie
+- `requestBody`: by content-type
+- `responses`: by status code and content-type
+- `security`: auth requirements
+
+## 4. Fuzzy Resolution (P0)
+
+Many users provide partial or inaccurate paths. Fuzzy matching is required.
+
+### 4.1 Match Inputs
+
+- partial path (example: `/user/li`)
+- natural keyword (example: `user list`)
+- optional method constraint (`GET`, `POST`, ...)
+
+### 4.2 Match Strategy
+
+Compute weighted score from:
+
+1. path prefix match (high weight)
+2. segment overlap ratio
+3. path parameter tolerance (`{id}` treated as wildcard)
+4. edit distance for typo tolerance
+5. summary/tag keyword hits
+
+### 4.3 Match Behavior
+
+- clear winner: return `bestMatch`
+- close ties: return `candidates` sorted by score
+- no match: return top 3 nearest hints
+
+## 5. Tool List and Descriptor Draft
+
+## 5.1 `openapi.load`
+
+Purpose: fetch and parse remote OpenAPI document.
+
+Input:
+
+- `url: string`
+- `headers?: Record<string,string>`
+- `forceRefresh?: boolean`
+
+Output:
+
+- `docId`
+- `title`
+- `version`
+- `servers[]`
+- `stats` (`operationCount`, `schemaCount`)
+
+## 5.2 `openapi.list_operations`
+
+Purpose: list operations with lightweight filters.
+
+Input:
+
+- `docId: string`
+- `tag?: string`
+- `method?: HttpMethod`
+- `keyword?: string`
+- `page?: number`
+- `pageSize?: number`
+
+Output:
+
+- paged operation summaries (`operationId`, `method`, `path`, `summary`, `tags`)
+
+## 5.3 `openapi.get_operation`
+
+Purpose: get full operation details by exact or fuzzy match.
+
+Input:
+
+- `docId: string`
+- `operationId?: string`
+- `method?: HttpMethod`
+- `path?: string`
+- `matchMode?: "exact" | "fuzzy"` (default `exact`)
+- `query?: string` (required when fuzzy mode is used)
+- `topK?: number` (default 5)
+- `minScore?: number` (default 0.55)
+- `resolveRefs?: boolean` (default true)
+
+Resolution rule:
+
+- exact mode: requires `operationId` or (`method` + `path`)
+- fuzzy mode: requires `query`, optional `method` filter
+
+## 5.4 `openapi.resolve_operation`
+
+Purpose: resolve incomplete path/keyword into operation candidates.
+
+Input:
+
+- `docId: string`
+- `query: string`
+- `method?: HttpMethod`
+- `tag?: string`
+- `topK?: number` (1..20, default 5)
+
+Output:
+
+- `bestMatch?`
+- `candidates[]` with `score` and `matchedBy`
+
+## 5.5 `openapi.get_schema`
+
+Purpose: fetch a schema in `components.schemas`.
+
+Input:
+
+- `docId: string`
+- `schemaName: string`
+- `resolveRefs?: boolean`
+
+Output:
+
+- schema object
+- optional references (`usedByOperations[]`)
+
+## 6. Unified Response Envelope
+
+Success:
+
+```json
+{
+  "ok": true,
+  "data": {},
+  "meta": {
+    "docId": "doc_xxx",
+    "cached": true
+  },
+  "error": null
+}
+```
+
+Failure:
+
+```json
+{
+  "ok": false,
+  "data": null,
+  "meta": {},
+  "error": {
+    "code": "OPENAPI_PARSE_ERROR",
+    "message": "Invalid OpenAPI document",
+    "details": {}
+  }
+}
+```
+
+Recommended error codes:
+
+- `OPENAPI_FETCH_ERROR`
+- `OPENAPI_PARSE_ERROR`
+- `DOC_NOT_FOUND`
+- `OPERATION_NOT_FOUND`
+- `SCHEMA_NOT_FOUND`
+- `VALIDATION_ERROR`
+
+## 7. Non-functional Requirements
+
+1. Security
+- allow only `http` / `https`
+- timeout and max payload limits
+- optional domain allowlist
+- SSRF protections (block private network targets)
+
+2. Performance
+- cache parsed docs and indexes
+- paginate list/search results
+- cap max candidate count for fuzzy tools
+
+3. Observability
+- structured logs with `docId`, `toolName`, duration, cache hit/miss
+
+## 8. Recommended Implementation Stack
+
+- parser: `@apidevtools/swagger-parser`
+- validation: `ajv`
+- schema/type validation: `zod`
+- http client: `undici` or `axios`
+- mcp sdk: `@modelcontextprotocol/sdk`
+
+## 9. Delivery Order
+
+1. `openapi.load`
+2. `openapi.list_operations`
+3. `openapi.resolve_operation`
+4. `openapi.get_operation` (exact + fuzzy)
+5. `openapi.get_schema`
+6. P1 tools
+

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "swaggertools-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for querying OpenAPI/Swagger documents, including fuzzy operation matching.",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "packageManager": "pnpm@10.12.1",
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1",
+    "undici": "^7.22.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,290 @@
+#!/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';
+import type { ApiError } from './tool-types.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(): Promise<void> {
+  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: string): Promise<string> {
+  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(): string | undefined {
+  const raw = process.env.OPENAPI_DEFAULT_URL ?? process.env.OPENAPI_URL;
+  const normalized = raw?.trim();
+  return normalized ? normalized : undefined;
+}
+
+function loadEnvFiles(): string[] {
+  const found: string[] = [];
+  const candidates = new Set<string>();
+  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: unknown, meta: Record<string, unknown> = {}) {
+  const envelope = { ok: true, data, meta, error: null };
+  return {
+    content: [{ type: 'text' as const, text: safeJson(envelope) }],
+    structuredContent: envelope,
+  };
+}
+
+function failure(error: ApiError, meta: Record<string, unknown> = {}) {
+  const envelope = { ok: false, data: null, meta, error };
+  return {
+    content: [{ type: 'text' as const, text: safeJson(envelope) }],
+    structuredContent: envelope,
+    isError: true,
+  };
+}
+
+function mapError(raw: unknown): ApiError {
+  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: unknown): string {
+  const seen = new WeakSet<object>();
+  return JSON.stringify(
+    value,
+    (_, currentValue) => {
+      if (currentValue && typeof currentValue === 'object') {
+        if (seen.has(currentValue)) {
+          return '[Circular]';
+        }
+        seen.add(currentValue);
+      }
+      return currentValue;
+    },
+    2,
+  );
+}