javascript-solid-server 0.0.200 → 0.0.202
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/MAINTAINERS.md +29 -0
- package/README.md +4 -0
- package/bin/jss.js +8 -2
- package/docs/mcp.md +110 -3
- package/package.json +1 -1
- package/src/mcp/index.js +81 -2
- package/src/mcp/tools.js +386 -1
- package/src/server.js +7 -4
- package/src/tunnel/index.js +8 -0
- package/test/mcp.test.js +291 -0
- package/test/nostr-cid-vm.test.js +6 -3
- package/.claude/scheduled_tasks.lock +0 -1
- package/.claude/settings.local.json +0 -420
package/MAINTAINERS.md
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# Maintainers
|
|
2
|
+
|
|
3
|
+
JSS is maintained by a small group with commit access, working in the open.
|
|
4
|
+
Decisions are recorded in issues and PRs.
|
|
5
|
+
|
|
6
|
+
## Current maintainers
|
|
7
|
+
|
|
8
|
+
| Maintainer | GitHub | Focus |
|
|
9
|
+
|---|---|---|
|
|
10
|
+
| Melvin Carvalho | [@melvincarvalho](https://github.com/melvincarvalho) | Project lead; substrate, releases |
|
|
11
|
+
| John O'Hare | [@jjohare](https://github.com/jjohare) | (onboarding) |
|
|
12
|
+
|
|
13
|
+
See [.github/CODEOWNERS](.github/CODEOWNERS) for path-level review routing.
|
|
14
|
+
|
|
15
|
+
## Process
|
|
16
|
+
|
|
17
|
+
Workflow, code style, and AI-assistance disclosure are covered in
|
|
18
|
+
[CONTRIBUTING.md](CONTRIBUTING.md). Maintainers follow the same workflow
|
|
19
|
+
as other contributors (issue → branch → PR → review → merge).
|
|
20
|
+
|
|
21
|
+
## Becoming a maintainer
|
|
22
|
+
|
|
23
|
+
By invitation of an existing maintainer, after demonstrated substantive
|
|
24
|
+
contribution. No formal vote; existing maintainers make the call and
|
|
25
|
+
update this file.
|
|
26
|
+
|
|
27
|
+
## Security
|
|
28
|
+
|
|
29
|
+
Security disclosures: use [GitHub private security advisories](https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/security/advisories/new).
|
package/README.md
CHANGED
|
@@ -145,6 +145,10 @@ Full options: [docs/configuration.md](docs/configuration.md)
|
|
|
145
145
|
npm test
|
|
146
146
|
```
|
|
147
147
|
|
|
148
|
+
## Maintainers
|
|
149
|
+
|
|
150
|
+
JSS is maintained by [@melvincarvalho](https://github.com/melvincarvalho) and [@jjohare](https://github.com/jjohare). See [MAINTAINERS.md](MAINTAINERS.md).
|
|
151
|
+
|
|
148
152
|
## License
|
|
149
153
|
|
|
150
154
|
Licensed under [AGPL-3.0](./LICENSE).
|
package/bin/jss.js
CHANGED
|
@@ -87,8 +87,8 @@ program
|
|
|
87
87
|
.option('-c, --config <file>', 'Config file path')
|
|
88
88
|
.option('--ssl-key <path>', 'Path to SSL private key (PEM)')
|
|
89
89
|
.option('--ssl-cert <path>', 'Path to SSL certificate (PEM)')
|
|
90
|
-
.option('--
|
|
91
|
-
.option('--no-
|
|
90
|
+
.option('--multi-user', 'Enable multi-user mode')
|
|
91
|
+
.option('--no-multi-user', 'Disable multi-user mode')
|
|
92
92
|
.option('--conneg', 'Enable content negotiation (Turtle support)')
|
|
93
93
|
.option('--no-conneg', 'Disable content negotiation')
|
|
94
94
|
.option('--notifications', 'Enable WebSocket notifications')
|
|
@@ -159,6 +159,12 @@ program
|
|
|
159
159
|
.option('--print-config', 'Print configuration and exit')
|
|
160
160
|
.action(async (options) => {
|
|
161
161
|
try {
|
|
162
|
+
// Normalize --multi-user (Commander camelCase: multiUser) to internal key
|
|
163
|
+
if (options.multiUser !== undefined) {
|
|
164
|
+
options.multiuser = options.multiUser;
|
|
165
|
+
delete options.multiUser;
|
|
166
|
+
}
|
|
167
|
+
|
|
162
168
|
const config = await loadConfig(options, options.config);
|
|
163
169
|
|
|
164
170
|
// Set DATA_ROOT env var so all modules use the same data directory
|
package/docs/mcp.md
CHANGED
|
@@ -82,6 +82,79 @@ Both `SKILL.md` (Anthropic markdown format) and `SKILL.jsonld` (typed JSON-LD de
|
|
|
82
82
|
|
|
83
83
|
Pod-resident docs (`/docs/`, `/public/apps/<name>/docs/`) are reachable via the regular CRUD tools — no separate surface.
|
|
84
84
|
|
|
85
|
+
### ACL editing (#496)
|
|
86
|
+
|
|
87
|
+
The most common owner operation is delegating an agent access to a resource. The MCP server exposes ACL editing as first-class tools so bots don't need to hand-roll JSON-LD.
|
|
88
|
+
|
|
89
|
+
| Tool | Effect | WAC check |
|
|
90
|
+
|---|---|---|
|
|
91
|
+
| `read_acl` | Return the ACL for a resource as a structured list (agents, agentClasses, modes, isDefault) | Control on resource |
|
|
92
|
+
| `write_acl` | Persist a structured ACL to the resource's `.acl` file | Control on resource |
|
|
93
|
+
|
|
94
|
+
```json
|
|
95
|
+
// write_acl arguments
|
|
96
|
+
{
|
|
97
|
+
"path": "/private/notes/",
|
|
98
|
+
"authorizations": [
|
|
99
|
+
{
|
|
100
|
+
"agents": ["did:nostr:abc...", "https://alice.example.com/profile#me"],
|
|
101
|
+
"modes": ["Read", "Append"],
|
|
102
|
+
"isDefault": true
|
|
103
|
+
},
|
|
104
|
+
{
|
|
105
|
+
"agentClasses": ["acl:AuthenticatedAgent"],
|
|
106
|
+
"modes": ["Read"]
|
|
107
|
+
}
|
|
108
|
+
]
|
|
109
|
+
}
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
The structured form abstracts away JSON-LD shape (`acl:agent` vs `acl:agentClass`, mode URI prefixes, `acl:default` propagation). New WAC vocabulary additions extend the structure without breaking existing bots.
|
|
113
|
+
|
|
114
|
+
### Subscribe — live change notifications (#494)
|
|
115
|
+
|
|
116
|
+
`subscribe` is a streaming tool. The response switches to SSE (`text/event-stream`) and emits MCP notifications as resources change. WAC-filtered per event so subscribers only see resources they have Read access to.
|
|
117
|
+
|
|
118
|
+
| Tool | Effect |
|
|
119
|
+
|---|---|
|
|
120
|
+
| `subscribe` | Stream resource_changed events for a container subtree or specific path |
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
curl -N http://localhost:4443/mcp \
|
|
124
|
+
-H "Content-Type: application/json" \
|
|
125
|
+
-H "Authorization: Bearer $TOKEN" \
|
|
126
|
+
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"subscribe","arguments":{"path":"/forum/channels/general/"}}}'
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Events arrive as:
|
|
130
|
+
```
|
|
131
|
+
event: notification
|
|
132
|
+
data: {"jsonrpc":"2.0","method":"notifications/tool_event","params":{"tool":"subscribe","event":{"type":"resource_changed","path":"/forum/channels/general/abc.jsonld"}}}
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
For chat-style bots, replace polling with `subscribe` and react to events as they land.
|
|
136
|
+
|
|
137
|
+
### Federation — bot-to-bot (#495)
|
|
138
|
+
|
|
139
|
+
`call_remote_pod` lets a bot on this pod invoke MCP tools on another pod. WAC-gated on both ends; depth-capped at 3 hops.
|
|
140
|
+
|
|
141
|
+
| Tool | Effect | Gating |
|
|
142
|
+
|---|---|---|
|
|
143
|
+
| `call_remote_pod` | Forward an MCP `tools/call` to another pod | Caller needs acl:Write on `<their-pod>/private/federation/` on this pod |
|
|
144
|
+
|
|
145
|
+
```json
|
|
146
|
+
{
|
|
147
|
+
"pod_url": "https://alice.example.com",
|
|
148
|
+
"tool": "read_resource",
|
|
149
|
+
"arguments": { "path": "/public/notes/shared.md" },
|
|
150
|
+
"auth": { "type": "bearer", "token": "..." }
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
To delegate outbound federation to a specific agent, grant them `acl:Write` on your `/private/federation/` container. Owners control which agents can initiate calls; remote pods control what they expose.
|
|
155
|
+
|
|
156
|
+
Foreign WebIDs (identities hosted on other pods) cannot initiate federation from this pod — there's no local path for the gate to live at. Multi-pod federation chains compose by hopping between pods, each gated locally.
|
|
157
|
+
|
|
85
158
|
### Introspection
|
|
86
159
|
|
|
87
160
|
| Tool | Returns |
|
|
@@ -98,13 +171,47 @@ http://localhost:4443/mcp
|
|
|
98
171
|
|
|
99
172
|
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
173
|
|
|
174
|
+
## Footguns
|
|
175
|
+
|
|
176
|
+
A short list of real gotchas to know about, learned from live-fire use:
|
|
177
|
+
|
|
178
|
+
### Use absolute WebIDs in `write_acl` agents
|
|
179
|
+
|
|
180
|
+
The `agents` array in a `write_acl` authorization is interpreted as a list of URIs. Relative paths (e.g. `../profile/card.jsonld#me`) resolve against the **.acl file's URL**, not the pod root — and the .acl URL changes depending on which resource the ACL applies to. Two pitfalls:
|
|
181
|
+
|
|
182
|
+
```json
|
|
183
|
+
// Pod owner WebID: http://example.com/profile/card.jsonld#me
|
|
184
|
+
// Writing this ACL to /public/forum/.acl:
|
|
185
|
+
{
|
|
186
|
+
"agents": ["../profile/card.jsonld#me"], // wrong — resolves to /public/profile/card.jsonld#me
|
|
187
|
+
"agents": ["./profile/card.jsonld#me"], // wrong — resolves to /public/forum/profile/card.jsonld#me
|
|
188
|
+
"agents": ["/profile/card.jsonld#me"], // right — absolute path, resolves to /profile/card.jsonld#me
|
|
189
|
+
"agents": ["http://example.com/profile/card.jsonld#me"] // right — absolute URL, host-portable
|
|
190
|
+
}
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
**Always use absolute WebID URLs unless you know exactly what relative-URL resolution will give you.** Absolute URLs also make the ACL portable across hostnames.
|
|
194
|
+
|
|
195
|
+
### `write_acl` will refuse if you'd lock yourself out
|
|
196
|
+
|
|
197
|
+
If the proposed ACL doesn't grant `Control` to the caller (typically a relative-URL mistake), `write_acl` refuses with an explanatory error. This is a safety, not a permission check — it's stopping you from breaking your own access.
|
|
198
|
+
|
|
199
|
+
If you really want to transfer ownership (remove your own access), do it in two steps:
|
|
200
|
+
|
|
201
|
+
1. First `write_acl` granting Control to the new owner *in addition to* yourself
|
|
202
|
+
2. Then the new owner calls `write_acl` removing you
|
|
203
|
+
|
|
204
|
+
### Subscribe over long-running connections needs a keep-alive client
|
|
205
|
+
|
|
206
|
+
The `subscribe` tool keeps an HTTP+SSE connection open indefinitely. Some HTTP clients, proxies, or load balancers will time out idle streams. If you're subscribing for hours, ensure your client handles SSE reconnect (most do; raw `curl` does not).
|
|
207
|
+
|
|
101
208
|
## What's not included (yet)
|
|
102
209
|
|
|
103
|
-
The
|
|
210
|
+
The current cut ships CRUD, structured ACL editing, subscribe, federation, skills, docs, and introspection. Deferred:
|
|
104
211
|
|
|
105
212
|
- **`update_resource` (PATCH)** — SPARQL Update / N3 patches. Read-modify-write through the CRUD tools is the workaround.
|
|
106
|
-
-
|
|
107
|
-
-
|
|
213
|
+
- **Discovery layer** — no DNS SRV / Solid Type Index entry for "this pod offers MCP". Owners share URLs explicitly today.
|
|
214
|
+
- **Pod-resident federation credentials** — every `call_remote_pod` carries its own auth. A vault for storing remote-pod credentials is a separate security surface worth its own design pass.
|
|
108
215
|
|
|
109
216
|
These are tracked as follow-ups on issue #490.
|
|
110
217
|
|
package/package.json
CHANGED
package/src/mcp/index.js
CHANGED
|
@@ -23,7 +23,7 @@ import {
|
|
|
23
23
|
rpcResult,
|
|
24
24
|
rpcError
|
|
25
25
|
} from './protocol.js';
|
|
26
|
-
import { listToolsForRpc, callTool } from './tools.js';
|
|
26
|
+
import { listToolsForRpc, callTool, TOOLS } from './tools.js';
|
|
27
27
|
import { getWebIdFromRequestAsync } from '../auth/token.js';
|
|
28
28
|
|
|
29
29
|
const ALLOWED_METHODS = new Set([
|
|
@@ -84,6 +84,75 @@ async function dispatch(msg, ctx) {
|
|
|
84
84
|
return rpcError(id, RPC_ERRORS.METHOD_NOT_FOUND, `unhandled method: ${method}`);
|
|
85
85
|
}
|
|
86
86
|
|
|
87
|
+
function isStreamingToolCall(body) {
|
|
88
|
+
return body
|
|
89
|
+
&& body.method === 'tools/call'
|
|
90
|
+
&& body.params?.name
|
|
91
|
+
&& TOOLS[body.params.name]
|
|
92
|
+
// Sniff: invoke the handler synchronously so we can detect the
|
|
93
|
+
// `{ stream: true, init, run }` shape. Streaming tools must be
|
|
94
|
+
// pure-synchronous in their shape-decision (no awaits before
|
|
95
|
+
// returning the stream descriptor).
|
|
96
|
+
&& (() => {
|
|
97
|
+
try {
|
|
98
|
+
// We can't safely call the handler without a ctx, so we just
|
|
99
|
+
// rely on the tool name being in our streaming-tools set.
|
|
100
|
+
return STREAMING_TOOLS.has(body.params.name);
|
|
101
|
+
} catch { return false; }
|
|
102
|
+
})();
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
const STREAMING_TOOLS = new Set(['subscribe']);
|
|
106
|
+
|
|
107
|
+
async function handleStreamingTool(request, reply, body, ctx) {
|
|
108
|
+
const tool = TOOLS[body.params.name];
|
|
109
|
+
let descriptor;
|
|
110
|
+
try {
|
|
111
|
+
descriptor = tool.handler(body.params.arguments || {}, ctx);
|
|
112
|
+
} catch (e) {
|
|
113
|
+
reply.code(500);
|
|
114
|
+
reply.header('Content-Type', 'application/json');
|
|
115
|
+
return rpcError(body.id, RPC_ERRORS.INTERNAL_ERROR, e.message);
|
|
116
|
+
}
|
|
117
|
+
if (!descriptor || descriptor.stream !== true) {
|
|
118
|
+
// Tool decided not to stream after all — emit single-shot response
|
|
119
|
+
reply.header('Content-Type', 'application/json');
|
|
120
|
+
return rpcResult(body.id, descriptor);
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
// Switch to SSE
|
|
124
|
+
reply.raw.writeHead(200, {
|
|
125
|
+
'Content-Type': 'text/event-stream',
|
|
126
|
+
'Cache-Control': 'no-cache, no-transform',
|
|
127
|
+
'Connection': 'keep-alive',
|
|
128
|
+
'X-Accel-Buffering': 'no'
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
const controller = new AbortController();
|
|
132
|
+
request.raw.on('close', () => controller.abort());
|
|
133
|
+
|
|
134
|
+
const sendEvent = (payload) => {
|
|
135
|
+
if (controller.signal.aborted) return;
|
|
136
|
+
const note = {
|
|
137
|
+
jsonrpc: '2.0',
|
|
138
|
+
method: 'notifications/tool_event',
|
|
139
|
+
params: { tool: body.params.name, event: payload }
|
|
140
|
+
};
|
|
141
|
+
reply.raw.write(`event: notification\ndata: ${JSON.stringify(note)}\n\n`);
|
|
142
|
+
};
|
|
143
|
+
|
|
144
|
+
try {
|
|
145
|
+
const initial = await descriptor.init();
|
|
146
|
+
if (initial) sendEvent(initial);
|
|
147
|
+
await descriptor.run(sendEvent, controller.signal);
|
|
148
|
+
} catch (e) {
|
|
149
|
+
sendEvent({ type: 'error', message: e.message });
|
|
150
|
+
} finally {
|
|
151
|
+
if (!controller.signal.aborted) reply.raw.end();
|
|
152
|
+
}
|
|
153
|
+
return reply;
|
|
154
|
+
}
|
|
155
|
+
|
|
87
156
|
/**
|
|
88
157
|
* Register the MCP plugin with Fastify.
|
|
89
158
|
*/
|
|
@@ -99,11 +168,21 @@ export async function mcpPlugin(fastify, _options) {
|
|
|
99
168
|
// null webId means "anonymous"; WAC will treat it accordingly.
|
|
100
169
|
const { webId } = await getWebIdFromRequestAsync(request).catch(() => ({ webId: null }));
|
|
101
170
|
|
|
171
|
+
// Federation depth (used by call_remote_pod to enforce the cap)
|
|
172
|
+
const depthHdr = request.headers['mcp-federation-depth'];
|
|
173
|
+
const federationDepth = depthHdr ? parseInt(depthHdr, 10) || 0 : 0;
|
|
174
|
+
|
|
102
175
|
const ctx = {
|
|
103
176
|
webId: webId || null,
|
|
104
|
-
origin: originOf(request)
|
|
177
|
+
origin: originOf(request),
|
|
178
|
+
federationDepth
|
|
105
179
|
};
|
|
106
180
|
|
|
181
|
+
// Streaming tool? Hand off to SSE handler.
|
|
182
|
+
if (!Array.isArray(body) && isStreamingToolCall(body)) {
|
|
183
|
+
return handleStreamingTool(request, reply, body, ctx);
|
|
184
|
+
}
|
|
185
|
+
|
|
107
186
|
// Batch support (array of requests)
|
|
108
187
|
if (Array.isArray(body)) {
|
|
109
188
|
const out = [];
|