@sapiom/mcp 0.7.2 → 0.8.1

package/README.md

@@ -0,0 +1,103 @@
+# @sapiom/mcp
+
+The **local developer** MCP server for Sapiom. It runs on your machine over
+stdio under the server name `sapiom-dev` — the unmetered `sapiom_dev_*` surface
+for building and operating on Sapiom. Today it gives a coding agent the tools to
+scaffold, test, deploy, and inspect Sapiom orchestrations; the namespace leaves
+room for other non-capability developer tooling later.
+
+> **Not the capability surface.** This is *not* the remote "Sapiom" MCP (the
+> hosted connector with `sapiom_sandbox_*`, scrape, search, … capability tools).
+> `sapiom-dev` is the local developer surface; it makes no paid capability calls
+> and exposes no capability tools. See
+> [the two Sapiom MCP servers](../../docs/mcp-servers.md) for which to use when.
+
+## Install
+
+No global install — run it on demand with `npx`:
+
+```jsonc
+{
+  "mcpServers": {
+    "sapiom-dev": {
+      "command": "npx",
+      "args": ["-y", "@sapiom/mcp"]
+    }
+  }
+}
+```
+
+In Claude Code:
+
+```sh
+claude mcp add sapiom-dev -- npx -y @sapiom/mcp
+```
+
+## Configuration
+
+The server targets the `production` environment by default. Override it with the
+`SAPIOM_ENVIRONMENT` environment variable:
+
+```jsonc
+{
+  "mcpServers": {
+    "sapiom-dev": {
+      "command": "npx",
+      "args": ["-y", "@sapiom/mcp"],
+      "env": { "SAPIOM_ENVIRONMENT": "staging" }
+    }
+  }
+}
+```
+
+- `production` (alias `prod`) → `app.sapiom.ai` / `api.sapiom.ai` — the default.
+- `staging` (alias `dev`) → `app.sapiom.dev` / `api.sapiom.dev`.
+
+Both resolve from built-in presets, so no config file is required. A custom
+target can be defined in `~/.sapiom/credentials.json` (the server prints the
+expected shape if it encounters an unknown environment name).
+
+## Authentication
+
+The first networked call (`link`, `deploy`, `run`, `inspect`, `signal`) needs a
+Sapiom API key. Run **`sapiom_authenticate`** and the server opens a browser
+login flow, then caches the resulting key per environment in
+`~/.sapiom/credentials.json`. After that, tools work without re-authenticating.
+`sapiom_status` reports who you're authenticated as; `sapiom_logout` clears the
+cached credentials.
+
+The local authoring tools (`scaffold`, `check`, `run_local`) need no
+authentication — they run entirely offline.
+
+## Tools
+
+| Tool | Network | What it does |
+| --- | --- | --- |
+| `sapiom_authenticate` | browser | Log in and cache an API key for the current environment |
+| `sapiom_status` | — | Report authentication status |
+| `sapiom_logout` | — | Clear cached credentials |
+| `sapiom_dev_orchestrations_scaffold` | — | Create a new orchestration project |
+| `sapiom_dev_orchestrations_check` | — | Bundle + validate the step graph offline |
+| `sapiom_dev_orchestrations_run_local` | — | Run the workflow locally, resolving capability calls from stubs (no cost) |
+| `sapiom_dev_orchestrations_link` | ✓ | Resolve/create the hosted orchestration and cache its id |
+| `sapiom_dev_orchestrations_deploy` | ✓ | Push the current commit, build, and wait for it |
+| `sapiom_dev_orchestrations_run` | ✓ | Start a real cloud execution |
+| `sapiom_dev_orchestrations_inspect` | ✓ | Inspect an execution or build (optionally waiting for it) |
+| `sapiom_dev_orchestrations_signal` | ✓ | Resume a paused execution by delivering a signal |
+
+A typical loop: `scaffold` → write step code → `run_local` until green → `link`
+→ `deploy` → `run` → `inspect`.
+
+## How capabilities fit in
+
+Workflows authored here call Sapiom capabilities — sandboxes, repositories,
+coding agents, search, storage, content generation — through
+[`@sapiom/tools`](../tools) (`ctx.sapiom.*`). `run_local` resolves those calls
+from stubs; a real `run`/`deploy` executes them in the cloud (metered). This MCP
+never grows a per-capability tool of its own — capabilities live in
+`@sapiom/tools` and the remote `sapiom` MCP. See
+[the positioning doc](../../docs/mcp-servers.md) for the full policy.
+
+## License
+
+MIT

