@sapiom/mcp 0.7.2 → 0.8.0

package/dist/index.js

@@ -5,16 +5,25 @@ 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.
         name: "sapiom-dev",
         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,4EAA4E;QAC5E,IAAI,EAAE,YAAY;QAClB,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sapiom/mcp",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Sapiom MCP server for Claude Code — browser-based authentication and API tools",
   "mcpName": "io.github.sapiom/mcp",
   "keywords": [
@@ -33,9 +33,9 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "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.0",
+    "@sapiom/core": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",