@sapiom/mcp 0.8.0 → 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

@@ -16,8 +16,16 @@ async function main() {
     // 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

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;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"}
+{"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/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.8.0",
-  "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",
@@ -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/core": "0.5.0"
+    "@sapiom/orchestration-core": "^0.4.2"
   },
   "devDependencies": {
     "@types/node": "^20.11.30",