openapi-dynamic-mcp 0.1.0

package/dist/openapi/jsonPointer.js

@@ -0,0 +1,40 @@
+import { OpenApiMcpError } from "../errors.js";
+export function getByJsonPointer(root, pointer) {
+    if (!pointer || pointer === "") {
+        return root;
+    }
+    if (!pointer.startsWith("/")) {
+        throw new OpenApiMcpError("SCHEMA_ERROR", "JSON pointer must start with '/'", { pointer });
+    }
+    const tokens = pointer
+        .slice(1)
+        .split("/")
+        .map((part) => part.replace(/~1/g, "/").replace(/~0/g, "~"));
+    let cursor = root;
+    for (const token of tokens) {
+        if (Array.isArray(cursor)) {
+            const idx = Number.parseInt(token, 10);
+            if (!Number.isInteger(idx) || idx < 0 || idx >= cursor.length) {
+                throw new OpenApiMcpError("SCHEMA_ERROR", "JSON pointer index out of bounds", { pointer, token });
+            }
+            cursor = cursor[idx];
+            continue;
+        }
+        if (!cursor || typeof cursor !== "object") {
+            throw new OpenApiMcpError("SCHEMA_ERROR", "JSON pointer target does not exist", {
+                pointer,
+                token
+            });
+        }
+        const object = cursor;
+        if (!(token in object)) {
+            throw new OpenApiMcpError("SCHEMA_ERROR", "JSON pointer target does not exist", {
+                pointer,
+                token
+            });
+        }
+        cursor = object[token];
+    }
+    return cursor;
+}
+//# sourceMappingURL=jsonPointer.js.map

package/dist/openapi/jsonPointer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonPointer.js","sourceRoot":"","sources":["../../src/openapi/jsonPointer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,MAAM,UAAU,gBAAgB,CAAC,IAAa,EAAE,OAAgB;IAC9D,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,kCAAkC,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,MAAM,MAAM,GAAG,OAAO;SACnB,KAAK,CAAC,CAAC,CAAC;SACR,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IAE/D,IAAI,MAAM,GAAY,IAAI,CAAC;IAC3B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACvC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC,IAAI,GAAG,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;gBAC9D,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,kCAAkC,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YACpG,CAAC;YACD,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;YACrB,SAAS;QACX,CAAC;QAED,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC1C,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,oCAAoC,EAAE;gBAC9E,OAAO;gBACP,KAAK;aACN,CAAC,CAAC;QACL,CAAC;QAED,MAAM,MAAM,GAAG,MAAiC,CAAC;QACjD,IAAI,CAAC,CAAC,KAAK,IAAI,MAAM,CAAC,EAAE,CAAC;YACvB,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,oCAAoC,EAAE;gBAC9E,OAAO;gBACP,KAAK;aACN,CAAC,CAAC;QACL,CAAC;QACD,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/openapi/loadSpec.d.ts

@@ -0,0 +1,2 @@
+import type { ApiRegistry, RootConfig } from "../types.js";
+export declare function loadApiRegistry(config: RootConfig, env?: NodeJS.ProcessEnv): Promise<ApiRegistry>;

package/dist/openapi/loadSpec.js

@@ -0,0 +1,67 @@
+import SwaggerParser from "@apidevtools/swagger-parser";
+import { readApiBaseUrl } from "../auth/env.js";
+import { OpenApiMcpError } from "../errors.js";
+import { buildEndpointIndex } from "./endpointIndex.js";
+function assertSupportedOpenApiVersion(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version);
+    if (!match) {
+        throw new OpenApiMcpError("SCHEMA_ERROR", `Unsupported OpenAPI version format: ${version}`);
+    }
+    const major = Number(match[1]);
+    if (major < 3) {
+        throw new OpenApiMcpError("SCHEMA_ERROR", `OpenAPI version must be 3.x (received ${version})`);
+    }
+}
+function resolveBaseUrl(api, document, env) {
+    const envBaseUrl = readApiBaseUrl(api.name, env);
+    const schemaBaseUrl = document.servers?.[0]?.url;
+    const baseUrl = envBaseUrl ?? api.baseUrl ?? schemaBaseUrl;
+    if (!baseUrl) {
+        throw new OpenApiMcpError("CONFIG_ERROR", `No base URL found for API '${api.name}'`, {
+            resolutionOrder: ["env:<API>_BASE_URL", "config.baseUrl", "openapi.servers[0].url"]
+        });
+    }
+    return baseUrl;
+}
+async function loadSingleApi(api, env) {
+    let parsed;
+    try {
+        parsed = await SwaggerParser.dereference(api.specPath);
+    }
+    catch (error) {
+        throw new OpenApiMcpError("SCHEMA_ERROR", `Failed to parse OpenAPI schema for '${api.name}'`, {
+            apiName: api.name,
+            specPath: api.specPath,
+            cause: error instanceof Error ? error.message : String(error)
+        });
+    }
+    const document = parsed;
+    if (!document || typeof document !== "object") {
+        throw new OpenApiMcpError("SCHEMA_ERROR", `Invalid OpenAPI document for '${api.name}'`);
+    }
+    if (!document.openapi) {
+        throw new OpenApiMcpError("SCHEMA_ERROR", `OpenAPI 'openapi' field is missing in '${api.name}'`);
+    }
+    assertSupportedOpenApiVersion(document.openapi);
+    const { endpoints, endpointById } = buildEndpointIndex(document);
+    const baseUrl = resolveBaseUrl(api, document, env);
+    const authSchemeNames = Object.keys(document.components?.securitySchemes ?? {});
+    return {
+        config: api,
+        schemaPath: api.specPath,
+        schema: document,
+        baseUrl,
+        endpoints,
+        endpointById,
+        authSchemeNames
+    };
+}
+export async function loadApiRegistry(config, env = process.env) {
+    const byName = new Map();
+    for (const api of config.apis) {
+        const loadedApi = await loadSingleApi(api, env);
+        byName.set(api.name.toLowerCase(), loadedApi);
+    }
+    return { byName };
+}
+//# sourceMappingURL=loadSpec.js.map

