javascript-solid-server 0.0.198 → 0.0.200
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 +4 -1
- package/bin/jss.js +6 -2
- package/docs/app-install.md +193 -0
- package/docs/mcp.md +121 -0
- package/package.json +1 -1
- package/src/cli/install.js +142 -8
- package/src/config.js +5 -0
- package/src/mcp/index.js +133 -0
- package/src/mcp/protocol.js +52 -0
- package/src/mcp/skills.js +138 -0
- package/src/mcp/tools.js +375 -0
- package/src/server.js +11 -0
- package/test/mcp.test.js +271 -0
package/README.md
CHANGED
|
@@ -34,6 +34,7 @@ A minimal, fast, JSON-LD native Solid server.
|
|
|
34
34
|
- **Tunnel Proxy** — Decentralized ngrok through your pod
|
|
35
35
|
- **Terminal** — WebSocket shell access via `--terminal`
|
|
36
36
|
- **Password CLI** — `jss passwd` for user password management
|
|
37
|
+
- **MCP Server** — Expose the pod as a tool surface for agents (Claude Desktop, Cursor, custom bots) via `--mcp` ([docs](docs/mcp.md))
|
|
37
38
|
- **HTTP 402 Payments** — Monetize endpoints with per-request sat payments
|
|
38
39
|
- **Mashlib / SolidOS UI** — Optional data browser (CDN, local, or ES module)
|
|
39
40
|
- **Storage Quotas** — Per-user limits with CLI management
|
|
@@ -92,7 +93,7 @@ jss quota <cmd> # Manage storage quotas
|
|
|
92
93
|
jss passwd <username> # Manage user passwords
|
|
93
94
|
```
|
|
94
95
|
|
|
95
|
-
Key options: `--port`, `--idp`, `--conneg`, `--mashlib`, `--git`, `--nostr`, `--activitypub`, `--webrtc`, `--tunnel`, `--terminal`, `--mongo`, `--pay`, `--public`, `--single-user`
|
|
96
|
+
Key options: `--port`, `--idp`, `--conneg`, `--mashlib`, `--git`, `--nostr`, `--mcp`, `--activitypub`, `--webrtc`, `--tunnel`, `--terminal`, `--mongo`, `--pay`, `--public`, `--single-user`
|
|
96
97
|
|
|
97
98
|
Full options: [docs/configuration.md](docs/configuration.md)
|
|
98
99
|
|
|
@@ -105,6 +106,8 @@ Full options: [docs/configuration.md](docs/configuration.md)
|
|
|
105
106
|
| Mashlib / SolidOS UI | [docs/mashlib.md](docs/mashlib.md) |
|
|
106
107
|
| WebSocket Notifications | [docs/notifications.md](docs/notifications.md) |
|
|
107
108
|
| Git Support | [docs/git-support.md](docs/git-support.md) |
|
|
109
|
+
| Installing Apps | [docs/app-install.md](docs/app-install.md) |
|
|
110
|
+
| MCP (pod as agent tool surface) | [docs/mcp.md](docs/mcp.md) |
|
|
108
111
|
| Nostr Relay | [docs/nostr.md](docs/nostr.md) |
|
|
109
112
|
| ActivityPub & Mastodon API | [docs/activitypub.md](docs/activitypub.md) |
|
|
110
113
|
| remoteStorage | [docs/remotestorage.md](docs/remotestorage.md) |
|
package/bin/jss.js
CHANGED
|
@@ -152,6 +152,8 @@ program
|
|
|
152
152
|
.option('--no-mongo', 'Disable MongoDB-backed /db/ route')
|
|
153
153
|
.option('--mongo-url <url>', 'MongoDB connection URL (default: mongodb://localhost:27017)')
|
|
154
154
|
.option('--mongo-database <name>', 'MongoDB database name (default: solid)')
|
|
155
|
+
.option('--mcp', 'Enable MCP (Model Context Protocol) server at /mcp — pod as a tool surface for agents (#490)')
|
|
156
|
+
.option('--no-mcp', 'Disable MCP server')
|
|
155
157
|
.option('-q, --quiet', 'Suppress log output')
|
|
156
158
|
.option('--log-level <level>', 'Log level: error, warn, info, debug (default: info)')
|
|
157
159
|
.option('--print-config', 'Print configuration and exit')
|
|
@@ -234,6 +236,7 @@ program
|
|
|
234
236
|
mongo: config.mongo,
|
|
235
237
|
mongoUrl: config.mongoUrl,
|
|
236
238
|
mongoDatabase: config.mongoDatabase,
|
|
239
|
+
mcp: config.mcp,
|
|
237
240
|
});
|
|
238
241
|
|
|
239
242
|
await server.listen({ port: config.port, host: config.host });
|
|
@@ -316,12 +319,13 @@ program
|
|
|
316
319
|
* resolution, NIP-98 auth, curated default sets, and --bundle.
|
|
317
320
|
*/
|
|
318
321
|
program
|
|
319
|
-
.command('install
|
|
320
|
-
.description('Install a Solid app
|
|
322
|
+
.command('install [names...]')
|
|
323
|
+
.description('Install a Solid app (or a bundle of apps) into a running pod')
|
|
321
324
|
.option('--pod <url>', 'Target pod URL', 'http://localhost:4443')
|
|
322
325
|
.option('--user <name>', 'Username for IDP auth', 'me')
|
|
323
326
|
.option('--password <pw>', 'Password (default: $JSS_SINGLE_USER_PASSWORD or "me")')
|
|
324
327
|
.option('--nostr-privkey <hex>', 'Sign install pushes with NIP-98 using this 64-char hex Nostr privkey instead of fetching a bearer token (default: $NOSTR_PRIVKEY)')
|
|
328
|
+
.option('--bundle <source>', 'Install everything in a bundle (JSON-LD doc). Source: bare name → solid-apps/bundles, <org>/<repo>, https://..., or a local path')
|
|
325
329
|
.action(async (names, options) => {
|
|
326
330
|
try {
|
|
327
331
|
const { runInstall } = await import('../src/cli/install.js');
|
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
# Installing Apps
|
|
2
|
+
|
|
3
|
+
JSS ships a built-in `install` subcommand that pulls a Solid app from a git repo and pushes it into your running pod at `/public/apps/<name>/`. One command, no clone-and-push dance, no token plumbing — the hard parts (git auto-init, ACL-gated push, working-tree extraction via `updateInstead`) are handled by the same git HTTP backend JSS already uses.
|
|
4
|
+
|
|
5
|
+
## Quick start
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
jss start --provision-keys & # pod running on http://localhost:4443
|
|
9
|
+
jss install chrome # installs solid-apps/chrome → /public/apps/chrome/
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Open `http://localhost:4443/public/apps/chrome/` in a browser. That's it.
|
|
13
|
+
|
|
14
|
+
## App specs
|
|
15
|
+
|
|
16
|
+
The argument to `install` accepts five forms:
|
|
17
|
+
|
|
18
|
+
| Input | Resolves to | Pod path |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `chrome` | `github.com/solid-apps/chrome` (default registry) | `/public/apps/chrome/` |
|
|
21
|
+
| `JavaScriptSolidServer/git` | `github.com/JavaScriptSolidServer/git` | `/public/apps/git/` |
|
|
22
|
+
| `https://github.com/foo/bar` | as-is | `/public/apps/bar/` |
|
|
23
|
+
| `chrome#v1` | `github.com/solid-apps/chrome` at ref `v1` | `/public/apps/chrome/` |
|
|
24
|
+
| `litecut/litecut.github.io=litecut` | `github.com/litecut/litecut.github.io`, renamed | `/public/apps/litecut/` |
|
|
25
|
+
|
|
26
|
+
Two optional suffixes apply to any form:
|
|
27
|
+
|
|
28
|
+
- **`#<branch-or-tag>`** — pin a ref. Uses `git clone --branch <ref>` under the hood.
|
|
29
|
+
- **`=<name>`** — override the pod-path name. Useful when the repo's last segment isn't what you want under `/public/apps/`.
|
|
30
|
+
|
|
31
|
+
Multiple specs in one command:
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
jss install chrome vellum pdf hub
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Each is installed independently; per-app `✓` / `⊘` / `✗` status, exit non-zero if any failed.
|
|
38
|
+
|
|
39
|
+
## Authentication
|
|
40
|
+
|
|
41
|
+
The install needs write access on the target pod. Two paths:
|
|
42
|
+
|
|
43
|
+
### Bearer token (default)
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
jss install chrome --user me --password me
|
|
47
|
+
# or via env (keeps the secret out of shell history):
|
|
48
|
+
JSS_SINGLE_USER_PASSWORD=secret jss install chrome
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
`POST <pod>/idp/credentials` returns a token, which is sent as `Authorization: Bearer ...` on each push.
|
|
52
|
+
|
|
53
|
+
If the pod runs in `--public` mode (no IDP), no token is fetched; writes are unauthenticated.
|
|
54
|
+
|
|
55
|
+
### Nostr (NIP-98)
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
jss install chrome --nostr-privkey <64-hex>
|
|
59
|
+
# or via env:
|
|
60
|
+
NOSTR_PRIVKEY=<64-hex> jss install chrome
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Each push is signed with a NIP-98 event (Schnorr signature on a `kind: 27235` Nostr event). JSS verifies the signature, derives a `did:nostr:<pubkey>` identity, and runs WAC against that.
|
|
64
|
+
|
|
65
|
+
Pairs naturally with `--provision-keys`: the privkey JSS auto-generates at `<pod>/private/privkey.jsonld` is the natural source.
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
jss start --provision-keys &
|
|
69
|
+
PRIVKEY=$(jq -r .secretKeyMultibase pod-data/private/privkey.jsonld | sed 's/^f8126//')
|
|
70
|
+
NOSTR_PRIVKEY=$PRIVKEY jss install chrome
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
The target ACL must grant the corresponding pubkey:
|
|
74
|
+
|
|
75
|
+
```turtle
|
|
76
|
+
<#owner> a acl:Authorization;
|
|
77
|
+
acl:agent <did:nostr:59427bb1...>;
|
|
78
|
+
acl:accessTo <./>;
|
|
79
|
+
acl:default <./>;
|
|
80
|
+
acl:mode acl:Read, acl:Write, acl:Control.
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
This is typically already true on a `--provision-keys` pod — JSS seeds the owner ACL to grant the provisioned key.
|
|
84
|
+
|
|
85
|
+
## Targeting a different pod
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
jss install chrome --pod http://192.168.1.10:5544
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Default is `http://localhost:4443`. Auth flags apply against the chosen pod.
|
|
92
|
+
|
|
93
|
+
## Bundles
|
|
94
|
+
|
|
95
|
+
`--bundle <source>` installs a set of apps from a JSON-LD manifest. Same auth, same target, same per-app status.
|
|
96
|
+
|
|
97
|
+
```bash
|
|
98
|
+
jss install --bundle starter # solid-apps/bundles/HEAD/starter.jsonld
|
|
99
|
+
jss install --bundle media chrome # bundle + ad-hoc additions
|
|
100
|
+
jss install --bundle ./my-stack.jsonld # local file
|
|
101
|
+
jss install --bundle https://my.pod/bundles/dev.jsonld
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### Source resolution
|
|
105
|
+
|
|
106
|
+
| Input | Resolves to |
|
|
107
|
+
|---|---|
|
|
108
|
+
| `--bundle starter` | `https://raw.githubusercontent.com/solid-apps/bundles/HEAD/starter.jsonld` |
|
|
109
|
+
| `--bundle <org>/<repo>` | `https://raw.githubusercontent.com/<org>/<repo>/HEAD/bundle.jsonld` |
|
|
110
|
+
| `--bundle https://...` | fetch as-is |
|
|
111
|
+
| `--bundle ./path.jsonld` | local filesystem (absolute paths supported) |
|
|
112
|
+
|
|
113
|
+
`/HEAD/` resolves to the repo's default branch — works for both `gh-pages`-default repos (solid-apps convention) and `main`-default repos.
|
|
114
|
+
|
|
115
|
+
### Bundle format
|
|
116
|
+
|
|
117
|
+
JSON-LD `schema:ItemList`:
|
|
118
|
+
|
|
119
|
+
```json
|
|
120
|
+
{
|
|
121
|
+
"@context": { "schema": "https://schema.org/", "app": "urn:jss:app:" },
|
|
122
|
+
"@id": "#bundle",
|
|
123
|
+
"@type": "schema:ItemList",
|
|
124
|
+
"schema:name": "Starter",
|
|
125
|
+
"schema:description": "Minimal pleasant first-run set",
|
|
126
|
+
"schema:itemListElement": [
|
|
127
|
+
"chrome",
|
|
128
|
+
"vellum",
|
|
129
|
+
{ "app:spec": "litecut/litecut.github.io=litecut", "app:label": "Litecut" }
|
|
130
|
+
]
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Each item is either:
|
|
135
|
+
|
|
136
|
+
- A **bare string** — any spec `jss install` accepts
|
|
137
|
+
- An **object** — required `app:spec`, optional `app:label` / `app:description` for UI tooling
|
|
138
|
+
|
|
139
|
+
### Curated bundles
|
|
140
|
+
|
|
141
|
+
The [`solid-apps/bundles`](https://github.com/solid-apps/bundles) repo hosts ready-made bundles:
|
|
142
|
+
|
|
143
|
+
| Bundle | Apps |
|
|
144
|
+
|---|---|
|
|
145
|
+
| `starter` | chrome, vellum, pdf, alarm |
|
|
146
|
+
| `all` | chrome, vellum, win98, pdf, hub, alarm, playlist |
|
|
147
|
+
| `media` | playlist, pdf |
|
|
148
|
+
| `productivity` | vellum, hub, win98 |
|
|
149
|
+
|
|
150
|
+
```bash
|
|
151
|
+
jss install --bundle starter
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Sharing custom bundles
|
|
155
|
+
|
|
156
|
+
Bundles are JSON-LD documents — they live anywhere a JSON-LD doc can. Host yours on your pod, in a GitHub repo, or any static server:
|
|
157
|
+
|
|
158
|
+
```bash
|
|
159
|
+
jss install --bundle https://my.pod/bundles/dev-stack.jsonld
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
ACL-gated, version-controlled (if in git), pointable from a single URL.
|
|
163
|
+
|
|
164
|
+
## How it works
|
|
165
|
+
|
|
166
|
+
Under the hood, `jss install <name>` is:
|
|
167
|
+
|
|
168
|
+
1. **Resolve** the spec to a source URL (`github.com/solid-apps/chrome` for bare names).
|
|
169
|
+
2. **Authenticate.** Fetch a bearer token from `<pod>/idp/credentials`, OR build a NIP-98 signed event if `--nostr-privkey` is set. Skipped entirely if the pod is in `--public` mode.
|
|
170
|
+
3. **Clone** the repo to a temp directory. Full clone — no `--depth`, because shallow pushes are rejected by `git-receive-pack`.
|
|
171
|
+
4. **Dual push** to `<pod>/public/apps/<name>` on both `HEAD:main` and `HEAD:gh-pages`. JSS auto-inits the destination repo, and whichever ref matches the server-side HEAD triggers `receive.denyCurrentBranch updateInstead` to extract the working tree onto disk where JSS serves it as static resources. The other ref is a harmless stranded reference.
|
|
172
|
+
5. **Clean up** the temp directory.
|
|
173
|
+
|
|
174
|
+
Idempotent on re-run. Skip-on-existing-non-repo paths (e.g. jspod's bundled `pilot`) report a friendly `⊘ skipped` instead of an error.
|
|
175
|
+
|
|
176
|
+
## Troubleshooting
|
|
177
|
+
|
|
178
|
+
| Symptom | Cause | Fix |
|
|
179
|
+
|---|---|---|
|
|
180
|
+
| `✗ <name>: invalid app name "..."` | Spec doesn't match the validation regex | Check the spec; review the [App specs](#app-specs) table |
|
|
181
|
+
| `✗ <name>: clone failed: Repository not found` | The repo doesn't exist at the resolved URL | Verify the source — `github.com/solid-apps/<name>` for bare names |
|
|
182
|
+
| `✗ <name>: push failed: shallow update not allowed` | A manual clone-and-push used `--depth=1` (the install itself never does this) | Remove `--depth` from the clone |
|
|
183
|
+
| `✗ <name>: push failed: HTTP 401` | Auth failed | Check `--user` / `--password`; for Nostr, check that the ACL grants the pubkey |
|
|
184
|
+
| `✗ <name>: push failed: HTTP 413` | Body exceeds JSS's `bodyLimit` (10 MB) | Tracked as [JSS#474](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/474). Workaround: install a smaller repo or push a no-history snapshot |
|
|
185
|
+
| Working tree empty (`/public/apps/<name>/index.html` returns 404) | Server-side HEAD doesn't match the pushed branch | JSS 0.0.197+ pins `-b main` on auto-init; upgrade if you see this |
|
|
186
|
+
| `⊘ <name>: skipped (path already in use)` | The target path has content but no `.git/` (e.g. jspod's bundled `pilot`) | Expected — JSS refuses to clobber non-repo content |
|
|
187
|
+
|
|
188
|
+
## See also
|
|
189
|
+
|
|
190
|
+
- [Git Support](./git-support.md) — the substrate that powers `install`
|
|
191
|
+
- [`jss install` source](../src/cli/install.js)
|
|
192
|
+
- [solid-apps/bundles](https://github.com/solid-apps/bundles) — curated bundle repo
|
|
193
|
+
- [Phased plan (JSS#464)](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/464) — design roadmap; Phases 3 (`--did`) and 5 (curated no-arg default) still ahead
|
package/docs/mcp.md
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# MCP — pod as a tool surface for agents
|
|
2
|
+
|
|
3
|
+
JSS speaks the [Model Context Protocol](https://modelcontextprotocol.io). Once `--mcp` is enabled, any MCP-compatible client — Claude Desktop, Cursor, custom agents, or `solid-apps/charlie` — can register your pod as a tool surface and read/write resources under the same WAC rules as any HTTP client.
|
|
4
|
+
|
|
5
|
+
> **Thesis**: MCP needs a backend. Solid is the backend.
|
|
6
|
+
|
|
7
|
+
## Quick start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
jss start --idp --mcp
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
The MCP endpoint is `POST /mcp` on your pod, speaking JSON-RPC 2.0 over MCP's Streamable HTTP transport (protocol version `2025-03-26`).
|
|
14
|
+
|
|
15
|
+
### Smoke test
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
# Handshake
|
|
19
|
+
curl -s http://localhost:4443/mcp \
|
|
20
|
+
-H "Content-Type: application/json" \
|
|
21
|
+
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' | jq
|
|
22
|
+
|
|
23
|
+
# List the tools the server offers
|
|
24
|
+
curl -s http://localhost:4443/mcp \
|
|
25
|
+
-H "Content-Type: application/json" \
|
|
26
|
+
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq '.result.tools[].name'
|
|
27
|
+
|
|
28
|
+
# Call a tool (anonymous read of /public/)
|
|
29
|
+
curl -s http://localhost:4443/mcp \
|
|
30
|
+
-H "Content-Type: application/json" \
|
|
31
|
+
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_resources","arguments":{"path":"/public/"}}}' | jq
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
## Auth
|
|
35
|
+
|
|
36
|
+
The MCP endpoint reuses JSS's existing auth chain. Any token format JSS accepts on regular HTTP endpoints works here:
|
|
37
|
+
|
|
38
|
+
- **Bearer** — simple HMAC tokens from `POST /idp/credentials`
|
|
39
|
+
- **Solid-OIDC + DPoP** — for federated WebID identities
|
|
40
|
+
- **LWS-CID JWTs** — kid resolution via WebID profile
|
|
41
|
+
- **NIP-98** — Schnorr-signed Nostr events with `did:nostr:<pubkey>` identity
|
|
42
|
+
|
|
43
|
+
The MCP server extracts the WebID from the inbound request to `/mcp` itself. Every tool call is then WAC-checked against that WebID, on the resource path the tool touches. **There is no separate MCP auth layer** — granting an agent access to `/private/notes/` is the same operation as granting a human: edit the ACL.
|
|
44
|
+
|
|
45
|
+
Anonymous requests get the same WAC treatment as any other anonymous request — public resources are reachable, private ones aren't.
|
|
46
|
+
|
|
47
|
+
## Tools
|
|
48
|
+
|
|
49
|
+
### Resource CRUD
|
|
50
|
+
|
|
51
|
+
| Tool | Effect | WAC check |
|
|
52
|
+
|---|---|---|
|
|
53
|
+
| `list_resources` | List a container's contents (`ldp:contains`) | Read on container |
|
|
54
|
+
| `read_resource` | Return resource body (UTF-8) | Read on resource |
|
|
55
|
+
| `write_resource` | PUT resource (overwrites) | Write on resource (parent fallback for new resources) |
|
|
56
|
+
| `create_resource` | POST to container (server mints name unless `slug` given) | Append on container |
|
|
57
|
+
| `delete_resource` | DELETE resource | Write on resource |
|
|
58
|
+
| `head_resource` | Return size/modified without body | Read on resource |
|
|
59
|
+
|
|
60
|
+
### Skill discovery
|
|
61
|
+
|
|
62
|
+
Skills live at conventional paths the MCP server walks:
|
|
63
|
+
|
|
64
|
+
- `<pod>/SKILL.md` — pod-wide (owner's instructions to any bot)
|
|
65
|
+
- `<pod>/public/apps/<name>/SKILL.md` — per-app
|
|
66
|
+
- `<pod>/private/bots/<name>/SKILL.md` — per-bot
|
|
67
|
+
|
|
68
|
+
| Tool | Returns |
|
|
69
|
+
|---|---|
|
|
70
|
+
| `list_skills` | `skill:SkillIndex` listing every discovered skill with `skill:format`, `skill:scope`, `skill:source` |
|
|
71
|
+
| `get_skill` | Body of a specific skill file |
|
|
72
|
+
| `get_pod_skill` | Pod-wide SKILL.md (convenience) |
|
|
73
|
+
|
|
74
|
+
Both `SKILL.md` (Anthropic markdown format) and `SKILL.jsonld` (typed JSON-LD descriptor) are first-class. The discovery channel stays stable; new formats plug in via the `skill:format` declaration.
|
|
75
|
+
|
|
76
|
+
### Docs
|
|
77
|
+
|
|
78
|
+
| Tool | Returns |
|
|
79
|
+
|---|---|
|
|
80
|
+
| `list_docs` | JSS's own built-in docs (the markdown files shipped with the server) |
|
|
81
|
+
| `read_docs` | Markdown body of a doc by filename |
|
|
82
|
+
|
|
83
|
+
Pod-resident docs (`/docs/`, `/public/apps/<name>/docs/`) are reachable via the regular CRUD tools — no separate surface.
|
|
84
|
+
|
|
85
|
+
### Introspection
|
|
86
|
+
|
|
87
|
+
| Tool | Returns |
|
|
88
|
+
|---|---|
|
|
89
|
+
| `pod_info` | Origin, server, MCP protocol version, authenticated identity, capability flags |
|
|
90
|
+
|
|
91
|
+
## Wiring Claude Desktop
|
|
92
|
+
|
|
93
|
+
In your Claude Desktop MCP settings, add an HTTP MCP server pointing at:
|
|
94
|
+
|
|
95
|
+
```
|
|
96
|
+
http://localhost:4443/mcp
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
For authenticated access, configure the client to send `Authorization: Bearer <token>`. Tokens come from `POST /idp/credentials` (username/password) or from any compatible OIDC/DPoP flow.
|
|
100
|
+
|
|
101
|
+
## What's not included (yet)
|
|
102
|
+
|
|
103
|
+
The first cut ships CRUD, ACL-as-resource (you can read/write `.acl` files via the regular tools), skills, docs, and introspection. Deferred:
|
|
104
|
+
|
|
105
|
+
- **`update_resource` (PATCH)** — SPARQL Update / N3 patches. Read-modify-write through the CRUD tools is the workaround.
|
|
106
|
+
- **`subscribe`** — wrap JSS's WebSocket notifications as MCP events over SSE. Today, agents can `read_resource` + poll.
|
|
107
|
+
- **`call_remote_pod`** — federation primitive for bot-to-bot. Today, an agent can talk to two pods by registering both as MCP servers in its client.
|
|
108
|
+
|
|
109
|
+
These are tracked as follow-ups on issue #490.
|
|
110
|
+
|
|
111
|
+
## Why this exists
|
|
112
|
+
|
|
113
|
+
The agent ecosystem has no shared answer for sovereign, ACL-gated storage. Every agent today bolts on its own DB, vector store, or secrets vault. Solid's pitch — user-owned data, queryable, access-controlled — is exactly what agents need. MCP is the wire that connects them.
|
|
114
|
+
|
|
115
|
+
When JSS exposes `/mcp`:
|
|
116
|
+
|
|
117
|
+
- **Agent identity becomes a first-class WAC subject.** `acl:agent <did:nostr:...>` for a bot is the same operation as for a human.
|
|
118
|
+
- **The pod is the bot's world.** A bot reads its instructions from `SKILL.md` on the pod, discovers tools as URL-addressable resources, and (with the owner's permission) writes back. No backend, no API key store, no secrets vault — just the pod.
|
|
119
|
+
- **Bot-to-bot falls out of the protocol.** Two pods running JSS can have their bots call each other's MCP endpoints, gated by WAC on both ends. No new federation wire.
|
|
120
|
+
|
|
121
|
+
See [#490](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues/490) for the design discussion and roadmap.
|
package/package.json
CHANGED
package/src/cli/install.js
CHANGED
|
@@ -25,8 +25,8 @@
|
|
|
25
25
|
*/
|
|
26
26
|
|
|
27
27
|
import { spawnSync } from 'child_process';
|
|
28
|
-
import { existsSync } from 'fs';
|
|
29
|
-
import { join } from 'path';
|
|
28
|
+
import { existsSync, readFileSync } from 'fs';
|
|
29
|
+
import { join, isAbsolute } from 'path';
|
|
30
30
|
import { nip98Token } from '../nostr/event.js';
|
|
31
31
|
|
|
32
32
|
// ANSI helpers — keep zero-dep so this works in any embedded usage.
|
|
@@ -87,6 +87,111 @@ function parseAppSpec(input) {
|
|
|
87
87
|
return { source, name, ref };
|
|
88
88
|
}
|
|
89
89
|
|
|
90
|
+
/**
|
|
91
|
+
* Resolve a `--bundle` source string to either a fully-qualified URL
|
|
92
|
+
* or an absolute local-file path.
|
|
93
|
+
*
|
|
94
|
+
* --bundle media → github.com/solid-apps/bundles/HEAD/media.jsonld
|
|
95
|
+
* --bundle <org>/<repo> → github.com/<org>/<repo>/HEAD/bundle.jsonld
|
|
96
|
+
* --bundle https://... → as-is (must end in a JSON-LD doc)
|
|
97
|
+
* --bundle ./path or /abs/path → absolute local-file path
|
|
98
|
+
*
|
|
99
|
+
* Returns { url } or { path } or { error }.
|
|
100
|
+
*/
|
|
101
|
+
function resolveBundleSource(input) {
|
|
102
|
+
if (!input || typeof input !== 'string') {
|
|
103
|
+
return { error: 'bundle source is required' };
|
|
104
|
+
}
|
|
105
|
+
if (/^https?:\/\//.test(input)) {
|
|
106
|
+
return { url: input };
|
|
107
|
+
}
|
|
108
|
+
if (input.startsWith('./') || input.startsWith('../') || isAbsolute(input) || input.startsWith('~/')) {
|
|
109
|
+
const path = input.startsWith('~/')
|
|
110
|
+
? join(process.env.HOME || '', input.slice(2))
|
|
111
|
+
: (isAbsolute(input) ? input : join(process.cwd(), input));
|
|
112
|
+
return { path };
|
|
113
|
+
}
|
|
114
|
+
// Bare names + <org>/<repo> shorthand. We hit raw.githubusercontent.com
|
|
115
|
+
// so the response is the raw JSON-LD body (no HTML wrapper).
|
|
116
|
+
if (input.includes('/')) {
|
|
117
|
+
const cleaned = input.replace(/\.git$/, '').replace(/^\/+|\/+$/g, '');
|
|
118
|
+
if (cleaned.split('/').length !== 2) {
|
|
119
|
+
return { error: 'expected <org>/<repo> shorthand for bundle source' };
|
|
120
|
+
}
|
|
121
|
+
return { url: `https://raw.githubusercontent.com/${cleaned}/HEAD/bundle.jsonld` };
|
|
122
|
+
}
|
|
123
|
+
if (!/^[a-z0-9][a-z0-9_.-]*$/i.test(input)) {
|
|
124
|
+
return { error: `invalid bundle name "${input}"` };
|
|
125
|
+
}
|
|
126
|
+
return { url: `https://raw.githubusercontent.com/solid-apps/bundles/HEAD/${input}.jsonld` };
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
/**
|
|
130
|
+
* Fetch + parse a bundle into a normalized list of app-spec strings.
|
|
131
|
+
*
|
|
132
|
+
* Returns { name, description, items } or { error }.
|
|
133
|
+
*
|
|
134
|
+
* Items are normalized: each becomes the string-form spec the caller
|
|
135
|
+
* feeds to `parseAppSpec`. Object items with `app:spec` are unwrapped
|
|
136
|
+
* to their spec string; the optional label/description are ignored
|
|
137
|
+
* by the install path (they're for UI tooling that consumes bundles).
|
|
138
|
+
*/
|
|
139
|
+
async function loadBundle(resolved) {
|
|
140
|
+
let body;
|
|
141
|
+
try {
|
|
142
|
+
if (resolved.path) {
|
|
143
|
+
if (!existsSync(resolved.path)) {
|
|
144
|
+
return { error: `bundle file not found: ${resolved.path}` };
|
|
145
|
+
}
|
|
146
|
+
body = readFileSync(resolved.path, 'utf8');
|
|
147
|
+
} else {
|
|
148
|
+
const r = await fetch(resolved.url);
|
|
149
|
+
if (!r.ok) return { error: `bundle fetch failed: HTTP ${r.status} on ${resolved.url}` };
|
|
150
|
+
body = await r.text();
|
|
151
|
+
}
|
|
152
|
+
} catch (e) {
|
|
153
|
+
return { error: `could not read bundle: ${e.message}` };
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
let doc;
|
|
157
|
+
try {
|
|
158
|
+
doc = JSON.parse(body);
|
|
159
|
+
} catch (e) {
|
|
160
|
+
return { error: `bundle is not valid JSON: ${e.message}` };
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
// Items live under `schema:itemListElement` (preferred) or the
|
|
164
|
+
// un-prefixed `itemListElement` (common when @context aliases it).
|
|
165
|
+
const rawItems = doc['schema:itemListElement']
|
|
166
|
+
?? doc['itemListElement']
|
|
167
|
+
?? doc['items'] // also accept a loose `items` key for hand-written bundles
|
|
168
|
+
?? null;
|
|
169
|
+
if (!Array.isArray(rawItems) || rawItems.length === 0) {
|
|
170
|
+
return { error: 'bundle has no items (expected schema:itemListElement array)' };
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
const items = [];
|
|
174
|
+
for (const it of rawItems) {
|
|
175
|
+
if (typeof it === 'string') {
|
|
176
|
+
items.push(it);
|
|
177
|
+
} else if (it && typeof it === 'object') {
|
|
178
|
+
const spec = it['app:spec'] || it['spec'] || it['urn:jss:app:spec'];
|
|
179
|
+
if (typeof spec !== 'string') {
|
|
180
|
+
return { error: `bundle item missing app:spec: ${JSON.stringify(it).slice(0, 100)}` };
|
|
181
|
+
}
|
|
182
|
+
items.push(spec);
|
|
183
|
+
} else {
|
|
184
|
+
return { error: `bundle item must be a string or object, got: ${typeof it}` };
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
return {
|
|
189
|
+
name: doc['schema:name'] || doc.name || null,
|
|
190
|
+
description: doc['schema:description'] || doc.description || null,
|
|
191
|
+
items
|
|
192
|
+
};
|
|
193
|
+
}
|
|
194
|
+
|
|
90
195
|
/**
|
|
91
196
|
* Fetch a bearer token from the pod's IDP, or null if the pod runs
|
|
92
197
|
* with `--public` (no auth required for writes).
|
|
@@ -207,20 +312,41 @@ export async function runInstall(names, options) {
|
|
|
207
312
|
const password = options.password || process.env.JSS_SINGLE_USER_PASSWORD || 'me';
|
|
208
313
|
const nostrPrivkey = options.nostrPrivkey || process.env.NOSTR_PRIVKEY || null;
|
|
209
314
|
|
|
210
|
-
if (!names || names.length === 0) {
|
|
211
|
-
throw new Error('expected at least one app name. Try: `jss install chrome`');
|
|
212
|
-
}
|
|
213
|
-
|
|
214
315
|
// Validate Nostr privkey if supplied (64 lowercase-hex chars).
|
|
215
316
|
if (nostrPrivkey && !/^[0-9a-f]{64}$/i.test(nostrPrivkey)) {
|
|
216
317
|
console.error(red('✗ --nostr-privkey must be 64 hex chars'));
|
|
217
318
|
throw new Error('invalid --nostr-privkey');
|
|
218
319
|
}
|
|
219
320
|
|
|
321
|
+
// Bundle mode: resolve, fetch, parse, then concatenate items with
|
|
322
|
+
// any positional ad-hoc apps. `--bundle <src> chrome` installs the
|
|
323
|
+
// bundle + chrome; same auth + target flags apply to all.
|
|
324
|
+
let bundleMeta = null;
|
|
325
|
+
let allNames = [...(names || [])];
|
|
326
|
+
if (options.bundle) {
|
|
327
|
+
const resolved = resolveBundleSource(options.bundle);
|
|
328
|
+
if (resolved.error) {
|
|
329
|
+
console.error(red(`✗ --bundle: ${resolved.error}`));
|
|
330
|
+
throw new Error(resolved.error);
|
|
331
|
+
}
|
|
332
|
+
const bundle = await loadBundle(resolved);
|
|
333
|
+
if (bundle.error) {
|
|
334
|
+
console.error(red(`✗ --bundle: ${bundle.error}`));
|
|
335
|
+
throw new Error(bundle.error);
|
|
336
|
+
}
|
|
337
|
+
bundleMeta = { name: bundle.name, description: bundle.description, count: bundle.items.length };
|
|
338
|
+
// Bundle items go first; positional names appended afterwards.
|
|
339
|
+
allNames = [...bundle.items, ...allNames];
|
|
340
|
+
}
|
|
341
|
+
|
|
342
|
+
if (allNames.length === 0) {
|
|
343
|
+
throw new Error('expected at least one app name or a --bundle. Try: `jss install chrome`');
|
|
344
|
+
}
|
|
345
|
+
|
|
220
346
|
// Validate every spec up front so we report invalid names before
|
|
221
347
|
// doing any network work.
|
|
222
348
|
const specs = [];
|
|
223
|
-
for (const n of
|
|
349
|
+
for (const n of allNames) {
|
|
224
350
|
const spec = parseAppSpec(n);
|
|
225
351
|
if (spec.error) {
|
|
226
352
|
console.error(red(`✗ ${n}: ${spec.error}`));
|
|
@@ -229,7 +355,15 @@ export async function runInstall(names, options) {
|
|
|
229
355
|
specs.push(spec);
|
|
230
356
|
}
|
|
231
357
|
|
|
232
|
-
|
|
358
|
+
if (bundleMeta) {
|
|
359
|
+
const label = bundleMeta.name
|
|
360
|
+
? `bundle "${bundleMeta.name}"`
|
|
361
|
+
: 'bundle';
|
|
362
|
+
console.log(bold(`\nInstalling ${specs.length} app${specs.length === 1 ? '' : 's'} from ${label} → `) + green(pod));
|
|
363
|
+
if (bundleMeta.description) console.log(dim(` ${bundleMeta.description}`));
|
|
364
|
+
} else {
|
|
365
|
+
console.log(bold(`\nInstalling ${specs.length} app${specs.length === 1 ? '' : 's'} → `) + green(pod));
|
|
366
|
+
}
|
|
233
367
|
if (nostrPrivkey) console.log(dim(' (signing with Nostr privkey — NIP-98)'));
|
|
234
368
|
console.log('');
|
|
235
369
|
|
package/src/config.js
CHANGED
|
@@ -127,6 +127,9 @@ export const defaults = {
|
|
|
127
127
|
mongoUrl: 'mongodb://localhost:27017',
|
|
128
128
|
mongoDatabase: 'solid',
|
|
129
129
|
|
|
130
|
+
// MCP (Model Context Protocol) server — pod as a tool surface for agents (#490)
|
|
131
|
+
mcp: false,
|
|
132
|
+
|
|
130
133
|
// Logging
|
|
131
134
|
logger: true,
|
|
132
135
|
quiet: false,
|
|
@@ -197,6 +200,7 @@ const envMap = {
|
|
|
197
200
|
JSS_MONGO: 'mongo',
|
|
198
201
|
JSS_MONGO_URL: 'mongoUrl',
|
|
199
202
|
JSS_MONGO_DATABASE: 'mongoDatabase',
|
|
203
|
+
JSS_MCP: 'mcp',
|
|
200
204
|
};
|
|
201
205
|
|
|
202
206
|
/**
|
|
@@ -242,6 +246,7 @@ const BOOLEAN_KEYS = new Set([
|
|
|
242
246
|
'liveReload',
|
|
243
247
|
'pay',
|
|
244
248
|
'mongo',
|
|
249
|
+
'mcp',
|
|
245
250
|
'idp',
|
|
246
251
|
'notifications',
|
|
247
252
|
'logger',
|