openapi-dynamic-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Starostin
+
+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,247 @@
+# openapi-dynamic-mcp
+
+TypeScript MCP stdio server that loads one or more OpenAPI 3.x specs from YAML config and exposes generic tools for API discovery and request execution.
+
+## What It Does
+
+- Runs as a single MCP stdio server for multiple APIs.
+- Supports OpenAPI `3.x` local spec files.
+- Exposes generic MCP tools:
+  - `list_apis`
+  - `list_api_endpoints`
+  - `get_api_endpoint`
+  - `get_api_schema`
+  - `make_endpoint_request`
+- Supports auth:
+  - `apiKey`
+  - OAuth2 client credentials (`oauth2`)
+  - combined OpenAPI security requirements (AND inside object, OR across array)
+- Supports per-API environment overrides for:
+  - base URL
+  - extra headers
+
+## Requirements
+
+- Node.js `20+`
+
+## Quick Start
+
+```bash
+npx openapi-dynamic-mcp --config ./examples/config.yaml
+```
+
+## Client Configuration
+
+### Claude Code
+
+```json
+{
+  "mcpServers": {
+    "openapi": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "openapi-dynamic-mcp@latest",
+        "--config",
+        "/absolute/path/to/config.yaml"
+      ],
+      "env": {
+        "PET_API_BASE_URL": "http://localhost:3000",
+        "PET_API_APIKEY_API_KEY": "secret",
+        "PET_API_OAUTH2_CLIENT_ID": "client_id",
+        "PET_API_OAUTH2_CLIENT_SECRET": "client_secret"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+```json
+{
+  "mcpServers": {
+    "openapi": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "openapi-dynamic-mcp@latest",
+        "--config",
+        "/absolute/path/to/config.yaml"
+      ],
+      "env": {
+        "PET_API_BASE_URL": "http://localhost:3000",
+        "PET_API_APIKEY_API_KEY": "secret",
+        "PET_API_OAUTH2_CLIENT_ID": "client_id",
+        "PET_API_OAUTH2_CLIENT_SECRET": "client_secret"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+```yaml
+# Config file version
+version: 1
+apis:
+  # Unique ID for this API
+  - name: pet-api
+    # Path to local OpenAPI spec
+    specPath: ./pet-api.yaml
+    # Base URL override
+    baseUrl: https://api.example.com/v1
+    # Request timeout in milliseconds
+    timeoutMs: 30000
+    headers:
+      # Custom headers for all requests
+      X-Client: openapi-dynamic-mcp
+    # Configuration for exponential retries on 429 Too Many Requests responses
+    retry429:
+      # Maximum number of retries
+      maxRetries: 2
+      # Initial retry delay in milliseconds
+      baseDelayMs: 250
+      # Maximum retry delay in milliseconds
+      maxDelayMs: 5000
+      # Jitter factor (0-1)
+      jitterRatio: 0.2
+      # Respect Retry-After header
+      respectRetryAfter: true
+    # OAuth2 client credentials configuration
+    oauth2:
+      # Optional token URL override
+      tokenUrlOverride: https://auth.example.com/oauth2/token
+      # Scopes to request
+      scopes: [read:pets, write:pets]
+      # How to pass Client Credentials to the token endpoint:
+      # Via HTTP Basic Authorization header: "client_secret_basic"
+      # Via POST body: "client_secret_post"
+      tokenEndpointAuthMethod: client_secret_basic
+```
+
+### Validation Rules
+
+- `apis[].name` must be unique (case-insensitive after normalization).
+- `apis[].specPath` must point to a readable local file.
+- OpenAPI version must be `3.x`.
+- Base URL resolution order: env -> config -> `openapi.servers[0].url`.
+
+## Environment Variables
+
+Environment variables allow specifying sensitive or environment-specific configuration for APIs. Variables are defined for each API separately.
+
+### Name Normalization
+
+API and auth scheme names are normalized as:
+
+- uppercase
+- non-alphanumeric -> `_`
+- repeated `_` collapsed
+- leading/trailing `_` removed
+
+Examples:
+
+- `pet-api` -> `PET_API`
+- `OAuth2` -> `OAUTH2`
+
+### API-Level Variables
+
+- `<API>_BASE_URL` - Overrides the API's base URL.
+- `<API>_HEADERS` (JSON object string) - Adds custom headers to all requests.
+
+### API Key Variables
+
+For each API key security scheme defined in the OpenAPI spec, the following environment variables can be set:
+
+- `<API>_<SCHEME>_API_KEY` - The API key value for the specified security scheme.
+
+### OAuth2 Client Credentials Variables
+
+For each OAuth2 client credentials security scheme defined in the OpenAPI spec, the following environment variables can be set:
+
+- `<API>_<SCHEME>_CLIENT_ID` - The client ID for OAuth2.
+- `<API>_<SCHEME>_CLIENT_SECRET` - The client secret for OAuth2.
+- `<API>_<SCHEME>_TOKEN_URL` - The token endpoint URL for OAuth2.
+- `<API>_<SCHEME>_SCOPES` (space-delimited) - The scopes required for the OAuth2 token.
+- `<API>_<SCHEME>_TOKEN_AUTH_METHOD` (`client_secret_basic` or `client_secret_post`) - The authentication method for the token endpoint.
+
+### Precedence
+
+- Base URL: env > config > OpenAPI servers.
+- OAuth token URL: scheme env > config override > OpenAPI flow `tokenUrl`.
+- OAuth scopes: scheme env > config scopes > OpenAPI flow scopes.
+- Headers: config headers + env headers + tool-request headers (later wins), then auth is applied.
+
+## MCP Tools
+
+### `list_apis`
+
+Returns all available APIs.
+
+Input: Nothing
+
+### `list_api_endpoints`
+
+Paginate or search through endpoints in a given APIs.
+
+Input fields:
+
+- required: `apiName`
+- optional: `method`, `tag`, `pathContains`, `search`, `limit`, `cursor`
+
+### `get_api_endpoint`
+
+Returns endpoint metadata including parameters, request body content types, responses, and security requirements.
+
+Input fields: `apiName`, `endpointId`
+
+### `get_api_schema`
+
+Returns the detailed specification of a given schema object.
+
+Input fields: `apiName`, optional `pointer` (JSON Pointer)
+
+### `make_endpoint_request`
+
+Executes an API endpoint request.
+
+Input fields:
+
+- `apiName`
+- `endpointId`
+- `pathParams`
+- `query`
+- `headers`
+- `cookies`
+- `body`
+- `contentType`
+- `accept`
+- `timeoutMs`
+- `retry429` object
+  - `maxRetries`
+  - `baseDelayMs`
+  - `maxDelayMs`
+  - `jitterRatio` (0..1)
+  - `respectRetryAfter`
+
+Output includes:
+
+- `request` metadata with redacted sensitive headers
+- `response` status, headers, and body
+- `timingMs`
+- `authUsed`
+
+## Development
+
+```bash
+npm test
+npm run build
+```
+
+## Notes
+
+- Supports local OpenAPI files only.
+- 429 retries are supported and disabled by default (`maxRetries: 0`).
+- JSON responses are parsed first; non-JSON is returned as text or base64 binary.

package/dist/auth/env.d.ts

@@ -0,0 +1,14 @@
+export interface OAuthClientCredentialsFromEnv {
+    clientId?: string;
+    clientSecret?: string;
+    tokenUrl?: string;
+    scopes?: string[];
+    tokenAuthMethod?: "client_secret_basic" | "client_secret_post";
+}
+export declare function normalizeEnvSegment(value: string): string;
+export declare function apiPrefix(apiName: string): string;
+export declare function schemePrefix(apiName: string, schemeName: string): string;
+export declare function readApiBaseUrl(apiName: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function readApiExtraHeaders(apiName: string, env?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function readApiKeyValue(apiName: string, schemeName: string, env?: NodeJS.ProcessEnv): string | undefined;
+export declare function readOAuthClientCredentials(apiName: string, schemeName: string, env?: NodeJS.ProcessEnv): OAuthClientCredentialsFromEnv;

package/dist/auth/env.js

@@ -0,0 +1,64 @@
+import { OpenApiMcpError } from "../errors.js";
+export function normalizeEnvSegment(value) {
+    return value
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^_+|_+$/g, "");
+}
+export function apiPrefix(apiName) {
+    return normalizeEnvSegment(apiName);
+}
+export function schemePrefix(apiName, schemeName) {
+    return `${apiPrefix(apiName)}_${normalizeEnvSegment(schemeName)}`;
+}
+export function readApiBaseUrl(apiName, env = process.env) {
+    return env[`${apiPrefix(apiName)}_BASE_URL`];
+}
+export function readApiExtraHeaders(apiName, env = process.env) {
+    const raw = env[`${apiPrefix(apiName)}_HEADERS`];
+    if (!raw) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new OpenApiMcpError("CONFIG_ERROR", `Invalid JSON in ${apiPrefix(apiName)}_HEADERS`, { value: raw });
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new OpenApiMcpError("CONFIG_ERROR", `${apiPrefix(apiName)}_HEADERS must be a JSON object`);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        if (typeof value !== "string") {
+            throw new OpenApiMcpError("CONFIG_ERROR", `${apiPrefix(apiName)}_HEADERS values must be strings`, { key });
+        }
+        out[key] = value;
+    }
+    return out;
+}
+export function readApiKeyValue(apiName, schemeName, env = process.env) {
+    return env[`${schemePrefix(apiName, schemeName)}_API_KEY`];
+}
+export function readOAuthClientCredentials(apiName, schemeName, env = process.env) {
+    const prefix = schemePrefix(apiName, schemeName);
+    const scopesRaw = env[`${prefix}_SCOPES`];
+    const tokenAuthMethodRaw = env[`${prefix}_TOKEN_AUTH_METHOD`];
+    let tokenAuthMethod;
+    if (tokenAuthMethodRaw === "client_secret_basic" || tokenAuthMethodRaw === "client_secret_post") {
+        tokenAuthMethod = tokenAuthMethodRaw;
+    }
+    else if (tokenAuthMethodRaw) {
+        throw new OpenApiMcpError("CONFIG_ERROR", `Invalid ${prefix}_TOKEN_AUTH_METHOD value`, { value: tokenAuthMethodRaw });
+    }
+    return {
+        clientId: env[`${prefix}_CLIENT_ID`],
+        clientSecret: env[`${prefix}_CLIENT_SECRET`],
+        tokenUrl: env[`${prefix}_TOKEN_URL`],
+        scopes: scopesRaw ? scopesRaw.split(/\s+/).filter(Boolean) : undefined,
+        tokenAuthMethod
+    };
+}
+//# sourceMappingURL=env.js.map

package/dist/auth/env.js.map

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

package/dist/auth/oauthClient.d.ts

@@ -0,0 +1,12 @@
+export interface OAuthTokenRequest {
+    cacheKey: string;
+    tokenUrl: string;
+    clientId: string;
+    clientSecret: string;
+    scopes: string[];
+    tokenEndpointAuthMethod: "client_secret_basic" | "client_secret_post";
+}
+export declare class OAuthClient {
+    private readonly cache;
+    getClientCredentialsToken(request: OAuthTokenRequest): Promise<string>;
+}

package/dist/auth/oauthClient.js

@@ -0,0 +1,55 @@
+import * as oauth from "oauth4webapi";
+import { OpenApiMcpError } from "../errors.js";
+const TOKEN_EXPIRY_SAFETY_MS = 60_000;
+export class OAuthClient {
+    cache = new Map();
+    async getClientCredentialsToken(request) {
+        const cached = this.cache.get(request.cacheKey);
+        if (cached && cached.expiresAtMs - Date.now() > TOKEN_EXPIRY_SAFETY_MS) {
+            return cached.accessToken;
+        }
+        const as = {
+            issuer: new URL(request.tokenUrl).origin,
+            token_endpoint: request.tokenUrl
+        };
+        const client = {
+            client_id: request.clientId
+        };
+        const clientAuth = request.tokenEndpointAuthMethod === "client_secret_post"
+            ? oauth.ClientSecretPost(request.clientSecret)
+            : oauth.ClientSecretBasic(request.clientSecret);
+        const parameters = new URLSearchParams();
+        if (request.scopes.length > 0) {
+            parameters.set("scope", request.scopes.join(" "));
+        }
+        try {
+            const tokenResponse = await oauth.clientCredentialsGrantRequest(as, client, clientAuth, parameters);
+            const tokenResult = await oauth.processClientCredentialsResponse(as, client, tokenResponse);
+            this.cache.set(request.cacheKey, {
+                accessToken: tokenResult.access_token,
+                expiresAtMs: Date.now() + Math.max(tokenResult.expires_in ?? 3600, 1) * 1000
+            });
+            return tokenResult.access_token;
+        }
+        catch (error) {
+            if (error instanceof oauth.ResponseBodyError) {
+                throw new OpenApiMcpError("AUTH_ERROR", "OAuth2 token request failed", {
+                    tokenUrl: request.tokenUrl,
+                    oauthError: error.cause
+                });
+            }
+            if (error instanceof oauth.OperationProcessingError) {
+                throw new OpenApiMcpError("AUTH_ERROR", "OAuth2 operation failed", {
+                    tokenUrl: request.tokenUrl,
+                    code: error.code,
+                    cause: error.message
+                });
+            }
+            throw new OpenApiMcpError("AUTH_ERROR", "OAuth2 token request failed", {
+                tokenUrl: request.tokenUrl,
+                cause: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+}
+//# sourceMappingURL=oauthClient.js.map

package/dist/auth/oauthClient.js.map

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

package/dist/auth/resolveAuth.d.ts

@@ -0,0 +1,10 @@
+import { OAuthClient } from "./oauthClient.js";
+import type { EndpointDefinition, LoadedApi, ResolvedAuthResult } from "../types.js";
+interface ResolveAuthInput {
+    api: LoadedApi;
+    endpoint: EndpointDefinition;
+    oauthClient: OAuthClient;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function resolveAuth({ api, endpoint, oauthClient, env }: ResolveAuthInput): Promise<ResolvedAuthResult>;
+export {};

package/dist/auth/resolveAuth.js

@@ -0,0 +1,118 @@
+import { readApiKeyValue, readOAuthClientCredentials, schemePrefix } from "./env.js";
+import { OpenApiMcpError } from "../errors.js";
+export async function resolveAuth({ api, endpoint, oauthClient, env = process.env }) {
+    const requirements = endpoint.operation.security ?? api.schema.security ?? [];
+    if (!requirements || requirements.length === 0) {
+        return { authUsed: [], schemes: [] };
+    }
+    const securitySchemes = api.schema.components?.securitySchemes ?? {};
+    const failures = [];
+    for (const requirementObject of requirements) {
+        if (Object.keys(requirementObject).length === 0) {
+            return { authUsed: [], schemes: [] };
+        }
+        const resolved = [];
+        const missingEnv = new Set();
+        let failedReason;
+        for (const [schemeName, requestedScopes] of Object.entries(requirementObject)) {
+            const scheme = securitySchemes[schemeName];
+            if (!scheme || "$ref" in scheme) {
+                failedReason = `Security scheme '${schemeName}' not found or unresolved`;
+                break;
+            }
+            if (scheme.type === "apiKey") {
+                const value = readApiKeyValue(api.config.name, schemeName, env);
+                if (!value) {
+                    missingEnv.add(`${schemePrefix(api.config.name, schemeName)}_API_KEY`);
+                    failedReason = `Missing API key for scheme '${schemeName}'`;
+                    break;
+                }
+                resolved.push({
+                    type: "apiKey",
+                    schemeName,
+                    in: scheme.in,
+                    name: scheme.name,
+                    value
+                });
+                continue;
+            }
+            if (scheme.type === "oauth2") {
+                const flow = scheme.flows.clientCredentials;
+                if (!flow) {
+                    failedReason = `Scheme '${schemeName}' does not support clientCredentials flow`;
+                    break;
+                }
+                const fromEnv = readOAuthClientCredentials(api.config.name, schemeName, env);
+                const clientId = fromEnv.clientId;
+                const clientSecret = fromEnv.clientSecret;
+                if (!clientId || !clientSecret) {
+                    missingEnv.add(`${schemePrefix(api.config.name, schemeName)}_CLIENT_ID`);
+                    missingEnv.add(`${schemePrefix(api.config.name, schemeName)}_CLIENT_SECRET`);
+                    failedReason = `Missing OAuth2 client credentials for '${schemeName}'`;
+                    break;
+                }
+                const tokenUrl = fromEnv.tokenUrl ?? api.config.oauth2?.tokenUrlOverride ?? flow.tokenUrl;
+                if (!tokenUrl) {
+                    failedReason = `No OAuth2 token URL resolved for scheme '${schemeName}'`;
+                    break;
+                }
+                const tokenEndpointAuthMethod = fromEnv.tokenAuthMethod ??
+                    api.config.oauth2?.tokenEndpointAuthMethod ??
+                    "client_secret_basic";
+                const scopes = resolveScopes(requestedScopes, fromEnv.scopes, api.config.oauth2?.scopes, flow);
+                const cacheKey = [
+                    api.config.name,
+                    schemeName,
+                    clientId,
+                    tokenUrl,
+                    tokenEndpointAuthMethod,
+                    scopes.sort().join(",")
+                ].join("|");
+                const token = await oauthClient.getClientCredentialsToken({
+                    cacheKey,
+                    tokenUrl,
+                    clientId,
+                    clientSecret,
+                    scopes,
+                    tokenEndpointAuthMethod
+                });
+                resolved.push({
+                    type: "oauth2",
+                    schemeName,
+                    token
+                });
+                continue;
+            }
+            failedReason = `Unsupported security scheme type '${scheme.type}' for '${schemeName}'`;
+            break;
+        }
+        if (!failedReason) {
+            return {
+                authUsed: resolved.map((item) => item.schemeName),
+                schemes: resolved
+            };
+        }
+        failures.push({
+            requirement: Object.keys(requirementObject),
+            reason: failedReason,
+            missingEnv: [...missingEnv]
+        });
+    }
+    throw new OpenApiMcpError("AUTH_ERROR", `Could not resolve authentication for '${api.config.name}'`, {
+        endpointId: endpoint.endpointId,
+        failures
+    });
+}
+function resolveScopes(requestedScopes, envScopes, configScopes, flow) {
+    if (envScopes && envScopes.length > 0) {
+        return envScopes;
+    }
+    if (configScopes && configScopes.length > 0) {
+        return configScopes;
+    }
+    if (requestedScopes && requestedScopes.length > 0) {
+        return requestedScopes;
+    }
+    return Object.keys(flow.scopes ?? {});
+}
+//# sourceMappingURL=resolveAuth.js.map

package/dist/auth/resolveAuth.js.map

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

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function runCli(argv?: string[]): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+import { loadConfig } from "./config/loadConfig.js";
+import { OAuthClient } from "./auth/oauthClient.js";
+import { OpenApiMcpError } from "./errors.js";
+import { startMcpServer } from "./mcp/server.js";
+import { loadApiRegistry } from "./openapi/loadSpec.js";
+function parseConfigPath(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === "--config") {
+            const value = argv[i + 1];
+            if (!value) {
+                throw new OpenApiMcpError("CONFIG_ERROR", "Missing value for --config");
+            }
+            return value;
+        }
+    }
+    throw new OpenApiMcpError("CONFIG_ERROR", "Missing required argument --config");
+}
+export async function runCli(argv = process.argv.slice(2)) {
+    const configPath = parseConfigPath(argv);
+    const config = await loadConfig(configPath);
+    const registry = await loadApiRegistry(config, process.env);
+    console.error(`[openapi-mcp] loaded ${registry.byName.size} API(s)`);
+    for (const api of registry.byName.values()) {
+        console.error(`[openapi-mcp] api=${api.config.name} endpoints=${api.endpoints.length} authSchemes=${api.authSchemeNames.join(",")}`);
+    }
+    await startMcpServer({
+        registry,
+        oauthClient: new OAuthClient(),
+        env: process.env
+    });
+}
+runCli().catch((error) => {
+    if (error instanceof OpenApiMcpError) {
+        console.error(JSON.stringify({
+            code: error.code,
+            message: error.message,
+            details: error.details
+        }, null, 2));
+        process.exit(1);
+    }
+    if (error instanceof Error) {
+        console.error(error.stack ?? error.message);
+    }
+    else {
+        console.error(String(error));
+    }
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExD,SAAS,eAAe,CAAC,IAAc;IACrC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,4BAA4B,CAAC,CAAC;YAC1E,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,MAAM,IAAI,eAAe,CAAC,cAAc,EAAE,oCAAoC,CAAC,CAAC;AAClF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACvD,MAAM,UAAU,GAAG,eAAe,CAAC,IAAI,CAAC,CAAC;IACzC,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAE5D,OAAO,CAAC,KAAK,CAAC,wBAAwB,QAAQ,CAAC,MAAM,CAAC,IAAI,SAAS,CAAC,CAAC;IACrE,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;QAC3C,OAAO,CAAC,KAAK,CACX,qBAAqB,GAAG,CAAC,MAAM,CAAC,IAAI,cAAc,GAAG,CAAC,SAAS,CAAC,MAAM,gBAAgB,GAAG,CAAC,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CACtH,CAAC;IACJ,CAAC;IAED,MAAM,cAAc,CAAC;QACnB,QAAQ;QACR,WAAW,EAAE,IAAI,WAAW,EAAE;QAC9B,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;AACL,CAAC;AAED,MAAM,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAChC,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;QACrC,OAAO,CAAC,KAAK,CACX,IAAI,CAAC,SAAS,CACZ;YACE,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO;SACvB,EACD,IAAI,EACJ,CAAC,CACF,CACF,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/config/loadConfig.d.ts

@@ -0,0 +1,2 @@
+import type { RootConfig } from "../types.js";
+export declare function loadConfig(configPath: string): Promise<RootConfig>;