openapi-explorer-mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Trofimov
+
+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,139 @@
+# openapi-explorer-mcp
+
+An MCP server for any OpenAPI 3 spec. It lets an AI agent find endpoints, inspect request and response shapes
+without loading a megabyte of JSON, generate TypeScript types, and call endpoints — with credentials mapped to the
+security schemes the spec already declares.
+
+Unlike servers that turn every operation into its own tool, this one stays small: a handful of tools that explore
+the spec and one generic caller.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `api_spec_info` | Spec version and age, counts, groups, security schemes with credential status, changes since the previous version. |
+| `api_search` | Searches method, path, operationId, summary, tags and parameter names. |
+| `api_endpoint` | Parameters, request and response shapes (compact, depth-limited), danger level, security alternatives, URL. |
+| `api_schema` | A component schema by name, with drill-down into nested fields and the endpoints that use it. |
+| `api_types` | TypeScript types for an endpoint's request, response and parameters, generated with `@hey-api/openapi-ts`. |
+| `api_get` | Calls a GET endpoint. |
+| `api_request` | Calls an endpoint with any method. Registered only with `OPENAPI_ALLOW_WRITE`; destructive endpoints need `confirm_danger: true`. |
+| `api_call_log` | Journal of `api_request` calls with ids from responses, for cleaning up. |
+| `api_auth` | Mints tokens through the auth module. Registered only when the module supports it. |
+| `recipe` | Markdown recipes for this API. Registered only with `OPENAPI_RECIPES_DIR`. |
+
+## Configuration
+
+| Variable | |
+|---|---|
+| `OPENAPI_SPEC_URL` | Required. URL or file path of an OpenAPI 3 JSON spec. URLs are cached on disk and revalidated with ETag. |
+| `OPENAPI_BASE_URL` | Base URL for calls. Required whenever any credential or header is configured; otherwise `servers[0].url` of the spec is used for anonymous calls. |
+| `OPENAPI_AUTH_<SCHEME>` | Credential for a security scheme — see [Authentication](#authentication). |
+| `OPENAPI_HEADER_<NAME>` | A header sent with every call, for specs that don't declare security schemes. `OPENAPI_HEADER_X_API_KEY` sends `x-api-key`. |
+| `OPENAPI_AUTH_MODULE` | Path to an ES module that supplies credentials minted at runtime. |
+| `OPENAPI_ENV_FILE` | Env file merged into the environment at startup; variables already set win. |
+| `OPENAPI_ALLOW_WRITE` | `1`, `true` or `yes` registers `api_request`. Off by default. |
+| `OPENAPI_DANGER_FILE` | JSON with danger overrides — see [Danger rules](#danger-rules). |
+| `OPENAPI_RECIPES_DIR` | Directory of markdown recipes (with a `description:` line) served by `recipe`. |
+| `OPENAPI_INSTRUCTIONS_FILE` | Markdown appended to the instructions the server gives the model. |
+| `OPENAPI_SERVER_NAME` | Server name reported to the client. Default `openapi`. |
+| `OPENAPI_CACHE_DIR` | Spec cache and generated types. Default `~/.cache/openapi-explorer-mcp/<hash of the spec source>`. |
+| `OPENAPI_CALL_LOG` | Journal of `api_request` calls. Default `<cache dir>/calls.jsonl`. |
+| `OPENAPI_SPEC_TTL_S` | How often a URL spec is revalidated. Default `900`. |
+| `OPENAPI_TIMEOUT_MS` | Timeout of spec fetches and calls. Default `20000`. |
+| `OPENAPI_MAX_RESPONSE_CHARS` | Cap on a tool response. Default `40000`. |
+
+```json
+{
+  "mcpServers": {
+    "my-api": {
+      "command": "npx",
+      "args": ["-y", "openapi-explorer-mcp"],
+      "env": {
+        "OPENAPI_SPEC_URL": "https://api.example.com/openapi.json",
+        "OPENAPI_BASE_URL": "https://api.example.com",
+        "OPENAPI_AUTH_X_API_KEY": "${MY_API_KEY}",
+        "OPENAPI_SERVER_NAME": "my-api"
+      }
+    }
+  }
+}
+```
+
+## Authentication
+
+The server doesn't invent headers — it reads them from the spec. `components.securitySchemes` says where a secret
+goes, and each operation's `security` says which schemes it accepts. You only give a scheme its value.
+
+**Credentials.** `OPENAPI_AUTH_<SCHEME>` holds the value for a scheme; the name is upper-cased with every other
+character replaced by `_`: `x-admin-token` → `OPENAPI_AUTH_X_ADMIN_TOKEN`, `bearer` → `OPENAPI_AUTH_BEARER`. The
+value is placed where the scheme says:
+
+| Scheme | Placement |
+|---|---|
+| `apiKey` in `header` / `query` / `cookie` | the named header, query parameter or cookie |
+| `http` `bearer`, `oauth2`, `openIdConnect` | `Authorization: Bearer <value>` |
+| `http` `basic` | `Authorization: Basic …` — give `user:password` or an already encoded value |
+
+**Which scheme a call uses.** `security` is a list of alternatives. With `as: "auto"` (the default) the server
+takes the first alternative whose schemes all have credentials. `as` can also name a scheme to force it, or be
+`"anonymous"`. When nothing is configured, a GET is sent anonymously with a note (many GET endpoints declare auth
+but also answer without it); any other method fails with the name of the variable to set.
+
+**Tokens minted at runtime.** `OPENAPI_AUTH_MODULE` points to an ES module whose default export creates a provider.
+The `identity` argument of `api_get` and `api_request` is passed to it as is. Types are exported by the package:
+
+```ts
+import type { AuthProviderFactory } from 'openapi-explorer-mcp';
+
+const createAuth: AuthProviderFactory = ({ baseUrl, timeoutMs, env }) => ({
+  canProvide: (scheme, { identity }) => scheme === 'bearer' && Boolean(identity ?? env.DEFAULT_USER),
+  getCredential: async (scheme, { identity, force }) => mintToken(baseUrl, identity ?? env.DEFAULT_USER, { force, timeoutMs }),
+  // optional: registers api_auth
+  authenticate: async ({ identity, force }) => ({ identity: identity ?? 'default', accessToken: await mintToken(/* … */) }),
+});
+
+export default createAuth;
+```
+
+A static credential from `OPENAPI_AUTH_<SCHEME>` wins over the module for the same scheme. When a call that used a
+module credential gets `401`, the server asks the module again with `force: true` and retries once.
+
+**What keeps credentials safe**
+
+- Only the person configuring the server sets values; no tool accepts headers or tokens, so the model picks a
+  scheme, never a value.
+- Credentials go only to `OPENAPI_BASE_URL`, which must be set explicitly when any credential exists. The spec's
+  `servers` is never trusted with them — the spec is fetched over the network and could point elsewhere.
+- The origin of every request is checked against the base URL before sending; path parameters are URL-encoded.
+- Values never appear in tool output or in the call journal: responses name the scheme, and `api_spec_info` shows
+  only whether a scheme has a credential.
+
+## Danger rules
+
+Every non-GET operation is `write`, and `destructive` when it is a `DELETE` or its path contains `drop`, `purge`,
+`reset`, `destroy`, `bulk` or `broadcast`. `api_request` refuses destructive operations without
+`confirm_danger: true`. `OPENAPI_DANGER_FILE` adds exact operations and path words:
+
+```json
+{
+  "operations": {
+    "POST /orders": "creates a real order"
+  },
+  "pathPatterns": ["close", "withdraw"]
+}
+```
+
+## Development
+
+```
+npm install
+npm run typecheck
+npm run build      # tsc into dist/
+npm run smoke      # stdio checks against scripts/fixtures/pets.json, no network
+npm run check      # all three
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/auth.d.ts

@@ -0,0 +1,90 @@
+import { type ExplorerConfig } from './config.js';
+import type { Operation, SecurityScheme } from './spec-index.js';
+/**
+ * Per-call context passed to an auth provider.
+ */
+export interface AuthContext {
+    /** Identity from the tool call, e.g. a user id; the provider decides what it means. */
+    identity?: string;
+    /** Ignore cached credentials, e.g. after a 401. */
+    force?: boolean;
+}
+/**
+ * Tokens a provider minted, shown by the api_auth tool.
+ */
+export interface AuthSession {
+    /** Who the tokens belong to. */
+    identity: string;
+    /** When the access token expires, ISO 8601. */
+    expiresAt?: string;
+    /** Access token. */
+    accessToken?: string;
+    /** Refresh token. */
+    refreshToken?: string;
+}
+/**
+ * Supplies credentials that can't be static, e.g. tokens minted per user.
+ */
+export interface AuthProvider {
+    /** Whether the provider can supply a credential for the scheme in this context, without doing I/O. */
+    canProvide(scheme: string, context: AuthContext): boolean;
+    /** Returns the credential value for the scheme. */
+    getCredential(scheme: string, context: AuthContext): Promise<string>;
+    /** Mints or refreshes tokens for an identity; registers the api_auth tool when present. */
+    authenticate?(context: AuthContext): Promise<AuthSession>;
+}
+/**
+ * What a provider factory receives.
+ */
+export interface AuthProviderOptions {
+    /** OPENAPI_BASE_URL. */
+    baseUrl: string;
+    /** OPENAPI_TIMEOUT_MS. */
+    timeoutMs: number;
+    /** The process environment, with OPENAPI_ENV_FILE already merged in. */
+    env: NodeJS.ProcessEnv;
+}
+/** The default export of an OPENAPI_AUTH_MODULE. */
+export type AuthProviderFactory = (options: AuthProviderOptions) => AuthProvider | Promise<AuthProvider>;
+/** Which security alternative a call uses. */
+export type AuthSelection = {
+    mode: 'anonymous';
+    note?: string;
+} | {
+    mode: 'credentials';
+    schemes: string[];
+};
+/**
+ * Imports OPENAPI_AUTH_MODULE and creates its provider.
+ */
+export declare function loadAuthProvider(config: ExplorerConfig): Promise<AuthProvider | undefined>;
+/**
+ * Maps credentials from the environment and an auth provider onto the security schemes of the spec.
+ */
+export declare class Credentials {
+    private readonly config;
+    private readonly provider?;
+    constructor(config: ExplorerConfig, provider?: AuthProvider | undefined);
+    /**
+     * Where the credential of a scheme comes from, or null when nothing supplies it.
+     */
+    source(scheme: string, context?: AuthContext): 'env' | 'module' | null;
+    /**
+     * Credential status of a scheme for spec info.
+     */
+    describe(scheme: string): string;
+    /**
+     * Picks the security alternative for a call: a forced scheme, the first alternative with all credentials, or anonymous.
+     */
+    select(op: Operation, as: string, context: AuthContext, schemes: Record<string, SecurityScheme>): AuthSelection;
+    /**
+     * Puts the credentials of the selected schemes into the request; reports whether any came from the provider.
+     */
+    apply(selection: AuthSelection, schemes: Record<string, SecurityScheme>, context: AuthContext, headers: Record<string, string>, url: URL): Promise<{
+        fromProvider: boolean;
+    }>;
+    /**
+     * Tells the user how to supply a credential for a scheme.
+     */
+    private hint;
+}

package/dist/auth.js

@@ -0,0 +1,140 @@
+import { pathToFileURL } from 'node:url';
+import { ConfigError, schemeEnvName, schemeEnvSuffix } from './config.js';
+/**
+ * Imports OPENAPI_AUTH_MODULE and creates its provider.
+ */
+export async function loadAuthProvider(config) {
+    if (!config.authModule || !config.baseUrl)
+        return undefined;
+    const mod = (await import(pathToFileURL(config.authModule).href));
+    if (typeof mod.default !== 'function') {
+        throw new ConfigError(`OPENAPI_AUTH_MODULE must default-export a factory function: ${config.authModule}`);
+    }
+    const provider = (await mod.default({ baseUrl: config.baseUrl, timeoutMs: config.timeoutMs, env: process.env }));
+    if (!provider || typeof provider.canProvide !== 'function' || typeof provider.getCredential !== 'function') {
+        throw new ConfigError('OPENAPI_AUTH_MODULE factory must return an object with canProvide and getCredential');
+    }
+    return provider;
+}
+/**
+ * Places a credential where its security scheme says: a header, the query string, a cookie or Authorization.
+ */
+function applyScheme(name, scheme, value, headers, url) {
+    switch (scheme.type) {
+        case 'apiKey': {
+            if (!scheme.name)
+                throw new Error(`security scheme "${name}" has no parameter name`);
+            if (scheme.in === 'header')
+                headers[scheme.name] = value;
+            else if (scheme.in === 'query')
+                url.searchParams.set(scheme.name, value);
+            else if (scheme.in === 'cookie')
+                headers.Cookie = [headers.Cookie, `${scheme.name}=${encodeURIComponent(value)}`].filter(Boolean).join('; ');
+            else
+                throw new Error(`security scheme "${name}" uses an unsupported location "${scheme.in}"`);
+            return;
+        }
+        case 'http': {
+            const kind = (scheme.scheme ?? '').toLowerCase();
+            if (kind === 'bearer')
+                headers.Authorization = `Bearer ${value}`;
+            else if (kind === 'basic')
+                headers.Authorization = `Basic ${value.includes(':') ? Buffer.from(value).toString('base64') : value}`;
+            else
+                throw new Error(`security scheme "${name}" uses an unsupported HTTP scheme "${scheme.scheme}"`);
+            return;
+        }
+        case 'oauth2':
+        case 'openIdConnect':
+            headers.Authorization = `Bearer ${value}`;
+            return;
+        default:
+            throw new Error(`security scheme "${name}" has an unsupported type "${scheme.type}"`);
+    }
+}
+/**
+ * Maps credentials from the environment and an auth provider onto the security schemes of the spec.
+ */
+export class Credentials {
+    config;
+    provider;
+    constructor(config, provider) {
+        this.config = config;
+        this.provider = provider;
+    }
+    /**
+     * Where the credential of a scheme comes from, or null when nothing supplies it.
+     */
+    source(scheme, context = {}) {
+        if (this.config.schemeCredentials.has(schemeEnvSuffix(scheme)))
+            return 'env';
+        return this.provider?.canProvide(scheme, context) ? 'module' : null;
+    }
+    /**
+     * Credential status of a scheme for spec info.
+     */
+    describe(scheme) {
+        const source = this.source(scheme);
+        if (source)
+            return source;
+        // canProvide does no I/O by contract, so probing with a placeholder identity is safe and tells whether passing one would help.
+        return this.provider?.canProvide(scheme, { identity: 'identity' }) ? 'module, when an identity is passed' : 'not configured';
+    }
+    /**
+     * Picks the security alternative for a call: a forced scheme, the first alternative with all credentials, or anonymous.
+     */
+    select(op, as, context, schemes) {
+        if (as === 'anonymous')
+            return { mode: 'anonymous' };
+        if (as !== 'auto') {
+            if (!schemes[as]) {
+                const known = Object.keys(schemes);
+                throw new Error(`unknown security scheme "${as}"; the spec defines: ${known.length ? known.join(', ') : 'none'}`);
+            }
+            if (!this.source(as, context))
+                throw new Error(`no credential for "${as}": ${this.hint(as)}`);
+            return { mode: 'credentials', schemes: [as] };
+        }
+        for (const alternative of op.security) {
+            if (alternative.every((scheme) => this.source(scheme, context))) {
+                return alternative.length ? { mode: 'credentials', schemes: alternative } : { mode: 'anonymous' };
+            }
+        }
+        if (op.security.length === 0)
+            return { mode: 'anonymous' };
+        const missing = [...new Set(op.security.flat())];
+        const hints = missing.map((scheme) => this.hint(scheme)).join('; ');
+        // Many GET endpoints declare auth but also answer anonymously, and a 401 explains itself; writes don't get that benefit of the doubt.
+        if (op.method === 'GET')
+            return { mode: 'anonymous', note: `no credentials for ${missing.join(' or ')}, called anonymously — ${hints}` };
+        throw new Error(`${op.key} requires ${op.security.map((a) => a.join(' + ')).join(' or ')}: ${hints}`);
+    }
+    /**
+     * Puts the credentials of the selected schemes into the request; reports whether any came from the provider.
+     */
+    async apply(selection, schemes, context, headers, url) {
+        if (selection.mode === 'anonymous')
+            return { fromProvider: false };
+        let fromProvider = false;
+        for (const name of selection.schemes) {
+            const scheme = schemes[name];
+            if (!scheme)
+                throw new Error(`the spec has no security scheme "${name}"`);
+            let value = this.config.schemeCredentials.get(schemeEnvSuffix(name));
+            if (value === undefined) {
+                if (!this.provider)
+                    throw new Error(`no credential for "${name}": ${this.hint(name)}`);
+                value = await this.provider.getCredential(name, context);
+                fromProvider = true;
+            }
+            applyScheme(name, scheme, value, headers, url);
+        }
+        return { fromProvider };
+    }
+    /**
+     * Tells the user how to supply a credential for a scheme.
+     */
+    hint(scheme) {
+        return `set ${schemeEnvName(scheme)}${this.provider ? ' or pass an identity the auth module accepts' : ''}`;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Runtime configuration read from environment variables.
+ */
+export interface ExplorerConfig {
+    /** URL of the spec, or an absolute path to a local spec file. */
+    specSource: string;
+    /** Whether specSource is an http(s) URL. */
+    specIsUrl: boolean;
+    /** Explicit base URL for calls, without a trailing slash. */
+    baseUrl?: string;
+    /** Directory for the spec cache and generated types. */
+    cacheDir: string;
+    /** How often a URL spec is revalidated, in milliseconds. */
+    specTtlMs: number;
+    /** Timeout of spec fetches and API calls, in milliseconds. */
+    timeoutMs: number;
+    /** Cap on the size of a tool response, in characters. */
+    maxResponseChars: number;
+    /** Whether api_request is registered. */
+    allowWrite: boolean;
+    /** Server name reported to MCP clients. */
+    serverName: string;
+    /** JSON file with danger overrides. */
+    dangerFile?: string;
+    /** Directory of markdown recipes; the recipe tool exists only when it is set. */
+    recipesDir?: string;
+    /** Markdown appended to the server instructions. */
+    instructionsFile?: string;
+    /** JSONL journal of api_request calls. */
+    callLog: string;
+    /** ES module whose default export creates an auth provider. */
+    authModule?: string;
+    /** Headers sent with every call, from OPENAPI_HEADER_<NAME>. */
+    staticHeaders: Record<string, string>;
+    /** Credentials keyed by the normalized scheme name, from OPENAPI_AUTH_<SCHEME>. */
+    schemeCredentials: Map<string, string>;
+}
+/**
+ * The environment is missing a required value or holds an invalid one.
+ */
+export declare class ConfigError extends Error {
+    name: string;
+}
+/**
+ * Normalizes a security scheme name into its environment variable suffix: x-admin-token becomes X_ADMIN_TOKEN.
+ */
+export declare function schemeEnvSuffix(scheme: string): string;
+/**
+ * Name of the environment variable that holds the credential of a scheme.
+ */
+export declare function schemeEnvName(scheme: string): string;
+/**
+ * Parses KEY=VALUE lines of an env file: comments, `export` prefixes and quoted values are supported.
+ */
+export declare function parseEnvText(text: string): Record<string, string>;
+/**
+ * Reads and validates the configuration from environment variables.
+ */
+export declare function readConfig(env?: NodeJS.ProcessEnv): ExplorerConfig;

package/dist/config.js

@@ -0,0 +1,164 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+/**
+ * The environment is missing a required value or holds an invalid one.
+ */
+export class ConfigError extends Error {
+    name = 'ConfigError';
+}
+const AUTH_PREFIX = 'OPENAPI_AUTH_';
+const HEADER_PREFIX = 'OPENAPI_HEADER_';
+const RESERVED_AUTH_KEYS = new Set(['OPENAPI_AUTH_MODULE']);
+/**
+ * Normalizes a security scheme name into its environment variable suffix: x-admin-token becomes X_ADMIN_TOKEN.
+ */
+export function schemeEnvSuffix(scheme) {
+    return scheme
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+/**
+ * Name of the environment variable that holds the credential of a scheme.
+ */
+export function schemeEnvName(scheme) {
+    return `${AUTH_PREFIX}${schemeEnvSuffix(scheme)}`;
+}
+/**
+ * Expands a leading ~ to the home directory.
+ */
+function expandHome(value) {
+    if (value === '~')
+        return homedir();
+    return value.startsWith('~/') ? path.join(homedir(), value.slice(2)) : value;
+}
+/**
+ * Parses KEY=VALUE lines of an env file: comments, `export` prefixes and quoted values are supported.
+ */
+export function parseEnvText(text) {
+    const out = {};
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const match = /^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        let value = match[2];
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.endsWith(quote) && value.length >= 2) {
+            value = value.slice(1, -1);
+        }
+        else {
+            value = value.replace(/\s+#.*$/, '').trim();
+        }
+        out[match[1]] = value;
+    }
+    return out;
+}
+/**
+ * Merges an env file into the environment; variables that are already set win, so a client config can override the file.
+ */
+function loadEnvFile(file, env) {
+    if (!existsSync(file))
+        throw new ConfigError(`OPENAPI_ENV_FILE points to a missing file: ${file}`);
+    for (const [key, value] of Object.entries(parseEnvText(readFileSync(file, 'utf8')))) {
+        if (env[key] === undefined)
+            env[key] = value;
+    }
+}
+/**
+ * Parses an optional positive number, failing loudly instead of silently turning garbage into NaN.
+ */
+function positiveNumber(raw, fallback, name) {
+    if (raw === undefined || raw.trim() === '')
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        throw new ConfigError(`${name} must be a positive number, got "${raw}"`);
+    return value;
+}
+/**
+ * Resolves an optional path variable; a variable that is set must point to something that exists.
+ */
+function optionalPath(env, name) {
+    const raw = env[name]?.trim();
+    if (!raw)
+        return undefined;
+    const resolved = path.resolve(expandHome(raw));
+    if (!existsSync(resolved))
+        throw new ConfigError(`${name} points to a missing path: ${resolved}`);
+    return resolved;
+}
+/**
+ * Reads and validates the configuration from environment variables.
+ */
+export function readConfig(env = process.env) {
+    const envFile = env.OPENAPI_ENV_FILE?.trim();
+    if (envFile)
+        loadEnvFile(path.resolve(expandHome(envFile)), env);
+    const rawSpec = env.OPENAPI_SPEC_URL?.trim();
+    if (!rawSpec)
+        throw new ConfigError('OPENAPI_SPEC_URL is required: the URL or file path of an OpenAPI 3 JSON spec');
+    const specIsUrl = /^https?:\/\//i.test(rawSpec);
+    const specSource = specIsUrl ? rawSpec : path.resolve(expandHome(rawSpec));
+    if (!specIsUrl && !existsSync(specSource))
+        throw new ConfigError(`OPENAPI_SPEC_URL points to a missing file: ${specSource}`);
+    let baseUrl;
+    const rawBase = env.OPENAPI_BASE_URL?.trim();
+    if (rawBase) {
+        let parsed;
+        try {
+            parsed = new URL(rawBase);
+        }
+        catch {
+            throw new ConfigError(`OPENAPI_BASE_URL is not a valid URL: ${rawBase}`);
+        }
+        if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+            throw new ConfigError(`OPENAPI_BASE_URL must be an http(s) URL, got ${parsed.protocol}`);
+        }
+        baseUrl = rawBase.replace(/\/+$/, '');
+    }
+    const staticHeaders = {};
+    const schemeCredentials = new Map();
+    for (const [key, value] of Object.entries(env)) {
+        // An empty value, e.g. from ${VAR:-} in a client config, means "not configured".
+        if (!value)
+            continue;
+        if (key.startsWith(HEADER_PREFIX)) {
+            staticHeaders[key.slice(HEADER_PREFIX.length).toLowerCase().replace(/_/g, '-')] = value;
+        }
+        else if (key.startsWith(AUTH_PREFIX) && !RESERVED_AUTH_KEYS.has(key)) {
+            schemeCredentials.set(key.slice(AUTH_PREFIX.length), value);
+        }
+    }
+    const authModule = optionalPath(env, 'OPENAPI_AUTH_MODULE');
+    if (!baseUrl && (schemeCredentials.size > 0 || Object.keys(staticHeaders).length > 0 || authModule)) {
+        throw new ConfigError('OPENAPI_BASE_URL is required when credentials or headers are configured: they only go to an origin you set explicitly, never to one taken from the spec');
+    }
+    const rawCacheDir = env.OPENAPI_CACHE_DIR?.trim();
+    const cacheDir = rawCacheDir
+        ? path.resolve(expandHome(rawCacheDir))
+        : path.join(homedir(), '.cache', 'openapi-explorer-mcp', createHash('sha1').update(specSource).digest('hex').slice(0, 12));
+    const rawCallLog = env.OPENAPI_CALL_LOG?.trim();
+    return {
+        specSource,
+        specIsUrl,
+        baseUrl,
+        cacheDir,
+        specTtlMs: positiveNumber(env.OPENAPI_SPEC_TTL_S, 900, 'OPENAPI_SPEC_TTL_S') * 1000,
+        timeoutMs: positiveNumber(env.OPENAPI_TIMEOUT_MS, 20_000, 'OPENAPI_TIMEOUT_MS'),
+        maxResponseChars: positiveNumber(env.OPENAPI_MAX_RESPONSE_CHARS, 40_000, 'OPENAPI_MAX_RESPONSE_CHARS'),
+        allowWrite: /^(1|true|yes)$/i.test(env.OPENAPI_ALLOW_WRITE ?? ''),
+        serverName: env.OPENAPI_SERVER_NAME?.trim() || 'openapi',
+        dangerFile: optionalPath(env, 'OPENAPI_DANGER_FILE'),
+        recipesDir: optionalPath(env, 'OPENAPI_RECIPES_DIR'),
+        instructionsFile: optionalPath(env, 'OPENAPI_INSTRUCTIONS_FILE'),
+        callLog: rawCallLog ? path.resolve(expandHome(rawCallLog)) : path.join(cacheDir, 'calls.jsonl'),
+        authModule,
+        staticHeaders,
+        schemeCredentials,
+    };
+}

package/dist/http.d.ts

@@ -0,0 +1,24 @@
+import type { HttpMethod } from './spec-index.js';
+/**
+ * Outcome of an HTTP call.
+ */
+export interface CallResult {
+    /** HTTP status. */
+    status: number;
+    /** Whether the status is 2xx. */
+    ok: boolean;
+    /** Call duration. */
+    durationMs: number;
+    /** Rate limit headers the API returned. */
+    rateLimit?: Record<string, string>;
+    /** Parsed JSON body, raw text, or null for an empty body. */
+    body: unknown;
+}
+/**
+ * Fills path parameters into a path template and appends the query string.
+ */
+export declare function buildUrl(baseUrl: string, pathTemplate: string, pathParams: Record<string, string | number>, query: Record<string, string | number | boolean>): URL;
+/**
+ * Sends a request and returns a structured result; authorization and retries are the caller's job.
+ */
+export declare function send(method: HttpMethod, url: URL, headers: Record<string, string>, body: unknown, timeoutMs: number): Promise<CallResult>;