package/dist/index.js

@@ -5,16 +5,33 @@ import { resolveEnvironment } from "./credentials.js";
 import { register as registerAuthenticate } from "./tools/authenticate.js";
 import { register as registerStatus } from "./tools/status.js";
 import { register as registerOrchestrations } from "./tools/orchestrations.js";
+import { fetchInstructions } from "./instructions-fetch.js";
 async function main() {
     // Resolve environment: SAPIOM_ENVIRONMENT env var > file > "production"
     const env = await resolveEnvironment(process.env.SAPIOM_ENVIRONMENT);
     if (env.name !== "production") {
         console.error(`\u26a0 Using environment "${env.name}": app=${env.appURL} api=${env.apiURL}`);
     }
+    // Pull the latest authoring instructions from the backend (falls back to the
+    // bundled copy offline / on error), so guidance can change without a release.
+    const instructions = await fetchInstructions(env);
     const server = new McpServer({
-        // The local dev surface — distinct from the remote Sapiom capabilities MCP.
+        // The local developer surface — distinct from the remote Sapiom
+        // capabilities MCP. This is the unmetered `sapiom_dev_*` namespace for
+        // building and operating on Sapiom (today: orchestration authoring &
+        // lifecycle; room for more dev tooling later). The `name` is the stable
+        // wire identifier; `title` and `description` are what MCP clients show, so
+        // they spell out which Sapiom this is to keep it from reading as a
+        // duplicate of the capability server.
         name: "sapiom-dev",
+        title: "Sapiom Dev — local developer tools",
+        description: "The local, unmetered Sapiom developer MCP (sapiom_dev_*). Today it scaffolds, tests, deploys, and inspects orchestrations. Not the remote Sapiom capability MCP — it makes no paid capability calls.",
         version: "0.1.0",
+    }, {
+        // Returned in the MCP `initialize` handshake; capable clients surface it to the
+        // model on connect, so an agent that adds this server gets the authoring primer
+        // automatically. Fetched from the backend; bundled fallback in ./instructions.ts.
+        instructions,
     });
     // Register all tools
     registerAuthenticate(server, env);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,QAAQ,IAAI,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAE/E,KAAK,UAAU,IAAI;IACjB,wEAAwE;IACxE,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAErE,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CACX,6BAA6B,GAAG,CAAC,IAAI,UAAU,GAAG,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,CAC9E,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,4EAA4E;QAC5E,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,OAAO;KACjB,CAAC,CAAC;IAEH,qBAAqB;IACrB,oBAAoB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClC,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,sBAAsB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEpC,8BAA8B;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;AAC1D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,QAAQ,IAAI,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,QAAQ,IAAI,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAAE,QAAQ,IAAI,sBAAsB,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAE5D,KAAK,UAAU,IAAI;IACjB,wEAAwE;IACxE,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAErE,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;QAC9B,OAAO,CAAC,KAAK,CACX,6BAA6B,GAAG,CAAC,IAAI,UAAU,GAAG,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,CAC9E,CAAC;IACJ,CAAC;IAED,6EAA6E;IAC7E,8EAA8E;IAC9E,MAAM,YAAY,GAAG,MAAM,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAElD,MAAM,MAAM,GAAG,IAAI,SAAS,CAC1B;QACE,gEAAgE;QAChE,uEAAuE;QACvE,qEAAqE;QACrE,wEAAwE;QACxE,2EAA2E;QAC3E,mEAAmE;QACnE,sCAAsC;QACtC,IAAI,EAAE,YAAY;QAClB,KAAK,EAAE,oCAAoC;QAC3C,WAAW,EACT,sMAAsM;QACxM,OAAO,EAAE,OAAO;KACjB,EACD;QACE,gFAAgF;QAChF,gFAAgF;QAChF,kFAAkF;QAClF,YAAY;KACb,CACF,CAAC;IAEF,qBAAqB;IACrB,oBAAoB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAClC,cAAc,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC5B,sBAAsB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAEpC,8BAA8B;IAC9B,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;AAC1D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;IACnC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/instructions-fetch.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedEnvironment } from "./credentials.js";
