openapi-explorer-mcp 0.0.1

package/dist/spec-index.js

@@ -0,0 +1,101 @@
+import { classifyDanger } from './risk.js';
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
+const NAMESPACE_SEGMENT = /^(admin|internal|api|v\d+)$/i;
+/**
+ * Browsing group: the first path segment, or the first two when the first is a namespace like admin or v1.
+ */
+function groupOf(path) {
+    const parts = path.split('/').filter(Boolean);
+    if (parts.length === 0)
+        return '(root)';
+    return NAMESPACE_SEGMENT.test(parts[0]) && parts[1] ? `${parts[0]}/${parts[1]}` : parts[0];
+}
+/**
+ * Documented success response: 200, then 201, then any 2xx, then default.
+ */
+function successResponse(responses = {}) {
+    const statuses = ['200', '201', ...Object.keys(responses).filter((s) => /^2\d\d$/.test(s) && s !== '200' && s !== '201'), 'default'];
+    for (const status of statuses) {
+        const schema = responses[status]?.content?.['application/json']?.schema;
+        if (schema)
+            return { status, schema };
+    }
+    return null;
+}
+/**
+ * Builds the searchable index of a spec.
+ */
+export function buildIndex(spec, rules) {
+    const operations = [];
+    const byKey = new Map();
+    const byOperationId = new Map();
+    const schemaUsedBy = new Map();
+    const globalSecurity = spec.security;
+    for (const [path, item] of Object.entries(spec.paths ?? {})) {
+        for (const lower of METHODS) {
+            const op = item[lower];
+            if (!op)
+                continue;
+            const method = lower.toUpperCase();
+            const key = `${method} ${path}`;
+            const params = { path: [], query: [], header: [], cookie: [] };
+            for (const param of [...(item.parameters ?? []), ...(op.parameters ?? [])]) {
+                (params[param.in] ??= []).push(param);
+            }
+            // Operation-level security overrides the global one; an empty requirement object means anonymous access.
+            const security = (op.security ?? globalSecurity ?? []).map((requirement) => Object.keys(requirement));
+            const response = successResponse(op.responses);
+            const verdict = classifyDanger(rules, method, path);
+            const record = {
+                key,
+                method,
+                path,
+                operationId: op.operationId,
+                summary: op.summary ?? '',
+                tags: op.tags ?? [],
+                group: groupOf(path),
+                admin: path.startsWith('/admin'),
+                danger: verdict.danger,
+                dangerReason: verdict.reason,
+                security,
+                authSchemes: [...new Set(security.flat())],
+                params,
+                request: op.requestBody?.content?.['application/json']?.schema,
+                responseStatus: response?.status ?? null,
+                response: response?.schema ?? null,
+                searchText: [method, path, op.operationId, op.summary, (op.tags ?? []).join(' '), Object.values(params).flat().map((p) => p.name).join(' ')]
+                    .filter(Boolean)
+                    .join(' ')
+                    .toLowerCase(),
+            };
+            operations.push(record);
+            byKey.set(key, record);
+            if (op.operationId) {
+                const keys = byOperationId.get(op.operationId) ?? [];
+                keys.push(key);
+                byOperationId.set(op.operationId, keys);
+            }
+            for (const name of new Set([...JSON.stringify(op).matchAll(/#\/components\/schemas\/([A-Za-z0-9_.-]+)/g)].map((m) => m[1]))) {
+                const keys = schemaUsedBy.get(name) ?? [];
+                keys.push(key);
+                schemaUsedBy.set(name, keys);
+            }
+        }
+    }
+    return {
+        version: spec.info?.version,
+        title: spec.info?.title,
+        operations,
+        byKey,
+        byOperationId,
+        schemaUsedBy,
+        schemas: spec.components?.schemas ?? {},
+        securitySchemes: spec.components?.securitySchemes ?? {},
+        servers: (spec.servers ?? []).map((s) => s.url).filter((url) => typeof url === 'string'),
+        counts: {
+            paths: Object.keys(spec.paths ?? {}).length,
+            operations: operations.length,
+            schemas: Object.keys(spec.components?.schemas ?? {}).length,
+        },
+    };
+}

package/dist/spec-store.d.ts

@@ -0,0 +1,82 @@
+import type { ExplorerConfig } from './config.js';
+import type { DangerRules } from './risk.js';
+import { type SpecIndex } from './spec-index.js';
+/**
+ * Operations added and removed between two spec versions.
+ */
+export interface KeyDiff {
+    /** Operation keys that appeared. */
+    added: string[];
+    /** Operation keys that disappeared. */
+    removed: string[];
+}
+/**
+ * What is known about the loaded spec.
+ */
+export interface SpecMeta {
+    /** Spec URL or file path. */
+    source: string;
+    /** ETag of the last fetched copy. */
+    etag: string | null;
+    /** When the current content was fetched (URL) or modified (file), epoch ms. */
+    fetchedAt: number;
+    /** When the source was last checked, epoch ms. */
+    checkedAt: number;
+    /** info.version. */
+    version?: string;
+    /** Size of the spec text in characters. */
+    size: number;
+    /** Operations changed since the previous version. */
+    changed?: KeyDiff;
+}
+/**
+ * The loaded spec with its index.
+ */
+export interface SpecState {
+    /** Searchable index. */
+    index: SpecIndex;
+    /** Metadata. */
+    meta: SpecMeta;
+    /** Set when the source is unreachable and a cached copy is served. */
+    offline: {
+        since: number;
+        reason: string;
+    } | null;
+    /** Path of a local copy of the spec, used for type generation. */
+    specPath: string;
+}
+/**
+ * Loads the spec lazily: a local file is re-read when modified, a URL is cached on disk and revalidated with ETag.
+ */
+export declare class SpecStore {
+    private readonly config;
+    private readonly rules;
+    private state;
+    private readonly cachedSpecPath;
+    private readonly metaPath;
+    constructor(config: ExplorerConfig, rules: DangerRules);
+    /**
+     * Returns the current spec, revalidating it when due.
+     */
+    load(force?: boolean): Promise<SpecState>;
+    /**
+     * Revalidates the spec now.
+     */
+    forceRevalidate(): Promise<SpecState>;
+    /**
+     * Loads a local spec file, re-reading it only when its modification time changes.
+     */
+    private loadFile;
+    /**
+     * Loads a URL spec: memory, then disk cache, then a conditional fetch; serves the cache when the source is down.
+     */
+    private loadUrl;
+    /**
+     * Reads the cached copy; ignores a cache that belongs to another spec source.
+     */
+    private readDisk;
+    /**
+     * Writes the fetched spec and its metadata; a failed cache write never fails the call.
+     */
+    private writeDisk;
+}

package/dist/spec-store.js

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { buildIndex } from './spec-index.js';
+/**
+ * Parses spec text and checks that it is OpenAPI 3.
+ */
+function parseSpec(text, source) {
+    let spec;
+    try {
+        spec = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`the spec at ${source} is not valid JSON (only JSON specs are supported)`);
+    }
+    if (typeof spec.openapi !== 'string' || !spec.openapi.startsWith('3.')) {
+        throw new Error(`the spec at ${source} is not OpenAPI 3.x (openapi: ${String(spec.openapi ?? spec.swagger ?? 'missing')})`);
+    }
+    return spec;
+}
+/**
+ * Lists operations added and removed between two indexes.
+ */
+function diffKeys(before, after) {
+    const old = new Set(before.operations.map((o) => o.key));
+    const next = new Set(after.operations.map((o) => o.key));
+    return { added: [...next].filter((k) => !old.has(k)), removed: [...old].filter((k) => !next.has(k)) };
+}
+/**
+ * Loads the spec lazily: a local file is re-read when modified, a URL is cached on disk and revalidated with ETag.
+ */
+export class SpecStore {
+    config;
+    rules;
+    state = null;
+    cachedSpecPath;
+    metaPath;
+    constructor(config, rules) {
+        this.config = config;
+        this.rules = rules;
+        this.cachedSpecPath = path.join(config.cacheDir, 'spec.json');
+        this.metaPath = path.join(config.cacheDir, 'meta.json');
+    }
+    /**
+     * Returns the current spec, revalidating it when due.
+     */
+    async load(force = false) {
+        return this.config.specIsUrl ? this.loadUrl(force) : this.loadFile(force);
+    }
+    /**
+     * Revalidates the spec now.
+     */
+    forceRevalidate() {
+        return this.load(true);
+    }
+    /**
+     * Loads a local spec file, re-reading it only when its modification time changes.
+     */
+    loadFile(force) {
+        const { mtimeMs } = statSync(this.config.specSource);
+        if (!force && this.state && this.state.meta.fetchedAt === mtimeMs)
+            return this.state;
+        const text = readFileSync(this.config.specSource, 'utf8');
+        const index = buildIndex(parseSpec(text, this.config.specSource), this.rules);
+        const meta = { source: this.config.specSource, etag: null, fetchedAt: mtimeMs, checkedAt: Date.now(), version: index.version, size: text.length };
+        if (this.state?.meta.version && this.state.meta.version !== meta.version)
+            meta.changed = diffKeys(this.state.index, index);
+        this.state = { index, meta, offline: null, specPath: this.config.specSource };
+        return this.state;
+    }
+    /**
+     * Loads a URL spec: memory, then disk cache, then a conditional fetch; serves the cache when the source is down.
+     */
+    async loadUrl(force) {
+        const now = Date.now();
+        if (!force && this.state && !this.state.offline && now - this.state.meta.checkedAt < this.config.specTtlMs)
+            return this.state;
+        this.state ??= this.readDisk();
+        try {
+            const response = await fetch(this.config.specSource, {
+                headers: this.state?.meta.etag ? { 'If-None-Match': this.state.meta.etag } : {},
+                signal: AbortSignal.timeout(this.config.timeoutMs),
+            });
+            if (response.status === 304 && this.state) {
+                this.state.meta.checkedAt = now;
+                this.state.offline = null;
+            }
+            else if (response.ok) {
+                const text = await response.text();
+                const index = buildIndex(parseSpec(text, this.config.specSource), this.rules);
+                const meta = {
+                    source: this.config.specSource,
+                    etag: response.headers.get('etag'),
+                    fetchedAt: now,
+                    checkedAt: now,
+                    version: index.version,
+                    size: text.length,
+                };
+                if (this.state?.meta.version && this.state.meta.version !== meta.version)
+                    meta.changed = diffKeys(this.state.index, index);
+                this.writeDisk(text, meta);
+                this.state = { index, meta, offline: null, specPath: this.cachedSpecPath };
+            }
+            else {
+                throw new Error(`HTTP ${response.status}`);
+            }
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            if (!this.state)
+                throw new Error(`the spec is unreachable and there is no cached copy: ${reason}. Check that ${this.config.specSource} is reachable`);
+            this.state.offline = { since: this.state.offline?.since ?? now, reason };
+        }
+        return this.state;
+    }
+    /**
+     * Reads the cached copy; ignores a cache that belongs to another spec source.
+     */
+    readDisk() {
+        if (!existsSync(this.cachedSpecPath) || !existsSync(this.metaPath))
+            return null;
+        try {
+            const meta = JSON.parse(readFileSync(this.metaPath, 'utf8'));
+            if ((meta.source ?? meta.url) !== this.config.specSource)
+                return null;
+            const text = readFileSync(this.cachedSpecPath, 'utf8');
+            const index = buildIndex(parseSpec(text, this.cachedSpecPath), this.rules);
+            return { index, meta: { ...meta, source: this.config.specSource, etag: meta.etag ?? null }, offline: null, specPath: this.cachedSpecPath };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Writes the fetched spec and its metadata; a failed cache write never fails the call.
+     */
+    writeDisk(text, meta) {
+        try {
+            mkdirSync(this.config.cacheDir, { recursive: true });
+            writeFileSync(`${this.cachedSpecPath}.tmp`, text);
+            renameSync(`${this.cachedSpecPath}.tmp`, this.cachedSpecPath);
+            writeFileSync(this.metaPath, JSON.stringify(meta, null, 2));
+        }
+        catch (error) {
+            process.stderr.write(`openapi-explorer-mcp: could not write the spec cache — ${error.message}\n`);
+        }
+    }
+}

package/dist/types-gen.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Splits types.gen.ts into declarations by name, keeping the JSDoc right above each one.
+ */
+export declare function parseTypes(source: string): Map<string, string>;
+/**
+ * Returns generated declarations for a spec, regenerating only when the cache key changes.
+ */
+export declare function getTypeMap(specPath: string, outDir: string, cacheKey: string): Promise<Map<string, string>>;
+/**
+ * Renames the declared name in `export type Old = ...`.
+ */
+export declare function renameDeclaration(declaration: string, from: string, to: string): string;

package/dist/types-gen.js

@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+const cache = { key: null, map: null };
+/**
+ * Splits types.gen.ts into declarations by name, keeping the JSDoc right above each one.
+ */
+export function parseTypes(source) {
+    const map = new Map();
+    const re = /export (?:type|interface) (\w+)/g;
+    let match;
+    while ((match = re.exec(source))) {
+        let start = match.index;
+        const before = source.slice(0, start).trimEnd();
+        if (before.endsWith('*/'))
+            start = before.lastIndexOf('/**');
+        let depth = 0;
+        let i = re.lastIndex;
+        for (; i < source.length; i += 1) {
+            const ch = source[i];
+            if (ch === '{' || ch === '(' || ch === '[')
+                depth += 1;
+            else if (ch === '}' || ch === ')' || ch === ']')
+                depth -= 1;
+            else if (ch === ';' && depth === 0)
+                break;
+        }
+        map.set(match[1], source.slice(start, i + 1).trim());
+    }
+    return map;
+}
+/**
+ * Returns generated declarations for a spec, regenerating only when the cache key changes.
+ */
+export async function getTypeMap(specPath, outDir, cacheKey) {
+    if (cache.key === cacheKey && cache.map)
+        return cache.map;
+    // Loaded lazily: the generator is heavy and only this tool needs it.
+    const { createClient } = await import('@hey-api/openapi-ts');
+    await createClient({
+        input: specPath,
+        output: { path: outDir, postProcess: [] },
+        plugins: ['@hey-api/typescript'],
+        logs: { level: 'silent' },
+    });
+    cache.map = parseTypes(readFileSync(path.join(outDir, 'types.gen.ts'), 'utf8'));
+    cache.key = cacheKey;
+    return cache.map;
+}
+/**
+ * Renames the declared name in `export type Old = ...`.
+ */
+export function renameDeclaration(declaration, from, to) {
+    return from === to ? declaration : declaration.replace(new RegExp(`(export (?:type|interface) )${from}\\b`), `$1${to}`);
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "openapi-explorer-mcp",
+  "version": "0.0.1",
+  "description": "MCP server for any OpenAPI 3 spec: search endpoints, inspect request and response shapes, generate TypeScript types, and call endpoints with credentials mapped to the spec's security schemes.",
+  "license": "MIT",
+  "author": "Eugene Trofimov",
+  "type": "module",
+  "bin": {
+    "openapi-explorer-mcp": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/auth.d.ts",
+      "default": "./dist/auth.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.19"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "typecheck": "tsc --noEmit",
+    "smoke": "node scripts/smoke.mjs",
+    "check": "npm run typecheck && npm run build && npm run smoke",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "openapi",
+    "swagger",
+    "mcp",
+    "model-context-protocol",
+    "api-explorer",
+    "typescript-types",
+    "claude-code"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deadrime/openapi-explorer-mcp.git"
+  },
+  "homepage": "https://github.com/deadrime/openapi-explorer-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/deadrime/openapi-explorer-mcp/issues"
+  },
+  "dependencies": {
+    "@hey-api/openapi-ts": "^0.95.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.43",
+    "typescript": "^5.9.3"
+  }
+}