package/dist/openapi/loadSpec.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,98 @@
+import type { OpenAPIV3 } from "openapi-types";
+export interface ApiOauth2Config {
+    tokenUrlOverride?: string;
+    scopes?: string[];
+    tokenEndpointAuthMethod?: "client_secret_basic" | "client_secret_post";
+}
+export interface Retry429Config {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitterRatio?: number;
+    respectRetryAfter?: boolean;
+}
+export interface ApiConfig {
+    name: string;
+    specPath: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    headers?: Record<string, string>;
+    oauth2?: ApiOauth2Config;
+    retry429?: Retry429Config;
+}
+export interface RootConfig {
+    version: 1;
+    apis: ApiConfig[];
+}
+export type HttpMethod = "get" | "put" | "post" | "delete" | "options" | "head" | "patch" | "trace";
+export interface EndpointDefinition {
+    endpointId: string;
+    method: HttpMethod;
+    path: string;
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    tags?: string[];
+    operation: OpenAPIV3.OperationObject;
+    pathItem: OpenAPIV3.PathItemObject;
+}
+export interface ResolvedApiKeyAuth {
+    type: "apiKey";
+    schemeName: string;
+    in: "query" | "header" | "cookie";
+    name: string;
+    value: string;
+}
+export interface ResolvedOAuth2Auth {
+    type: "oauth2";
+    schemeName: string;
+    token: string;
+}
+export type ResolvedAuthScheme = ResolvedApiKeyAuth | ResolvedOAuth2Auth;
+export interface ResolvedAuthResult {
+    authUsed: string[];
+    schemes: ResolvedAuthScheme[];
+}
+export interface LoadedApi {
+    config: ApiConfig;
+    schemaPath: string;
+    schema: OpenAPIV3.Document;
+    baseUrl: string;
+    endpoints: EndpointDefinition[];
+    endpointById: Map<string, EndpointDefinition>;
+    authSchemeNames: string[];
+}
+export interface ApiRegistry {
+    byName: Map<string, LoadedApi>;
+}
+export interface MakeEndpointRequestInput {
+    apiName: string;
+    endpointId: string;
+    pathParams?: Record<string, unknown>;
+    query?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    cookies?: Record<string, string>;
+    body?: unknown;
+    contentType?: string;
+    accept?: string;
+    timeoutMs?: number;
+    retry429?: Retry429Config;
+}
+export interface RequestExecutionResult {
+    request: {
+        url: string;
+        method: string;
+        headersRedacted: Record<string, string>;
+        endpointId: string;
+    };
+    response: {
+        status: number;
+        headers: Record<string, string>;
+        bodyType: "json" | "text" | "binary" | "empty";
+        bodyJson?: unknown;
+        bodyText?: string;
+        bodyBase64?: string;
+    };
+    timingMs: number;
+    authUsed: string[];
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "openapi-dynamic-mcp",
+  "version": "0.1.0",
+  "description": "MCP stdio server for OpenAPI APIs",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "openapi-dynamic-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mayorandrew/openapi-dynamic-mcp.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "openapi",
+    "stdio"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@modelcontextprotocol/sdk": "^1.17.3",
+    "oauth4webapi": "^3.8.5",
+    "openapi-types": "^12.1.3",
+    "yaml": "^2.8.1",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.8",
+    "nock": "^14.0.10",
+    "tsx": "^4.20.5",
+    "typescript": "^5.8.2",
+    "vitest": "^3.2.4"
+  }
+}