@powerduck/openapi-mcp-server 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,374 @@
+import { Document, ParameterObject, OperationObject, PathItemObject } from '@scalar/openapi-types/3.2';
+import { Tool, GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
+import { P as ParameterLocation, B as BodyEncoding, G as GeneratedPrompt, a as GeneratedResource, R as ResourceContentItem, E as ExecutionContext, b as ProtocolHint } from './admin-server-B4fQWUnc.js';
+export { A as AdminStatus, c as AppState, d as BODY_ENCODINGS, e as GeneratedTool, L as LOG_DIRECTIONS, f as LOG_LEVELS, g as LogDirection, h as LogLevel, i as LogQueryOptions, j as LogQueryResult, k as LoggedQuery, M as ManagedServiceRecord, l as PARAMETER_LOCATIONS, m as PROTOCOL_HINTS, n as PersistedState, o as PromptMessageShape, p as RequestLogEntry, q as ResolvedPrompt, S as SERVICE_STATUSES, r as SPEC_SOURCES, s as SecurityContext, t as ServerConfig, u as ServiceEndpointInfo, v as ServiceStatus, w as SpecIssue, x as SpecSource, T as TRANSPORT_MODES, y as TransportMode, z as isBodyEncoding, C as isParameterLocation, D as isPlainRecord, F as isProtocolHint, H as isServiceStatus, I as isSpecSource, J as startAdminServer } from './admin-server-B4fQWUnc.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import express, { RequestHandler } from 'express';
+import 'node:http';
+
+declare function loadOpenApiSpec(filePath: string): Promise<Document>;
+declare function parseSpecContent(rawText: string, isYaml: boolean): Promise<Document>;
+
+/**
+ * A parameter validated to carry the fields this library relies on.
+ *
+ * The upstream `ParameterObject` type is a union (schema form vs. content
+ * form), so it is normalized into a single permissive shape after runtime
+ * validation.
+ */
+interface NormalizedParameter {
+    name: string;
+    in: ParameterLocation;
+    required: boolean;
+    description?: string | undefined;
+    deprecated?: boolean | undefined;
+    style?: string | undefined;
+    explode?: boolean | undefined;
+    allowReserved?: boolean | undefined;
+    allowEmptyValue?: boolean | undefined;
+    /** Present when the parameter uses the `schema` form. */
+    schema?: Record<string, unknown> | undefined;
+    /** Present when the parameter uses the `content` form. */
+    content?: Record<string, unknown> | undefined;
+    /** Media type selected from `content`, when the content form is used. */
+    contentMediaType?: string | undefined;
+    /** True when the transport owns this value and it must not be exposed. */
+    reserved?: boolean | undefined;
+    /** The original object, kept for callers that need untouched data. */
+    raw: ParameterObject;
+}
+/** A single resolved operation together with its owning path item. */
+interface ResolvedOperation {
+    path: string;
+    /**
+     * Lower-cased HTTP method. Normally a {@link HttpMethod}, but may be any
+     * token when it originates from the OpenAPI 3.2 `additionalOperations` map.
+     */
+    method: string;
+    operation: OperationObject;
+    pathItem: PathItemObject;
+    /** Guaranteed non-empty and unique across the document. */
+    operationId: string;
+    /** True when the id was synthesized because the document omitted it. */
+    operationIdGenerated: boolean;
+    /** False when the method came from `additionalOperations`. */
+    isStandardMethod: boolean;
+}
+/**
+ * Public alias kept for library consumers. `ResolvedOperation` is the internal
+ * name; both refer to the exact same shape.
+ */
+type OperationEntry = ResolvedOperation;
+/** Codes attached to non-fatal problems found while walking a document. */
+type SpecWalkIssueCode = "invalid-paths-object" | "invalid-path-template" | "invalid-path-item" | "invalid-operation" | "invalid-parameter" | "unsupported-parameter-location" | "reserved-parameter" | "unresolved-ref" | "duplicate-operation-id" | "generated-operation-id" | "truncated-operation-id";
+/** Non-fatal issues collected while walking the document. */
+interface SpecWalkIssue {
+    path: string;
+    method?: string | undefined;
+    code: SpecWalkIssueCode;
+    message: string;
+}
+/**
+ * Extracts the `{name}` template variables from a path template.
+ * Duplicates are collapsed; order follows first appearance.
+ */
+declare function extractPathTemplateVariables(pathTemplate: string): string[];
+/**
+ * Normalizes a raw parameter entry. Returns null when the entry is unusable,
+ * which happens for unresolved references, missing `name` / `in`, unsupported
+ * locations, or a malformed schema/content combination.
+ */
+declare function normalizeParameter(candidate: unknown): NormalizedParameter | null;
+/**
+ * Effective style for a parameter, applying the defaults mandated by the spec
+ * when the document does not state one explicitly.
+ */
+declare function effectiveStyle(parameter: NormalizedParameter): string;
+/** Effective explode flag. The spec default is true only when style is `form`. */
+declare function effectiveExplode(parameter: NormalizedParameter): boolean;
+/**
+ * Merges path-item level parameters with operation level parameters.
+ *
+ * Per the specification the merge key is the pair (name, in), and an operation
+ * level entry overrides an inherited one. Entries that cannot be normalized are
+ * dropped and reported through `issues` instead of silently corrupting output.
+ */
+declare function collectOperationParameters(pathItem: PathItemObject | undefined, operation: OperationObject | undefined, issues?: SpecWalkIssue[], context?: {
+    path: string;
+    method: string;
+}): NormalizedParameter[];
+/**
+ * Builds a deterministic, identifier-safe fallback name for an operation that
+ * omits `operationId`. The result is stable across runs for the same document,
+ * which matters because tool names are persisted by clients.
+ */
+declare function synthesizeOperationId(method: string, pathTemplate: string): string;
+/**
+ * Ensures a candidate name is unique within `taken` by appending a numeric
+ * suffix, and registers the result. The original name is returned untouched
+ * when it is already free.
+ */
+declare function ensureUniqueName(candidate: string, taken: Set<string>): string;
+/**
+ * Walks every operation in the document.
+ *
+ * Guarantees for consumers:
+ *  - only operation keys are yielded, never path item metadata;
+ *  - OpenAPI 3.2 `additionalOperations` entries are included, flagged via
+ *    `isStandardMethod: false`;
+ *  - malformed path items and operations are skipped, never thrown on;
+ *  - `operationId` is always a non-empty string, unique across the document,
+ *    and no longer than {@link MAX_GENERATED_NAME_LENGTH}.
+ *
+ * Non-fatal problems are appended to `issues` when the caller supplies an array.
+ */
+declare function iterateOperations(spec: Document | null | undefined, issues?: SpecWalkIssue[]): Generator<ResolvedOperation>;
+/**
+ * Locates an operation by id, in O(1) after the first call.
+ *
+ * The effective id produced by {@link iterateOperations} always wins, because
+ * that is the name the tool generator exposes and therefore the only value a
+ * client can legitimately send. A declared id is consulted only as a fallback,
+ * and only when it is unambiguous — otherwise a document mixing declared and
+ * synthesized ids could route a call to the wrong endpoint without any error.
+ *
+ * Returns null instead of throwing: an unknown id is a caller-level condition
+ * (bad tool name), not a malformed document.
+ */
+declare function findOperationById(spec: Document | null | undefined, operationId: string): OperationEntry | null;
+/** Describes one operationId claimed by more than one operation. */
+interface DuplicateOperationId {
+    operationId: string;
+    occurrences: Array<{
+        method: string;
+        path: string;
+    }>;
+}
+/**
+ * Reports every operationId declared more than once. Synthesized ids are
+ * excluded because they are derived from method + path and are unique by
+ * construction; only author-declared ids can collide.
+ *
+ * This is a validation helper, not part of the generation path — tool naming
+ * already de-duplicates via {@link ensureUniqueName}, so a duplicate id
+ * degrades the tool names rather than breaking the server. Use it to warn the
+ * operator.
+ */
+declare function findDuplicateOperationIds(spec: Document | null | undefined): DuplicateOperationId[];
+/**
+ * Throws when the document declares the same operationId twice. Kept as a
+ * separate strict entry point so library consumers can choose between failing
+ * fast at load time and merely surfacing a warning.
+ */
+declare function assertUniqueOperationIds(spec: Document | null | undefined): void;
+
+interface ArgumentBinding {
+    key: string;
+    name: string;
+    in: "path" | "query" | "header" | "cookie";
+    parameter: NormalizedParameter;
+}
+interface OmittedParameter {
+    name: string;
+    in: string;
+    reason: string;
+}
+interface ToolBinding {
+    toolName: string;
+    path: string;
+    pathItem: PathItemObject;
+    method: string;
+    isStandardMethod: boolean;
+    operation: OperationObject;
+    arguments: ArgumentBinding[];
+    bodyKey: string | null;
+    bodyEncoding: BodyEncoding | null;
+    bodyMediaType: string | null;
+    bodyRequired: boolean;
+    omittedParameters: OmittedParameter[];
+    fullySupported: boolean;
+    degradationReasons: string[];
+    usageNotes: string[];
+}
+interface GeneratedTool {
+    tool: Tool;
+    binding: ToolBinding;
+}
+interface GenerateToolsResult {
+    tools: Tool[];
+    bindings: ToolBinding[];
+    issues: SpecWalkIssue[];
+}
+declare function generateToolsDetailed(spec: Document | null | undefined): GenerateToolsResult;
+declare function generateTools(spec: Document | null | undefined): Tool[];
+declare function getBindingIndex(spec: Document | null | undefined): Map<string, ToolBinding>;
+declare const buildBindingIndex: typeof getBindingIndex;
+
+/** List every prompt exposed for the given specification. */
+declare function generatePrompts(spec: Document): GeneratedPrompt[];
+/**
+ * Resolve a prompt by name. Returns null when the prompt is unknown so the
+ * transport layer can answer with the correct JSON-RPC error.
+ */
+declare function resolvePrompt(spec: Document, name: string, args?: Record<string, unknown>): GetPromptResult | null;
+
+declare function generateResources(spec: Document): GeneratedResource[];
+declare function readResource(spec: Document, uri: string): ResourceContentItem | null;
+
+interface ToolCallResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, unknown>;
+    data: unknown;
+    truncated: boolean;
+    url: string;
+    method: string;
+    durationMs: number;
+    /** Ties the request and response log entries together. */
+    correlationId: string;
+}
+/**
+ * Executes one generated tool against the upstream API.
+ *
+ * A non-2xx upstream response is returned as data rather than thrown: the model
+ * must be able to read the status and body to decide what to do next. Only
+ * transport-level failures throw.
+ */
+declare function executeToolCall(spec: Document, toolName: string, args: Record<string, unknown> | undefined, context?: ExecutionContext): Promise<ToolCallResult>;
+
+/** A parameter or argument that was deliberately not sent, with the reason. */
+interface DroppedArgument {
+    key: string;
+    reason: string;
+}
+interface BuiltRequest {
+    /**
+     * Absolute URL without a query string. The query is kept separate so the
+     * executor can log it in a structured form and so encoding happens exactly
+     * once, inside `query`.
+     */
+    url: string;
+    /**
+     * Fully-formed query parameters. `URLSearchParams` is the only shape that can
+     * represent the repeated keys produced by an exploded array — the default for
+     * query parameters — and it applies percent-encoding once on `toString()`.
+     */
+    query: URLSearchParams;
+    headers: Record<string, string>;
+    body: unknown;
+    /** Reported so the executor can surface silently ignored arguments in a log. */
+    dropped: DroppedArgument[];
+}
+declare function buildRequest(baseUrl: string, templatePath: string, pathItem: PathItemObject, operation: OperationObject, args: Record<string, unknown>, binding?: ToolBinding): BuiltRequest;
+
+/** Returns the active document, or null when no service is running. */
+type SpecProvider = () => Document | null;
+/** Returns the upstream execution context for the current call. */
+type ContextProvider = () => ExecutionContext;
+interface BuildMcpServerOptions {
+    protocol?: ProtocolHint | undefined;
+    /** Advertised server name. Clients may display this to end users. */
+    name?: string | undefined;
+    /** Advertised server version. */
+    version?: string | undefined;
+    /**
+     * Maximum entries returned by a single list request. Large documents must be
+     * paginated, otherwise a single response can exceed what the transport (and
+     * some clients) will accept.
+     */
+    pageSize?: number | undefined;
+    /** Human-readable usage hint surfaced through `instructions`. */
+    instructions?: string | undefined;
+}
+/**
+ * Builds one MCP server instance.
+ *
+ * A fresh instance is created per transport session so that per-session state
+ * (client capabilities, negotiated protocol version, in-flight requests) is
+ * never shared. The document itself is read through `specProvider` on every
+ * request rather than captured, so a session always reflects the currently
+ * running service instead of a stale snapshot.
+ */
+declare function buildMcpServer(specProvider: SpecProvider, contextProvider?: ContextProvider, options?: BuildMcpServerOptions): Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+        progressToken?: string | number | undefined;
+        "io.modelcontextprotocol/related-task"?: {
+            taskId: string;
+        } | undefined;
+    } | undefined;
+}>;
+
+interface StdioServerHandle {
+    /** Resolves when the peer closes stdin or {@link close} is called. */
+    closed: Promise<void>;
+    close(): Promise<void>;
+}
+interface StartStdioServerOptions {
+    /**
+     * Install process signal handlers so the transport is shut down cleanly.
+     * Defaults to true, which is what a CLI entry point wants; a host embedding
+     * this in a larger process should pass false and drive `close()` itself.
+     */
+    handleSignals?: boolean;
+}
+/**
+ * Serves a single specification over stdio.
+ *
+ * The specification is captured once: unlike the HTTP transports there is no
+ * admin surface able to swap it, and a stdio client holds exactly one session
+ * whose tool list it caches after `initialize`.
+ */
+declare function startStdioServer(spec: Document, context?: ExecutionContext, options?: StartStdioServerOptions): Promise<StdioServerHandle>;
+
+/**
+ * Backwards-compatible alias for the previous export name.
+ *
+ * @deprecated Use {@link attachMcpRoutes}. This wrapper keeps the old
+ * positional signature working but no longer serves the legacy SSE stream at
+ * `GET /mcp`, because that path now belongs to the Streamable HTTP transport.
+ * It also drops the sweeper handle, so callers cannot fully shut down; migrate.
+ */
+declare function attachSseRoutes(app: express.Express, specProvider: SpecProvider, contextProvider: ContextProvider, routeGuard?: express.RequestHandler): {
+    activeSessionCount: () => number;
+    closeAll: () => Promise<void>;
+};
+
+/**
+ * Guards the admin API with a shared secret.
+ *
+ * Passing `undefined` disables the guard, which is the documented default for
+ * loopback-only use. An empty or whitespace-only string is rejected instead of
+ * being treated as "disabled": that case almost always means an environment
+ * variable was set but never populated, and silently serving an unprotected
+ * admin API to an operator who believes it is locked down is the worst possible
+ * outcome.
+ */
+declare function createAuthMiddleware(apiKey?: string): RequestHandler;
+
+export { BodyEncoding, type ContextProvider, type DuplicateOperationId, ExecutionContext, GeneratedPrompt, GeneratedResource, type GeneratedTool as GeneratedToolWithBinding, type OperationEntry, ParameterLocation, ProtocolHint, ResourceContentItem, type SpecProvider, type ToolBinding, assertUniqueOperationIds, attachSseRoutes, buildBindingIndex, buildMcpServer, buildRequest, collectOperationParameters, createAuthMiddleware, effectiveExplode, effectiveStyle, ensureUniqueName, executeToolCall, extractPathTemplateVariables, findDuplicateOperationIds, findOperationById, generatePrompts, generateResources, generateTools, generateToolsDetailed, iterateOperations, loadOpenApiSpec, normalizeParameter, parseSpecContent, readResource, resolvePrompt, startStdioServer, synthesizeOperationId };