Skip to content

feat: expose JSS as an MCP server (--mcp) — proposed v0.0.200 #490

Description

@melvincarvalho

Why

The agent ecosystem (Claude Desktop, Cursor, custom agents, …) 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, but the wire connecting them doesn't exist yet.

MCP (Model Context Protocol) is becoming that wire. If JSS speaks MCP, every MCP-compatible agent gets a sovereign data layer for free, with WAC, WebIDs, and Nostr identities all already in place.

Thesis statement: "MCP needs a backend. Solid is the backend."

This is the proposed v0.0.200 capstone — completing the feature-development phase before consolidation.

What

```bash
jss start --mcp # exposes /mcp endpoint speaking MCP
```

Initial tools

Tiny surface to start; expand once the foundation is in:

Tool Maps to
`list_resources` LDP container GET (lists `ldp:contains`)
`read_resource` GET resource (any content type, including JSON-LD)
`write_resource` PUT / POST resource
`subscribe` Existing JSS WebSocket notifications wrapped as MCP events

Deferred: `query` (SPARQL or JSON-LD frame), `delete_resource`, `patch_resource`.

Auth

Reuse existing JSS layers — no new auth code:

  • WebID-OIDC + DPoP — for Claude Desktop and other browser-OIDC agents
  • NIP-98 — for Nostr-native agents
  • Bearer token — for headless agents / CI

The MCP server enforces WAC the same way every other JSS endpoint does. `acl:agent did:agent:claude` can grant a specific agent specific resources. `acl:agentClass` with a new `acl:Agent` term could grant agent-class-wide access.

Wire format

MCP supports stdio, HTTP+SSE, and WebSocket transports. HTTP+SSE is the natural fit — JSS already serves HTTP, and SSE composes with the existing notification infrastructure. Stdio is irrelevant (JSS is a long-running daemon).

Scope estimate

~500 lines. The protocol is thin, JSS already has all the backend primitives. The work is an adapter layer:

  • MCP handshake (initialize, list_tools, capabilities)
  • Tool dispatch (route MCP tool calls to existing JSS internals)
  • SSE event stream wrapping the WS notification pipe

Why it's distinctive

  • No other Solid server has this
  • No other MCP server has WAC, WebID, or sovereign storage
  • The combination is what's unique — Solid's strength (data sovereignty) becomes MCP's missing piece

Acceptance

  • `jss start --mcp` exposes `/mcp` endpoint
  • Claude Desktop can register the endpoint as an MCP server and read/write a resource
  • WAC applies: agent without `acl:Write` gets 403 on `write_resource`
  • `subscribe` emits events on resource changes via SSE
  • Tested end-to-end with at least one external MCP-compatible client
  • `docs/mcp.md` covers wiring up Claude Desktop / generic MCP clients

Out of scope (for v0.0.200)

  • `query` tool (deferred to v0.0.201+)
  • Agent-class WAC term (`acl:Agent`) — proposed but not blocking
  • MCP "prompts" or "resources" surface (we expose tools first)
  • Local LLM hosting / inference inside JSS

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions