@seldonframe/mcp 1.0.0 → 1.0.2
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 +112 -112
- package/package.json +42 -42
- package/src/client.js +194 -194
- package/src/index.js +81 -49
- package/src/tools.js +2001 -2001
- package/src/welcome.js +132 -80
package/README.md
CHANGED
|
@@ -1,112 +1,112 @@
|
|
|
1
|
-
# @seldonframe/mcp
|
|
2
|
-
|
|
3
|
-
Official SeldonFrame MCP server for Claude Code and Claude Desktop.
|
|
4
|
-
|
|
5
|
-
**One command, one real workspace.** The first time you run it, no API key is needed. Say `create_workspace({ name: "Dental Clinic Laval" })` and the server mints a real hosted workspace on `dental-clinic-laval.app.seldonframe.com` — with CRM, Cal.diy booking, Formbricks intake, and Brain v2 pre-installed — and returns live URLs. No signup wall, no "guest mode", no claim step.
|
|
6
|
-
|
|
7
|
-
## 60-second quickstart
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
# 1. From the repo root
|
|
11
|
-
cd skills/mcp-server && npm install
|
|
12
|
-
|
|
13
|
-
# 2. Register with Claude Code — no env vars needed
|
|
14
|
-
claude mcp add seldonframe -s user -- node "$(pwd)/src/index.js"
|
|
15
|
-
|
|
16
|
-
# 3. In Claude Code, just ask:
|
|
17
|
-
# create_workspace({ name: "My Business OS" })
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
That call returns something like:
|
|
21
|
-
|
|
22
|
-
```json
|
|
23
|
-
{
|
|
24
|
-
"workspace": { "id": "wsp_…", "slug": "my-business-os", "tier": "free" },
|
|
25
|
-
"urls": {
|
|
26
|
-
"dashboard": "https://my-business-os.app.seldonframe.com",
|
|
27
|
-
"book": "https://my-business-os.app.seldonframe.com/book",
|
|
28
|
-
"intake": "https://my-business-os.app.seldonframe.com/intake"
|
|
29
|
-
},
|
|
30
|
-
"installed": ["crm", "caldiy-booking", "formbricks-intake", "brain-v2"],
|
|
31
|
-
"next": [ "…" ]
|
|
32
|
-
}
|
|
33
|
-
```
|
|
34
|
-
|
|
35
|
-
Every subsequent tool response includes a `next:` array — follow the rails.
|
|
36
|
-
|
|
37
|
-
## How auth works
|
|
38
|
-
|
|
39
|
-
| Situation | What happens |
|
|
40
|
-
|---|---|
|
|
41
|
-
| First ever call | `create_workspace` POSTs with no auth. Server mints a workspace + bearer token. MCP stores the token in `~/.seldonframe/device.json`. |
|
|
42
|
-
| Subsequent calls | MCP sends `Authorization: Bearer <workspace token>` automatically. |
|
|
43
|
-
| `SELDONFRAME_API_KEY` set | Takes precedence over device tokens. Unlocks Pro capabilities. |
|
|
44
|
-
|
|
45
|
-
You never have to juggle modes. The first workspace is free forever.
|
|
46
|
-
|
|
47
|
-
## When you need `SELDONFRAME_API_KEY`
|
|
48
|
-
|
|
49
|
-
- Adding a **second workspace**
|
|
50
|
-
- Connecting a **custom domain**
|
|
51
|
-
- **Full Brain v2** intelligence (heuristic Brain is always free)
|
|
52
|
-
- Publishing, exporting, org-scoped secret rotation
|
|
53
|
-
|
|
54
|
-
Get one at <https://app.seldonframe.com/settings/api>, then:
|
|
55
|
-
|
|
56
|
-
```bash
|
|
57
|
-
export SELDONFRAME_API_KEY=sk-…
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
Restart the MCP server. Your existing workspaces continue to work untouched.
|
|
61
|
-
|
|
62
|
-
## Install via plugin manifest (one-shot)
|
|
63
|
-
|
|
64
|
-
The repo ships a `.claude-plugin/plugin.json` at the root. From inside Claude Code:
|
|
65
|
-
|
|
66
|
-
```
|
|
67
|
-
/plugin install <path-to-repo>
|
|
68
|
-
```
|
|
69
|
-
|
|
70
|
-
## Install via npm
|
|
71
|
-
|
|
72
|
-
```bash
|
|
73
|
-
claude mcp add seldonframe -- npx -y @seldonframe/mcp
|
|
74
|
-
```
|
|
75
|
-
|
|
76
|
-
This is the canonical install command surfaced on the marketing site,
|
|
77
|
-
the `/docs/quickstart` page, and the repo README. It uses `npx -y`
|
|
78
|
-
so users never have to globally install anything; the latest version
|
|
79
|
-
is fetched and run on demand.
|
|
80
|
-
|
|
81
|
-
## Environment
|
|
82
|
-
|
|
83
|
-
- `SELDONFRAME_API_KEY` *(optional)* — Enables Pro capabilities (second workspace, custom domains, full Brain v2).
|
|
84
|
-
- `SELDONFRAME_API_BASE` *(optional)* — Override the API base URL. Defaults to `https://app.seldonframe.com/api/v1`.
|
|
85
|
-
|
|
86
|
-
## Tools
|
|
87
|
-
|
|
88
|
-
**Workspace:** `create_workspace`, `list_workspaces`, `switch_workspace`, `clone_workspace`, `link_workspace_owner`, `get_workspace_snapshot`.
|
|
89
|
-
**Blocks:** `install_caldiy_booking`, `install_formbricks_intake`, `install_vertical_pack`.
|
|
90
|
-
**Customize (typed, no backend LLM):** `update_landing_content`, `customize_intake_form`, `configure_booking`, `update_theme`.
|
|
91
|
-
**Soul:** `fetch_source_for_soul`, `submit_soul`.
|
|
92
|
-
**Ops:** `list_automations`, `connect_custom_domain`, `export_agent`, `store_secret`, `list_secrets`, `rotate_secret`.
|
|
93
|
-
|
|
94
|
-
### Architecture: zero backend LLM cost
|
|
95
|
-
|
|
96
|
-
Natural-language reasoning happens in the MCP session (Claude Code on the user's side). The backend only accepts **structured** commands and applies them deterministically. There is no `seldon_it` endpoint that parses prompts server-side; the old `query_brain` is replaced by `get_workspace_snapshot`, which returns raw state for Claude to reason over. Seldon spends $0 on LLM for the free tier — the user's Claude Code subscription is the reasoning engine.
|
|
97
|
-
|
|
98
|
-
### Soul compilation (zero cost to Seldon)
|
|
99
|
-
|
|
100
|
-
Soul compilation runs in **your** Claude Code session, not on Seldon's servers:
|
|
101
|
-
|
|
102
|
-
1. `fetch_source_for_soul({ url })` — returns up to 256KB of normalized text.
|
|
103
|
-
2. You (the agent) extract a structured Soul object.
|
|
104
|
-
3. `submit_soul({ soul })` — persists it to the workspace.
|
|
105
|
-
|
|
106
|
-
## Troubleshooting
|
|
107
|
-
|
|
108
|
-
**`Seldon API 401`** — Your `SELDONFRAME_API_KEY` is invalid or expired. Regenerate at <https://app.seldonframe.com/settings/api>, or unset the env var to fall back to your device token.
|
|
109
|
-
|
|
110
|
-
**`Seldon API 402`** — You tried a Pro capability without a key. Set `SELDONFRAME_API_KEY` and restart.
|
|
111
|
-
|
|
112
|
-
**Want to reset device state?** Delete `~/.seldonframe/device.json`. Your hosted workspaces stay live at `app.seldonframe.com`; only the local tokens are cleared.
|
|
1
|
+
# @seldonframe/mcp
|
|
2
|
+
|
|
3
|
+
Official SeldonFrame MCP server for Claude Code and Claude Desktop.
|
|
4
|
+
|
|
5
|
+
**One command, one real workspace.** The first time you run it, no API key is needed. Say `create_workspace({ name: "Dental Clinic Laval" })` and the server mints a real hosted workspace on `dental-clinic-laval.app.seldonframe.com` — with CRM, Cal.diy booking, Formbricks intake, and Brain v2 pre-installed — and returns live URLs. No signup wall, no "guest mode", no claim step.
|
|
6
|
+
|
|
7
|
+
## 60-second quickstart
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
# 1. From the repo root
|
|
11
|
+
cd skills/mcp-server && npm install
|
|
12
|
+
|
|
13
|
+
# 2. Register with Claude Code — no env vars needed
|
|
14
|
+
claude mcp add seldonframe -s user -- node "$(pwd)/src/index.js"
|
|
15
|
+
|
|
16
|
+
# 3. In Claude Code, just ask:
|
|
17
|
+
# create_workspace({ name: "My Business OS" })
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
That call returns something like:
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"workspace": { "id": "wsp_…", "slug": "my-business-os", "tier": "free" },
|
|
25
|
+
"urls": {
|
|
26
|
+
"dashboard": "https://my-business-os.app.seldonframe.com",
|
|
27
|
+
"book": "https://my-business-os.app.seldonframe.com/book",
|
|
28
|
+
"intake": "https://my-business-os.app.seldonframe.com/intake"
|
|
29
|
+
},
|
|
30
|
+
"installed": ["crm", "caldiy-booking", "formbricks-intake", "brain-v2"],
|
|
31
|
+
"next": [ "…" ]
|
|
32
|
+
}
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Every subsequent tool response includes a `next:` array — follow the rails.
|
|
36
|
+
|
|
37
|
+
## How auth works
|
|
38
|
+
|
|
39
|
+
| Situation | What happens |
|
|
40
|
+
|---|---|
|
|
41
|
+
| First ever call | `create_workspace` POSTs with no auth. Server mints a workspace + bearer token. MCP stores the token in `~/.seldonframe/device.json`. |
|
|
42
|
+
| Subsequent calls | MCP sends `Authorization: Bearer <workspace token>` automatically. |
|
|
43
|
+
| `SELDONFRAME_API_KEY` set | Takes precedence over device tokens. Unlocks Pro capabilities. |
|
|
44
|
+
|
|
45
|
+
You never have to juggle modes. The first workspace is free forever.
|
|
46
|
+
|
|
47
|
+
## When you need `SELDONFRAME_API_KEY`
|
|
48
|
+
|
|
49
|
+
- Adding a **second workspace**
|
|
50
|
+
- Connecting a **custom domain**
|
|
51
|
+
- **Full Brain v2** intelligence (heuristic Brain is always free)
|
|
52
|
+
- Publishing, exporting, org-scoped secret rotation
|
|
53
|
+
|
|
54
|
+
Get one at <https://app.seldonframe.com/settings/api>, then:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
export SELDONFRAME_API_KEY=sk-…
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Restart the MCP server. Your existing workspaces continue to work untouched.
|
|
61
|
+
|
|
62
|
+
## Install via plugin manifest (one-shot)
|
|
63
|
+
|
|
64
|
+
The repo ships a `.claude-plugin/plugin.json` at the root. From inside Claude Code:
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
/plugin install <path-to-repo>
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
## Install via npm
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
claude mcp add seldonframe -- npx -y @seldonframe/mcp
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
This is the canonical install command surfaced on the marketing site,
|
|
77
|
+
the `/docs/quickstart` page, and the repo README. It uses `npx -y`
|
|
78
|
+
so users never have to globally install anything; the latest version
|
|
79
|
+
is fetched and run on demand.
|
|
80
|
+
|
|
81
|
+
## Environment
|
|
82
|
+
|
|
83
|
+
- `SELDONFRAME_API_KEY` *(optional)* — Enables Pro capabilities (second workspace, custom domains, full Brain v2).
|
|
84
|
+
- `SELDONFRAME_API_BASE` *(optional)* — Override the API base URL. Defaults to `https://app.seldonframe.com/api/v1`.
|
|
85
|
+
|
|
86
|
+
## Tools
|
|
87
|
+
|
|
88
|
+
**Workspace:** `create_workspace`, `list_workspaces`, `switch_workspace`, `clone_workspace`, `link_workspace_owner`, `get_workspace_snapshot`.
|
|
89
|
+
**Blocks:** `install_caldiy_booking`, `install_formbricks_intake`, `install_vertical_pack`.
|
|
90
|
+
**Customize (typed, no backend LLM):** `update_landing_content`, `customize_intake_form`, `configure_booking`, `update_theme`.
|
|
91
|
+
**Soul:** `fetch_source_for_soul`, `submit_soul`.
|
|
92
|
+
**Ops:** `list_automations`, `connect_custom_domain`, `export_agent`, `store_secret`, `list_secrets`, `rotate_secret`.
|
|
93
|
+
|
|
94
|
+
### Architecture: zero backend LLM cost
|
|
95
|
+
|
|
96
|
+
Natural-language reasoning happens in the MCP session (Claude Code on the user's side). The backend only accepts **structured** commands and applies them deterministically. There is no `seldon_it` endpoint that parses prompts server-side; the old `query_brain` is replaced by `get_workspace_snapshot`, which returns raw state for Claude to reason over. Seldon spends $0 on LLM for the free tier — the user's Claude Code subscription is the reasoning engine.
|
|
97
|
+
|
|
98
|
+
### Soul compilation (zero cost to Seldon)
|
|
99
|
+
|
|
100
|
+
Soul compilation runs in **your** Claude Code session, not on Seldon's servers:
|
|
101
|
+
|
|
102
|
+
1. `fetch_source_for_soul({ url })` — returns up to 256KB of normalized text.
|
|
103
|
+
2. You (the agent) extract a structured Soul object.
|
|
104
|
+
3. `submit_soul({ soul })` — persists it to the workspace.
|
|
105
|
+
|
|
106
|
+
## Troubleshooting
|
|
107
|
+
|
|
108
|
+
**`Seldon API 401`** — Your `SELDONFRAME_API_KEY` is invalid or expired. Regenerate at <https://app.seldonframe.com/settings/api>, or unset the env var to fall back to your device token.
|
|
109
|
+
|
|
110
|
+
**`Seldon API 402`** — You tried a Pro capability without a key. Set `SELDONFRAME_API_KEY` and restart.
|
|
111
|
+
|
|
112
|
+
**Want to reset device state?** Delete `~/.seldonframe/device.json`. Your hosted workspaces stay live at `app.seldonframe.com`; only the local tokens are cleared.
|
package/package.json
CHANGED
|
@@ -1,42 +1,42 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@seldonframe/mcp",
|
|
3
|
-
"version": "1.0.
|
|
4
|
-
"description": "MCP server for SeldonFrame — AI-native Business OS platform. One command creates a real hosted workspace with CRM, booking, intake, and Brain v2.",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"bin": {
|
|
7
|
-
"seldonframe-mcp": "src/index.js"
|
|
8
|
-
},
|
|
9
|
-
"files": [
|
|
10
|
-
"src",
|
|
11
|
-
"README.md"
|
|
12
|
-
],
|
|
13
|
-
"engines": {
|
|
14
|
-
"node": ">=18"
|
|
15
|
-
},
|
|
16
|
-
"scripts": {
|
|
17
|
-
"start": "node src/index.js"
|
|
18
|
-
},
|
|
19
|
-
"dependencies": {
|
|
20
|
-
"@modelcontextprotocol/sdk": "^1.0.4"
|
|
21
|
-
},
|
|
22
|
-
"keywords": [
|
|
23
|
-
"mcp",
|
|
24
|
-
"model-context-protocol",
|
|
25
|
-
"seldonframe",
|
|
26
|
-
"ai",
|
|
27
|
-
"agents",
|
|
28
|
-
"business-os",
|
|
29
|
-
"claude-code",
|
|
30
|
-
"crm"
|
|
31
|
-
],
|
|
32
|
-
"license": "MIT",
|
|
33
|
-
"homepage": "https://seldonframe.com",
|
|
34
|
-
"repository": {
|
|
35
|
-
"type": "git",
|
|
36
|
-
"url": "https://github.com/seldonframe/seldonframe",
|
|
37
|
-
"directory": "skills/mcp-server"
|
|
38
|
-
},
|
|
39
|
-
"publishConfig": {
|
|
40
|
-
"access": "public"
|
|
41
|
-
}
|
|
42
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@seldonframe/mcp",
|
|
3
|
+
"version": "1.0.2",
|
|
4
|
+
"description": "MCP server for SeldonFrame — AI-native Business OS platform. One command creates a real hosted workspace with CRM, booking, intake, and Brain v2.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"bin": {
|
|
7
|
+
"seldonframe-mcp": "src/index.js"
|
|
8
|
+
},
|
|
9
|
+
"files": [
|
|
10
|
+
"src",
|
|
11
|
+
"README.md"
|
|
12
|
+
],
|
|
13
|
+
"engines": {
|
|
14
|
+
"node": ">=18"
|
|
15
|
+
},
|
|
16
|
+
"scripts": {
|
|
17
|
+
"start": "node src/index.js"
|
|
18
|
+
},
|
|
19
|
+
"dependencies": {
|
|
20
|
+
"@modelcontextprotocol/sdk": "^1.0.4"
|
|
21
|
+
},
|
|
22
|
+
"keywords": [
|
|
23
|
+
"mcp",
|
|
24
|
+
"model-context-protocol",
|
|
25
|
+
"seldonframe",
|
|
26
|
+
"ai",
|
|
27
|
+
"agents",
|
|
28
|
+
"business-os",
|
|
29
|
+
"claude-code",
|
|
30
|
+
"crm"
|
|
31
|
+
],
|
|
32
|
+
"license": "MIT",
|
|
33
|
+
"homepage": "https://seldonframe.com",
|
|
34
|
+
"repository": {
|
|
35
|
+
"type": "git",
|
|
36
|
+
"url": "https://github.com/seldonframe/seldonframe",
|
|
37
|
+
"directory": "skills/mcp-server"
|
|
38
|
+
},
|
|
39
|
+
"publishConfig": {
|
|
40
|
+
"access": "public"
|
|
41
|
+
}
|
|
42
|
+
}
|