@apicircle/mcp-server 1.0.1 → 1.0.2

package/dist/index.d.cts

@@ -3,6 +3,7 @@ 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';
+import { WorkspaceRegistry } from '@apicircle/core/workspace/registry';
 
 interface WorkspaceProvider {
     /** Snapshot the current `{ synced, local }` pair. */
@@ -45,8 +46,59 @@ interface MockController {
     }>>;
 }
 
+interface WorkspaceSummary {
+    id: string;
+    name: string;
+    isActive: boolean;
+    /** ISO timestamps surfaced from the on-disk registry entry. */
+    createdAt: string;
+    lastOpenedAt: string;
+    /** Cheap counts populated when the summary is built so AI clients can
+     *  decide which workspace to drill into without a second tool call.
+     *  May be `null` if the per-workspace doc couldn't be read. */
+    counts: {
+        requests: number;
+        folders: number;
+        environments: number;
+        mockServers: number;
+        plans: number;
+    } | null;
+}
+interface Workspaces {
+    /** Enumerate every workspace + which is currently active. */
+    list(): Promise<WorkspaceSummary[]>;
+    /** Return a `WorkspaceProvider` scoped to a specific workspace id. */
+    for(workspaceId: string): WorkspaceProvider;
+    /** id of the workspace that `ctx.workspace` currently points at. */
+    activeId(): string | null;
+    /** Switch which workspace `ctx.workspace` resolves to. */
+    setActive(workspaceId: string): Promise<void>;
+}
+/**
+ * Trivial single-workspace adapter — wraps an existing `WorkspaceProvider`
+ * so legacy single-dir hosts can still answer `list()` and `for()` calls.
+ * `list()` returns one entry (the active workspace itself); `for(id)` is a
+ * passthrough that asserts the id matches.
+ */
+declare class SingleWorkspaceAdapter implements Workspaces {
+    private readonly provider;
+    private workspaceId;
+    private readonly displayName;
+    constructor(provider: WorkspaceProvider, workspaceId: string | null, displayName?: string);
+    list(): Promise<WorkspaceSummary[]>;
+    for(workspaceId: string): WorkspaceProvider;
+    activeId(): string | null;
+    setActive(workspaceId: string): Promise<void>;
+}
+declare class WorkspaceNotFoundError extends Error {
+    readonly code: "workspace-not-found";
+    readonly workspaceId: string;
+    constructor(workspaceId: string);
+}
+
 interface ToolHandlerContext {
     workspace: WorkspaceProvider;
+    workspaces: Workspaces;
     mock: MockController;
 }
 interface ToolDef<S extends z.ZodTypeAny = z.ZodTypeAny> {
@@ -119,6 +171,30 @@ declare class FileBackedWorkspaceProvider implements WorkspaceProvider {
     }): Promise<WorkspaceState>;
 }
 
+declare class MultiWorkspaceProvider implements Workspaces {
+    private readonly registryRoot;
+    private active;
+    private activeWorkspaceId;
+    constructor(registryRoot: string);
+    /**
+     * Hydrate the active provider from disk. Must be called once before the
+     * MCP host boots so `ctx.workspace.read()` doesn't race the first
+     * registry-load. Returns the registry the boot can log.
+     */
+    init(): Promise<WorkspaceRegistry>;
+    /** The provider tool handlers see as `ctx.workspace`. */
+    activeProvider(): WorkspaceProvider;
+    list(): Promise<WorkspaceSummary[]>;
+    for(workspaceId: string): WorkspaceProvider;
+    activeId(): string | null;
+    setActive(workspaceId: string): Promise<void>;
+    /**
+     * Idempotent registry write — used by tests / tools that need to
+     * persist registry updates that didn't go through `setActive`.
+     */
+    writeRegistry(registry: WorkspaceRegistry): Promise<void>;
+}
+
 /**
  * MockController implementation that owns its mock processes directly via
  * `@apicircle/mock-server-core`. Used by the CLI and any embedder that
@@ -140,7 +216,18 @@ declare class InProcessMockController implements MockController {
 }
 
 interface CreateMcpServerOptions {
+    /**
+     * Provider for the ACTIVE workspace. Tools that consume `ctx.workspace`
+     * see this directly. When you pass a `MultiWorkspaceProvider`, use its
+     * `activeProvider()` here.
+     */
     workspace: WorkspaceProvider;
+    /**
+     * Optional multi-workspace surface. When omitted, the host wraps
+     * `workspace` in a `SingleWorkspaceAdapter` so `workspace.list` and the
+     * multi-workspace envelope still work (with one entry).
+     */
+    workspaces?: Workspaces;
     mock: MockController;
     /** Override the registered tool list. Defaults to `TOOL_REGISTRY`. */
     tools?: AnyToolDef[];
@@ -157,4 +244,4 @@ interface CreateMcpServerOptions {
  */
 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 };
+export { type AnyToolDef, type CreateMcpServerOptions, FileBackedWorkspaceProvider, InMemoryWorkspaceProvider, InProcessMockController, McpHost, type MockController, MultiWorkspaceProvider, SingleWorkspaceAdapter, type StartMockResult, TOOL_REGISTRY, type ToolDef, type ToolHandlerContext, WorkspaceNotFoundError, type WorkspaceProvider, type WorkspaceSummary, type Workspaces, createMcpServer, getTool };

