@powerduck/openapi-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,116 @@
+A production-oriented TypeScript library and runtime that converts OpenAPI documents into MCP services.
+
+## Features
+
+- Tools generated from OpenAPI operations
+- Prompts generated from API metadata and operations
+- Resources generated from the OpenAPI catalog
+- HTTP and STDIO MCP transports
+- Admin Web UI
+- Persistent runtime state
+- Stronger validation and safer request execution
+- Production-oriented structure for future SaaS evolution
+
+## Install
+
+```bash
+npm install
+```
+
+## Build
+
+```bash
+npm run build
+```
+
+## Start web runtime
+
+```bash
+npm run start -- serve --port 3000 --host 127.0.0.1
+```
+
+## Start STDIO runtime
+
+```bash
+node dist/cli.js serve --transport stdio --spec ./openapi.yaml
+```
+
+## Demo
+
+```bash
+npm run demo
+```
+
+## Library usage
+
+```ts
+import {
+  parseSpecContent,
+  generateTools,
+  generatePrompts,
+  generateResources,
+  buildMcpServer,
+} from "openapi-mcp-production";
+```
+
+## CLI usage
+
+### Web mode
+
+```bash
+openapi-mcp serve \
+  --transport web \
+  --port 3000 \
+  --host 127.0.0.1 \
+  --api-key your-admin-key
+```
+
+### STDIO mode
+
+```bash
+openapi-mcp serve \
+  --transport stdio \
+  --spec ./openapi.yaml \
+  --base-url https://api.example.com
+```
+
+## Production notes
+
+This version is production-oriented, but you should still add the following for SaaS deployment:
+
+- tenant isolation
+- database-backed project registry
+- rate limits
+- audit logs
+- RBAC
+- secure secret storage
+- upstream host allowlists
+- comprehensive test suites
+- full OpenAPI parameter serialization coverage
+- full requestBody content negotiation support
+
+## Project structure
+
+- `src/core`: spec parsing, operation traversal, tool generation, request building, execution
+- `src/mcp`: MCP server creation and transports
+- `src/registry`: prompts and resources registries
+- `src/runtime`: runtime service registry
+- `src/server`: admin HTTP server
+- `src/webui`: browser UI
+- `src/config`: persistence helpers
+
+## Web UI
+
+The UI supports:
+
+- upload and paste OpenAPI documents
+- view tools, prompts, and resources
+- inspect runtime services
+- stop services
+- basic MCP debugging hints
+- SSE endpoint discovery
+- STDIO tooltip guidance
+
+## Important implementation policy
+
+All source comments are written in American English.

package/dist/admin-server-B4fQWUnc.d.cts

