@sapiom/mcp 0.8.0 → 0.8.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -0
- package/dist/index.js +9 -1
- package/dist/index.js.map +1 -1
- package/dist/tools/authenticate.js +1 -1
- package/dist/tools/authenticate.js.map +1 -1
- package/dist/tools/status.js +1 -1
- package/dist/tools/status.js.map +1 -1
- package/package.json +4 -4
package/README.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# @sapiom/mcp
|
|
2
|
+
|
|
3
|
+
The **local developer** MCP server for Sapiom. It runs on your machine over
|
|
4
|
+
stdio under the server name `sapiom-dev` — the unmetered `sapiom_dev_*` surface
|
|
5
|
+
for building and operating on Sapiom. Today it gives a coding agent the tools to
|
|
6
|
+
scaffold, test, deploy, and inspect Sapiom orchestrations; the namespace leaves
|
|
7
|
+
room for other non-capability developer tooling later.
|
|
8
|
+
|
|
9
|
+
> **Not the capability surface.** This is *not* the remote "Sapiom" MCP (the
|
|
10
|
+
> hosted connector with `sapiom_sandbox_*`, scrape, search, … capability tools).
|
|
11
|
+
> `sapiom-dev` is the local developer surface; it makes no paid capability calls
|
|
12
|
+
> and exposes no capability tools. See
|
|
13
|
+
> [the two Sapiom MCP servers](../../docs/mcp-servers.md) for which to use when.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
No global install — run it on demand with `npx`:
|
|
18
|
+
|
|
19
|
+
```jsonc
|
|
20
|
+
{
|
|
21
|
+
"mcpServers": {
|
|
22
|
+
"sapiom-dev": {
|
|
23
|
+
"command": "npx",
|
|
24
|
+
"args": ["-y", "@sapiom/mcp"]
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
}
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
In Claude Code:
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
claude mcp add sapiom-dev -- npx -y @sapiom/mcp
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## Configuration
|
|
37
|
+
|
|
38
|
+
The server targets the `production` environment by default. Override it with the
|
|
39
|
+
`SAPIOM_ENVIRONMENT` environment variable:
|
|
40
|
+
|
|
41
|
+
```jsonc
|
|
42
|
+
{
|
|
43
|
+
"mcpServers": {
|
|
44
|
+
"sapiom-dev": {
|
|
45
|
+
"command": "npx",
|
|
46
|
+
"args": ["-y", "@sapiom/mcp"],
|
|
47
|
+
"env": { "SAPIOM_ENVIRONMENT": "staging" }
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
}
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
- `production` (alias `prod`) → `app.sapiom.ai` / `api.sapiom.ai` — the default.
|
|
54
|
+
- `staging` (alias `dev`) → `app.sapiom.dev` / `api.sapiom.dev`.
|
|
55
|
+
|
|
56
|
+
Both resolve from built-in presets, so no config file is required. A custom
|
|
57
|
+
target can be defined in `~/.sapiom/credentials.json` (the server prints the
|
|
58
|
+
expected shape if it encounters an unknown environment name).
|
|
59
|
+
|
|
60
|
+
## Authentication
|
|
61
|
+
|
|
62
|
+
The first networked call (`link`, `deploy`, `run`, `inspect`, `signal`) needs a
|
|
63
|
+
Sapiom API key. Run **`sapiom_authenticate`** and the server opens a browser
|
|
64
|
+
login flow, then caches the resulting key per environment in
|
|
65
|
+
`~/.sapiom/credentials.json`. After that, tools work without re-authenticating.
|
|
66
|
+
`sapiom_status` reports who you're authenticated as; `sapiom_logout` clears the
|
|
67
|
+
cached credentials.
|
|
68
|
+
|
|
69
|
+
The local authoring tools (`scaffold`, `check`, `run_local`) need no
|
|
70
|
+
authentication — they run entirely offline.
|
|
71
|
+
|
|
72
|
+
## Tools
|
|
73
|
+
|
|
74
|
+
| Tool | Network | What it does |
|
|
75
|
+
| --- | --- | --- |
|
|
76
|
+
| `sapiom_authenticate` | browser | Log in and cache an API key for the current environment |
|
|
77
|
+
| `sapiom_status` | — | Report authentication status |
|
|
78
|
+
| `sapiom_logout` | — | Clear cached credentials |
|
|
79
|
+
| `sapiom_dev_orchestrations_scaffold` | — | Create a new orchestration project |
|
|
80
|
+
| `sapiom_dev_orchestrations_check` | — | Bundle + validate the step graph offline |
|
|
81
|
+
| `sapiom_dev_orchestrations_run_local` | — | Run the workflow locally, resolving capability calls from stubs (no cost) |
|
|
82
|
+
| `sapiom_dev_orchestrations_link` | ✓ | Resolve/create the hosted orchestration and cache its id |
|
|
83
|
+
| `sapiom_dev_orchestrations_deploy` | ✓ | Push the current commit, build, and wait for it |
|
|
84
|
+
| `sapiom_dev_orchestrations_run` | ✓ | Start a real cloud execution |
|
|
85
|
+
| `sapiom_dev_orchestrations_inspect` | ✓ | Inspect an execution or build (optionally waiting for it) |
|
|
86
|
+
| `sapiom_dev_orchestrations_signal` | ✓ | Resume a paused execution by delivering a signal |
|
|
87
|
+
|
|
88
|
+
A typical loop: `scaffold` → write step code → `run_local` until green → `link`
|
|
89
|
+
→ `deploy` → `run` → `inspect`.
|
|
90
|
+
|
|
91
|
+
## How capabilities fit in
|
|
92
|
+
|
|
93
|
+
Workflows authored here call Sapiom capabilities — sandboxes, repositories,
|
|
94
|
+
coding agents, search, storage, content generation — through
|
|
95
|
+
[`@sapiom/tools`](../tools) (`ctx.sapiom.*`). `run_local` resolves those calls
|
|
96
|
+
from stubs; a real `run`/`deploy` executes them in the cloud (metered). This MCP
|
|
97
|
+
never grows a per-capability tool of its own — capabilities live in
|
|
98
|
+
`@sapiom/tools` and the remote `sapiom` MCP. See
|
|
99
|
+
[the positioning doc](../../docs/mcp-servers.md) for the full policy.
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
MIT
|
package/dist/index.js
CHANGED
|
@@ -16,8 +16,16 @@ async function main() {
|
|
|
16
16
|
// bundled copy offline / on error), so guidance can change without a release.
|
|
17
17
|
const instructions = await fetchInstructions(env);
|
|
18
18
|
const server = new McpServer({
|
|
19
|
-
// The local
|
|
19
|
+
// The local developer surface — distinct from the remote Sapiom
|
|
20
|
+
// capabilities MCP. This is the unmetered `sapiom_dev_*` namespace for
|
|
21
|
+
// building and operating on Sapiom (today: orchestration authoring &
|
|
22
|
+
// lifecycle; room for more dev tooling later). The `name` is the stable
|
|
23
|
+
// wire identifier; `title` and `description` are what MCP clients show, so
|
|
24
|
+
// they spell out which Sapiom this is to keep it from reading as a
|
|
25
|
+
// duplicate of the capability server.
|
|
20
26
|
name: "sapiom-dev",
|
|
27
|
+
title: "Sapiom Dev — local developer tools",
|
|
28
|
+
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.",
|
|
21
29
|
version: "0.1.0",
|
|
22
30
|
}, {
|
|
23
31
|
// Returned in the MCP `initialize` handshake; capable clients surface it to the
|
package/dist/index.js.map
CHANGED
|
@@ -1 +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,
|
|
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,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"}
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { readCredentials, writeCredentials, } from "../credentials.js";
|
|
2
2
|
import { performBrowserAuth } from "../auth.js";
|
|
3
3
|
export function register(server, env) {
|
|
4
|
-
server.tool("sapiom_authenticate", "Authenticate
|
|
4
|
+
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 () => {
|
|
5
5
|
// Check if already authenticated
|
|
6
6
|
const existing = await readCredentials(env.name);
|
|
7
7
|
if (existing) {
|
|
@@ -1 +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,
|
|
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,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
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { readCredentials, clearCredentials, } from "../credentials.js";
|
|
2
2
|
export function register(server, env) {
|
|
3
|
-
server.tool("sapiom_status", "Check Sapiom
|
|
3
|
+
server.tool("sapiom_status", "Check authentication status for this local Sapiom developer MCP (sapiom-dev). Returns whether you're authenticated and which organization.", {}, async () => {
|
|
4
4
|
const creds = await readCredentials(env.name);
|
|
5
5
|
if (creds) {
|
|
6
6
|
return {
|
package/dist/tools/status.js.map
CHANGED
|
@@ -1 +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,
|
|
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,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
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sapiom/mcp",
|
|
3
|
-
"version": "0.8.
|
|
4
|
-
"description": "Sapiom MCP server for
|
|
3
|
+
"version": "0.8.1",
|
|
4
|
+
"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.",
|
|
5
5
|
"mcpName": "io.github.sapiom/mcp",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"sapiom",
|
|
@@ -33,9 +33,9 @@
|
|
|
33
33
|
"dependencies": {
|
|
34
34
|
"@modelcontextprotocol/sdk": "^1.26.0",
|
|
35
35
|
"zod": "^3.25.0",
|
|
36
|
+
"@sapiom/core": "0.5.0",
|
|
36
37
|
"@sapiom/fetch": "0.5.0",
|
|
37
|
-
"@sapiom/orchestration-core": "^0.4.
|
|
38
|
-
"@sapiom/core": "0.5.0"
|
|
38
|
+
"@sapiom/orchestration-core": "^0.4.2"
|
|
39
39
|
},
|
|
40
40
|
"devDependencies": {
|
|
41
41
|
"@types/node": "^20.11.30",
|