# Meet Rupert MCP Server

An [MCP](https://modelcontextprotocol.io) server that lets Claude work with the
**Meet Rupert** knowledgebase (<https://app.meetrupert.com>): search and read
documentation, ask the RAG AI questions (one-shot or in a conversation), and
create/edit documents.

Node 20+ / TypeScript ESM, the official `@modelcontextprotocol/sdk` over stdio,
built with `tsup`.

## Tools

| Tool                  | Description                                                                                          |
| --------------------- | ---------------------------------------------------------------------------------------------------- |
| `search_documents`    | Search documents by title; returns ids, titles, status, categories (paginated).                      |
| `read_document`       | Read a document by id; body returned as Markdown.                                                    |
| `create_document`     | Create a document from Markdown. **Defaults to draft** (not AI-searchable) unless `published: true`. |
| `update_document`     | Edit a document; omitted fields are preserved. `content` (Markdown) replaces the whole body.         |
| `list_categories`     | List categories with ids and document counts (for tagging / retrieval scoping).                      |
| `create_attachment`   | Upload an image from a **file path or HTTPS URL** (never base64) and get a `markdownRef` to embed.   |
| `list_attachments`    | List a document's images with their ids and whether they still resolve in storage.                   |
| `download_attachment` | Write an image to a path, or return a short-lived signed URL. Reports size + sha256.                 |
| `delete_attachment`   | Remove an image's reference from a document. **Does not delete the stored file** — see Attachments.  |
| `ask_ai`              | Ask a one-shot natural-language question; returns an answer + source documents.                      |
| `create_chat_thread`  | Start a multi-turn conversation thread; returns a `threadId`.                                        |
| `ask_in_thread`       | Ask a question within a thread (remembers prior context).                                            |
| `list_chat_threads`   | List recent conversation threads to resume.                                                          |

## How it works

Meet Rupert has no API-key / service-token auth, so this server logs in as a
real user via `POST /api/login/local`, caches the short-lived JWT access token,
and silently re-authenticates when it nears expiry or on a `401`. All requests
are scoped to the user's organisation, which is auto-resolved from the login
response (override with `MEETRUPERT_ORG_ID`).

The two "ask" tools consume the platform's `text/event-stream` RAG endpoints and
return the fully-accumulated answer plus its sources. Document `content` is
stored as Tiptap JSON and transparently converted to/from Markdown so Claude can
read and author documents in plain text.

Images use the platform's existing presigned-upload flow: the server asks for a
presigned `PUT`, uploads the bytes itself, and stores the returned storage key in
a Tiptap `image` node — the same representation the web editor produces. Reading
an image back goes through a short-lived media token. See
[Attachments](#attachments).

> **Tip:** Create a dedicated low-privilege **service user** (role `editor`) in
> Meet Rupert for this server rather than using a personal admin login.

## Attachments

Documents can embed images. The workflow is two calls:

```
create_attachment { path: "C:/Users/you/Pictures/step4-poll-fileset-500.png" }
  → { attachmentId: "9f3c1a2e-….png",
      contentLength: 92324,
      sha256: "…",
      markdownRef: "![step4-poll-fileset-500.png](attachment://9f3c1a2e-….png)" }

create_document { title: "New Defect Form",
                  content: "# Steps\n\n![Poll fileset](attachment://9f3c1a2e-….png)" }
```

`create_document` and `update_document` resolve every `attachment://<id>` to its
storage key at save time. `read_document` renders stored images back as
`attachment://` refs, so a document can be read, edited and written back without
losing them.

### Why there is no base64 parameter

The caller never supplies image bytes — it names a source and **the server reads
it**. This is not a stylistic choice. A model cannot reliably reproduce a large
base64 payload into a tool-call argument: in testing an 18,880-byte payload
arrived as 7,312 bytes, silently corrupting the file with no error raised.
Anything above roughly 10 KB is unsafe, which rules out essentially every real
screenshot.

Reading server-side also makes the returned `contentLength` and `sha256` facts
about the file rather than facts about the transport, so a caller can verify them
against the source. Compare with `Get-FileHash -Algorithm SHA256 <file>`.

### What is accepted

`image/png`, `image/jpeg`, `image/webp` and `image/gif`, up to 10 MB. The type is
determined from the file's **magic bytes**, not its extension, and a file whose
extension disagrees with its content is rejected rather than uploaded.

SVG is rejected outright — it can carry script and external references, and the
platform's own content-type allowlist excludes it. Non-image files (PDF, `.docx`,
plain text) are also rejected: the platform has no storage for them.

### Limitations

These follow from the platform having no attachment entity — images are presigned
S3 uploads referenced by storage key, with no table, no metadata and no delete
endpoint. Removing them needs a backend change, not a change here.

- **Images only.** No PDF, `.docx` or text attachments.
- **`delete_attachment` unlinks, it does not delete.** It removes the reference
  from a document; the stored object remains and stays readable by anyone holding
  a signed URL. Don't tell a user their file has been erased.
- **No garbage collection.** Attachments uploaded but never referenced by a saved
  document are _reported_ on stderr after `MEETRUPERT_ATTACHMENT_TTL_MS`, not
  reclaimed. (Orphans are not unique to this server — the web editor presigns an
  upload before the user saves and records nothing, so an abandoned edit leaks an
  object the same way.)
- **`filename` and `sha256` are advisory.** They are returned at creation and not
  persisted, because there is nowhere to persist them.

### Security

- **`path` fails closed.** Reads are confined to `MEETRUPERT_ATTACHMENT_DIRS`,
  which is empty by default, so `path` is refused until an operator opts in.
  Symlinks are resolved before the containment check and containment is compared
  on path segments, so neither a symlink nor a `..` nor a same-prefix sibling
  directory (`/srv/uploads-evil` vs `/srv/uploads`) can escape.
- **`source_url` is SSRF-hardened.** HTTPS only; private, loopback, link-local,
  CGNAT and cloud-metadata ranges are blocked after DNS resolution, with the
  connection pinned to the vetted address so a rebind cannot land elsewhere;
  redirects are not followed; connect and read timeouts apply; and the size cap is
  enforced per chunk while streaming, aborting the transfer rather than checking
  after the download completes.
- **Tenancy.** Storage keys are always built from the resolved org id, never from
  caller input, so an attachment is only reachable within the workspace that
  created it. The backend independently enforces the same prefix.
- **Logging.** Filenames, byte counts and checksums only — never file contents,
  and attachment bytes are never placed in an error message or stack trace.
  Fetched URLs have credentials and query strings redacted.

## Setup

```bash
npm install
cp .env.example .env   # then fill in credentials
npm run build
```

### Credentials (`.env`)

| Variable                          | Required | Description                                                                                                                                                                                              |
| --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MEETRUPERT_EMAIL`                | yes      | Service user's email.                                                                                                                                                                                    |
| `MEETRUPERT_PASSWORD`             | yes      | Service user's password.                                                                                                                                                                                 |
| `MEETRUPERT_BASE_URL`             | no       | API base URL incl. `/api`. Defaults to `https://app.meetrupert.com/api`.                                                                                                                                 |
| `MEETRUPERT_ORG_ID`               | no       | Override the organisation. Defaults to the logged-in user's org.                                                                                                                                         |
| `MEETRUPERT_ATTACHMENT_DIRS`      | no       | Directories `create_attachment` may read from and `download_attachment` may write to (`;`-separated on Windows, `:` elsewhere). **Empty by default, which refuses every `path` read** — see Attachments. |
| `MEETRUPERT_ATTACHMENT_MAX_BYTES` | no       | Per-attachment size cap. Defaults to `10485760` (10 MB), the platform's own limit.                                                                                                                       |
| `MEETRUPERT_ATTACHMENT_TTL_MS`    | no       | How long before an unreferenced attachment is reported as an orphan. Defaults to `3600000` (1 h).                                                                                                        |

## Registering with Claude

### Claude Desktop / Claude Code (`claude_desktop_config.json` or `.claude/settings.json`)

```json
{
  "mcpServers": {
    "meetrupert": {
      "command": "node",
      "args": ["/path/to/meet-rupert-mcp/dist/index.js"],
      "env": {
        "MEETRUPERT_EMAIL": "service-user@yourdomain.com",
        "MEETRUPERT_PASSWORD": "…",
        "MEETRUPERT_BASE_URL": "https://app.meetrupert.com/api"
      }
    }
  }
}
```

The `env` block can be omitted if a `.env` file sits next to the server (env is
loaded relative to the built file, not the host's working directory). You can
also add it interactively via `/mcp` in Claude Code.

## Development

```bash
npm run typecheck   # tsc --noEmit
npm run build       # tsup → dist/
npm run dev         # rebuild + restart on change
npm start           # node dist/index.js
npm test            # vitest — Tiptap converters, SSE parser, attachments
```

The attachment tests cover round-trip sha256 integrity, the size cap on every
input path (including a body that only breaches it partway through streaming),
extension/magic-byte mismatch, path traversal via `..` and via symlink, SSRF
against private and metadata addresses, cross-tenant reads, and a document
referencing an unknown `attachment://` id failing without saving.