@walkeros/mcp 4.7.0 → 4.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walkeros/mcp",
-  "version": "4.7.0",
+  "version": "4.7.1",
   "description": "MCP server for walkerOS flow development - discover packages, scaffold configs, validate, bundle, simulate, and test event pipelines",
   "license": "MIT",
   "type": "module",
@@ -14,13 +14,15 @@
     "./stdio": {
       "types": "./dist/stdio.d.ts",
       "default": "./dist/stdio.js"
-    }
+    },
+    "./surface.json": "./src/surface.json"
   },
   "bin": {
     "walkeros-mcp": "./dist/stdio.js"
   },
   "files": [
     "dist/**",
+    "src/surface.json",
     "README.md"
   ],
   "scripts": {
@@ -35,15 +37,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "@walkeros/cli": "4.7.0",
-    "@walkeros/core": "4.7.0"
+    "@walkeros/cli": "4.7.1",
+    "@walkeros/core": "4.7.1"
   },
   "peerDependencies": {
     "zod": "^4.0"
   },
   "devDependencies": {
     "@types/node": "^25.9.1",
-    "@walkeros/config": "4.7.0",
+    "@walkeros/config": "4.7.1",
     "msw": "^2.12.10"
   },
   "repository": {

package/src/surface.json

@@ -0,0 +1,370 @@
+{
+  "$comment": "Shipped as @walkeros/mcp/surface.json; the app asserts its hosted server registers this roster.",
+  "toolNames": [
+    "auth",
+    "deploy_manage",
+    "diagnostics",
+    "feedback",
+    "flow_bundle",
+    "flow_examples",
+    "flow_load",
+    "flow_manage",
+    "flow_push",
+    "flow_simulate",
+    "flow_validate",
+    "frame_manage",
+    "hub_manage",
+    "observe_journeys",
+    "observe_session",
+    "package_get",
+    "package_search",
+    "project_manage",
+    "secret_manage"
+  ],
+  "links": {
+    "$comment": "Deep links the tools emit, under the response key named here. They land in chat transcripts and notes nobody can reach back into, so a route rename or a view-key rename in the app has to fail a test at edit time instead of rotting in someone's history. The builders live in walkerOS packages/mcps/mcp/src/links.ts; the app checks these against its real routes and its url-state registry in src/lib/mcp/__tests__/link-routes.test.ts. A route template names its params as the BUILDER names them, and the app's folder may spell the same segment differently ([id] for {flowId}), so a template is matched by shape and position, never by param name.",
+    "responseKey": "appUrl",
+    "viewParamKey": "view",
+    "routes": {
+      "flowPage": "/projects/{projectId}/flows/{flowId}",
+      "deploymentPage": "/projects/{projectId}/deployments/{deploymentId}"
+    },
+    "views": {
+      "contract": [],
+      "releases": [],
+      "step": ["flow", "step"]
+    }
+  },
+  "observeSession": {
+    "name": "observe_session",
+    "title": "Observe Session",
+    "description": "Open, inspect, or end an Observe session: a time-boxed window on one flow that runtimes attach to as arms. A preview arm streams from a browser, a container arm runs server-side, and both feed ONE shared journeys feed. start opens the window (arms picks which runtimes attach), status reports per-arm state plus recordsReceived and expiresAt, stop ends the whole session including every arm. A flow has at most one session, so status/stop resolve it from flowId when sessionId is omitted. Read the events with observe_journeys; this tool never returns event data and never judges whether events are correct.",
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": true,
+      "idempotentHint": false,
+      "openWorldHint": true
+    },
+    "inputSchema": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": ["start", "status", "stop"],
+          "description": "start opens a session, status reports arm state, stop ends the whole session."
+        },
+        "flowId": {
+          "type": "string",
+          "description": "Flow the Observe session runs on."
+        },
+        "projectId": {
+          "description": "Project ID. Optional; falls back to the default project.",
+          "type": "string"
+        },
+        "sessionId": {
+          "description": "Session to act on for status/stop. Optional; the flow has at most one session and it is resolved for you.",
+          "type": "string"
+        },
+        "arms": {
+          "description": "Which runtimes attach. Omit to attach the default preview arm; a web settings that references a server flow brings its container arm with it.",
+          "type": "object",
+          "properties": {
+            "container": {
+              "description": "Pass true to attach the server container arm, which selects the flow's server settings when no preview arm is named. Only true is accepted: a web settings that references a server flow always brings its container arm along, so a container cannot be suppressed here.",
+              "type": "boolean",
+              "const": true
+            },
+            "preview": {
+              "description": "Name the flow settings this session observes. A web settings attaches the browser preview arm (plus the container arm of any server flow it references); a server settings attaches the container arm alone. Omit to use the flow's single web settings.",
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
+        "origins": {
+          "description": "Bare https origins (https://host[:port]) the session may ingest web events from.",
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "level": {
+          "description": "Container observation verbosity. Defaults to the app's own.",
+          "type": "string",
+          "enum": ["off", "standard", "trace"]
+        },
+        "replace": {
+          "description": "Replace the flow's existing window instead of attaching to it. Re-provisions from the new config.",
+          "type": "boolean"
+        }
+      },
+      "required": ["action", "flowId"],
+      "additionalProperties": false
+    },
+    "hints": {
+      "SIMULATE_FIRST": "Simulate before preview: flow_simulate checks mapping with no browser.",
+      "PREVIEW_STREAMS": "Preview streams into this session: mint a link with flow_manage preview_regrant, then open it on your site.",
+      "READ": "Read with observe_journeys (flowId); it is the only read.",
+      "STOP": "End both arms with observe_session stop.",
+      "EMPTY_FEED": "recordsReceived is 0: nothing has reached the feed yet. Drive traffic on an attached arm.",
+      "ENDED": "Session ended and both arms detached. Start a new one with observe_session start.",
+      "NO_WINDOW": "No Observe session on this flow. Open one with observe_session start."
+    },
+    "hintOrder": {
+      "start": ["SIMULATE_FIRST", "PREVIEW_STREAMS", "READ"],
+      "statusWithRecords": ["READ", "STOP"],
+      "statusEmptyFeed": ["EMPTY_FEED", "READ", "STOP"],
+      "statusNoWindow": ["NO_WINDOW", "SIMULATE_FIRST"],
+      "stopEnded": ["ENDED"],
+      "stopNoWindow": ["NO_WINDOW"]
+    }
+  },
+  "hubManage": {
+    "name": "hub_manage",
+    "title": "Release History and Rationale",
+    "description": "Read a flow’s release history and the reasoning behind it: what each release changed, and why. Actions: releases (lean index of a flow’s releases, newest first, no snapshots), release_get (one release in full: its rationale plus a server-computed diff against the release before it), step_history (which releases added, changed, or removed one step), rationale_set (write the human rationale for one release; additive, nothing is ever deleted), threads (the discussion anchored to one release, or every open discussion on the flow), note_add (add a message to a thread, or open a new one on a release), knowledge (read what people wrote on the marks of a page in Tag Mode: one page, one mark, or the whole project). Threads are resolved by a person in the app, never here: this tool can only add to a discussion. Knowledge is read-only here for the same reason, and is addressed by frame and mark rather than by flow. Steps are addressed as \"type.name\", the same form flow_simulate takes, for example \"destination.ga4\", \"transformer.router\", \"source.browser\", \"store.session\", or \"contract.checkout\" for a contract entry. This tool carries history only: use flow_manage for the current config and package_get for step schemas.",
+    "annotations": {
+      "readOnlyHint": false,
+      "destructiveHint": false,
+      "idempotentHint": false,
+      "openWorldHint": true
+    },
+    "inputSchema": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": [
+            "releases",
+            "release_get",
+            "step_history",
+            "rationale_set",
+            "threads",
+            "note_add",
+            "knowledge"
+          ],
+          "description": "Which part of the release history to read or write"
+        },
+        "projectId": {
+          "description": "Project ID. Optional: falls back to the default project when omitted.",
+          "type": "string"
+        },
+        "flowId": {
+          "description": "Flow ID (flow_...). Required for every action except \"knowledge\", which hangs on a page rather than a flow and refuses this field.",
+          "type": "string"
+        },
+        "versionId": {
+          "description": "Release version ID (ver_...) from action \"releases\". Addresses one release for release_get and rationale_set. Pass this or versionNumber.",
+          "type": "string",
+          "minLength": 1
+        },
+        "versionNumber": {
+          "description": "Spine release number for this flow, the `versionNumber` field of action \"releases\". Alternative to versionId. Not the same as a row's deploymentAttempt.",
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "step": {
+          "description": "Step key as \"type.name\", e.g. \"destination.ga4\" or \"contract.checkout\". Required for step_history.",
+          "type": "string"
+        },
+        "flow": {
+          "description": "Named flow inside the config, e.g. \"web\" or \"server\". Optional for step_history: omit to scan every named flow. Ignored for contract steps, which are top-level.",
+          "type": "string"
+        },
+        "text": {
+          "description": "The text to write (1-4000 chars). Required for rationale_set and note_add. As rationale it replaces the note already on the release and never touches the machine summary; as a note it is appended to a thread and nothing is ever replaced.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 4000
+        },
+        "limit": {
+          "description": "Page size. Releases to list for action \"releases\" (max 100), or releases to SCAN for step_history (max 50). For step_history this bounds releases, not entries: a step present in several named flows yields one entry per flow per release, and the scan stops at 200 entries with entriesTruncated set. Narrow with \"flow\" to avoid that. For threads it bounds threads, and a read that carries messages is held to 20 of them. Knowledge entries are bounded the same way.",
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 9007199254740991
+        },
+        "offset": {
+          "description": "Releases to skip. Action \"releases\" only.",
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "anchorType": {
+          "description": "What a thread hangs on. Defaults to \"release\", the only anchor the app writes today. Pair it with anchorKey; a key means a different thing under each type.",
+          "type": "string",
+          "enum": ["step", "entity_action", "release", "contract", "tag"]
+        },
+        "anchorKey": {
+          "description": "What the anchor addresses within its type: a release version ID (ver_...) for \"release\", a \"type.name\" step key for \"step\". For a release you can pass versionId or versionNumber instead. Omit entirely on action \"threads\" to read every thread on the flow.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255
+        },
+        "anchorLabel": {
+          "description": "How the anchor reads on screen, stored once when a thread is opened so a later rename leaves it readable. Derived for a release (\"v14\"); pass it only when opening a thread on another anchor type.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 255
+        },
+        "threadId": {
+          "description": "Thread ID (thr_...) from action \"threads\". Pass it to note_add to reply in that thread; omit it to open a new thread on the anchor.",
+          "type": "string",
+          "minLength": 1
+        },
+        "status": {
+          "description": "Read only threads in this state. Action \"threads\" only; omit for both.",
+          "type": "string",
+          "enum": ["open", "resolved"]
+        },
+        "pageKey": {
+          "description": "The page a note was left on, as Tag Mode addressed it, usually the page URL. Narrows action \"knowledge\" to every frame that page holds, at any depth; omit it to read the whole project.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "frameId": {
+          "description": "One frame (frm_...), the named rectangle a note hangs on. Action \"knowledge\" only. Narrower than pageKey, since a page holds several frames.",
+          "type": "string",
+          "pattern": "^frm_[A-Za-z0-9_-]{21}$"
+        },
+        "markId": {
+          "description": "One tag within \"frameId\", by its tag id (the id of an entry in frame_manage marks.tags). Action \"knowledge\" only, and refused without frameId, since a mark id alone addresses nothing. Naming a mark is also what attaches the message bodies.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        }
+      },
+      "required": ["action"],
+      "additionalProperties": false
+    },
+    "denialHint": "The \"hub\" feature is not enabled for this project. Tell the person that \"hub\" needs a plan or project entitlement that unlocks it, which is changed in the app, not through this tool.",
+    "notFoundHint": "Use action \"releases\" to find version ids and action \"threads\" to find thread ids.",
+    "hints": {
+      "CONFIRM_INDEX": "Use action \"releases\" to confirm it appears in the index.",
+      "ENTRY_NAMES_FLOW": "An entry names the flow it was written against in flowId, and validity says which release was live at the time.",
+      "KEEP_ONE_THREAD": "Pass its threadId back to action \"note_add\" to keep the conversation in one place instead of opening another thread.",
+      "KNOWLEDGE_INDEX": "This is an index: message bodies are omitted. Pass markId with frameId to read one mark in full.",
+      "KNOWLEDGE_PAGE_CAPPED": "More knowledge matches than was returned. Narrow with pageKey, then frameId, then markId, rather than treating this as everything that was written.",
+      "KNOWLEDGE_READ_ONLY": "This tool only reads knowledge. Answering a note, and settling it, are done by a person in the app.",
+      "MASKED_ONLY": "The diff is empty because the only changes are inside masked values. Say that the change is not visible here rather than that nothing changed.",
+      "MESSAGES_TRUNCATED": "A thread here is marked hasMoreMessages: only its newest messages were returned. Say the discussion is longer than what you read rather than summarizing it as complete.",
+      "MESSAGE_VISIBLE": "The message is now visible in this thread in the app.",
+      "NOTHING_DISCUSSED": "Nothing is being discussed on this flow. Use action \"note_add\" with a versionId to start a thread on a release.",
+      "NOTHING_WRITTEN": "Nothing has been written here. Notes are left on the page in Tag Mode, not through this tool.",
+      "NO_MATCH": "No scanned release touched this step. Check the step key against knownSteps, or raise limit to scan further back.",
+      "NO_THREAD_ON_ANCHOR": "No thread hangs on this anchor yet. Use action \"note_add\" to open one.",
+      "OPEN_RELEASE": "Use action \"release_get\" on one of these versionIds to read the full diff and rationale.",
+      "RATIONALE_VISIBLE": "The rationale is now visible on this release in the app.",
+      "READ_BACK": "Use action \"threads\" to read the discussion back.",
+      "READ_FRAME": "Use frame_manage action \"get\" with the frameId to read the frame and its marks.",
+      "RELEASE_GET": "Use action \"release_get\" with a versionId or versionNumber to read one release in full, with its diff.",
+      "REPLY_OR_OPEN": "Use action \"note_add\" with a threadId to reply in one of these threads, or without one to open another.",
+      "RESOLVE_IN_APP": "Resolving a thread into a release is done by a person in the app, not through this tool.",
+      "ROWS_ARE_DEPLOYMENTS": "Rows are deployments, not releases: the same versionId on several rows is a redeploy of identical content, so count distinct versionId values, and note that total counts deployments.",
+      "SCAN_CAPPED": "The scan stopped at the entry cap, so older releases were not compared. Narrow with \"flow\" to see the whole history of one occurrence.",
+      "STAYS_RESOLVED": "This thread is resolved and stayed resolved: a reply never retracts the release link.",
+      "STEP_HISTORY": "Use action \"step_history\" to see which releases touched one step.",
+      "THREADS_INDEX": "This is an index: message bodies are omitted. Pass a versionId, or anchorType with anchorKey, to read one discussion in full.",
+      "THREADS_PAGE_CAPPED": "More threads match than were returned (the page is capped at 20 when messages are attached). Narrow with anchorType and anchorKey, or with status, rather than treating this as the complete list.",
+      "THREAD_OPEN": "The thread is now open on this anchor in the app.",
+      "TRACE_STEP": "Use action \"step_history\" to trace one step across releases.",
+      "WRITE_RATIONALE": "This release has no human rationale. Read the diff, then use action \"rationale_set\" to record why it changed."
+    },
+    "hintOrder": {
+      "releases": ["RELEASE_GET", "ROWS_ARE_DEPLOYMENTS", "STEP_HISTORY"],
+      "releaseGetMaskedOnly": ["MASKED_ONLY"],
+      "releaseGetWithRationale": ["TRACE_STEP"],
+      "releaseGetNoRationale": ["WRITE_RATIONALE"],
+      "stepHistoryCapped": ["SCAN_CAPPED"],
+      "stepHistoryEmpty": ["NO_MATCH"],
+      "stepHistoryMatched": ["OPEN_RELEASE"],
+      "rationaleSet": ["RATIONALE_VISIBLE", "CONFIRM_INDEX"],
+      "threadsIndexEmpty": ["NOTHING_DISCUSSED"],
+      "threadsAnchorEmpty": ["NO_THREAD_ON_ANCHOR"],
+      "threadsIndexCapped": ["THREADS_PAGE_CAPPED", "THREADS_INDEX"],
+      "threadsAnchorTruncated": [
+        "MESSAGES_TRUNCATED",
+        "REPLY_OR_OPEN",
+        "RESOLVE_IN_APP"
+      ],
+      "noteAddReplyOpen": ["MESSAGE_VISIBLE", "READ_BACK"],
+      "noteAddReplyResolved": ["MESSAGE_VISIBLE", "STAYS_RESOLVED"],
+      "noteAddOpen": ["THREAD_OPEN", "KEEP_ONE_THREAD"],
+      "knowledgeEmpty": ["NOTHING_WRITTEN"],
+      "knowledgeIndexCapped": [
+        "KNOWLEDGE_PAGE_CAPPED",
+        "KNOWLEDGE_INDEX",
+        "ENTRY_NAMES_FLOW",
+        "KNOWLEDGE_READ_ONLY",
+        "READ_FRAME"
+      ],
+      "knowledgeMarkTruncated": [
+        "MESSAGES_TRUNCATED",
+        "ENTRY_NAMES_FLOW",
+        "KNOWLEDGE_READ_ONLY",
+        "READ_FRAME"
+      ]
+    }
+  },
+  "frameManage": {
+    "name": "frame_manage",
+    "title": "Frames",
+    "description": "Read the frames of a measurement plan: named rectangles with marks inside them, drawn in Tag Mode or in the app. Actions: list (every frame of the project, without marks), page (the frames of one page at any depth, with marks), get (one frame with its marks). Read-only: frames are drawn and edited in Tag Mode or the app, never here. A frame name is documentation; the marks inside it carry the meaning. A frame that extends another stores only what it adds, so its tags may carry only the fields they change. Marks are { tags, note }: tags is one flat list of tags, each with an id, a kind such as entity, property or action, a name, and a parentId naming the tag it sits under; note is the frame’s own description and thread. Use hub_manage action \"knowledge\" with a frameId or markId to read what people wrote on a frame. A markId is a tag id: a tag’s id, parentId and threadRef come back literal when they have the shape the app mints, so they can be passed straight back; every other string value in the marks is wrapped as data, and so is an object key that is not a plain identifier.",
+    "annotations": {
+      "readOnlyHint": true,
+      "destructiveHint": false,
+      "idempotentHint": true,
+      "openWorldHint": true
+    },
+    "inputSchema": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "object",
+      "properties": {
+        "action": {
+          "type": "string",
+          "enum": ["list", "page", "get"],
+          "description": "list the project’s frames, read one page with marks, or read one frame"
+        },
+        "projectId": {
+          "description": "Project ID. Optional: falls back to the default project when omitted.",
+          "type": "string"
+        },
+        "pageKey": {
+          "description": "The page as its frames address it (the `source.key` of a page frame, usually the page URL without query). Required for page.",
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 1024
+        },
+        "frameId": {
+          "description": "Frame ID (frm_...). Required for get. Use action \"list\" or \"page\" to find one.",
+          "type": "string",
+          "pattern": "^frm_[A-Za-z0-9_-]{21}$"
+        }
+      },
+      "required": ["action"],
+      "additionalProperties": false
+    },
+    "denialHint": "The \"frames\" feature is not enabled for this project. Tell the person that \"frames\" needs a plan or project entitlement that unlocks it, which is changed in the app, not through this tool.",
+    "notFoundHint": "Use action \"list\" or \"page\" to find frame ids.",
+    "hints": {
+      "EXTENDS_BASE": "This frame extends another and stores only what it adds; read the base frame (extends) for the rest.",
+      "MARK_SPACE": "Tag geometry is fractional: a rect is 0..1 of its frame, and an at is 0..1 of its parent tag’s box, or of the frame for a root tag; a child frame sits inside its parent through placements[].rect.",
+      "NAMES_ARE_DOCUMENTATION": "Frame names are documentation; the marks inside a frame carry the meaning.",
+      "NONE_ON_PAGE": "No frames on this page. Check the pageKey against the source.key values from action \"list\".",
+      "NONE_YET": "This project has no frames yet. Frames are drawn in Tag Mode or the app, not through this tool.",
+      "OPEN_PAGE_OR_GET": "Use action \"page\" with a pageKey (a frame’s source.key) to read a page with marks, or action \"get\" with a frameId.",
+      "READ_KNOWLEDGE": "Use hub_manage action \"knowledge\" with frameId (and markId) to read what people wrote here. A markId is a tag id from these marks, and a tag’s threadRef is the id of its thread entry there."
+    },
+    "hintOrder": {
+      "list": ["OPEN_PAGE_OR_GET", "NAMES_ARE_DOCUMENTATION"],
+      "listEmpty": ["NONE_YET"],
+      "page": ["MARK_SPACE", "READ_KNOWLEDGE"],
+      "pageEmpty": ["NONE_ON_PAGE"],
+      "getVariation": ["EXTENDS_BASE", "READ_KNOWLEDGE"],
+      "getBase": ["READ_KNOWLEDGE"]
+    }
+  }
+}