@powerduck/dev-mcp-server 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,384 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { Tool, Resource, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
+import { AuthConfig, CliConfig, DeclarativeAssertion, TestResult, TestReport, ScenarioReport } from '@powerduck/openapi-cli';
+import { RequestValues } from '@powerduck/openapi-request';
+
+interface ServerFact {
+    url: string;
+    description?: string;
+    /** Names of variables the server URL still requires. */
+    variables: string[];
+}
+interface SecuritySchemeFact {
+    name: string;
+    type: string;
+    scheme?: string;
+    bearerFormat?: string;
+    in?: string;
+    parameterName?: string;
+    openIdConnectUrl?: string;
+    /** OAuth2 flow names and the scopes each declares. */
+    flows: Record<string, string[]>;
+}
+interface CompactOperation {
+    /** Stable reference, e.g. "POST /orders". */
+    ref: string;
+    operationId?: string;
+    method: string;
+    path: string;
+    summary?: string;
+    tags: string[];
+    /** A non-empty security requirement applies to this operation. */
+    secured: boolean;
+    statusCodes: string[];
+    hasParameters: boolean;
+    hasRequestBody: boolean;
+    protocol: string;
+}
+interface ParameterFact {
+    name: string;
+    in: "path" | "query" | "header" | "cookie";
+    required: boolean;
+    description?: string;
+    deprecated: boolean;
+    /** Compact JSON Schema describing the parameter value. */
+    schema: Record<string, unknown>;
+    example?: unknown;
+}
+interface MediaFact {
+    /** Dereferenced JSON Schema for the payload. */
+    schema: unknown;
+    example?: unknown;
+    /** Named examples declared by the specification. */
+    examples: string[];
+}
+interface HeaderFact {
+    name: string;
+    required: boolean;
+    description?: string;
+    schema: Record<string, unknown>;
+}
+interface ResponseFact {
+    status: string;
+    description?: string;
+    headers: HeaderFact[];
+    content: Record<string, MediaFact>;
+}
+interface RequestBodyFact {
+    required: boolean;
+    description?: string;
+    content: Record<string, MediaFact>;
+}
+interface OperationFact {
+    ref: string;
+    operationId?: string;
+    method: string;
+    path: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    deprecated: boolean;
+    idempotent: boolean;
+    protocol: string;
+    parameters: ParameterFact[];
+    requestBody?: RequestBodyFact;
+    responses: ResponseFact[];
+    /** Effective security requirements after operation-level overrides. */
+    security: SecuritySchemeFact[];
+    servers: ServerFact[];
+}
+type IssueSeverity = "error" | "warning" | "info";
+interface ValidationIssue {
+    message: string;
+    severity: IssueSeverity;
+    path?: string;
+}
+interface ValidationFact {
+    valid: boolean;
+    openapiVersion?: string;
+    issues: ValidationIssue[];
+}
+interface OverviewFact {
+    title: string;
+    version: string;
+    description?: string;
+    openapiVersion?: string;
+    servers: ServerFact[];
+    endpointCount: number;
+    tags: string[];
+    protocols: string[];
+    schemaCount: number;
+    securitySchemes: SecuritySchemeFact[];
+}
+interface PagedOperations {
+    items: CompactOperation[];
+    total: number;
+    nextCursor?: string;
+}
+interface OperationLocator {
+    /** "METHOD /path" reference. */
+    ref?: string;
+    operationId?: string;
+    method?: string;
+    path?: string;
+}
+/** A failed tool call whose cause is the caller's input, not the server. */
+declare class FactError extends Error {
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(code: string, message: string, details?: unknown);
+}
+
+/**
+ * Loads an OpenAPI document from disk and keeps it fresh.
+ *
+ * A developer edits the spec while the coding agent is connected, so the
+ * store re-reads the file whenever its mtime changes. Parsing and validation
+ * are best effort: an in-progress document with validation issues must still
+ * answer fact queries, and the validate_spec tool surfaces those problems.
+ */
+
+interface SpecSnapshot {
+    /** Absolute source path. */
+    path: string;
+    /** Document normalized to 3.x when conversion is safe; otherwise as authored. */
+    document: Record<string, any>;
+    /** Document with internal $ref values inlined where possible. */
+    dereferenced: Record<string, any>;
+    /** Raw source text, served by the `source` resource. */
+    sourceText: string;
+    mediaType: "application/yaml" | "application/json";
+    validation: ValidationFact;
+    mtimeMs: number;
+}
+declare class SpecStore {
+    readonly specPath: string;
+    private cache;
+    constructor(specPath: string);
+    /** Read and normalize the document, reusing the cache while mtime is stable. */
+    load(force?: boolean): Promise<SpecSnapshot>;
+}
+
+/**
+ * Builds the developer MCP server: read-only contract facts plus verification
+ * against a running backend.
+ *
+ * The server is transport agnostic. A SpecStore supplies a live document, and
+ * every request re-reads the file when it changed on disk. Long-running tools
+ * stream MCP $/progress and honor notifications/cancelled.
+ */
+
+interface CreateServerOptions {
+    name?: string;
+    version?: string;
+    /** Free-form usage instructions surfaced during MCP initialization. */
+    instructions?: string;
+}
+declare function createDevMcpServer(store: SpecStore, options?: CreateServerOptions): Server;
+
+/**
+ * stdio transport for AI coding clients (Claude Code, Codex CLI, Cursor,
+ * Claude Desktop). stdout is the JSON-RPC channel, so all accidental logging
+ * is diverted to stderr for the lifetime of the server.
+ */
+interface StdioHandle {
+    closed: Promise<void>;
+    close(): Promise<void>;
+}
+interface StartStdioOptions {
+    specPath: string;
+    name?: string;
+    version?: string;
+    handleSignals?: boolean;
+}
+declare function startStdioServer(options: StartStdioOptions): Promise<StdioHandle>;
+
+/**
+ * Builds the @powerduck/openapi-cli runner configuration for a verification
+ * request. Fact tools read an in-memory document; the runner also needs a real
+ * spec path (used as an identifier and fallback loader), which the SpecStore
+ * always has.
+ */
+
+interface RunOverrides {
+    baseUrl?: string;
+    timeoutMs?: number;
+    concurrency?: number;
+    headers?: Record<string, string>;
+    variables?: Record<string, string>;
+    proxy?: string;
+    auth?: AuthConfig;
+}
+interface ProgressSink {
+    /** Emit MCP $/progress when a progress token was supplied by the client. */
+    report?: (progress: number, total: number, message?: string) => void;
+    /** Cancellation propagated from notifications/cancelled. */
+    signal?: AbortSignal;
+}
+declare function buildRunnerConfig(snapshot: SpecSnapshot, overrides: RunOverrides): CliConfig;
+/** Resolves the target base URL from an explicit override or the spec servers. */
+declare function resolveBaseUrl(snapshot: SpecSnapshot, explicit: string | undefined): string | undefined;
+/** Maps raw tool arguments into typed runner overrides with validation. */
+declare function runOverridesFromArgs(snapshot: SpecSnapshot, args: Record<string, unknown>): RunOverrides;
+
+/**
+ * Developer MCP tools.
+ *
+ * Fact tools (M0) expose read-only contract truth. Verification tools (M1)
+ * send requests and run contract/scenario tests against a running backend via
+ * @powerduck/openapi-cli.
+ */
+
+declare const devTools: Tool[];
+/** Executes one tool call and returns a JSON-serializable result. */
+declare function executeDevTool(name: string, args: Record<string, unknown>, store: SpecStore, sink?: ProgressSink): Promise<unknown>;
+
+/**
+ * MCP resources expose the same facts as stable URIs, so agents can attach
+ * contract context directly to a conversation.
+ */
+
+declare function listSpecResources(store: SpecStore): Promise<Resource[]>;
+declare const specResourceTemplates: ResourceTemplate[];
+interface ResourceContents {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+declare function readSpecResource(uri: string, store: SpecStore): Promise<ResourceContents>;
+
+/**
+ * Pure fact extraction over an OpenAPI document.
+ *
+ * Every function here is deterministic and side-effect free. The MCP layer is
+ * a thin transport over these functions so the same logic is unit-testable
+ * without a JSON-RPC client.
+ */
+
+declare const HTTP_METHODS: readonly ["get", "post", "put", "patch", "delete", "head", "options", "trace"];
+/** Resolves a local JSON pointer ("#/components/schemas/Foo"). */
+declare function resolvePointer(doc: unknown, ref: string): unknown;
+declare function overview(doc: Record<string, any>): OverviewFact;
+interface ListOptions {
+    tag?: string;
+    method?: string;
+    protocol?: string;
+    secured?: boolean;
+    search?: string;
+    pageSize?: number;
+    cursor?: string;
+}
+declare function listOperations(doc: Record<string, any>, options?: ListOptions): PagedOperations;
+declare function getOperation(doc: Record<string, any>, rawDoc: Record<string, any>, locator: OperationLocator): OperationFact;
+interface SchemaLocator {
+    name?: string;
+    ref?: string;
+}
+declare function getSchema(doc: Record<string, any>, rawDoc: Record<string, any>, locator: SchemaLocator): {
+    name?: string;
+    schema: unknown;
+};
+declare function authRequirements(doc: Record<string, any>, locator?: OperationLocator): {
+    global: SecuritySchemeFact[];
+    operation?: SecuritySchemeFact[];
+};
+
+/**
+ * Project-level developer configuration (powerduck.dev.json).
+ *
+ * This file is safe to commit: it points at the specification and the local
+ * development server. Secrets must come from environment variables, never from
+ * this file.
+ */
+interface DevConfig {
+    /** Path to the OpenAPI document, relative to the config file. */
+    spec?: string;
+    /** Default base URL of the local backend under development. */
+    baseUrl?: string;
+    /** Backend project root, used by future code-aware tools. */
+    project?: string;
+}
+/**
+ * Loads optional configuration. Explicit `--config` wins; otherwise a
+ * powerduck.dev.json in the current working directory is used when present.
+ */
+declare function loadDevConfig(configPath?: string): {
+    config: DevConfig;
+    configDir: string;
+};
+/** Resolves a possibly config-relative path to an absolute one. */
+declare function resolveFrom(configDir: string, target?: string): string | undefined;
+
+/**
+ * Lightweight reachability probe. Unlike send_request this does not require a
+ * matching operation; it confirms the local backend is up before testing.
+ */
+interface PingResult {
+    url: string;
+    reachable: boolean;
+    status?: number;
+    statusText?: string;
+    contentType?: string;
+    latencyMs: number;
+    error?: string;
+}
+declare function pingTarget(rawUrl: string, timeoutMs: number): Promise<PingResult>;
+
+/**
+ * Single-operation verification: send one request to the local backend and
+ * report the normalized response plus spec-derived assertion results.
+ */
+
+interface SendInput {
+    values?: RequestValues;
+    variables?: Record<string, string>;
+    assertions?: DeclarativeAssertion[];
+    /** Per-call target override; wins over the configured base URL. */
+    baseUrl?: string;
+}
+declare function sendOne(snapshot: SpecSnapshot, overrides: RunOverrides, locator: OperationLocator, input: SendInput): Promise<TestResult>;
+
+/**
+ * Batch contract verification against a running backend.
+ *
+ * Mirrors openapi-cli's runTests but executes against the in-memory live
+ * document so the MCP never depends on a stale file on disk.
+ */
+
+interface ContractFilter {
+    methods?: string[];
+    paths?: string[];
+    tags?: string[];
+    operationIds?: string[];
+}
+interface ContractSuiteResult {
+    summary: TestReport["summary"];
+    results: TestResult[];
+    generatedAt: string;
+    version: string;
+}
+declare function contractFilterFromArgs(args: Record<string, unknown>): ContractFilter;
+declare function runContractSuite(snapshot: SpecSnapshot, overrides: RunOverrides, filter: ContractFilter, sink?: ProgressSink): Promise<ContractSuiteResult>;
+
+/**
+ * Scenario validation and execution.
+ *
+ * Validation resolves every step reference up front and never touches the
+ * network, so an agent can confirm a plan before running it. Execution reuses
+ * openapi-cli's ordered, stateful engine with live progress and cancellation.
+ */
+
+interface ScenarioValidation {
+    valid: boolean;
+    errors?: string[];
+    steps?: Array<{
+        index: number;
+        ref: string;
+        name?: string;
+    }>;
+    count?: number;
+}
+declare function validateScenario(snapshot: SpecSnapshot, rawScenario: unknown): ScenarioValidation;
+declare function runScenarioTool(snapshot: SpecSnapshot, rawScenario: unknown, overrides: RunOverrides, sink?: ProgressSink): Promise<Omit<ScenarioReport, "config">>;
+
+export { type CompactOperation, type ContractFilter, type ContractSuiteResult, type CreateServerOptions, type DevConfig, FactError, HTTP_METHODS, type HeaderFact, type ListOptions, type MediaFact, type OperationFact, type OperationLocator, type OverviewFact, type PagedOperations, type ParameterFact, type PingResult, type ProgressSink, type RequestBodyFact, type ResponseFact, type RunOverrides, type ScenarioValidation, type SecuritySchemeFact, type SendInput, type ServerFact, type SpecSnapshot, SpecStore, type StartStdioOptions, type StdioHandle, type ValidationFact, type ValidationIssue, authRequirements, buildRunnerConfig, contractFilterFromArgs, createDevMcpServer, devTools, executeDevTool, getOperation, getSchema, listOperations, listSpecResources, loadDevConfig, overview, pingTarget, readSpecResource, resolveBaseUrl, resolveFrom, resolvePointer, runContractSuite, runOverridesFromArgs, runScenarioTool, sendOne, specResourceTemplates, startStdioServer, validateScenario };