@apicircle/mcp-server 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { z } from 'zod';
+import { WorkspaceSynced, WorkspaceLocal, MockServer, MockRuntimeEntry, McpToolName } from '@apicircle/shared';
+import { WorkspaceState, WorkspacePatch } from '@apicircle/core';
+
+interface WorkspaceProvider {
+    /** Snapshot the current `{ synced, local }` pair. */
+    read(): Promise<WorkspaceState>;
+    /**
+     * Apply a single mutation. Returns the resulting state + the ids the
+     * patch touched, so the tool handler can echo a meaningful response back
+     * to the AI client (e.g. "created request `r-abc`").
+     */
+    apply(patch: WorkspacePatch): Promise<{
+        state: WorkspaceState;
+        changedIds: string[];
+    }>;
+    /**
+     * Bulk overwrite. Used by `workspace.write` (rare — most edits go
+     * through `apply`). Implementations should accept a partial pair so
+     * tools targeting only synced or only local can leave the other side
+     * untouched.
+     */
+    write(next: {
+        synced?: WorkspaceSynced;
+        local?: WorkspaceLocal;
+    }): Promise<WorkspaceState>;
+}
+
+interface StartMockResult {
+    port: number;
+    pid: number | null;
+    startedAt: string;
+}
+interface MockController {
+    start(server: MockServer, opts?: {
+        port?: number;
+    }): Promise<StartMockResult>;
+    stop(serverId: string): Promise<void>;
+    /** Snapshot of currently running mocks. */
+    list(): Promise<Array<{
+        serverId: string;
+        runtime: MockRuntimeEntry;
+    }>>;
+}
+
+interface ToolHandlerContext {
+    workspace: WorkspaceProvider;
+    mock: MockController;
+}
+interface ToolDef<S extends z.ZodTypeAny = z.ZodTypeAny> {
+    name: McpToolName;
+    description: string;
+    inputSchema: S;
+    handler: (input: z.infer<S>, ctx: ToolHandlerContext) => Promise<unknown>;
+}
+type AnyToolDef = ToolDef<z.ZodTypeAny>;
+
+interface McpHostOptions {
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+    context: ToolHandlerContext;
+    tools: AnyToolDef[];
+}
+declare class McpHost {
+    readonly server: McpServer;
+    private readonly tools;
+    private readonly context;
+    constructor(options: McpHostOptions);
+    private registerAll;
+    /** Connect the underlying server to a transport (defaults to stdio). */
+    connect(transport?: Transport): Promise<void>;
+    close(): Promise<void>;
+}
+
+declare const TOOL_REGISTRY: AnyToolDef[];
+declare function getTool(name: McpToolName): AnyToolDef | undefined;
+
+/**
+ * Pure in-memory provider. Used for unit tests and any programmatic
+ * embedding where the consumer already owns workspace state and just
+ * wants to drive the MCP tool catalog without disk or IPC.
+ */
+declare class InMemoryWorkspaceProvider implements WorkspaceProvider {
+    private state;
+    constructor(initial: WorkspaceState);
+    read(): Promise<WorkspaceState>;
+    apply(patch: WorkspacePatch): Promise<{
+        state: WorkspaceState;
+        changedIds: string[];
+    }>;
+    write(next: {
+        synced?: WorkspaceSynced;
+        local?: WorkspaceLocal;
+    }): Promise<WorkspaceState>;
+}
+
+/**
+ * Disk-backed provider used by the standalone CLI and the headless MCP
+ * server when launched outside Electron. Each `apply` runs a full
+ * load → mutate → save cycle under a `proper-lockfile` advisory lock so
+ * concurrent writers (a second CLI invocation, the desktop app on the
+ * same workspace) can't clobber each other.
+ */
+declare class FileBackedWorkspaceProvider implements WorkspaceProvider {
+    private readonly dir;
+    constructor(dir: string);
+    read(): Promise<WorkspaceState>;
+    apply(patch: WorkspacePatch): Promise<{
+        state: WorkspaceState;
+        changedIds: string[];
+    }>;
+    write(next: {
+        synced?: WorkspaceSynced;
+        local?: WorkspaceLocal;
+    }): Promise<WorkspaceState>;
+}
+
+/**
+ * MockController implementation that owns its mock processes directly via
+ * `@apicircle/mock-server-core`. Used by the CLI and any embedder that
+ * wants the simplest possible setup. The desktop app supplies a
+ * different controller (process-bridge to its main process) so renderer-
+ * side state stays consistent.
+ */
+declare class InProcessMockController implements MockController {
+    private readonly handles;
+    private readonly meta;
+    start(server: MockServer, opts?: {
+        port?: number;
+    }): Promise<StartMockResult>;
+    stop(serverId: string): Promise<void>;
+    list(): Promise<Array<{
+        serverId: string;
+        runtime: MockRuntimeEntry;
+    }>>;
+}
+
+interface CreateMcpServerOptions {
+    workspace: WorkspaceProvider;
+    mock: MockController;
+    /** Override the registered tool list. Defaults to `TOOL_REGISTRY`. */
+    tools?: AnyToolDef[];
+    serverInfo?: {
+        name: string;
+        version: string;
+    };
+}
+/**
+ * Build a fully-wired McpHost ready to `await host.connect()` over stdio.
+ * Tool implementations come from `TOOL_REGISTRY` by default; pass `tools`
+ * to inject a curated subset (useful for tests or for hosting only the
+ * import surface).
+ */
+declare function createMcpServer(options: CreateMcpServerOptions): McpHost;
+
+export { type AnyToolDef, type CreateMcpServerOptions, FileBackedWorkspaceProvider, InMemoryWorkspaceProvider, InProcessMockController, McpHost, type MockController, type StartMockResult, TOOL_REGISTRY, type ToolDef, type ToolHandlerContext, type WorkspaceProvider, createMcpServer, getTool };