@powerduck/openapi-mcp-server 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -1,13 +1,13 @@
-import { Document, ParameterObject, OperationObject, PathItemObject } from '@scalar/openapi-types/3.2';
+import { Oas32Document, ParameterObject, OperationObject, PathItemObject } from '@powerduck/openapi-parser';
 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.cjs';
-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.cjs';
+import { P as ParameterLocation, B as BodyEncoding, G as GeneratedPrompt, a as GeneratedResource, R as ResourceContentItem, E as ExecutionContext, b as ProtocolHint, M as ManagedServiceRecord } from './admin-server-dcPWB2yO.cjs';
+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, 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-dcPWB2yO.cjs';
 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>;
+declare function loadOpenApiSpec(filePath: string): Promise<Oas32Document>;
+declare function parseSpecContent(rawText: string, isYaml: boolean): Promise<Oas32Document>;
 
 /**
  * A parameter validated to carry the fields this library relies on.
@@ -68,6 +68,12 @@ interface SpecWalkIssue {
     code: SpecWalkIssueCode;
     message: string;
 }
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Shortens an identifier to {@link MAX_GENERATED_NAME_LENGTH} while preserving
+ * uniqueness by appending a hash of the original value.
+ */
+declare function truncateGeneratedName(name: string, limit?: number): string;
 /**
  * Extracts the `{name}` template variables from a path template.
  * Duplicates are collapsed; order follows first appearance.
@@ -122,7 +128,7 @@ declare function ensureUniqueName(candidate: string, taken: Set<string>): string
  *
  * Non-fatal problems are appended to `issues` when the caller supplies an array.
  */