+/**
+ * Fetch the authoring instructions from the Sapiom backend
+ * (`GET {apiURL}/v1/mcp/instructions`, public / no auth), so the guidance a
+ * coding agent receives on connect can change without republishing this package.
+ *
+ * Falls back to the bundled {@link AUTHORING_INSTRUCTIONS} on any failure — a
+ * non-200, an empty body, a network error, or a timeout. Never throws: the MCP
+ * server must always start with usable instructions, online or off.
+ */
+export declare function fetchInstructions(env: ResolvedEnvironment): Promise<string>;
+//# sourceMappingURL=instructions-fetch.d.ts.map

package/dist/instructions-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions-fetch.d.ts","sourceRoot":"","sources":["../src/instructions-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAM5D;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAgBjF"}

package/dist/instructions-fetch.js

@@ -0,0 +1,33 @@
+import { AUTHORING_INSTRUCTIONS } from "./instructions.js";
+/** How long to wait for the instructions endpoint before falling back. */
+const FETCH_TIMEOUT_MS = 5000;
+/**
+ * Fetch the authoring instructions from the Sapiom backend
+ * (`GET {apiURL}/v1/mcp/instructions`, public / no auth), so the guidance a
+ * coding agent receives on connect can change without republishing this package.
+ *
+ * Falls back to the bundled {@link AUTHORING_INSTRUCTIONS} on any failure — a
+ * non-200, an empty body, a network error, or a timeout. Never throws: the MCP
+ * server must always start with usable instructions, online or off.
+ */
+export async function fetchInstructions(env) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+        const response = await fetch(`${env.apiURL}/v1/mcp/instructions`, {
+            headers: { Accept: "text/markdown, text/plain" },
+            signal: controller.signal,
+        });
+        if (!response.ok)
+            return AUTHORING_INSTRUCTIONS;
+        const body = (await response.text()).trim();
+        return body.length > 0 ? body : AUTHORING_INSTRUCTIONS;
+    }
+    catch {
+        return AUTHORING_INSTRUCTIONS;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+//# sourceMappingURL=instructions-fetch.js.map

package/dist/instructions-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions-fetch.js","sourceRoot":"","sources":["../src/instructions-fetch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,0EAA0E;AAC1E,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,GAAwB;IAC9D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,gBAAgB,CAAC,CAAC;IACvE,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,GAAG,CAAC,MAAM,sBAAsB,EAAE;YAChE,OAAO,EAAE,EAAE,MAAM,EAAE,2BAA2B,EAAE;YAChD,MAAM,EAAE,UAAU,CAAC,MAAM;SAC1B,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,EAAE;YAAE,OAAO,sBAAsB,CAAC;QAChD,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,sBAAsB,CAAC;IACzD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,sBAAsB,CAAC;IAChC,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;AACH,CAAC"}

package/dist/instructions.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The MCP server `instructions` string, returned during the `initialize` handshake.
+ * Capable MCP clients surface it to the model on connect, so an agent that adds this
+ * server gets a workflow-authoring primer without any extra setup.
+ *
+ * Kept intentionally short — it stays in the model's context for the whole session, and
+ * points to the full documentation and the `AGENTS.md` generated into each scaffolded
+ * project rather than restating them.
+ */
+export declare const AUTHORING_INSTRUCTIONS = "# Sapiom dev MCP (sapiom-dev)\n\n`sapiom-dev` is Sapiom's local developer MCP \u2014 the terminal surface for setting up and managing\nyour Sapiom projects. Today it drives **workflow authoring** (more dev/management tools will land\nhere over time): these tools build, test, and deploy a Sapiom workflow \u2014 a\n`defineOrchestration({ name, entry, steps })` (from `@sapiom/orchestration`) where each step's\n`run(input, ctx)` does work and returns a directive. All from the terminal; no dashboard.\n\n## Two ways to use Sapiom\nThis server (`sapiom-dev`) is where you **author workflows** \u2014 the\n`sapiom_dev_orchestrations_*` tools build, test, and deploy them. For a **one-off capability call** without authoring a\nworkflow, use Sapiom's **remote MCP** at `https://api.sapiom.ai/v1/mcp`\n(`claude mcp add sapiom --transport http https://api.sapiom.ai/v1/mcp`) \u2014 it exposes every\ncapability as a direct `sapiom_*` tool (e.g. `sapiom_search`; run `tool_discover` to find the right one) \u2014 or call the gateway from code with the SDK\n(`@sapiom/fetch`). Rule of thumb: author a workflow for anything multi-step, scheduled, or\ndeployable; use the remote MCP or the SDK for a single action.\n\n## Lifecycle (in order)\n1. `sapiom_authenticate` \u2014 browser login; caches an API key (makes you an API-key principal,\n   required for deploy/run). Confirm with `sapiom_status`.\n2. `sapiom_dev_orchestrations_scaffold` \u2014 writes a project. READ its `AGENTS.md` first; it is\n   the full authoring guide, shipped inside every scaffold. Then `npm install`.\n3. Test for free: `npm run typecheck` \u2192 `sapiom_dev_orchestrations_check` (validates the step\n   graph, offline) \u2192 `sapiom_dev_orchestrations_run_local` (capabilities are stubbed; zero spend).\n4. Ship: `sapiom_dev_orchestrations_link` \u2192 `_deploy` \u2192 `_run` (real, billed) \u2192 `_inspect`.\n\n## Canonical rules (types are the source of truth \u2014 run `npm run typecheck`)\n- Import `defineOrchestration`, `defineStep`, and the directives\n  (`goto` / `terminate` / `fail` / `retry` / `pauseUntilSignal`) from `@sapiom/orchestration`.\n  NEVER `defineWorkflow` or `@sapiom/workflow-sdk` (they do not exist). Import Zod from `zod/v4`.\n- `defineStep({ name, next, terminal?, canFail?, pause?, inputSchema?, run })`:\n  `terminate()` requires `terminal: true`; `fail()` requires `canFail: true`;\n  `pauseUntilSignal(handle, \u2026)` requires `pause: { signal, resumeStep }`; every `goto` target\n  must be listed in `next[]`. TypeScript enforces all of these.\n- Cross-step state: `ctx.shared` \u2014 the entry input reaches only the entry step.\n- Capabilities run via `ctx.sapiom.*` (sandboxes, repositories, agent(+coding), orchestrations,\n  fileStorage, contentGeneration.{images,video}, search, database) \u2014 a typed subset of the gateway\n  catalog; use autocomplete/typecheck.\n\nFull reference: https://docs.sapiom.ai/workflows/quick-start (authoring \u00B7 capabilities \u00B7 reference \u00B7 examples)\nand the `AGENTS.md` inside your scaffolded project.";
+//# sourceMappingURL=instructions.d.ts.map

package/dist/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,+/FAwCmB,CAAC"}

package/dist/instructions.js

@@ -0,0 +1,51 @@
+/**
+ * The MCP server `instructions` string, returned during the `initialize` handshake.
+ * Capable MCP clients surface it to the model on connect, so an agent that adds this
+ * server gets a workflow-authoring primer without any extra setup.
+ *
+ * Kept intentionally short — it stays in the model's context for the whole session, and
+ * points to the full documentation and the `AGENTS.md` generated into each scaffolded
+ * project rather than restating them.
+ */
+export const AUTHORING_INSTRUCTIONS = `# Sapiom dev MCP (sapiom-dev)
+
+\`sapiom-dev\` is Sapiom's local developer MCP — the terminal surface for setting up and managing
+your Sapiom projects. Today it drives **workflow authoring** (more dev/management tools will land
+here over time): these tools build, test, and deploy a Sapiom workflow — a
+\`defineOrchestration({ name, entry, steps })\` (from \`@sapiom/orchestration\`) where each step's
+\`run(input, ctx)\` does work and returns a directive. All from the terminal; no dashboard.
+
+## Two ways to use Sapiom
+This server (\`sapiom-dev\`) is where you **author workflows** — the
+\`sapiom_dev_orchestrations_*\` tools build, test, and deploy them. For a **one-off capability call** without authoring a
+workflow, use Sapiom's **remote MCP** at \`https://api.sapiom.ai/v1/mcp\`
+(\`claude mcp add sapiom --transport http https://api.sapiom.ai/v1/mcp\`) — it exposes every
+capability as a direct \`sapiom_*\` tool (e.g. \`sapiom_search\`; run \`tool_discover\` to find the right one) — or call the gateway from code with the SDK
+(\`@sapiom/fetch\`). Rule of thumb: author a workflow for anything multi-step, scheduled, or
+deployable; use the remote MCP or the SDK for a single action.
+
+## Lifecycle (in order)
+1. \`sapiom_authenticate\` — browser login; caches an API key (makes you an API-key principal,
+   required for deploy/run). Confirm with \`sapiom_status\`.
+2. \`sapiom_dev_orchestrations_scaffold\` — writes a project. READ its \`AGENTS.md\` first; it is
+   the full authoring guide, shipped inside every scaffold. Then \`npm install\`.
+3. Test for free: \`npm run typecheck\` → \`sapiom_dev_orchestrations_check\` (validates the step
+   graph, offline) → \`sapiom_dev_orchestrations_run_local\` (capabilities are stubbed; zero spend).
+4. Ship: \`sapiom_dev_orchestrations_link\` → \`_deploy\` → \`_run\` (real, billed) → \`_inspect\`.
+
+## Canonical rules (types are the source of truth — run \`npm run typecheck\`)
+- Import \`defineOrchestration\`, \`defineStep\`, and the directives
+  (\`goto\` / \`terminate\` / \`fail\` / \`retry\` / \`pauseUntilSignal\`) from \`@sapiom/orchestration\`.
+  NEVER \`defineWorkflow\` or \`@sapiom/workflow-sdk\` (they do not exist). Import Zod from \`zod/v4\`.
+- \`defineStep({ name, next, terminal?, canFail?, pause?, inputSchema?, run })\`:
+  \`terminate()\` requires \`terminal: true\`; \`fail()\` requires \`canFail: true\`;
+  \`pauseUntilSignal(handle, …)\` requires \`pause: { signal, resumeStep }\`; every \`goto\` target
+  must be listed in \`next[]\`. TypeScript enforces all of these.
+- Cross-step state: \`ctx.shared\` — the entry input reaches only the entry step.
+- Capabilities run via \`ctx.sapiom.*\` (sandboxes, repositories, agent(+coding), orchestrations,
+  fileStorage, contentGeneration.{images,video}, search, database) — a typed subset of the gateway
+  catalog; use autocomplete/typecheck.
+
+Full reference: https://docs.sapiom.ai/workflows/quick-start (authoring · capabilities · reference · examples)
+and the \`AGENTS.md\` inside your scaffolded project.`;
+//# sourceMappingURL=instructions.js.map

package/dist/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../src/instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;sDAwCgB,CAAC"}

package/dist/tools/authenticate.js

@@ -1,7 +1,7 @@
 import { readCredentials, writeCredentials, } from "../credentials.js";
 import { performBrowserAuth } from "../auth.js";
 export function register(server, env) {
-    server.tool("sapiom_authenticate", "Authenticate with Sapiom by opening a browser login flow. Run this when other Sapiom tools report that authentication is required.", {}, async () => {
+    server.tool("sapiom_authenticate", "Authenticate this local Sapiom developer MCP (sapiom-dev) by opening a browser login flow. Run this when a networked orchestration tool (link/deploy/run/inspect/signal) reports that authentication is required.", {}, async () => {
         // Check if already authenticated
         const existing = await readCredentials(env.name);
         if (existing) {

package/dist/tools/authenticate.js.map

@@ -1 +1 @@
-{"version":3,"file":"authenticate.js","sourceRoot":"","sources":["../../src/tools/authenticate.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,UAAU,QAAQ,CAAC,MAAiB,EAAE,GAAwB;IAClE,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,oIAAoI,EACpI,EAAE,EACF,KAAK,IAAI,EAAE;QACT,iCAAiC;QACjC,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,4BAA4B,QAAQ,CAAC,gBAAgB,aAAa,QAAQ,CAAC,QAAQ,iDAAiD;qBAC3I;iBACF;aACF,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAEhE,MAAM,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;gBACvD,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,QAAQ,EAAE,MAAM,CAAC,QAAQ;aAC1B,CAAC,CAAC;YAEH,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,iCAAiC,MAAM,CAAC,gBAAgB,sCAAsC;qBACrG;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GACX,GAAG,YAAY,KAAK;gBAClB,CAAC,CAAC,GAAG,CAAC,OAAO;gBACb,CAAC,CAAC,qCAAqC,CAAC;YAC5C,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,0BAA0B,OAAO,EAAE;qBAC1C;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"authenticate.js","sourceRoot":"","sources":["../../src/tools/authenticate.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,UAAU,QAAQ,CAAC,MAAiB,EAAE,GAAwB;IAClE,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,mNAAmN,EACnN,EAAE,EACF,KAAK,IAAI,EAAE;QACT,iCAAiC;QACjC,MAAM,QAAQ,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjD,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,4BAA4B,QAAQ,CAAC,gBAAgB,aAAa,QAAQ,CAAC,QAAQ,iDAAiD;qBAC3I;iBACF;aACF,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,kBAAkB,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;YAEhE,MAAM,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;gBACvD,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;gBACzB,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,QAAQ,EAAE,MAAM,CAAC,QAAQ;aAC1B,CAAC,CAAC;YAEH,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,iCAAiC,MAAM,CAAC,gBAAgB,sCAAsC;qBACrG;iBACF;aACF,CAAC;QACJ,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,OAAO,GACX,GAAG,YAAY,KAAK;gBAClB,CAAC,CAAC,GAAG,CAAC,OAAO;gBACb,CAAC,CAAC,qCAAqC,CAAC;YAC5C,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,0BAA0B,OAAO,EAAE;qBAC1C;iBACF;gBACD,OAAO,EAAE,IAAI;aACd,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/status.js

@@ -1,6 +1,6 @@
 import { readCredentials, clearCredentials, } from "../credentials.js";
 export function register(server, env) {
-    server.tool("sapiom_status", "Check Sapiom authentication status. Returns whether you're authenticated and which organization.", {}, async () => {
+    server.tool("sapiom_status", "Check authentication status for this local Sapiom developer MCP (sapiom-dev). Returns whether you're authenticated and which organization.", {}, async () => {
         const creds = await readCredentials(env.name);
         if (creds) {
             return {

package/dist/tools/status.js.map

@@ -1 +1 @@
-{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/tools/status.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,UAAU,QAAQ,CAAC,MAAiB,EAAE,GAAwB;IAClE,MAAM,CAAC,IAAI,CACT,eAAe,EACf,kGAAkG,EAClG,EAAE,EACF,KAAK,IAAI,EAAE;QACT,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAE9C,IAAI,KAAK,EAAE,CAAC;YACV,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,oBAAoB,KAAK,CAAC,gBAAgB,aAAa,KAAK,CAAC,QAAQ,GAAG;qBAC/E;iBACF;aACF,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,gEAAgE;iBACvE;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,eAAe,EACf,+EAA+E,EAC/E,EAAE,EACF,KAAK,IAAI,EAAE;QACT,MAAM,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEjC,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,gEAAgE;iBACvE;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/tools/status.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EACf,gBAAgB,GAEjB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,UAAU,QAAQ,CAAC,MAAiB,EAAE,GAAwB;IAClE,MAAM,CAAC,IAAI,CACT,eAAe,EACf,4IAA4I,EAC5I,EAAE,EACF,KAAK,IAAI,EAAE;QACT,MAAM,KAAK,GAAG,MAAM,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAE9C,IAAI,KAAK,EAAE,CAAC;YACV,OAAO;gBACL,OAAO,EAAE;oBACP;wBACE,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,oBAAoB,KAAK,CAAC,gBAAgB,aAAa,KAAK,CAAC,QAAQ,GAAG;qBAC/E;iBACF;aACF,CAAC;QACJ,CAAC;QAED,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,gEAAgE;iBACvE;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;IAEF,MAAM,CAAC,IAAI,CACT,eAAe,EACf,+EAA+E,EAC/E,EAAE,EACF,KAAK,IAAI,EAAE;QACT,MAAM,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAEjC,OAAO;YACL,OAAO,EAAE;gBACP;oBACE,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE,gEAAgE;iBACvE;aACF;SACF,CAAC;IACJ,CAAC,CACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sapiom/mcp",
-  "version": "0.7.2",
-  "description": "Sapiom MCP server for Claude Code — browser-based authentication and API tools",
+  "version": "0.8.1",
+  "description": "Local Sapiom developer MCP server (sapiom-dev) — the unmetered surface for building and operating on Sapiom; today it scaffolds, tests, deploys, and inspects orchestrations. Not the remote Sapiom capability MCP.",
   "mcpName": "io.github.sapiom/mcp",
   "keywords": [
     "sapiom",
@@ -35,7 +35,7 @@
     "zod": "^3.25.0",
     "@sapiom/core": "0.5.0",
     "@sapiom/fetch": "0.5.0",
-    "@sapiom/orchestration-core": "^0.4.0"
+    "@sapiom/orchestration-core": "^0.4.2"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",