@walkeros/mcp 3.4.2 → 4.0.0-next-1777463920154

package/dist/index.d.ts

@@ -1,2 +1,329 @@
+import { ListFlowsOptions, ListPreviewsOptions, GetPreviewOptions, CreatePreviewOptions, DeletePreviewOptions, DeployOptions, ListDeploymentsOptions, DeviceCodeResult, PollResult, FeedbackOptions } from '@walkeros/cli';
+import { ZodRawShape } from 'zod';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { WebStandardStreamableHTTPServerTransportOptions } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js';
 
-export {  }
+/**
+ * Transport-agnostic client for network-reach MCP tools. The stdio build
+ * plugs in HttpToolClient (talks to the walkerOS app over HTTPS via the
+ * CLI's programmatic API). In-process hosts (e.g. the app itself) can plug
+ * in a direct client that calls database helpers without HTTP overhead.
+ */
+interface ToolClient {
+    listProjects(): Promise<unknown>;
+    getProject(options: {
+        projectId?: string;
+    }): Promise<unknown>;
+    createProject(options: {
+        name: string;
+    }): Promise<unknown>;
+    updateProject(options: {
+        projectId?: string;
+        name: string;
+    }): Promise<unknown>;
+    deleteProject(options: {
+        projectId?: string;
+    }): Promise<unknown>;
+    setDefaultProject(projectId: string): void;
+    getDefaultProject(): string | null;
+    listAllFlows(options?: {
+        sort?: string;
+        order?: 'asc' | 'desc';
+        includeDeleted?: boolean;
+    }): Promise<unknown>;
+    listFlows(options: ListFlowsOptions): Promise<unknown>;
+    getFlow(options: {
+        flowId: string;
+        projectId?: string;
+        fields?: string[];
+    }): Promise<unknown>;
+    createFlow(options: {
+        name: string;
+        content: Record<string, unknown>;
+        projectId?: string;
+    }): Promise<unknown>;
+    updateFlow(options: {
+        flowId: string;
+        projectId?: string;
+        name?: string;
+        content?: Record<string, unknown>;
+        mergePatch?: boolean;
+    }): Promise<unknown>;
+    deleteFlow(options: {
+        flowId: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    duplicateFlow(options: {
+        flowId: string;
+        name?: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    listPreviews(options: ListPreviewsOptions): Promise<unknown>;
+    getPreview(options: GetPreviewOptions): Promise<unknown>;
+    createPreview(options: CreatePreviewOptions): Promise<unknown>;
+    deletePreview(options: DeletePreviewOptions): Promise<unknown>;
+    deploy(options: DeployOptions): Promise<unknown>;
+    listDeployments(options: ListDeploymentsOptions): Promise<unknown>;
+    getDeploymentBySlug(options: {
+        slug: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    deleteDeployment(options: {
+        slug: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    requestDeviceCode(): Promise<DeviceCodeResult>;
+    pollForToken(deviceCode: string, options?: {
+        timeoutMs?: number;
+    }): Promise<PollResult>;
+    whoami(): Promise<unknown>;
+    resolveToken(): {
+        token: string;
+        source: 'env' | 'config';
+    } | null;
+    deleteConfig(): boolean;
+    submitFeedback(text: string, options?: FeedbackOptions): Promise<void>;
+    getFeedbackPreference(): boolean | undefined;
+    setFeedbackPreference(anonymous: boolean): void;
+}
+
+interface ToolAnnotations {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+}
+interface ToolDefinition {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: ZodRawShape;
+    annotations: ToolAnnotations;
+}
+/**
+ * Declarative registry mirroring the inputSchema + annotations of every tool
+ * registered in `createWalkerOSMcpServer`. Use this to bridge tools into
+ * non-MCP runtimes (e.g., Vercel AI SDK adapters) without booting an
+ * `McpServer`. Tool handlers are not included here, they require a
+ * `ToolClient`, which the caller provides.
+ */
+declare const TOOL_DEFINITIONS: readonly ToolDefinition[];
+
+/**
+ * A full tool specification: metadata + executable handler.
+ *
+ * Produced by each `create<Name>ToolSpec(...)` factory and by the aggregate
+ * `createToolHandlers(client)`. Consumers without an `McpServer` (e.g., the
+ * walkerOS app's chat route wrapping tools as Vercel AI SDK tools) use this
+ * directly; the server factory uses it to call `McpServer.registerTool`.
+ */
+interface ToolSpec {
+    name: string;
+    title: string;
+    description: string;
+    inputSchema: ZodRawShape;
+    annotations: ToolAnnotations;
+    handler: (input: unknown) => Promise<unknown>;
+}
+
+interface Logger {
+    debug?(message: string, meta?: Record<string, unknown>): void;
+    info?(message: string, meta?: Record<string, unknown>): void;
+    warn?(message: string, meta?: Record<string, unknown>): void;
+    error?(message: string, meta?: Record<string, unknown>): void;
+}
+interface CreateServerOptions {
+    client: ToolClient;
+    logger?: Logger;
+    version?: string;
+    catalogBaseUrl?: string;
+}
+declare function createWalkerOSMcpServer(opts: CreateServerOptions): McpServer;
+
+/**
+ * Default ToolClient implementation backed by @walkeros/cli. Every method
+ * delegates to the CLI's programmatic API, which in turn talks to the
+ * walkerOS app over HTTPS via openapi-fetch. Token resolution and the
+ * base URL come from the CLI's config file and environment
+ * (WALKEROS_TOKEN, APP_URL), so no constructor args are required.
+ */
+declare class HttpToolClient implements ToolClient {
+    listProjects(): Promise<unknown>;
+    getProject(options: {
+        projectId?: string;
+    }): Promise<unknown>;
+    createProject(options: {
+        name: string;
+    }): Promise<unknown>;
+    updateProject(options: {
+        projectId?: string;
+        name: string;
+    }): Promise<unknown>;
+    deleteProject(options: {
+        projectId?: string;
+    }): Promise<unknown>;
+    setDefaultProject(projectId: string): void;
+    getDefaultProject(): string | null;
+    listAllFlows(options?: {
+        sort?: string;
+        order?: 'asc' | 'desc';
+        includeDeleted?: boolean;
+    }): Promise<unknown>;
+    listFlows(options: ListFlowsOptions): Promise<unknown>;
+    getFlow(options: {
+        flowId: string;
+        projectId?: string;
+        fields?: string[];
+    }): Promise<unknown>;
+    createFlow(options: {
+        name: string;
+        content: Record<string, unknown>;
+        projectId?: string;
+    }): Promise<unknown>;
+    updateFlow(options: {
+        flowId: string;
+        projectId?: string;
+        name?: string;
+        content?: Record<string, unknown>;
+        mergePatch?: boolean;
+    }): Promise<unknown>;
+    deleteFlow(options: {
+        flowId: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    duplicateFlow(options: {
+        flowId: string;
+        name?: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    listPreviews(options: ListPreviewsOptions): Promise<unknown>;
+    getPreview(options: GetPreviewOptions): Promise<unknown>;
+    createPreview(options: CreatePreviewOptions): Promise<unknown>;
+    deletePreview(options: DeletePreviewOptions): Promise<unknown>;
+    deploy(options: DeployOptions): Promise<unknown>;
+    listDeployments(options: ListDeploymentsOptions): Promise<unknown>;
+    getDeploymentBySlug(options: {
+        slug: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    deleteDeployment(options: {
+        slug: string;
+        projectId?: string;
+    }): Promise<unknown>;
+    requestDeviceCode(): Promise<DeviceCodeResult>;
+    pollForToken(deviceCode: string, options?: {
+        timeoutMs?: number;
+    }): Promise<PollResult>;
+    whoami(): Promise<unknown>;
+    resolveToken(): {
+        token: string;
+        source: 'env' | 'config';
+    } | null;
+    deleteConfig(): boolean;
+    submitFeedback(text: string, options?: FeedbackOptions): Promise<void>;
+    getFeedbackPreference(): boolean | undefined;
+    setFeedbackPreference(anonymous: boolean): void;
+}
+
+interface CreateStreamableHttpHandlerOptions extends WebStandardStreamableHTTPServerTransportOptions {
+    /**
+     * Called after a session is initialized. Wraps onsessioninitialized.
+     */
+    onSessionInitialized?: (sessionId: string) => void | Promise<void>;
+}
+/**
+ * Returns a Fetch-style handler: `(Request) => Promise<Response>`.
+ *
+ * Single call creates a dedicated transport instance and connects it to the
+ * given `McpServer`. The handler holds that transport for its entire
+ * lifetime, call `createStreamableHttpHandler` once per app lifecycle, not
+ * per request. For multi-session hosting (different users, persistent
+ * sessions), instantiate one handler per session keyed by `Mcp-Session-Id`
+ * at the Route Handler layer; this factory is the session-agnostic
+ * building block.
+ */
+declare function createStreamableHttpHandler(server: McpServer, opts?: CreateStreamableHttpHandlerOptions): (request: Request) => Promise<Response>;
+
+/**
+ * Wraps a user-writable string in `<user_data>…</user_data>` so the chat
+ * assistant treats it as data, never as instructions. Inner `</user_data>`
+ * sequences are mangled (`</user_data_>`) so a malicious string can't close
+ * the envelope early.
+ *
+ * Idempotent: a string that is already a well-formed envelope with no inner
+ * `</user_data>` is returned unchanged.
+ */
+declare function wrapUserData(s: string): string;
+interface RedactOptions {
+    /** Return `true` to skip wrapping for a given object key. Only invoked for
+     *  string values on object entries — not for array elements or scalar
+     *  roots. Use to keep ids / slugs / dates literal. */
+    skip?: (key: string) => boolean;
+}
+/**
+ * Recursively walks `value` and returns a deep-copied structure where every
+ * string leaf has been passed through `wrapUserData`. Pass `skip` to exclude
+ * specific keys (e.g. `id`) from wrapping.
+ */
+declare function redactNestedStrings<T>(value: T, opts?: RedactOptions): T;
+
+type SuggestionTile = {
+    label: string;
+    description?: string;
+    prompt: string;
+    autoSend?: boolean;
+};
+interface FlowCanvasPayload {
+    flowId?: string;
+    configName: string;
+    platform: 'web' | 'server';
+    flowConfig: Record<string, unknown>;
+    highlight?: {
+        stepAddress: string;
+        reason: string;
+    };
+    suggestions?: SuggestionTile[];
+}
+interface FlowCanvasToolResult extends FlowCanvasPayload {
+    kind: 'flow-canvas';
+}
+/**
+ * Tool-result helper that marks a response as renderable as a FlowCanvas.
+ * The chat UI inspects `structuredContent.kind === 'flow-canvas'` and mounts
+ * a `FlowCanvasBubble` instead of the generic JSON fallback. The `content[0]`
+ * text is the same JSON stringified — the LLM sees a self-describing object.
+ */
+declare function flowCanvasResult(payload: FlowCanvasPayload): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown> & {
+        kind: "flow-canvas";
+    };
+};
+declare function isFlowCanvasResult(v: unknown): v is FlowCanvasToolResult;
+
+declare module '@walkeros/core' {
+    interface SourceMap {
+        mcp: {
+            type: 'mcp';
+            platform: 'server';
+            tool?: string;
+        };
+    }
+}
+
+/**
+ * Handler-bearing spec for every tool `createWalkerOSMcpServer` registers.
+ *
+ * Consumers that need to drive the tools WITHOUT an `McpServer` (e.g., the
+ * walkerOS app's chat route wrapping them as Vercel AI SDK tools) should call
+ * `createToolHandlers(client)` and iterate the returned record. Handlers are
+ * closed over `client`, so the caller can bind a single `ToolClient` (such as
+ * the zero-hop `ServiceToolClient`) once per session.
+ */
+declare function createToolHandlers(client: ToolClient): Record<string, ToolSpec>;
+
+export { type CreateServerOptions, type CreateStreamableHttpHandlerOptions, type FlowCanvasPayload, type FlowCanvasToolResult, HttpToolClient, type Logger, type RedactOptions, type SuggestionTile, TOOL_DEFINITIONS, type ToolAnnotations, type ToolClient, type ToolDefinition, type ToolSpec, createStreamableHttpHandler, createToolHandlers, createWalkerOSMcpServer, flowCanvasResult, isFlowCanvasResult, redactNestedStrings, wrapUserData };