# mcp-solid-pod

MCP server for [Solid](https://solidproject.org/) Pods — list, read, search, and (opt-in) write — with **CSS client-credentials** auth for headless use (AIsuru MCP Gateway, Claude Desktop, etc.).

Portions adapted from [`@jeswr/solid-mcp`](https://github.com/jeswr/solid-mcp) (MIT).

## Requirements

- **Node.js >= 24**
- A Solid server that supports client credentials (e.g. [Community Solid Server](https://communitysolidserver.github.io/CommunitySolidServer/latest/))

## Tools

| Tool           | Args                            | Notes                                            |
| -------------- | ------------------------------- | ------------------------------------------------ |
| `solid_list`   | `{ container }`                 | List LDP container children                      |
| `solid_read`   | `{ url }`                       | Read resource (Turtle for RDF)                   |
| `solid_search` | `{ query, scope? }`             | Client-side search                               |
| `solid_write`  | `{ url, content, contentType }` | PUT — disabled unless `SOLID_MCP_READONLY=false` |

All URLs are confined to `SOLID_MCP_POD_ROOT` (SSRF / pod-scope guard).

## Environment

| Variable                  | Required         | Description                              |
| ------------------------- | ---------------- | ---------------------------------------- |
| `SOLID_MCP_POD_ROOT`      | yes              | Pod/container URL ending in `/`          |
| `SOLID_MCP_OIDC_ISSUER`   | for private pods | IdP base (e.g. `http://localhost:3000/`) |
| `SOLID_MCP_CLIENT_ID`     | for private pods | CSS client credentials id                |
| `SOLID_MCP_CLIENT_SECRET` | for private pods | CSS client credentials secret            |
| `SOLID_MCP_WEBID`         | no               | Enables Type-Index search hints          |
| `SOLID_MCP_READONLY`      | no               | Default `true`                           |

Credentials are read from the environment only (gateway `server_parameters`) — never from the LLM.

## Local run

```sh
npm install
npm run build
npm test

SOLID_MCP_POD_ROOT=http://localhost:3000/alice/ \
SOLID_MCP_OIDC_ISSUER=http://localhost:3000/ \
SOLID_MCP_CLIENT_ID=… \
SOLID_MCP_CLIENT_SECRET=… \
node build/cli.js
```

## E2E against Community Solid Server

```sh
npm run build
npm run e2e
```

This starts `npx @solid/community-server` with [`e2e/seed.json`](e2e/seed.json), creates client credentials, and asserts list/read/search/write via the MCP stdio client.

With Docker instead:

```sh
docker compose -f e2e/docker-compose.yml up -d
SKIP_CSS_START=1 npm run e2e
docker compose -f e2e/docker-compose.yml down
```

## Configure in the AIsuru MCP Gateway UI (admin)

Gateway admin → **MCP Server Schemas** → **Nuovo schema**. Fill the form with the values below (copy-paste).

### Informazioni base

| Field                                             | Value                             |
| ------------------------------------------------- | --------------------------------- |
| **ID Schema**                                     | `solid-pod-mcp-server`            |
| **Nome**                                          | `Solid Pod`                       |
| **Tipo Server**                                   | `Server MCP Generico` (`generic`) |
| **Logo/Emoji**                                    | `🌐`                              |
| **Comando/URL di Esempio** (`url_command_hidden`) | `npx -y @memori.ai/mcp-solid-pod` |
| **Priorità**                                      | `16`                              |
| **Schema disponibile**                            | checked                           |

Local unpublished package (dev gateway host):

```text
node /absolute/path/to/MCP Solid/build/cli.js
```

### Descrizioni

**🇮🇹 Descrizione Italiana**

```text
Server MCP per leggere e (opzionalmente) scrivere dati in un Solid Pod tramite LDP/RDF. Autenticazione headless con client credentials CSS / Solid-OIDC. Le credenziali non sono mai passate al LLM.
```

**🇺🇸 English Description**

```text
MCP Server to read and (optionally) write data in a Solid Pod via LDP/RDF. Headless auth with CSS / Solid-OIDC client credentials. Credentials are not given to the LLM.
```

### Prompt per Agenti AI

**Prompt per Lista Tools**

```text
Questo server Solid Pod permette di elencare, leggere e cercare risorse LDP/RDF nel pod configurato. Questa funzione permette di leggere la lista di tool disponibili per questo MCP.
```

**Prompt per Esecuzione Tools**

```text
Usa solid_list per esplorare un container (URL che termina con /), solid_read per leggere una risorsa, solid_search per cercare per nome/URL/letterali RDF. solid_write e' disponibile solo se SOLID_MCP_READONLY=false. Tutti gli URL devono stare dentro SOLID_MCP_POD_ROOT.
```

### Parametri (JSON) — paste into “Parametri di Configurazione”

```json
[
  {
    "name": "SOLID_MCP_POD_ROOT",
    "type": "string",
    "required": true,
    "description": "URL assoluto del pod/container (deve terminare con /)",
    "description_it": "URL assoluto del pod/container (deve terminare con /)",
    "description_en": "Absolute pod/container URL (must end with /)",
    "example": "https://pod.example/alice/"
  },
  {
    "name": "SOLID_MCP_OIDC_ISSUER",
    "type": "string",
    "required": true,
    "description": "Base URL dell'Identity Provider / CSS (es. https://pod.example/)",
    "description_it": "Base URL dell'Identity Provider / CSS (es. https://pod.example/)",
    "description_en": "Identity Provider / CSS base URL (e.g. https://pod.example/)",
    "example": "https://pod.example/"
  },
  {
    "name": "SOLID_MCP_CLIENT_ID",
    "type": "string",
    "required": true,
    "description": "Client credentials ID (CSS)",
    "description_it": "Client credentials ID (CSS)",
    "description_en": "Client credentials ID (CSS)",
    "example": "my-token_xxxxxxxx"
  },
  {
    "name": "SOLID_MCP_CLIENT_SECRET",
    "type": "string",
    "required": true,
    "description": "Client credentials secret (CSS)",
    "description_it": "Client credentials secret (CSS)",
    "description_en": "Client credentials secret (CSS)",
    "example": "your-client-secret"
  },
  {
    "name": "SOLID_MCP_WEBID",
    "type": "string",
    "required": false,
    "description": "WebID del proprietario (abilita Type-Index in search)",
    "description_it": "WebID del proprietario (abilita Type-Index in search)",
    "description_en": "Owner WebID (enables Type-Index hints in search)",
    "example": "https://pod.example/alice/profile/card#me"
  },
  {
    "name": "SOLID_MCP_READONLY",
    "type": "boolean",
    "required": false,
    "description": "Se true (default) disabilita solid_write",
    "description_it": "Se true (default) disabilita solid_write",
    "description_en": "If true (default) disables solid_write",
    "example": "true",
    "default": "true"
  }
]
```

Click **Crea Schema**.

### When an agent activates this MCP

Fill instance parameters with real values (injected as env vars; never sent to the LLM):

```json
{
  "SOLID_MCP_POD_ROOT": "https://pod.example/alice/",
  "SOLID_MCP_OIDC_ISSUER": "https://pod.example/",
  "SOLID_MCP_CLIENT_ID": "my-token_xxxxxxxx",
  "SOLID_MCP_CLIENT_SECRET": "the-secret-value",
  "SOLID_MCP_WEBID": "https://pod.example/alice/profile/card#me",
  "SOLID_MCP_READONLY": "true"
}
```

`SOLID_MCP_CLIENT_SECRET` is encrypted at rest.

## License

MIT — see [LICENSE](LICENSE).