@@ -0,0 +1,313 @@
+import { Express } from 'express';
+import { Server } from 'node:http';
+import { Document } from '@scalar/openapi-types/3.2';
+import { Prompt, PromptArgument, Resource, Tool } from '@modelcontextprotocol/sdk/types.js';
+
+/** How the MCP server is exposed to a client. */
+declare const TRANSPORT_MODES: readonly ["stdio", "web"];
+type TransportMode = (typeof TRANSPORT_MODES)[number];
+/** Where the currently loaded specification came from. */
+declare const SPEC_SOURCES: readonly ["startup-file", "upload", "paste", "runtime"];
+type SpecSource = (typeof SPEC_SOURCES)[number];
+/** Lifecycle state of a managed MCP service. */
+declare const SERVICE_STATUSES: readonly ["running", "stopped", "error"];
+type ServiceStatus = (typeof SERVICE_STATUSES)[number];
+/**
+ * Wire protocol a log entry or session belongs to.
+ *
+ * `streamable-http` is the transport introduced by the 2025 protocol revision
+ * and is preferred for new clients; `sse` remains for backward compatibility
+ * with clients pinned to the legacy HTTP+SSE transport.
+ */
+declare const PROTOCOL_HINTS: readonly ["streamable-http", "sse", "stdio"];
+type ProtocolHint = (typeof PROTOCOL_HINTS)[number];
+/** Direction of a recorded log entry relative to this process. */
+declare const LOG_DIRECTIONS: readonly ["request", "response", "internal"];
+type LogDirection = (typeof LOG_DIRECTIONS)[number];
+/** Severity used for filtering and colour-coding in the web console. */
+declare const LOG_LEVELS: readonly ["debug", "info", "warn", "error"];
+type LogLevel = (typeof LOG_LEVELS)[number];
+/** OpenAPI parameter locations supported by the request builder. */
+declare const PARAMETER_LOCATIONS: readonly ["path", "query", "header", "cookie"];
+type ParameterLocation = (typeof PARAMETER_LOCATIONS)[number];
+/** Request body serialization strategies supported by the HTTP executor. */
+declare const BODY_ENCODINGS: readonly ["json", "form-urlencoded", "multipart", "text", "binary"];
+type BodyEncoding = (typeof BODY_ENCODINGS)[number];
+/** Narrow an untrusted value to a {@link SpecSource}. */
+declare function isSpecSource(value: unknown): value is SpecSource;
+/** Narrow an untrusted value to a {@link ServiceStatus}. */
+declare function isServiceStatus(value: unknown): value is ServiceStatus;
+/** Narrow an untrusted value to a {@link ProtocolHint}. */
+declare function isProtocolHint(value: unknown): value is ProtocolHint;
+/** Narrow an untrusted value to a {@link ParameterLocation}. */
+declare function isParameterLocation(value: unknown): value is ParameterLocation;
+/** Narrow an untrusted value to a {@link BodyEncoding}. */
+declare function isBodyEncoding(value: unknown): value is BodyEncoding;
+/** True for plain, non-array objects usable as an argument bag. */
+declare function isPlainRecord(value: unknown): value is Record<string, unknown>;
+/**
+ * Options accepted when starting the bundled web console and HTTP transport.
+ *
+ * Every field is optional except {@link ServerConfig.port} so that embedders can
+ * start a usable server with a single value.
+ */
+interface ServerConfig {
+    /** TCP port to bind. Must be an integer in the range 0-65535. */
+    port: number;
+    /** Interface to bind. Defaults to `127.0.0.1` to avoid accidental exposure. */
+    host?: string | undefined;
+    /** Shared secret required by the admin API and HTTP transport when set. */
+    apiKey?: string | undefined;
+    /** Path to a specification loaded once at startup. */
+    specPath?: string | undefined;
+    /** Overrides the upstream base URL derived from `servers[0].url`. */
+    baseUrlOverride?: string | undefined;
+    /** Headers merged into every upstream request. */
+    upstreamHeaders?: Record<string, string> | undefined;
+    /** Per-request upstream timeout in milliseconds. */
+    requestTimeoutMs?: number | undefined;
+    /** Persist the loaded specification across restarts. Defaults to true. */
+    persistState?: boolean | undefined;
+    /** Location of the persisted state file. */
+    stateFilePath?: string | undefined;
+    /** Allowed CORS origins. Empty or omitted disables cross-origin access. */
+    allowedOrigins?: string[] | undefined;
+    allowedHosts?: string[];
+    /** Maximum number of in-memory log entries retained. */
+    maxLogEntries?: number | undefined;
+    /** Redact sensitive header values before logging. Defaults to true. */
+    redactSensitiveHeaders?: boolean | undefined;
+    /** Additional header names to redact, in addition to the built-in list. */
+    redactHeaderNames?: string[] | undefined;
+    /** Credentials forwarded to the upstream API for every tool call. */
+    security?: SecurityContext | undefined;
+}
+/** Credentials applied to upstream requests. */
+interface SecurityContext {
+    /** Sent as `Authorization: Bearer <token>`. */
+    bearerToken?: string | undefined;
+    /** Sent as `Authorization: Basic <base64>`. */
+    basicAuth?: {
+        username: string;
+        password: string;
+    } | undefined;
+    /** Header-name to value pairs for API-key schemes. */
+    apiKeys?: Record<string, string> | undefined;
+}
+/** Mutable runtime state of the loaded specification. */
+interface AppState {
+    spec: Document | null;
+    baseUrlOverride?: string | undefined;
+    specSource?: SpecSource | undefined;
+}
+/** Shape of the on-disk state file. All fields are untrusted when read back. */
+interface PersistedState {
+    specRaw?: string | undefined;
+    specIsYaml?: boolean | undefined;
+    baseUrlOverride?: string | undefined;
+    /** Schema version, allowing forward-compatible migrations. */
+    stateVersion?: number | undefined;
+    savedAt?: string | undefined;
+}
+/** Per-call context handed to the request builder and HTTP executor. */
+interface ExecutionContext {
+    baseUrlOverride?: string | undefined;
+    upstreamHeaders?: Record<string, string> | undefined;
+    requestTimeoutMs?: number | undefined;
+    security?: SecurityContext | undefined;
+    /** Correlates every log entry produced by one logical tool invocation. */
+    correlationId?: string | undefined;
+    /** Transport that initiated the call, recorded on emitted log entries. */
+    protocol?: ProtocolHint | undefined;
+    /** Receives request and response log entries. Must never throw. */
+    onLog?: ((entry: RequestLogEntry) => void) | undefined;
+    signal?: AbortSignal | undefined;
+}
+/** Endpoints a client can use to reach a managed service. */
+interface ServiceEndpointInfo {
+    /** Legacy HTTP+SSE stream path. */
+    sse: string;
+    /** Legacy HTTP+SSE message-post path. */
+    messages: string;
+    /** Whether the service can also be launched over stdio by the CLI. */
+    stdioSupported: boolean;
+    /** Streamable HTTP endpoint path, when the transport is mounted. */
+    streamableHttp?: string | undefined;
+}
+/** A specification that has been compiled into a runnable MCP service. */
+interface ManagedServiceRecord {
+    id: string;
+    createdAt: string;
+    updatedAt: string;
+    status: ServiceStatus;
+    title: string;
+    version: string;
+    source: SpecSource;
+    toolCount: number;
+    promptCount: number;
+    resourceCount: number;
+    endpoint: ServiceEndpointInfo;
+    /** Number of tools that could not be fully mapped from the specification. */
+    degradedToolCount?: number | undefined;
+    /** Upstream base URL in effect for this service. */
+    baseUrl?: string | undefined;
+    /** Timestamp of the most recent tool invocation. */
+    lastCallAt?: string | undefined;
+    lastError?: {
+        message: string;
+        at: string;
+    } | undefined;
+}
+/** A problem detected while compiling the specification. */
+interface SpecIssue {
+    path: string;
+    method?: string | undefined;
+    message: string;
+    severity?: Exclude<LogLevel, "debug"> | undefined;
+}
+/** Snapshot returned by the admin status endpoint. */
+interface AdminStatus {
+    specLoaded: boolean;
+    specSource: SpecSource | null;
+    serviceId: string | null;
+    active: boolean;
+    title: string | null;
+    version: string | null;
+    baseUrl: string | null;
+    toolCount: number;
+    degradedToolCount: number;
+    promptCount: number;
+    resourceCount: number;
+    activeSessions: number;
+    services: ManagedServiceRecord[];
+    /** Human-readable issue strings, ready for display. */
+    issues: string[];
+    lastUpdatedAt: string;
+    /** Whether an API key is required to reach the admin API. */
+    /** Process uptime in seconds. */
+    uptimeSeconds?: number | undefined;
+    pendingSessions: number;
+    persistEnabled: boolean;
+    authRequired: boolean;
+    /** Library version reported to clients. */
+    serverVersion?: string | undefined;
+}
+/**
+ * A prompt generated from the specification.
+ *
+ * `Prompt` already requires `name`; the alias exists so generated values are
+ * distinguishable from prompts supplied by an embedder.
+ */
+interface GeneratedPrompt extends Prompt {
+    name: string;
+    arguments?: PromptArgument[] | undefined;
+}
+/** A resource generated from the specification. */
+interface GeneratedResource extends Resource {
+    uri: string;
+    name: string;
+}
+/** A tool generated from the specification. */
+interface GeneratedTool extends Tool {
+    name: string;
+}
+/** One textual resource body returned by a `resources/read` call. */
+interface ResourceContentItem {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+/**
+ * Message shape used when assembling prompt results.
+ *
+ * Only `user` and `assistant` are valid MCP prompt roles; a `system` role would
+ * make this type unassignable to the SDK's `GetPromptResult`.
+ */
+interface PromptMessageShape {
+    role: "user" | "assistant";
+    content: {
+        type: "text";
+        text: string;
+    };
+}
+/**
+ * Internal representation of a rendered prompt.
+ *
+ * @deprecated Build `GetPromptResult` from the SDK directly. Retained so that
+ * existing imports keep compiling.
+ */
+interface ResolvedPrompt {
+    name: string;
+    description?: string | undefined;
+    messages: PromptMessageShape[];
+}
+/** Query parameters as recorded, preserving repeated keys. */
+type LoggedQuery = Record<string, string | string[]>;
+/** A single entry in the in-memory request log surfaced by the web console. */
+interface RequestLogEntry {
+    id: string;
+    at: string;
+    direction: LogDirection;
+    /** Defaults to `info` for successes and `error` for failures when omitted. */
+    level?: LogLevel | undefined;
+    protocol?: ProtocolHint | undefined;
+    /** Ties a request entry to its matching response entry. */
+    correlationId?: string | undefined;
+    serviceId?: string | undefined;
+    sessionId?: string | undefined;
+    toolName?: string | undefined;
+    operationId?: string | undefined;
+    method?: string | undefined;
+    path?: string | undefined;
+    url?: string | undefined;
+    status?: number | undefined;
+    durationMs?: number | undefined;
+    success?: boolean | undefined;
+    requestHeaders?: Record<string, string> | undefined;
+    requestQuery?: LoggedQuery | undefined;
+    requestBody?: unknown;
+    responseHeaders?: Record<string, unknown> | undefined;
+    responseBody?: unknown;
+    /** Set when a body was shortened to respect the size limit. */
+    truncated?: boolean | undefined;
+    /** Set when one or more header values were replaced with a placeholder. */
+    redacted?: boolean | undefined;
+    /** Byte length of the upstream response, before truncation. */
+    responseBytes?: number | undefined;
+    error?: string | undefined;
+    /** Structured detail for internal events such as `spec-applied`. */
+    meta?: Record<string, unknown> | undefined;
+    requestQueryString?: string | undefined;
+}
+/** Filter accepted by the log query endpoint. */
+interface LogQueryOptions {
+    limit?: number | undefined;
+    offset?: number | undefined;
+    direction?: LogDirection | undefined;
+    level?: LogLevel | undefined;
+    toolName?: string | undefined;
+    /** Case-insensitive substring match across tool name, URL and error text. */
+    search?: string | undefined;
+    /** Restrict to failures only. */
+    onlyErrors?: boolean | undefined;
+}
+/** Paged log response. */
+interface LogQueryResult {
+    logs: RequestLogEntry[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+
+/** Handle returned to the embedding process so it can shut everything down. */
+interface AdminServerHandle {
+    app: Express;
+    server: Server;
+    /** Actual bound port, which differs from the request when port 0 is used. */
+    port: number;
+    /** Closes MCP sessions and the HTTP listener. Safe to call more than once. */
+    close: () => Promise<void>;
+}
+declare function startAdminServer(config: ServerConfig): Promise<AdminServerHandle>;
+
+export { type AdminStatus as A, type BodyEncoding as B, isParameterLocation as C, isPlainRecord as D, type ExecutionContext as E, isProtocolHint as F, type GeneratedPrompt as G, isServiceStatus as H, isSpecSource as I, startAdminServer as J, type AdminServerHandle as K, LOG_DIRECTIONS as L, type ManagedServiceRecord as M, type ParameterLocation as P, type ResourceContentItem as R, SERVICE_STATUSES as S, TRANSPORT_MODES as T, type GeneratedResource as a, type ProtocolHint as b, type AppState as c, BODY_ENCODINGS as d, type GeneratedTool as e, LOG_LEVELS as f, type LogDirection as g, type LogLevel as h, type LogQueryOptions as i, type LogQueryResult as j, type LoggedQuery as k, PARAMETER_LOCATIONS as l, PROTOCOL_HINTS as m, type PersistedState as n, type PromptMessageShape as o, type RequestLogEntry as p, type ResolvedPrompt as q, SPEC_SOURCES as r, type SecurityContext as s, type ServerConfig as t, type ServiceEndpointInfo as u, type ServiceStatus as v, type SpecIssue as w, type SpecSource as x, type TransportMode as y, isBodyEncoding as z };