-declare function iterateOperations(spec: Document | null | undefined, issues?: SpecWalkIssue[]): Generator<ResolvedOperation>;
+declare function iterateOperations(spec: Oas32Document | null | undefined, issues?: SpecWalkIssue[]): Generator<ResolvedOperation>;
 /**
  * Locates an operation by id, in O(1) after the first call.
  *
@@ -135,7 +141,7 @@ declare function iterateOperations(spec: Document | null | undefined, issues?: S
  * 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;
+declare function findOperationById(spec: Oas32Document | null | undefined, operationId: string): OperationEntry | null;
 /** Describes one operationId claimed by more than one operation. */
 interface DuplicateOperationId {
     operationId: string;
@@ -154,13 +160,13 @@ interface DuplicateOperationId {
  * degrades the tool names rather than breaking the server. Use it to warn the
  * operator.
  */
-declare function findDuplicateOperationIds(spec: Document | null | undefined): DuplicateOperationId[];
+declare function findDuplicateOperationIds(spec: Oas32Document | 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;
+declare function assertUniqueOperationIds(spec: Oas32Document | null | undefined): void;
 
 interface ArgumentBinding {
     key: string;
@@ -199,21 +205,21 @@ interface GenerateToolsResult {
     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 function generateToolsDetailed(spec: Oas32Document | null | undefined): GenerateToolsResult;
+declare function generateTools(spec: Oas32Document | null | undefined): Tool[];
+declare function getBindingIndex(spec: Oas32Document | null | undefined): Map<string, ToolBinding>;
 declare const buildBindingIndex: typeof getBindingIndex;
 
 /** List every prompt exposed for the given specification. */
-declare function generatePrompts(spec: Document): GeneratedPrompt[];
+declare function generatePrompts(spec: Oas32Document): 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 resolvePrompt(spec: Oas32Document, name: string, args?: Record<string, unknown>): GetPromptResult | null;
 
-declare function generateResources(spec: Document): GeneratedResource[];
-declare function readResource(spec: Document, uri: string): ResourceContentItem | null;
+declare function generateResources(spec: Oas32Document): GeneratedResource[];
+declare function readResource(spec: Oas32Document, uri: string): ResourceContentItem | null;
 
 interface ToolCallResult {
     status: number;
@@ -234,7 +240,7 @@ interface ToolCallResult {
  * 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>;
+declare function executeToolCall(spec: Oas32Document, 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 {
@@ -262,7 +268,7 @@ interface BuiltRequest {
 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;
+type SpecProvider = () => Oas32Document | null;
 /** Returns the upstream execution context for the current call. */
 type ContextProvider = () => ExecutionContext;
 interface BuildMcpServerOptions {
@@ -344,7 +350,7 @@ interface StartStdioServerOptions {
  * 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>;
+declare function startStdioServer(spec: Oas32Document, context?: ExecutionContext, options?: StartStdioServerOptions): Promise<StdioServerHandle>;
 
 /**
  * Backwards-compatible alias for the previous export name.
@@ -371,4 +377,24 @@ declare function attachSseRoutes(app: express.Express, specProvider: SpecProvide
  */
 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 };
+/**
+ * Node throws DOMException on AbortSignal and Error subclasses elsewhere, and
+ * axios reports its own CanceledError. Matching on `name` covers all three
+ * without importing axios internals.
+ */
+declare function isAbortError(error: unknown): boolean;
+declare function newId(): string;
+
+declare class ServiceRegistry {
+    private readonly records;
+    upsert(record: ManagedServiceRecord): void;
+    list(): ManagedServiceRecord[];
+    get(id: string): ManagedServiceRecord | undefined;
+    remove(id: string): boolean;
+    clear(): void;
+    start(id: string): ManagedServiceRecord | undefined;
+    stop(id: string): ManagedServiceRecord | undefined;
+    fail(id: string, message: string): ManagedServiceRecord | undefined;
+}
+
+export { BodyEncoding, type ContextProvider, type DuplicateOperationId, ExecutionContext, GeneratedPrompt, GeneratedResource, type GeneratedTool as GeneratedToolWithBinding, ManagedServiceRecord, type OperationEntry, ParameterLocation, ProtocolHint, ResourceContentItem, ServiceRegistry, type SpecProvider, type ToolBinding, assertUniqueOperationIds, attachSseRoutes, buildBindingIndex, buildMcpServer, buildRequest, collectOperationParameters, createAuthMiddleware, effectiveExplode, effectiveStyle, ensureUniqueName, executeToolCall, extractPathTemplateVariables, findDuplicateOperationIds, findOperationById, generatePrompts, generateResources, generateTools, generateToolsDetailed, isAbortError, isPlainObject, iterateOperations, loadOpenApiSpec, newId, normalizeParameter, parseSpecContent, readResource, resolvePrompt, startStdioServer, synthesizeOperationId, truncateGeneratedName };

package/dist/index.d.ts

@@ -1,13 +1,13 @@
-import { Document, ParameterObject, OperationObject, PathItemObject } from '@scalar/openapi-types/3.2';
+import { Oas32Document, ParameterObject, OperationObject, PathItemObject } from '@powerduck/openapi-parser';
 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 { P as ParameterLocation, B as BodyEncoding, G as GeneratedPrompt, a as GeneratedResource, R as ResourceContentItem, E as ExecutionContext, b as ProtocolHint, M as ManagedServiceRecord } from './admin-server-dcPWB2yO.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, 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-dcPWB2yO.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>;
+declare function loadOpenApiSpec(filePath: string): Promise<Oas32Document>;
+declare function parseSpecContent(rawText: string, isYaml: boolean): Promise<Oas32Document>;
 
 /**
  * A parameter validated to carry the fields this library relies on.
@@ -68,6 +68,12 @@ interface SpecWalkIssue {
     code: SpecWalkIssueCode;
     message: string;
 }
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Shortens an identifier to {@link MAX_GENERATED_NAME_LENGTH} while preserving
+ * uniqueness by appending a hash of the original value.
+ */
+declare function truncateGeneratedName(name: string, limit?: number): string;
 /**
  * Extracts the `{name}` template variables from a path template.
  * Duplicates are collapsed; order follows first appearance.
@@ -122,7 +128,7 @@ declare function ensureUniqueName(candidate: string, taken: Set<string>): string
  *
  * Non-fatal problems are appended to `issues` when the caller supplies an array.
  */
-declare function iterateOperations(spec: Document | null | undefined, issues?: SpecWalkIssue[]): Generator<ResolvedOperation>;
+declare function iterateOperations(spec: Oas32Document | null | undefined, issues?: SpecWalkIssue[]): Generator<ResolvedOperation>;
 /**
  * Locates an operation by id, in O(1) after the first call.
  *
@@ -135,7 +141,7 @@ declare function iterateOperations(spec: Document | null | undefined, issues?: S
  * 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;
+declare function findOperationById(spec: Oas32Document | null | undefined, operationId: string): OperationEntry | null;
 /** Describes one operationId claimed by more than one operation. */
 interface DuplicateOperationId {
     operationId: string;
@@ -154,13 +160,13 @@ interface DuplicateOperationId {
  * degrades the tool names rather than breaking the server. Use it to warn the
  * operator.
  */
-declare function findDuplicateOperationIds(spec: Document | null | undefined): DuplicateOperationId[];
+declare function findDuplicateOperationIds(spec: Oas32Document | 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;
+declare function assertUniqueOperationIds(spec: Oas32Document | null | undefined): void;
 
 interface ArgumentBinding {
     key: string;
@@ -199,21 +205,21 @@ interface GenerateToolsResult {
     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 function generateToolsDetailed(spec: Oas32Document | null | undefined): GenerateToolsResult;
+declare function generateTools(spec: Oas32Document | null | undefined): Tool[];
+declare function getBindingIndex(spec: Oas32Document | null | undefined): Map<string, ToolBinding>;
 declare const buildBindingIndex: typeof getBindingIndex;
 
 /** List every prompt exposed for the given specification. */
-declare function generatePrompts(spec: Document): GeneratedPrompt[];
+declare function generatePrompts(spec: Oas32Document): 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 resolvePrompt(spec: Oas32Document, name: string, args?: Record<string, unknown>): GetPromptResult | null;
 
-declare function generateResources(spec: Document): GeneratedResource[];
-declare function readResource(spec: Document, uri: string): ResourceContentItem | null;
+declare function generateResources(spec: Oas32Document): GeneratedResource[];
+declare function readResource(spec: Oas32Document, uri: string): ResourceContentItem | null;
 
 interface ToolCallResult {
     status: number;
@@ -234,7 +240,7 @@ interface ToolCallResult {
  * 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>;
+declare function executeToolCall(spec: Oas32Document, 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 {
@@ -262,7 +268,7 @@ interface BuiltRequest {
 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;
+type SpecProvider = () => Oas32Document | null;
 /** Returns the upstream execution context for the current call. */
 type ContextProvider = () => ExecutionContext;
 interface BuildMcpServerOptions {
@@ -344,7 +350,7 @@ interface StartStdioServerOptions {
  * 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>;
+declare function startStdioServer(spec: Oas32Document, context?: ExecutionContext, options?: StartStdioServerOptions): Promise<StdioServerHandle>;
 
 /**
  * Backwards-compatible alias for the previous export name.
@@ -371,4 +377,24 @@ declare function attachSseRoutes(app: express.Express, specProvider: SpecProvide
  */
 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 };
+/**
+ * Node throws DOMException on AbortSignal and Error subclasses elsewhere, and
+ * axios reports its own CanceledError. Matching on `name` covers all three
+ * without importing axios internals.
+ */
+declare function isAbortError(error: unknown): boolean;
+declare function newId(): string;
+
+declare class ServiceRegistry {
+    private readonly records;
+    upsert(record: ManagedServiceRecord): void;
+    list(): ManagedServiceRecord[];
+    get(id: string): ManagedServiceRecord | undefined;
+    remove(id: string): boolean;
+    clear(): void;
+    start(id: string): ManagedServiceRecord | undefined;
+    stop(id: string): ManagedServiceRecord | undefined;
+    fail(id: string, message: string): ManagedServiceRecord | undefined;
+}
+
+export { BodyEncoding, type ContextProvider, type DuplicateOperationId, ExecutionContext, GeneratedPrompt, GeneratedResource, type GeneratedTool as GeneratedToolWithBinding, ManagedServiceRecord, type OperationEntry, ParameterLocation, ProtocolHint, ResourceContentItem, ServiceRegistry, type SpecProvider, type ToolBinding, assertUniqueOperationIds, attachSseRoutes, buildBindingIndex, buildMcpServer, buildRequest, collectOperationParameters, createAuthMiddleware, effectiveExplode, effectiveStyle, ensureUniqueName, executeToolCall, extractPathTemplateVariables, findDuplicateOperationIds, findOperationById, generatePrompts, generateResources, generateTools, generateToolsDetailed, isAbortError, isPlainObject, iterateOperations, loadOpenApiSpec, newId, normalizeParameter, parseSpecContent, readResource, resolvePrompt, startStdioServer, synthesizeOperationId, truncateGeneratedName };