@walkeros/mcp 4.7.0 → 4.7.1

package/README.md

@@ -95,17 +95,17 @@ The server registers 19 tools.
 
 ### Local, no account
 
-| Tool             | Description                                                                        |
-| ---------------- | ---------------------------------------------------------------------------------- |
-| `flow_load`      | Load a flow from a file path, URL, inline JSON, or flow ID, or create an empty one |
-| `flow_validate`  | Validate an event, flow config, mapping rule, or data contract                     |
-| `flow_simulate`  | Run an event through a flow with mocked vendor calls and inspect each step         |
-| `flow_bundle`    | Compile a flow into a tree-shaken, deployable JavaScript bundle                    |
-| `flow_push`      | Push a real event through a flow to real destinations, making real API calls       |
-| `flow_examples`  | List the step examples in a flow, the fixtures simulation can replay               |
-| `package_search` | Find packages by name, type, or platform. The entry point for package discovery    |
-| `package_get`    | Read one package's schemas, configuration hints, and examples by exact name        |
-| `diagnostics`    | Report MCP and CLI versions, app URL, backend, and whether the app is reachable    |
+| Tool             | Description                                                                          |
+| ---------------- | ------------------------------------------------------------------------------------ |
+| `flow_load`      | Load a flow from a file path, URL, inline JSON, or flow ID, or create an empty one   |
+| `flow_validate`  | Validate an event, flow config, mapping rule, or data contract                       |
+| `flow_simulate`  | Run an event through a flow with mocked vendor calls and inspect each step           |
+| `flow_bundle`    | Compile a flow into a tree-shaken, deployable JavaScript bundle                      |
+| `flow_push`      | Push a real event through a flow to real destinations, making real API calls         |
+| `flow_examples`  | List the step examples in a flow, the fixtures simulation can replay                 |
+| `package_search` | Find packages by name, type, or platform. The entry point for package discovery      |
+| `package_get`    | Read one package's schemas, configuration hints, and examples by exact name          |
+| `diagnostics`    | Report MCP and CLI versions, app URL, app reachability, and the API contract verdict |
 
 ### walkerOS cloud
 
@@ -132,7 +132,7 @@ The server registers 19 tools.
 | `walkeros://reference/consent`     | The consent model at destination, rule, and field level         |
 | `walkeros://reference/variables`   | Variable patterns: `$var`, `$env`, `$secret`, `$code`, `$store` |
 | `walkeros://reference/contract`    | Event schemas, wildcards, and inheritance                       |
-| `walkeros://reference/openapi`     | OpenAPI 3.1 specification for the walkerOS API                  |
+| `walkeros://reference/openapi`     | The live OpenAPI 3.1 document of the app this server talks to   |
 | `walkeros://reference/packages`    | The full package catalog                                        |
 | `walkeros://schema/{packageName}`  | JSON schema for one package                                     |
 
@@ -193,6 +193,12 @@ AI SDK, call `createToolHandlers(client, version, runtime)` or import
 `TOOL_DEFINITIONS` and supply your own `ToolClient`. The stdio binary stays
 available as `@walkeros/mcp/stdio` and the `walkeros-mcp` bin entry.
 
+A `ToolClient` may implement `checkContract()` and `openapiDocument()`. The
+`diagnostics` tool reports the first as its contract verdict, `unknown` when it
+is absent; the `walkeros://reference/openapi` resource serves the second.
+`HttpToolClient` implements both against the app it talks to. The tool roster
+ships as `@walkeros/mcp/surface.json`.
+
 ## Documentation
 
 Full parameter tables, workflows, and examples live in the docs:

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ListFlowsOptions, ListPreviewsOptions, GetPreviewOptions, CreatePreviewOptions, DeletePreviewOptions, ListSecretsOptions, CreateSecretOptions, UpdateSecretOptions, DeleteSecretOptions, DeployOptions, ListDeploymentsOptions, DeviceAuthorization, DeviceLoginResult, FeedbackOptions, BundleStats, PushResult } from '@walkeros/cli';
+import { ListFlowsOptions, ListPreviewsOptions, GetPreviewOptions, CreatePreviewOptions, DeletePreviewOptions, ListSecretsOptions, CreateSecretOptions, UpdateSecretOptions, DeleteSecretOptions, DeployOptions, ListDeploymentsOptions, DeviceAuthorization, DeviceLoginResult, ContractComparison, FeedbackOptions, BundleStats, PushResult } from '@walkeros/cli';
 import { Journey, JourneyGap, JourneyUnattributed, Flow, Ingest, WalkerOS, Simulation } from '@walkeros/core';
 import { ZodRawShape, z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
@@ -81,12 +81,18 @@ interface ObserveSessionResult {
     flowId: string;
     status: string;
     errorMessage: string | null;
+    /** The flow config the session was opened on, as the app snapshotted it. */
+    configSnapshot: Record<string, unknown>;
     observedFlowName: string | null;
     serverFlowName: string | null;
+    /** Legacy mirror of `server.endpoint`, kept for published readers; read `server.endpoint`. */
+    serverEndpoint: string | null;
     web: ObserveSessionWebPart | null;
     server: ObserveSessionServerPart | null;
     expiresAt: string;
     recordsReceived: number;
+    /** Id of the user who opened the session. */
+    createdBy: string;
     createdAt: string;
 }
 /**
@@ -545,7 +551,21 @@ interface ToolClient {
         reachable: boolean;
         status?: string;
         version?: string;
+        error?: string;
     }>;
+    /**
+     * The API contract verdict for this door against the app it talks to
+     * (`appBaseUrl()`). A door that calls the app over HTTP compares per
+     * operation; a door served inside the app answers `in-process`. Optional:
+     * without it, diagnostics reports `unknown`.
+     */
+    checkContract?(): Promise<ContractComparison>;
+    /**
+     * The live OpenAPI document of the app this door talks to, served as the
+     * `walkeros://reference/openapi` resource. Rejects when it cannot be read.
+     * Optional: without it, the resource states that it is unavailable.
+     */
+    openapiDocument?(): Promise<unknown>;
     submitFeedback(text: string, options?: FeedbackOptions): Promise<void>;
     getFeedbackPreference(): boolean | undefined;
     setFeedbackPreference(anonymous: boolean): void;
@@ -898,16 +918,24 @@ declare class HttpToolClient implements ToolClient {
      */
     appBaseUrl(): string;
     /**
-     * Unauthenticated reachability probe of the app's PUBLIC `/api/health`
-     * route. Uses a plain `fetch` (no `createApiClient`, whose every request
-     * rejects without a credential) so diagnostics works logged-out. Resolves
-     * `{ reachable: false }` only on a real network/timeout failure.
+     * Unauthenticated reachability probe of the app's PUBLIC health route
+     * (`GET /api/health`) at `appBaseUrl()`, through the CLI's `fetchHealth`.
+     * Sends no credential, so diagnostics works logged-out. Resolves
+     * `{ reachable: false, error }` only on a real network/timeout failure.
      */
     checkHealth(): Promise<{
         reachable: boolean;
         status?: string;
         version?: string;
+        error?: string;
     }>;
+    /**
+     * The contract verdict for this MCP against `appBaseUrl()`, per operation,
+     * naming `@walkeros/mcp` as the client.
+     */
+    checkContract(): Promise<ContractComparison>;
+    /** The live public OpenAPI document of `appBaseUrl()`, without a credential. */
+    openapiDocument(): Promise<unknown>;
     submitFeedback(text: string, options?: FeedbackOptions): Promise<void>;
     getFeedbackPreference(): boolean | undefined;
     setFeedbackPreference(anonymous: boolean): void;