postmd-mcp-server

# PostMD MCP Server

[Model Context Protocol](https://modelcontextprotocol.io) server for **[PostMD](https://postmd.turink.com)** — publish a Markdown document, get a web page you share by link, and add a document graph that the viewer draws: the reading order, the bodies and rules a document names, a procedure spread over its chapters. Optional groups, document passwords and viewer themes. This server wraps PostMD's public API (`/api/v1`) so assistants can publish, read, update and organize documents.

**Publishing needs no account and no key.** With zero configuration this server can already turn Markdown into a shareable page, and the hosted server at `https://postmd.turink.com/mcp` needs no install either. An API key adds management: organizing documents in groups, and notes.

**30-day retention.** Documents have a 30-day retention period (`data.retainedUntil`) that extends by 30 days whenever the document is read (at most once per day). Documents without a password can be updated or deleted by anyone; password-protected documents require the password or the owner's API key.

**Where things are written down:** [/llms.txt](https://postmd.turink.com/llms.txt) lists what the service can do and which page answers each thing; it is the place to start. [/docs/api](https://postmd.turink.com/docs/api) is the HTTP reference and [/api-docs](https://postmd.turink.com/api-docs) the machine-readable spec.

## Hosted or local

| | Hosted | Local |
|---|---|---|
| Address | `https://postmd.turink.com/mcp` | `npx -y postmd-mcp-server` |
| Needs | nothing | Node.js 20 or later |
| Tools | 5 | all 20 |
| API key | not accepted | optional, for member-scoped tools |
| Clients | any, including web-only ones such as ChatGPT and claude.ai | any that can run a local process |

The hosted server has no way to receive an API key, so it carries only the tools that need
none. Groups, notes and the tools that read a file from your disk are local-only.

## Configuration

Local only — the hosted server reads none of these. All are optional.

| Variable | Description |
|----------|-------------|
| `POSTMD_BASE_URL` | Defaults to `https://postmd.turink.com`. Set for a self-hosted / local instance. Origin only, no trailing slash. |
| `POSTMD_API_KEY` | `pmk_…` for the tools marked with a scope below. Sign in at [postmd.turink.com](https://postmd.turink.com), open **Account → API keys**, pick the scopes you need — read and write are independent, and a `403` usually means a missing scope. |
| `POSTMD_DEBUG` | `1` / `true` / `yes` → extra stderr logging. |

Load order: this repo's `.env` (if present) is applied via `dotenv` without overwriting variables already set by the host (e.g. MCP `env`). Do **not** commit `.env` or keys.

## Tools

Every tool below works on the local server. The hosted server carries five of them:
`postmd_create_document`, `postmd_get_document`, `postmd_get_document_raw`, `postmd_update_document`, and `postmd_delete_document`.

Publishing and reading — no key needed:

| Tool | Purpose |
|------|---------|
| `postmd_create_document` | Publish Markdown, get `docCode` + share URL |
| `postmd_create_document_from_file` | Same, but this server reads a local `filePath` (large files) |
| `postmd_get_document` | Metadata by `docCode` |
| `postmd_get_document_raw` | Stored Markdown body (optional `password`) |

Managing documents — key with `documents:write` (or password / no credential for unowned documents without password):

| Tool | Purpose |
|------|---------|
| `postmd_update_document` | Replace content and/or metadata; can clear password |
| `postmd_update_document_from_file` | Same, body read from a local `filePath` |
| `postmd_delete_document` | Delete a document (no undo) |
| `postmd_create_documents_from_files` | Bulk-publish several `.md` files in one call |
| `postmd_move_document_to_group` | Move a document into a group |

### Graphs

A PostMD document can carry graph data that the viewer draws, showing
how the parts of the document relate. No tool here creates or edits a graph, because there is no
endpoint for one: the data sits in the Markdown as an HTML comment and travels with the body.

Adding a graph to an existing document therefore means reading it with `postmd_get_document_raw`,
inserting the comment, and sending the whole body back with `postmd_update_document`. Publishing a
new document with a graph is an ordinary `postmd_create_document` call.

The format is at <https://postmd.turink.com/docs/graph>. Working out what the nodes are and how
they connect requires reading the document, which is the calling agent's part; PostMD only draws
what it finds.

### Replacing content on a document that has notes

Notes are located by the text they quote, not by a stored position. Replacing a
document's body therefore moves or loses where they point: a note whose quote is
gone loses its place in the body, and one whose quote now appears elsewhere points
there instead. The note itself, including the quoted text, is kept either way.

Both update tools require `notesOnReplace` whenever new content is sent.

| Value | Effect |
|-------|--------|
| `keep` | Replaces the content and leaves the notes as they are |
| `abort` | Refuses when the document has notes anchored to its text, and says how many |

Metadata-only updates do not take it.

Notes and highlights — key with `documents:read` / `documents:write`. A note is
text anchored to a quoted passage; a highlight is the same object carrying only
a colour. Visibility comes from ownership: on the key member's own document a note
is `PRIVATE` or `SHARED`, and on anyone else's document it is always `SHARED`.
Documents nobody owns — anonymous uploads and service-owned pages — take no notes:

| Tool | Purpose |
|------|---------|
| `postmd_list_notes` | Notes on a document: yours + every `SHARED` one |
| `postmd_add_note` | Attach a note, or a colour-only highlight to a quoted passage |
| `postmd_update_note` | Edit a note you wrote |
| `postmd_resolve_note` | Mark a `SHARED` discussion settled, or reopen it |
| `postmd_delete_note` | Delete yours, or a `SHARED` note on your document |
| `postmd_list_my_notes` | Your notes across every document |

Groups — key with `groups:read` / `groups:write`:

| Tool | Purpose |
|------|---------|
| `postmd_list_groups` | Groups visible to the key (paged) |
| `postmd_list_group_documents` | Documents in a group (paged, searchable, sortable) |
| `postmd_create_group` | New group |
| `postmd_update_group` | Rename group |
| `postmd_delete_group` | Delete a group (documents survive) |

For uploads: either pass the full Markdown as the `markdown` argument, or pass a local `filePath` only so this server reads the file. The path must exist on the machine running the MCP server.

## Client configuration

### Hosted

Claude Code:

```bash
claude mcp add --transport http postmd https://postmd.turink.com/mcp
```

Clients that take a JSON config:

```json
{
  "mcpServers": {
    "PostMD": {
      "type": "http",
      "url": "https://postmd.turink.com/mcp"
    }
  }
}
```

In ChatGPT, add it under **Settings → Apps**; in claude.ai, under **Settings → Connectors**.
There is nothing to authorize.

### Local

There is nothing to install: `npx` fetches the package and the client spawns it.

Claude Code:

```bash
claude mcp add postmd -- npx -y postmd-mcp-server
```

Cursor (`~/.cursor/mcp.json`) and most other stdio clients:

```json
{
  "mcpServers": {
    "PostMD": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "postmd-mcp-server"],
      "env": { "POSTMD_API_KEY": "pmk_…" }
    }
  }
}
```

To run a checkout instead — changing the code, or debugging against a local PostMD —
point the client at the file.

```bash
git clone https://github.com/reinlainer/postmd-mcp-server.git
cd postmd-mcp-server && npm ci
claude mcp add postmd-dev -- node "$PWD/src/index.js"
```

Leave `env` out entirely for publish/read-only use. `cp .env.example .env` works too — the server loads its own `.env`.

Running `npx -y postmd-mcp-server` by hand only checks that it starts. It speaks MCP over
stdin and stdout, so it will sit there waiting for a client.

## Smoke test

Runs the full write path against a live server and cleans up after itself. Needs a key with all four scopes.

```bash
export POSTMD_API_KEY=pmk_…
npm run smoke
```

Creates a group and a passworded document, reads it back, updates it, clears the password, then deletes both. It also publishes one document with no credential and removes it without a token.

## Stack

`@modelcontextprotocol/sdk` **1.30.0**, `dotenv`. **License:** MIT.