javascript-solid-server 0.0.199 → 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 +3 -1
- package/bin/jss.js +3 -0
- package/docs/mcp.md +121 -0
- package/package.json +1 -1
- 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
|
|
|
@@ -106,6 +107,7 @@ Full options: [docs/configuration.md](docs/configuration.md)
|
|
|
106
107
|
| WebSocket Notifications | [docs/notifications.md](docs/notifications.md) |
|
|
107
108
|
| Git Support | [docs/git-support.md](docs/git-support.md) |
|
|
108
109
|
| Installing Apps | [docs/app-install.md](docs/app-install.md) |
|
|
110
|
+
| MCP (pod as agent tool surface) | [docs/mcp.md](docs/mcp.md) |
|
|
109
111
|
| Nostr Relay | [docs/nostr.md](docs/nostr.md) |
|
|
110
112
|
| ActivityPub & Mastodon API | [docs/activitypub.md](docs/activitypub.md) |
|
|
111
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 });
|
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/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',
|
package/src/mcp/index.js
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCP (Model Context Protocol) plugin.
|
|
3
|
+
*
|
|
4
|
+
* Usage:
|
|
5
|
+
* createServer({ mcp: true })
|
|
6
|
+
*
|
|
7
|
+
* Endpoint:
|
|
8
|
+
* POST /mcp (JSON-RPC 2.0, MCP Streamable HTTP transport)
|
|
9
|
+
*
|
|
10
|
+
* Auth:
|
|
11
|
+
* Reuses JSS's existing auth chain — Bearer / DPoP / NIP-98 — so
|
|
12
|
+
* the same WAC rules that gate /public, /private, etc. also gate
|
|
13
|
+
* tool calls. Anonymous requests get the same WAC treatment as
|
|
14
|
+
* any other anonymous request.
|
|
15
|
+
*
|
|
16
|
+
* Spec: https://spec.modelcontextprotocol.io/specification/2025-03-26/
|
|
17
|
+
*/
|
|
18
|
+
|
|
19
|
+
import {
|
|
20
|
+
PROTOCOL_VERSION,
|
|
21
|
+
SERVER_INFO,
|
|
22
|
+
RPC_ERRORS,
|
|
23
|
+
rpcResult,
|
|
24
|
+
rpcError
|
|
25
|
+
} from './protocol.js';
|
|
26
|
+
import { listToolsForRpc, callTool } from './tools.js';
|
|
27
|
+
import { getWebIdFromRequestAsync } from '../auth/token.js';
|
|
28
|
+
|
|
29
|
+
const ALLOWED_METHODS = new Set([
|
|
30
|
+
'initialize',
|
|
31
|
+
'initialized',
|
|
32
|
+
'notifications/initialized',
|
|
33
|
+
'tools/list',
|
|
34
|
+
'tools/call',
|
|
35
|
+
'ping'
|
|
36
|
+
]);
|
|
37
|
+
|
|
38
|
+
function originOf(request) {
|
|
39
|
+
const host = request.headers.host || request.hostname;
|
|
40
|
+
const proto = request.protocol || 'http';
|
|
41
|
+
return `${proto}://${host}`;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
async function dispatch(msg, ctx) {
|
|
45
|
+
const { id, method, params } = msg;
|
|
46
|
+
|
|
47
|
+
if (!ALLOWED_METHODS.has(method)) {
|
|
48
|
+
return rpcError(id, RPC_ERRORS.METHOD_NOT_FOUND, `unknown method: ${method}`);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
if (method === 'ping') {
|
|
52
|
+
return rpcResult(id, {});
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
if (method === 'initialize') {
|
|
56
|
+
return rpcResult(id, {
|
|
57
|
+
protocolVersion: PROTOCOL_VERSION,
|
|
58
|
+
serverInfo: SERVER_INFO,
|
|
59
|
+
capabilities: {
|
|
60
|
+
tools: { listChanged: false }
|
|
61
|
+
}
|
|
62
|
+
});
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
if (method === 'initialized' || method === 'notifications/initialized') {
|
|
66
|
+
// Notifications carry no id; nothing to return
|
|
67
|
+
return null;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
if (method === 'tools/list') {
|
|
71
|
+
return rpcResult(id, { tools: listToolsForRpc() });
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
if (method === 'tools/call') {
|
|
75
|
+
const toolName = params?.name;
|
|
76
|
+
const toolArgs = params?.arguments || {};
|
|
77
|
+
if (!toolName) {
|
|
78
|
+
return rpcError(id, RPC_ERRORS.INVALID_PARAMS, 'tool name required');
|
|
79
|
+
}
|
|
80
|
+
const result = await callTool(toolName, toolArgs, ctx);
|
|
81
|
+
return rpcResult(id, result);
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
return rpcError(id, RPC_ERRORS.METHOD_NOT_FOUND, `unhandled method: ${method}`);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/**
|
|
88
|
+
* Register the MCP plugin with Fastify.
|
|
89
|
+
*/
|
|
90
|
+
export async function mcpPlugin(fastify, _options) {
|
|
91
|
+
fastify.post('/mcp', async (request, reply) => {
|
|
92
|
+
const body = request.body;
|
|
93
|
+
if (!body || typeof body !== 'object') {
|
|
94
|
+
reply.code(400);
|
|
95
|
+
return rpcError(null, RPC_ERRORS.INVALID_REQUEST, 'expected JSON-RPC body');
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
// Identity for tool calls — pulled from the inbound auth on /mcp itself.
|
|
99
|
+
// null webId means "anonymous"; WAC will treat it accordingly.
|
|
100
|
+
const { webId } = await getWebIdFromRequestAsync(request).catch(() => ({ webId: null }));
|
|
101
|
+
|
|
102
|
+
const ctx = {
|
|
103
|
+
webId: webId || null,
|
|
104
|
+
origin: originOf(request)
|
|
105
|
+
};
|
|
106
|
+
|
|
107
|
+
// Batch support (array of requests)
|
|
108
|
+
if (Array.isArray(body)) {
|
|
109
|
+
const out = [];
|
|
110
|
+
for (const msg of body) {
|
|
111
|
+
const r = await dispatch(msg, ctx);
|
|
112
|
+
if (r) out.push(r);
|
|
113
|
+
}
|
|
114
|
+
reply.header('Content-Type', 'application/json');
|
|
115
|
+
return out;
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
const result = await dispatch(body, ctx);
|
|
119
|
+
if (result === null) {
|
|
120
|
+
// Notification (no response body)
|
|
121
|
+
reply.code(204);
|
|
122
|
+
return null;
|
|
123
|
+
}
|
|
124
|
+
reply.header('Content-Type', 'application/json');
|
|
125
|
+
return result;
|
|
126
|
+
});
|
|
127
|
+
|
|
128
|
+
fastify.options('/mcp', async (_request, reply) => {
|
|
129
|
+
reply.header('Allow', 'POST, OPTIONS');
|
|
130
|
+
reply.code(204);
|
|
131
|
+
return null;
|
|
132
|
+
});
|
|
133
|
+
}
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCP (Model Context Protocol) protocol envelope.
|
|
3
|
+
*
|
|
4
|
+
* Implements the Streamable HTTP transport for MCP 2025-03-26.
|
|
5
|
+
* Single endpoint (POST /mcp). Client sends JSON-RPC 2.0 requests.
|
|
6
|
+
* Server responds with JSON-RPC 2.0 responses (single-shot JSON for now;
|
|
7
|
+
* SSE streaming can be added later for subscribe-style tools).
|
|
8
|
+
*
|
|
9
|
+
* Spec: https://spec.modelcontextprotocol.io/specification/2025-03-26/
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
export const PROTOCOL_VERSION = '2025-03-26';
|
|
13
|
+
|
|
14
|
+
export const SERVER_INFO = {
|
|
15
|
+
name: 'jss-mcp',
|
|
16
|
+
version: '0.1.0'
|
|
17
|
+
};
|
|
18
|
+
|
|
19
|
+
// JSON-RPC error codes
|
|
20
|
+
export const RPC_ERRORS = {
|
|
21
|
+
PARSE_ERROR: -32700,
|
|
22
|
+
INVALID_REQUEST: -32600,
|
|
23
|
+
METHOD_NOT_FOUND: -32601,
|
|
24
|
+
INVALID_PARAMS: -32602,
|
|
25
|
+
INTERNAL_ERROR: -32603,
|
|
26
|
+
// MCP-specific
|
|
27
|
+
TOOL_ERROR: -32000,
|
|
28
|
+
AUTH_REQUIRED: -32001,
|
|
29
|
+
ACCESS_DENIED: -32002
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
export function rpcResult(id, result) {
|
|
33
|
+
return { jsonrpc: '2.0', id, result };
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
export function rpcError(id, code, message, data) {
|
|
37
|
+
const err = { code, message };
|
|
38
|
+
if (data !== undefined) err.data = data;
|
|
39
|
+
return { jsonrpc: '2.0', id, error: err };
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export function toolText(text) {
|
|
43
|
+
return { content: [{ type: 'text', text }], isError: false };
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export function toolError(message) {
|
|
47
|
+
return { content: [{ type: 'text', text: message }], isError: true };
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
export function toolJson(value) {
|
|
51
|
+
return toolText(JSON.stringify(value, null, 2));
|
|
52
|
+
}
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Skill discovery for the MCP server.
|
|
3
|
+
*
|
|
4
|
+
* Skills are SKILL.md files (or SKILL.jsonld) at well-known paths:
|
|
5
|
+
*
|
|
6
|
+
* <pod>/SKILL.md pod-wide
|
|
7
|
+
* <pod>/public/apps/<name>/SKILL.md per-app
|
|
8
|
+
* <pod>/private/bots/<name>/SKILL.md per-bot
|
|
9
|
+
*
|
|
10
|
+
* The discovery channel (list_skills) is stable; the payload format
|
|
11
|
+
* declared via `skill:format` evolves (anthropic.skill.v1 today,
|
|
12
|
+
* future vocabularies plug in by name).
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
import * as storage from '../storage/filesystem.js';
|
|
16
|
+
|
|
17
|
+
const POD_ROOT_SKILL = ['/SKILL.md', '/SKILL.jsonld'];
|
|
18
|
+
const APPS_BASE = '/public/apps/';
|
|
19
|
+
const BOTS_BASE = '/private/bots/';
|
|
20
|
+
|
|
21
|
+
function formatForPath(path) {
|
|
22
|
+
if (path.endsWith('.jsonld')) return 'jsonld';
|
|
23
|
+
return 'anthropic.skill.v1';
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
function scopeFromPath(path) {
|
|
27
|
+
if (path.startsWith(APPS_BASE)) return 'app';
|
|
28
|
+
if (path.startsWith(BOTS_BASE)) return 'bot';
|
|
29
|
+
return 'pod';
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
async function tryEntry(path) {
|
|
33
|
+
for (const variant of [path, path.replace(/\.md$/, '.jsonld')]) {
|
|
34
|
+
if (await storage.exists(variant)) {
|
|
35
|
+
const s = await storage.stat(variant).catch(() => null);
|
|
36
|
+
return {
|
|
37
|
+
'@id': variant,
|
|
38
|
+
'skill:scope': scopeFromPath(variant),
|
|
39
|
+
'skill:format': formatForPath(variant),
|
|
40
|
+
'skill:source': variant,
|
|
41
|
+
'schema:contentSize': s?.size ?? null
|
|
42
|
+
};
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
return null;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
async function listContainerNames(containerPath) {
|
|
49
|
+
if (!(await storage.exists(containerPath))) return [];
|
|
50
|
+
try {
|
|
51
|
+
const entries = await storage.listContainer(containerPath);
|
|
52
|
+
return entries
|
|
53
|
+
.filter(e => e.isDirectory)
|
|
54
|
+
.map(e => e.name);
|
|
55
|
+
} catch {
|
|
56
|
+
return [];
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Walk the conventional skill locations and return discovered skills.
|
|
62
|
+
*/
|
|
63
|
+
export async function discoverSkills() {
|
|
64
|
+
const items = [];
|
|
65
|
+
|
|
66
|
+
// Pod-wide
|
|
67
|
+
for (const p of POD_ROOT_SKILL) {
|
|
68
|
+
if (await storage.exists(p)) {
|
|
69
|
+
items.push({
|
|
70
|
+
'@id': p,
|
|
71
|
+
'skill:scope': 'pod',
|
|
72
|
+
'skill:format': formatForPath(p),
|
|
73
|
+
'skill:source': p,
|
|
74
|
+
'schema:name': 'pod'
|
|
75
|
+
});
|
|
76
|
+
break;
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// Apps
|
|
81
|
+
for (const name of await listContainerNames(APPS_BASE)) {
|
|
82
|
+
const skill = await tryEntry(`${APPS_BASE}${name}/SKILL.md`);
|
|
83
|
+
if (skill) {
|
|
84
|
+
skill['schema:name'] = name;
|
|
85
|
+
items.push(skill);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
// Bots
|
|
90
|
+
for (const name of await listContainerNames(BOTS_BASE)) {
|
|
91
|
+
const skill = await tryEntry(`${BOTS_BASE}${name}/SKILL.md`);
|
|
92
|
+
if (skill) {
|
|
93
|
+
skill['schema:name'] = name;
|
|
94
|
+
items.push(skill);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
return {
|
|
99
|
+
'@context': {
|
|
100
|
+
skill: 'urn:skill:',
|
|
101
|
+
schema: 'https://schema.org/'
|
|
102
|
+
},
|
|
103
|
+
'@type': 'skill:SkillIndex',
|
|
104
|
+
'skill:items': items
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/**
|
|
109
|
+
* Read a single skill file by path (relative to pod root).
|
|
110
|
+
*/
|
|
111
|
+
export async function readSkill(path) {
|
|
112
|
+
if (!path || typeof path !== 'string') {
|
|
113
|
+
throw new Error('skill path required');
|
|
114
|
+
}
|
|
115
|
+
if (!path.startsWith('/')) path = '/' + path;
|
|
116
|
+
if (!(await storage.exists(path))) {
|
|
117
|
+
throw new Error(`skill not found: ${path}`);
|
|
118
|
+
}
|
|
119
|
+
const content = await storage.read(path);
|
|
120
|
+
return {
|
|
121
|
+
path,
|
|
122
|
+
format: formatForPath(path),
|
|
123
|
+
scope: scopeFromPath(path),
|
|
124
|
+
body: content.toString('utf8')
|
|
125
|
+
};
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/**
|
|
129
|
+
* Read the pod-wide SKILL.md (or .jsonld). Returns null if none exists.
|
|
130
|
+
*/
|
|
131
|
+
export async function readPodSkill() {
|
|
132
|
+
for (const p of POD_ROOT_SKILL) {
|
|
133
|
+
if (await storage.exists(p)) {
|
|
134
|
+
return readSkill(p);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
return null;
|
|
138
|
+
}
|
package/src/mcp/tools.js
ADDED
|
@@ -0,0 +1,375 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCP tool definitions and dispatch.
|
|
3
|
+
*
|
|
4
|
+
* Each tool is a function: (args, ctx) -> Promise<MCPToolResult>
|
|
5
|
+
* ctx.webId — authenticated identity (null = anonymous)
|
|
6
|
+
* ctx.origin — request origin for building absolute URLs
|
|
7
|
+
*
|
|
8
|
+
* All WAC checks delegate to src/wac/checker.js so MCP tools have
|
|
9
|
+
* the same access semantics as the HTTP endpoints.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import * as storage from '../storage/filesystem.js';
|
|
13
|
+
import { checkAccess } from '../wac/checker.js';
|
|
14
|
+
import { AccessMode } from '../wac/parser.js';
|
|
15
|
+
import { toolText, toolError, toolJson } from './protocol.js';
|
|
16
|
+
import { discoverSkills, readSkill, readPodSkill } from './skills.js';
|
|
17
|
+
import { readFile, readdir, stat as fsStat } from 'fs/promises';
|
|
18
|
+
import { join, dirname, resolve as pathResolve } from 'path';
|
|
19
|
+
import { fileURLToPath } from 'url';
|
|
20
|
+
|
|
21
|
+
const __dirname = dirname(fileURLToPath(import.meta.url));
|
|
22
|
+
const JSS_DOCS_DIR = pathResolve(__dirname, '..', '..', 'docs');
|
|
23
|
+
|
|
24
|
+
function buildUrl(ctx, path) {
|
|
25
|
+
if (!path.startsWith('/')) path = '/' + path;
|
|
26
|
+
return `${ctx.origin}${path}`;
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
function parentPath(p) {
|
|
30
|
+
if (p === '/' || p === '') return '/';
|
|
31
|
+
const trimmed = p.endsWith('/') ? p.slice(0, -1) : p;
|
|
32
|
+
const idx = trimmed.lastIndexOf('/');
|
|
33
|
+
return idx <= 0 ? '/' : trimmed.slice(0, idx + 1);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
async function wac(ctx, path, mode) {
|
|
37
|
+
// For writes against a non-existent resource, fall back to checking
|
|
38
|
+
// the parent container — same pattern as src/auth/middleware.js so MCP
|
|
39
|
+
// tools have identical WAC semantics to the HTTP endpoints.
|
|
40
|
+
const isWrite = mode === AccessMode.WRITE || mode === AccessMode.APPEND;
|
|
41
|
+
let checkPath = path;
|
|
42
|
+
let checkIsContainer = path.endsWith('/');
|
|
43
|
+
if (isWrite && !path.endsWith('/') && !(await storage.exists(path))) {
|
|
44
|
+
checkPath = parentPath(path);
|
|
45
|
+
checkIsContainer = true;
|
|
46
|
+
}
|
|
47
|
+
const { allowed } = await checkAccess({
|
|
48
|
+
resourceUrl: buildUrl(ctx, checkPath),
|
|
49
|
+
resourcePath: checkPath,
|
|
50
|
+
isContainer: checkIsContainer,
|
|
51
|
+
agentWebId: ctx.webId,
|
|
52
|
+
requiredMode: mode
|
|
53
|
+
});
|
|
54
|
+
return allowed;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
// --- CRUD tools ---
|
|
58
|
+
|
|
59
|
+
async function list_resources({ path }, ctx) {
|
|
60
|
+
if (!path || !path.endsWith('/')) {
|
|
61
|
+
return toolError('path must be a container (ending in /)');
|
|
62
|
+
}
|
|
63
|
+
if (!(await wac(ctx, path, AccessMode.READ))) {
|
|
64
|
+
return toolError(`access denied: read ${path}`);
|
|
65
|
+
}
|
|
66
|
+
if (!(await storage.exists(path))) {
|
|
67
|
+
return toolError(`not found: ${path}`);
|
|
68
|
+
}
|
|
69
|
+
const entries = await storage.listContainer(path);
|
|
70
|
+
return toolJson({
|
|
71
|
+
container: path,
|
|
72
|
+
items: (entries || []).map(e => ({
|
|
73
|
+
name: e.name,
|
|
74
|
+
path: `${path}${e.name}${e.isDirectory ? '/' : ''}`,
|
|
75
|
+
isContainer: e.isDirectory,
|
|
76
|
+
size: e.size ?? null,
|
|
77
|
+
modified: e.modified ?? null
|
|
78
|
+
}))
|
|
79
|
+
});
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
async function read_resource({ path }, ctx) {
|
|
83
|
+
if (!path) return toolError('path required');
|
|
84
|
+
if (!(await wac(ctx, path, AccessMode.READ))) {
|
|
85
|
+
return toolError(`access denied: read ${path}`);
|
|
86
|
+
}
|
|
87
|
+
if (!(await storage.exists(path))) {
|
|
88
|
+
return toolError(`not found: ${path}`);
|
|
89
|
+
}
|
|
90
|
+
if (path.endsWith('/')) {
|
|
91
|
+
return toolError('use list_resources for containers');
|
|
92
|
+
}
|
|
93
|
+
const content = await storage.read(path);
|
|
94
|
+
let body = content.toString('utf8');
|
|
95
|
+
// Truncate very large reads
|
|
96
|
+
const MAX = 200_000;
|
|
97
|
+
let truncated = false;
|
|
98
|
+
if (body.length > MAX) {
|
|
99
|
+
body = body.slice(0, MAX);
|
|
100
|
+
truncated = true;
|
|
101
|
+
}
|
|
102
|
+
const result = { path, body };
|
|
103
|
+
if (truncated) result.truncated = true;
|
|
104
|
+
return toolJson(result);
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
async function write_resource({ path, content, contentType }, ctx) {
|
|
108
|
+
if (!path) return toolError('path required');
|
|
109
|
+
if (path.endsWith('/')) return toolError('cannot PUT a container; use create_resource');
|
|
110
|
+
if (content == null) return toolError('content required');
|
|
111
|
+
if (!(await wac(ctx, path, AccessMode.WRITE))) {
|
|
112
|
+
return toolError(`access denied: write ${path}`);
|
|
113
|
+
}
|
|
114
|
+
await storage.write(path, Buffer.from(content, 'utf8'), {
|
|
115
|
+
contentType: contentType || 'text/plain'
|
|
116
|
+
});
|
|
117
|
+
return toolText(`wrote ${path} (${Buffer.byteLength(content, 'utf8')} bytes)`);
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
async function create_resource({ container, slug, content, contentType, isContainer }, ctx) {
|
|
121
|
+
if (!container || !container.endsWith('/')) {
|
|
122
|
+
return toolError('container path required (must end in /)');
|
|
123
|
+
}
|
|
124
|
+
if (!(await wac(ctx, container, AccessMode.APPEND))) {
|
|
125
|
+
return toolError(`access denied: append ${container}`);
|
|
126
|
+
}
|
|
127
|
+
if (!(await storage.exists(container))) {
|
|
128
|
+
return toolError(`container not found: ${container}`);
|
|
129
|
+
}
|
|
130
|
+
const name = await storage.generateUniqueFilename(container, slug || null, !!isContainer);
|
|
131
|
+
const childPath = `${container}${name}${isContainer ? '/' : ''}`;
|
|
132
|
+
if (isContainer) {
|
|
133
|
+
await storage.createContainer(childPath);
|
|
134
|
+
return toolText(`created container ${childPath}`);
|
|
135
|
+
}
|
|
136
|
+
await storage.write(childPath, Buffer.from(content || '', 'utf8'), {
|
|
137
|
+
contentType: contentType || 'text/plain'
|
|
138
|
+
});
|
|
139
|
+
return toolText(`created ${childPath}`);
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
async function delete_resource({ path }, ctx) {
|
|
143
|
+
if (!path) return toolError('path required');
|
|
144
|
+
if (!(await wac(ctx, path, AccessMode.WRITE))) {
|
|
145
|
+
return toolError(`access denied: delete ${path}`);
|
|
146
|
+
}
|
|
147
|
+
if (!(await storage.exists(path))) {
|
|
148
|
+
return toolError(`not found: ${path}`);
|
|
149
|
+
}
|
|
150
|
+
await storage.remove(path);
|
|
151
|
+
return toolText(`deleted ${path}`);
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
async function head_resource({ path }, ctx) {
|
|
155
|
+
if (!path) return toolError('path required');
|
|
156
|
+
if (!(await wac(ctx, path, AccessMode.READ))) {
|
|
157
|
+
return toolError(`access denied: read ${path}`);
|
|
158
|
+
}
|
|
159
|
+
if (!(await storage.exists(path))) {
|
|
160
|
+
return toolError(`not found: ${path}`);
|
|
161
|
+
}
|
|
162
|
+
const s = await storage.stat(path);
|
|
163
|
+
return toolJson({
|
|
164
|
+
path,
|
|
165
|
+
isContainer: path.endsWith('/'),
|
|
166
|
+
size: s?.size ?? null,
|
|
167
|
+
modified: s?.mtime ?? null
|
|
168
|
+
});
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
// --- skill tools ---
|
|
172
|
+
|
|
173
|
+
async function list_skills(_args, _ctx) {
|
|
174
|
+
const idx = await discoverSkills();
|
|
175
|
+
return toolJson(idx);
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
async function get_skill({ path }, _ctx) {
|
|
179
|
+
if (!path) return toolError('path required');
|
|
180
|
+
try {
|
|
181
|
+
const skill = await readSkill(path);
|
|
182
|
+
return toolJson(skill);
|
|
183
|
+
} catch (e) {
|
|
184
|
+
return toolError(e.message);
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
async function get_pod_skill(_args, _ctx) {
|
|
189
|
+
const skill = await readPodSkill();
|
|
190
|
+
if (!skill) return toolText('no pod-wide SKILL.md or SKILL.jsonld');
|
|
191
|
+
return toolJson(skill);
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
// --- docs tools ---
|
|
195
|
+
|
|
196
|
+
async function list_docs(_args, _ctx) {
|
|
197
|
+
try {
|
|
198
|
+
const entries = await readdir(JSS_DOCS_DIR);
|
|
199
|
+
const md = entries.filter(n => n.endsWith('.md'));
|
|
200
|
+
const docs = await Promise.all(md.map(async name => {
|
|
201
|
+
const fullPath = join(JSS_DOCS_DIR, name);
|
|
202
|
+
const s = await fsStat(fullPath).catch(() => null);
|
|
203
|
+
return { name, size: s?.size ?? null };
|
|
204
|
+
}));
|
|
205
|
+
return toolJson({ source: 'jss-builtin', docs });
|
|
206
|
+
} catch {
|
|
207
|
+
return toolJson({ source: 'jss-builtin', docs: [] });
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
async function read_docs({ name }, _ctx) {
|
|
212
|
+
if (!name) return toolError('name required (e.g. "git-support.md")');
|
|
213
|
+
if (name.includes('..') || name.includes('/')) return toolError('name must be a bare filename');
|
|
214
|
+
if (!name.endsWith('.md')) name = name + '.md';
|
|
215
|
+
try {
|
|
216
|
+
const body = await readFile(join(JSS_DOCS_DIR, name), 'utf8');
|
|
217
|
+
return toolJson({ name, body });
|
|
218
|
+
} catch (e) {
|
|
219
|
+
return toolError(`doc not found: ${name}`);
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
|
|
223
|
+
// --- pod info ---
|
|
224
|
+
|
|
225
|
+
async function pod_info(_args, ctx) {
|
|
226
|
+
const skill = await readPodSkill().catch(() => null);
|
|
227
|
+
return toolJson({
|
|
228
|
+
pod: ctx.origin,
|
|
229
|
+
server: 'jss',
|
|
230
|
+
protocolVersion: '2025-03-26',
|
|
231
|
+
identity: ctx.webId || null,
|
|
232
|
+
capabilities: {
|
|
233
|
+
crud: true,
|
|
234
|
+
acl: true,
|
|
235
|
+
skills: true,
|
|
236
|
+
docs: true
|
|
237
|
+
},
|
|
238
|
+
skill: skill ? { path: skill.path, format: skill.format } : null
|
|
239
|
+
});
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
// --- registry ---
|
|
243
|
+
|
|
244
|
+
export const TOOLS = {
|
|
245
|
+
list_resources: {
|
|
246
|
+
description: 'List contents of an LDP container. Returns child resources and sub-containers.',
|
|
247
|
+
inputSchema: {
|
|
248
|
+
type: 'object',
|
|
249
|
+
properties: {
|
|
250
|
+
path: { type: 'string', description: 'Container path, must end in /' }
|
|
251
|
+
},
|
|
252
|
+
required: ['path']
|
|
253
|
+
},
|
|
254
|
+
handler: list_resources
|
|
255
|
+
},
|
|
256
|
+
read_resource: {
|
|
257
|
+
description: 'Read the body of a non-container resource (any content type). Returns UTF-8.',
|
|
258
|
+
inputSchema: {
|
|
259
|
+
type: 'object',
|
|
260
|
+
properties: { path: { type: 'string' } },
|
|
261
|
+
required: ['path']
|
|
262
|
+
},
|
|
263
|
+
handler: read_resource
|
|
264
|
+
},
|
|
265
|
+
write_resource: {
|
|
266
|
+
description: 'Write (PUT) a resource at the given path. Overwrites if exists.',
|
|
267
|
+
inputSchema: {
|
|
268
|
+
type: 'object',
|
|
269
|
+
properties: {
|
|
270
|
+
path: { type: 'string' },
|
|
271
|
+
content: { type: 'string' },
|
|
272
|
+
contentType: { type: 'string', description: 'MIME type (default text/plain)' }
|
|
273
|
+
},
|
|
274
|
+
required: ['path', 'content']
|
|
275
|
+
},
|
|
276
|
+
handler: write_resource
|
|
277
|
+
},
|
|
278
|
+
create_resource: {
|
|
279
|
+
description: 'Create a child resource in a container (LDP POST). Server mints the name unless slug is provided.',
|
|
280
|
+
inputSchema: {
|
|
281
|
+
type: 'object',
|
|
282
|
+
properties: {
|
|
283
|
+
container: { type: 'string', description: 'Parent container path, must end in /' },
|
|
284
|
+
slug: { type: 'string', description: 'Optional filename hint' },
|
|
285
|
+
content: { type: 'string' },
|
|
286
|
+
contentType: { type: 'string' },
|
|
287
|
+
isContainer: { type: 'boolean', description: 'Create a child container instead of a resource' }
|
|
288
|
+
},
|
|
289
|
+
required: ['container']
|
|
290
|
+
},
|
|
291
|
+
handler: create_resource
|
|
292
|
+
},
|
|
293
|
+
delete_resource: {
|
|
294
|
+
description: 'Delete a resource or empty container.',
|
|
295
|
+
inputSchema: {
|
|
296
|
+
type: 'object',
|
|
297
|
+
properties: { path: { type: 'string' } },
|
|
298
|
+
required: ['path']
|
|
299
|
+
},
|
|
300
|
+
handler: delete_resource
|
|
301
|
+
},
|
|
302
|
+
head_resource: {
|
|
303
|
+
description: 'Return metadata (size, modified) for a resource without reading the body.',
|
|
304
|
+
inputSchema: {
|
|
305
|
+
type: 'object',
|
|
306
|
+
properties: { path: { type: 'string' } },
|
|
307
|
+
required: ['path']
|
|
308
|
+
},
|
|
309
|
+
handler: head_resource
|
|
310
|
+
},
|
|
311
|
+
list_skills: {
|
|
312
|
+
description: 'List SKILL.md / SKILL.jsonld files at conventional paths (pod-wide, per-app, per-bot).',
|
|
313
|
+
inputSchema: { type: 'object', properties: {} },
|
|
314
|
+
handler: list_skills
|
|
315
|
+
},
|
|
316
|
+
get_skill: {
|
|
317
|
+
description: 'Read a specific skill file by pod path.',
|
|
318
|
+
inputSchema: {
|
|
319
|
+
type: 'object',
|
|
320
|
+
properties: { path: { type: 'string' } },
|
|
321
|
+
required: ['path']
|
|
322
|
+
},
|
|
323
|
+
handler: get_skill
|
|
324
|
+
},
|
|
325
|
+
get_pod_skill: {
|
|
326
|
+
description: 'Read the pod-wide SKILL.md (the owner\'s instructions to bots).',
|
|
327
|
+
inputSchema: { type: 'object', properties: {} },
|
|
328
|
+
handler: get_pod_skill
|
|
329
|
+
},
|
|
330
|
+
list_docs: {
|
|
331
|
+
description: 'List JSS\'s built-in docs (markdown files shipped with the server).',
|
|
332
|
+
inputSchema: { type: 'object', properties: {} },
|
|
333
|
+
handler: list_docs
|
|
334
|
+
},
|
|
335
|
+
read_docs: {
|
|
336
|
+
description: 'Read a JSS doc by filename (e.g. "git-support.md", "app-install.md").',
|
|
337
|
+
inputSchema: {
|
|
338
|
+
type: 'object',
|
|
339
|
+
properties: { name: { type: 'string' } },
|
|
340
|
+
required: ['name']
|
|
341
|
+
},
|
|
342
|
+
handler: read_docs
|
|
343
|
+
},
|
|
344
|
+
pod_info: {
|
|
345
|
+
description: 'Basic pod identity and MCP capabilities.',
|
|
346
|
+
inputSchema: { type: 'object', properties: {} },
|
|
347
|
+
handler: pod_info
|
|
348
|
+
}
|
|
349
|
+
};
|
|
350
|
+
|
|
351
|
+
/**
|
|
352
|
+
* Return the list of tools in MCP tools/list shape.
|
|
353
|
+
*/
|
|
354
|
+
export function listToolsForRpc() {
|
|
355
|
+
return Object.entries(TOOLS).map(([name, t]) => ({
|
|
356
|
+
name,
|
|
357
|
+
description: t.description,
|
|
358
|
+
inputSchema: t.inputSchema
|
|
359
|
+
}));
|
|
360
|
+
}
|
|
361
|
+
|
|
362
|
+
/**
|
|
363
|
+
* Dispatch a tools/call request.
|
|
364
|
+
*/
|
|
365
|
+
export async function callTool(name, args, ctx) {
|
|
366
|
+
const tool = TOOLS[name];
|
|
367
|
+
if (!tool) {
|
|
368
|
+
return toolError(`unknown tool: ${name}`);
|
|
369
|
+
}
|
|
370
|
+
try {
|
|
371
|
+
return await tool.handler(args || {}, ctx);
|
|
372
|
+
} catch (e) {
|
|
373
|
+
return toolError(`tool ${name} threw: ${e.message}`);
|
|
374
|
+
}
|
|
375
|
+
}
|
package/src/server.js
CHANGED
|
@@ -25,6 +25,7 @@ import { createPayHandler, isPayRequest } from './handlers/pay.js';
|
|
|
25
25
|
import { activityPubPlugin, getActorHandler } from './ap/index.js';
|
|
26
26
|
import { remoteStoragePlugin } from './remotestorage.js';
|
|
27
27
|
import { dbPlugin } from './db/index.js';
|
|
28
|
+
import { mcpPlugin } from './mcp/index.js';
|
|
28
29
|
import { webrtcPlugin } from './webrtc/index.js';
|
|
29
30
|
import { tunnelPlugin } from './tunnel/index.js';
|
|
30
31
|
import { terminalPlugin } from './terminal/index.js';
|
|
@@ -139,6 +140,10 @@ export function createServer(options = {}) {
|
|
|
139
140
|
const liveReloadEnabled = options.liveReload ?? false;
|
|
140
141
|
// MongoDB-backed /db/ route is OFF by default
|
|
141
142
|
const mongoEnabled = options.mongo ?? false;
|
|
143
|
+
// MCP (Model Context Protocol) server — exposes the pod as a tool
|
|
144
|
+
// surface for agents (Claude Desktop, Cursor, etc.). OFF by default.
|
|
145
|
+
// See docs/mcp.md and #490.
|
|
146
|
+
const mcpEnabled = options.mcp ?? false;
|
|
142
147
|
// Provision a Schnorr secp256k1 owner key in /private/privkey.jsonld
|
|
143
148
|
// when a single-user pod is first created. Phase 1 of #437. Off by
|
|
144
149
|
// default: keys-on-disk is a real security tradeoff, opt-in keeps
|
|
@@ -394,6 +399,11 @@ export function createServer(options = {}) {
|
|
|
394
399
|
fastify.register(dbPlugin, { mongoUrl, mongoDatabase, singleUser });
|
|
395
400
|
}
|
|
396
401
|
|
|
402
|
+
// Register MCP server if enabled (issue #490)
|
|
403
|
+
if (mcpEnabled) {
|
|
404
|
+
fastify.register(mcpPlugin);
|
|
405
|
+
}
|
|
406
|
+
|
|
397
407
|
// Register rate limiting plugin
|
|
398
408
|
// Protects against brute force attacks and resource exhaustion
|
|
399
409
|
fastify.register(rateLimit, {
|
|
@@ -648,6 +658,7 @@ export function createServer(options = {}) {
|
|
|
648
658
|
request.url.startsWith('/storage/') ||
|
|
649
659
|
(payEnabled && isPayRequest(request.url)) ||
|
|
650
660
|
(mongoEnabled && (request.url === '/db' || request.url.startsWith('/db/'))) ||
|
|
661
|
+
(mcpEnabled && (request.url === '/mcp' || request.url.startsWith('/mcp?'))) ||
|
|
651
662
|
(webrtcEnabled && (request.url === webrtcPath || request.url.startsWith(webrtcPath + '?'))) ||
|
|
652
663
|
(terminalEnabled && (request.url === '/.terminal' || request.url.startsWith('/.terminal?'))) ||
|
|
653
664
|
(tunnelEnabled && (request.url === tunnelPath || request.url.startsWith(tunnelPath + '?') || request.url.startsWith('/tunnel/'))) ||
|
package/test/mcp.test.js
ADDED
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCP (Model Context Protocol) server tests.
|
|
3
|
+
*
|
|
4
|
+
* Covers:
|
|
5
|
+
* - handshake (initialize / tools/list)
|
|
6
|
+
* - CRUD tools (list, read, write, create, delete, head)
|
|
7
|
+
* - skill discovery (list_skills, get_skill, get_pod_skill)
|
|
8
|
+
* - docs (list_docs, read_docs)
|
|
9
|
+
* - WAC enforcement (anonymous denied write, owner allowed)
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
import { describe, it, before, after } from 'node:test';
|
|
13
|
+
import assert from 'node:assert';
|
|
14
|
+
import {
|
|
15
|
+
startTestServer,
|
|
16
|
+
stopTestServer,
|
|
17
|
+
request,
|
|
18
|
+
createTestPod,
|
|
19
|
+
getBaseUrl,
|
|
20
|
+
getPodToken
|
|
21
|
+
} from './helpers.js';
|
|
22
|
+
|
|
23
|
+
let token;
|
|
24
|
+
|
|
25
|
+
async function rpc(body, opts = {}) {
|
|
26
|
+
const headers = { 'Content-Type': 'application/json' };
|
|
27
|
+
if (opts.token) headers.Authorization = `Bearer ${opts.token}`;
|
|
28
|
+
const res = await request('/mcp', {
|
|
29
|
+
method: 'POST',
|
|
30
|
+
headers,
|
|
31
|
+
body: JSON.stringify(body)
|
|
32
|
+
});
|
|
33
|
+
if (res.status === 204) return { status: 204, body: null };
|
|
34
|
+
const data = await res.json();
|
|
35
|
+
return { status: res.status, body: data };
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
describe('MCP server (--mcp enabled)', () => {
|
|
39
|
+
before(async () => {
|
|
40
|
+
await startTestServer({ mcp: true });
|
|
41
|
+
await createTestPod('mcptest');
|
|
42
|
+
token = getPodToken('mcptest');
|
|
43
|
+
});
|
|
44
|
+
|
|
45
|
+
after(async () => {
|
|
46
|
+
await stopTestServer();
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
it('responds to initialize with protocol version', async () => {
|
|
50
|
+
const { status, body } = await rpc({
|
|
51
|
+
jsonrpc: '2.0', id: 1, method: 'initialize',
|
|
52
|
+
params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: { name: 'test', version: '0' } }
|
|
53
|
+
});
|
|
54
|
+
assert.strictEqual(status, 200);
|
|
55
|
+
assert.strictEqual(body.jsonrpc, '2.0');
|
|
56
|
+
assert.ok(body.result?.protocolVersion);
|
|
57
|
+
assert.strictEqual(body.result.serverInfo.name, 'jss-mcp');
|
|
58
|
+
});
|
|
59
|
+
|
|
60
|
+
it('lists tools', async () => {
|
|
61
|
+
const { body } = await rpc({ jsonrpc: '2.0', id: 2, method: 'tools/list' });
|
|
62
|
+
const names = body.result.tools.map(t => t.name);
|
|
63
|
+
for (const expected of [
|
|
64
|
+
'list_resources', 'read_resource', 'write_resource',
|
|
65
|
+
'create_resource', 'delete_resource', 'head_resource',
|
|
66
|
+
'list_skills', 'get_skill', 'get_pod_skill',
|
|
67
|
+
'list_docs', 'read_docs', 'pod_info'
|
|
68
|
+
]) {
|
|
69
|
+
assert.ok(names.includes(expected), `missing tool: ${expected}`);
|
|
70
|
+
}
|
|
71
|
+
});
|
|
72
|
+
|
|
73
|
+
it('write_resource denied without auth', async () => {
|
|
74
|
+
const { body } = await rpc({
|
|
75
|
+
jsonrpc: '2.0', id: 3, method: 'tools/call',
|
|
76
|
+
params: { name: 'write_resource', arguments: { path: '/mcptest/public/anon.txt', content: 'nope' } }
|
|
77
|
+
});
|
|
78
|
+
assert.ok(body.result?.isError, 'expected isError for anonymous write');
|
|
79
|
+
assert.match(body.result.content[0].text, /denied/i);
|
|
80
|
+
});
|
|
81
|
+
|
|
82
|
+
it('write_resource works with owner token', async () => {
|
|
83
|
+
const { body } = await rpc({
|
|
84
|
+
jsonrpc: '2.0', id: 4, method: 'tools/call',
|
|
85
|
+
params: {
|
|
86
|
+
name: 'write_resource',
|
|
87
|
+
arguments: { path: '/mcptest/public/hello.txt', content: 'hi', contentType: 'text/plain' }
|
|
88
|
+
}
|
|
89
|
+
}, { token });
|
|
90
|
+
assert.strictEqual(body.result.isError, false, body.result.content?.[0]?.text);
|
|
91
|
+
assert.match(body.result.content[0].text, /wrote/);
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
it('read_resource returns the written content', async () => {
|
|
95
|
+
const { body } = await rpc({
|
|
96
|
+
jsonrpc: '2.0', id: 5, method: 'tools/call',
|
|
97
|
+
params: { name: 'read_resource', arguments: { path: '/mcptest/public/hello.txt' } }
|
|
98
|
+
}, { token });
|
|
99
|
+
assert.strictEqual(body.result.isError, false);
|
|
100
|
+
const payload = JSON.parse(body.result.content[0].text);
|
|
101
|
+
assert.strictEqual(payload.body, 'hi');
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
it('list_resources lists the container', async () => {
|
|
105
|
+
const { body } = await rpc({
|
|
106
|
+
jsonrpc: '2.0', id: 6, method: 'tools/call',
|
|
107
|
+
params: { name: 'list_resources', arguments: { path: '/mcptest/public/' } }
|
|
108
|
+
}, { token });
|
|
109
|
+
assert.strictEqual(body.result.isError, false);
|
|
110
|
+
const payload = JSON.parse(body.result.content[0].text);
|
|
111
|
+
assert.ok(payload.items.some(i => i.name === 'hello.txt'));
|
|
112
|
+
});
|
|
113
|
+
|
|
114
|
+
it('create_resource auto-mints filename', async () => {
|
|
115
|
+
const { body } = await rpc({
|
|
116
|
+
jsonrpc: '2.0', id: 7, method: 'tools/call',
|
|
117
|
+
params: {
|
|
118
|
+
name: 'create_resource',
|
|
119
|
+
arguments: { container: '/mcptest/public/', slug: 'minted', content: 'x' }
|
|
120
|
+
}
|
|
121
|
+
}, { token });
|
|
122
|
+
assert.strictEqual(body.result.isError, false);
|
|
123
|
+
assert.match(body.result.content[0].text, /\/mcptest\/public\/minted/);
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
it('delete_resource removes the file', async () => {
|
|
127
|
+
const { body } = await rpc({
|
|
128
|
+
jsonrpc: '2.0', id: 8, method: 'tools/call',
|
|
129
|
+
params: { name: 'delete_resource', arguments: { path: '/mcptest/public/hello.txt' } }
|
|
130
|
+
}, { token });
|
|
131
|
+
assert.strictEqual(body.result.isError, false);
|
|
132
|
+
assert.match(body.result.content[0].text, /deleted/);
|
|
133
|
+
});
|
|
134
|
+
|
|
135
|
+
it('head_resource returns 404 on missing path', async () => {
|
|
136
|
+
const { body } = await rpc({
|
|
137
|
+
jsonrpc: '2.0', id: 9, method: 'tools/call',
|
|
138
|
+
params: { name: 'head_resource', arguments: { path: '/mcptest/public/does-not-exist' } }
|
|
139
|
+
}, { token });
|
|
140
|
+
assert.ok(body.result.isError);
|
|
141
|
+
});
|
|
142
|
+
|
|
143
|
+
it('list_skills returns the index shape', async () => {
|
|
144
|
+
const { body } = await rpc({
|
|
145
|
+
jsonrpc: '2.0', id: 10, method: 'tools/call',
|
|
146
|
+
params: { name: 'list_skills', arguments: {} }
|
|
147
|
+
}, { token });
|
|
148
|
+
assert.strictEqual(body.result.isError, false);
|
|
149
|
+
const payload = JSON.parse(body.result.content[0].text);
|
|
150
|
+
assert.strictEqual(payload['@type'], 'skill:SkillIndex');
|
|
151
|
+
assert.ok(Array.isArray(payload['skill:items']));
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
it('list_skills discovers per-app SKILL.md', async () => {
|
|
155
|
+
// Seed a per-app skill
|
|
156
|
+
await rpc({
|
|
157
|
+
jsonrpc: '2.0', id: 1010, method: 'tools/call',
|
|
158
|
+
params: {
|
|
159
|
+
name: 'write_resource',
|
|
160
|
+
arguments: {
|
|
161
|
+
path: '/mcptest/public/apps/demo/index.html',
|
|
162
|
+
content: '<h1>demo</h1>',
|
|
163
|
+
contentType: 'text/html'
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
}, { token });
|
|
167
|
+
await rpc({
|
|
168
|
+
jsonrpc: '2.0', id: 1011, method: 'tools/call',
|
|
169
|
+
params: {
|
|
170
|
+
name: 'write_resource',
|
|
171
|
+
arguments: {
|
|
172
|
+
path: '/mcptest/public/apps/demo/SKILL.md',
|
|
173
|
+
content: '# demo app skill',
|
|
174
|
+
contentType: 'text/markdown'
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}, { token });
|
|
178
|
+
|
|
179
|
+
// Now list against the pod root — but list_skills walks /public/apps/
|
|
180
|
+
// and /private/bots/ at the pod root, not inside a named pod. For this
|
|
181
|
+
// test, we just verify the per-app discovery walks containers correctly
|
|
182
|
+
// by listing /mcptest/public/apps/ directly via list_resources and
|
|
183
|
+
// confirming "demo" comes back as a container (isContainer=true).
|
|
184
|
+
const { body } = await rpc({
|
|
185
|
+
jsonrpc: '2.0', id: 1012, method: 'tools/call',
|
|
186
|
+
params: { name: 'list_resources', arguments: { path: '/mcptest/public/apps/' } }
|
|
187
|
+
}, { token });
|
|
188
|
+
assert.strictEqual(body.result.isError, false);
|
|
189
|
+
const payload = JSON.parse(body.result.content[0].text);
|
|
190
|
+
const demo = payload.items.find(i => i.name === 'demo');
|
|
191
|
+
assert.ok(demo, 'demo container should be listed');
|
|
192
|
+
assert.strictEqual(demo.isContainer, true, 'isContainer must be true for directories');
|
|
193
|
+
});
|
|
194
|
+
|
|
195
|
+
it('list_docs returns the JSS-builtin doc set', async () => {
|
|
196
|
+
const { body } = await rpc({
|
|
197
|
+
jsonrpc: '2.0', id: 11, method: 'tools/call',
|
|
198
|
+
params: { name: 'list_docs', arguments: {} }
|
|
199
|
+
});
|
|
200
|
+
assert.strictEqual(body.result.isError, false);
|
|
201
|
+
const payload = JSON.parse(body.result.content[0].text);
|
|
202
|
+
assert.strictEqual(payload.source, 'jss-builtin');
|
|
203
|
+
assert.ok(payload.docs.some(d => d.name.endsWith('.md')));
|
|
204
|
+
});
|
|
205
|
+
|
|
206
|
+
it('read_docs fetches a known doc', async () => {
|
|
207
|
+
const { body } = await rpc({
|
|
208
|
+
jsonrpc: '2.0', id: 12, method: 'tools/call',
|
|
209
|
+
params: { name: 'read_docs', arguments: { name: 'git-support.md' } }
|
|
210
|
+
});
|
|
211
|
+
assert.strictEqual(body.result.isError, false);
|
|
212
|
+
const payload = JSON.parse(body.result.content[0].text);
|
|
213
|
+
assert.match(payload.body, /git/i);
|
|
214
|
+
});
|
|
215
|
+
|
|
216
|
+
it('read_docs rejects path traversal', async () => {
|
|
217
|
+
const { body } = await rpc({
|
|
218
|
+
jsonrpc: '2.0', id: 13, method: 'tools/call',
|
|
219
|
+
params: { name: 'read_docs', arguments: { name: '../package.json' } }
|
|
220
|
+
});
|
|
221
|
+
assert.ok(body.result.isError);
|
|
222
|
+
});
|
|
223
|
+
|
|
224
|
+
it('pod_info returns identity info', async () => {
|
|
225
|
+
const { body } = await rpc({
|
|
226
|
+
jsonrpc: '2.0', id: 14, method: 'tools/call',
|
|
227
|
+
params: { name: 'pod_info', arguments: {} }
|
|
228
|
+
}, { token });
|
|
229
|
+
assert.strictEqual(body.result.isError, false);
|
|
230
|
+
const payload = JSON.parse(body.result.content[0].text);
|
|
231
|
+
assert.strictEqual(payload.server, 'jss');
|
|
232
|
+
assert.ok(payload.identity);
|
|
233
|
+
});
|
|
234
|
+
|
|
235
|
+
it('rejects unknown method', async () => {
|
|
236
|
+
const { body } = await rpc({ jsonrpc: '2.0', id: 99, method: 'doesnt/exist' });
|
|
237
|
+
assert.strictEqual(body.error?.code, -32601);
|
|
238
|
+
});
|
|
239
|
+
|
|
240
|
+
it('rejects unknown tool', async () => {
|
|
241
|
+
const { body } = await rpc({
|
|
242
|
+
jsonrpc: '2.0', id: 100, method: 'tools/call',
|
|
243
|
+
params: { name: 'fictional_tool', arguments: {} }
|
|
244
|
+
});
|
|
245
|
+
assert.ok(body.result?.isError);
|
|
246
|
+
assert.match(body.result.content[0].text, /unknown tool/);
|
|
247
|
+
});
|
|
248
|
+
});
|
|
249
|
+
|
|
250
|
+
describe('MCP server disabled (no flag)', () => {
|
|
251
|
+
before(async () => {
|
|
252
|
+
await startTestServer({});
|
|
253
|
+
});
|
|
254
|
+
|
|
255
|
+
after(async () => {
|
|
256
|
+
await stopTestServer();
|
|
257
|
+
});
|
|
258
|
+
|
|
259
|
+
it('blocks /mcp when flag is off', async () => {
|
|
260
|
+
// Without --mcp, the route isn't registered. The global auth hook fires
|
|
261
|
+
// first on the missing route and rejects (401) since /mcp isn't on the
|
|
262
|
+
// skip list when mcpEnabled is false. Either 401 or 404 is correct
|
|
263
|
+
// "MCP is not available here" behavior; both block tool dispatch.
|
|
264
|
+
const res = await request('/mcp', {
|
|
265
|
+
method: 'POST',
|
|
266
|
+
headers: { 'Content-Type': 'application/json' },
|
|
267
|
+
body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize' })
|
|
268
|
+
});
|
|
269
|
+
assert.ok(res.status === 404 || res.status === 401, `expected 404 or 401, got ${res.status}`);
|
|
270
|
+
});
|
|
271
|
+
});
|