package/dist/index.d.ts

@@ -3,6 +3,7 @@ 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';
+import { WorkspaceRegistry } from '@apicircle/core/workspace/registry';
 
 interface WorkspaceProvider {
     /** Snapshot the current `{ synced, local }` pair. */
@@ -45,8 +46,59 @@ interface MockController {
     }>>;
 }
 
+interface WorkspaceSummary {
+    id: string;
+    name: string;
+    isActive: boolean;
+    /** ISO timestamps surfaced from the on-disk registry entry. */
+    createdAt: string;
+    lastOpenedAt: string;
+    /** Cheap counts populated when the summary is built so AI clients can
+     *  decide which workspace to drill into without a second tool call.
+     *  May be `null` if the per-workspace doc couldn't be read. */
+    counts: {
+        requests: number;
+        folders: number;
+        environments: number;
+        mockServers: number;
+        plans: number;
+    } | null;
+}
+interface Workspaces {
+    /** Enumerate every workspace + which is currently active. */
+    list(): Promise<WorkspaceSummary[]>;
+    /** Return a `WorkspaceProvider` scoped to a specific workspace id. */
+    for(workspaceId: string): WorkspaceProvider;
+    /** id of the workspace that `ctx.workspace` currently points at. */
+    activeId(): string | null;
+    /** Switch which workspace `ctx.workspace` resolves to. */
+    setActive(workspaceId: string): Promise<void>;
+}
+/**
+ * Trivial single-workspace adapter — wraps an existing `WorkspaceProvider`
+ * so legacy single-dir hosts can still answer `list()` and `for()` calls.
+ * `list()` returns one entry (the active workspace itself); `for(id)` is a
+ * passthrough that asserts the id matches.
+ */
+declare class SingleWorkspaceAdapter implements Workspaces {
+    private readonly provider;
+    private workspaceId;
+    private readonly displayName;
+    constructor(provider: WorkspaceProvider, workspaceId: string | null, displayName?: string);
+    list(): Promise<WorkspaceSummary[]>;
+    for(workspaceId: string): WorkspaceProvider;
+    activeId(): string | null;
+    setActive(workspaceId: string): Promise<void>;
+}
+declare class WorkspaceNotFoundError extends Error {
+    readonly code: "workspace-not-found";
+    readonly workspaceId: string;
+    constructor(workspaceId: string);
+}
+
 interface ToolHandlerContext {
     workspace: WorkspaceProvider;
+    workspaces: Workspaces;
     mock: MockController;
 }
 interface ToolDef<S extends z.ZodTypeAny = z.ZodTypeAny> {
@@ -119,6 +171,30 @@ declare class FileBackedWorkspaceProvider implements WorkspaceProvider {
     }): Promise<WorkspaceState>;
 }
 
+declare class MultiWorkspaceProvider implements Workspaces {
+    private readonly registryRoot;
+    private active;
+    private activeWorkspaceId;
+    constructor(registryRoot: string);
+    /**
+     * Hydrate the active provider from disk. Must be called once before the
+     * MCP host boots so `ctx.workspace.read()` doesn't race the first
+     * registry-load. Returns the registry the boot can log.
+     */
+    init(): Promise<WorkspaceRegistry>;
+    /** The provider tool handlers see as `ctx.workspace`. */
+    activeProvider(): WorkspaceProvider;
+    list(): Promise<WorkspaceSummary[]>;
+    for(workspaceId: string): WorkspaceProvider;
+    activeId(): string | null;
+    setActive(workspaceId: string): Promise<void>;
+    /**
+     * Idempotent registry write — used by tests / tools that need to
+     * persist registry updates that didn't go through `setActive`.
+     */
+    writeRegistry(registry: WorkspaceRegistry): Promise<void>;
+}
+
 /**
  * MockController implementation that owns its mock processes directly via
  * `@apicircle/mock-server-core`. Used by the CLI and any embedder that
@@ -140,7 +216,18 @@ declare class InProcessMockController implements MockController {
 }
 
 interface CreateMcpServerOptions {
+    /**
+     * Provider for the ACTIVE workspace. Tools that consume `ctx.workspace`
+     * see this directly. When you pass a `MultiWorkspaceProvider`, use its
+     * `activeProvider()` here.
+     */
     workspace: WorkspaceProvider;
+    /**
+     * Optional multi-workspace surface. When omitted, the host wraps
+     * `workspace` in a `SingleWorkspaceAdapter` so `workspace.list` and the
+     * multi-workspace envelope still work (with one entry).
+     */
+    workspaces?: Workspaces;
     mock: MockController;
     /** Override the registered tool list. Defaults to `TOOL_REGISTRY`. */
     tools?: AnyToolDef[];
@@ -157,4 +244,4 @@ interface CreateMcpServerOptions {
  */
 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 };
+export { type AnyToolDef, type CreateMcpServerOptions, FileBackedWorkspaceProvider, InMemoryWorkspaceProvider, InProcessMockController, McpHost, type MockController, MultiWorkspaceProvider, SingleWorkspaceAdapter, type StartMockResult, TOOL_REGISTRY, type ToolDef, type ToolHandlerContext, WorkspaceNotFoundError, type WorkspaceProvider, type WorkspaceSummary, type Workspaces, createMcpServer, getTool };