remark-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Freddie Wheeler
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# remark-mcp
+
+**Connect Claude to Remark — push documents in for provocation-driven review, pull them back with their full thinking trail.**
+
+`remark-mcp` is a small [MCP](https://modelcontextprotocol.io) server. It lets any Claude Code or Claude Desktop session push a document into [Remark](https://remark.freddie.nyc) — optionally with a *context brief* capturing the session's reasoning — and pull any Remark document back as a single composed markdown artifact, including every remark and its status. Work is born in a Claude session, handed to Remark for deeper thinking, and referenceable from any later session.
+
+## Quickstart
+
+1. **Create a Bridge token** in Remark → Settings → Bridge tokens (copy it once — it is shown only once).
+2. **Add the server to Claude Code**, passing the token via env:
+   ```sh
+   claude mcp add remark --env REMARK_TOKEN=rmk_your_token_here -- npx -y remark-mcp
+   ```
+3. **Use it**: in a Claude session, say *"push this document to Remark with a brief covering what we decided"* — you'll get back a link. Later, *"pull my latest Remark doc"* or *"what did Remark say about it?"*
+
+That's it. The token lives in your client config, never on the command line or in a log.
+
+---
+
+## Configuration
+
+All configuration is via environment variables — never argv, so your token never lands in a process list.
+
+| Variable | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `REMARK_TOKEN` | Yes | — | A Bridge token from Remark → Settings → Bridge tokens (`rmk_…`). |
+| `REMARK_URL` | No | `https://remark.freddie.nyc` | Point at a different Remark instance if you self-host. |
+
+The server fails fast at startup with a clear message if `REMARK_TOKEN` is missing.
+
+## Client setup
+
+The supported (QA'd) clients are **Claude Code** and **Claude Desktop**. Cursor and VS Code use the same standard MCP config and should work, but are documented-not-guaranteed.
+
+### Claude Code
+
+```sh
+claude mcp add remark --env REMARK_TOKEN=rmk_your_token_here -- npx -y remark-mcp
+```
+
+### Claude Desktop
+
+**Option A — one-click bundle (`.mcpb`):** download the `remark-mcp.mcpb` file from the [latest release](https://github.com/freddie-wheeler/remark-mcp/releases), double-click it to install into Claude Desktop, and paste your token when prompted. No terminal required.
+
+**Option B — config file:** add this to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "remark": {
+      "command": "npx",
+      "args": ["-y", "remark-mcp"],
+      "env": { "REMARK_TOKEN": "rmk_your_token_here" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after editing.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or the project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "remark": {
+      "command": "npx",
+      "args": ["-y", "remark-mcp"],
+      "env": { "REMARK_TOKEN": "rmk_your_token_here" }
+    }
+  }
+}
+```
+
+### VS Code
+
+Add to your user or workspace MCP config:
+
+```json
+{
+  "servers": {
+    "remark": {
+      "command": "npx",
+      "args": ["-y", "remark-mcp"],
+      "env": { "REMARK_TOKEN": "rmk_your_token_here" }
+    }
+  }
+}
+```
+
+### Run from source (development / pre-release)
+
+Before the npm package is published you can run the server straight from a clone. Requires [Bun](https://bun.sh).
+
+```sh
+git clone https://github.com/freddie-wheeler/remark-mcp.git
+cd remark-mcp
+bun install
+# then point your client at the local entry:
+claude mcp add remark --env REMARK_TOKEN=rmk_your_token_here -- bun run /absolute/path/to/remark-mcp/src/index.ts
+```
+
+## Creating a Bridge token
+
+1. Open Remark and go to **Settings → Bridge tokens**.
+2. Click **Create token**, give it a name (e.g. "Claude Code"), and confirm.
+3. **Copy the `rmk_…` value immediately** — it is shown exactly once and cannot be retrieved later. If you lose it, revoke it and create another.
+4. Provide it to your MCP client as `REMARK_TOKEN` (see the config blocks above).
+
+To rotate: create a new token, update `REMARK_TOKEN`, reconnect the server, then revoke the old one.
+
+![Where to find Bridge tokens in Remark Settings](docs/bridge-token.png)
+
+## Tools
+
+### `remark_push`
+
+Push a document into Remark for review. Triggers on *"push / send / transfer this to Remark"*.
+
+| Arg | Required | Description |
+| --- | --- | --- |
+| `markdown` | Yes | The full document as markdown. |
+| `title` | No | Defaults to the first heading or line. |
+| `goal` | No | What you want from the review (e.g. "find the weak assumptions"). |
+| `context_brief` | No (recommended) | A markdown summary of the session: decisions, rejected paths, open questions. Stored with the document. |
+
+> *"Push this strategy memo to Remark with a brief covering what we decided and what we ruled out."*
+
+### `remark_list`
+
+List your Remark documents, newest first (id, title, goal, lens, updated-at). No arguments.
+
+> *"What documents do I have in Remark?"*
+
+### `remark_get`
+
+Pull a document back as a composed artifact — header, context briefs, content, and the full provocation trail with statuses and replies. Triggers on *"get / pull / reference my Remark doc"* and *"what did Remark say about…"*.
+
+| Arg | Required | Description |
+| --- | --- | --- |
+| `document_id` | Yes | The document to fetch (use `remark_list` to find it). |
+| `format` | No | `markdown` (default) or `json`. |
+
+> *"Pull document abc123 from Remark and tell me what was dismissed and why."*
+
+## Security & privacy
+
+- **No telemetry.** This client sends nothing anywhere except your own Remark instance. It holds no state, writes no files, and keeps no logs of its own.
+- **Token via env only.** `REMARK_TOKEN` is read from the environment, never accepted on the command line (which would leak it into process lists), and never written to any log.
+- **Content stays between you and Remark.** Document content and context briefs flow only between your machine and your own Remark account. They are never logged by this server.
+- **Consent.** Whether your sessions contribute to Remark's learning is governed by your Remark account's consent setting, not by this client.
+
+## Troubleshooting
+
+- **"token invalid or revoked (401)"** — the token is wrong, expired, or revoked. Create a fresh one in Remark → Settings → Bridge tokens and update `REMARK_TOKEN`, then reconnect the server.
+- **"could not reach Remark at …"** — check `REMARK_URL` (default `https://remark.freddie.nyc`) and your network. The error names the exact URL tried.
+- **"document not found (404)"** — the `document_id` is wrong or belongs to another account. Run `remark_list` to get valid ids.
+- **`npx` / Node not found** — the `npx` route needs Node 18+ on your PATH. Either install Node, or use the *Run from source* route above with Bun.
+- **Server won't start** — if `REMARK_TOKEN` is unset the server exits immediately with a message pointing you to Settings. Confirm your client is passing the `env` block.
+
+## Development
+
+```sh
+bun install
+bun run typecheck   # tsc --noEmit
+bun run build       # emits dist/
+bun run start       # run the server on stdio
+```
+
+## License
+
+[MIT](LICENSE)

package/dist/client.js

@@ -0,0 +1,128 @@
+// A failure whose `message` is safe to show the user as-is. Thrown for every
+// mapped error condition so the server layer never has to interpret raw
+// fetch/HTTP internals.
+export class RemarkError extends Error {
+}
+export class RemarkClient {
+    token;
+    baseUrl;
+    constructor(config) {
+        this.token = config.token;
+        this.baseUrl = config.baseUrl;
+    }
+    // POST /api/bridge/documents — create, or update in place when document_id
+    // is supplied.
+    async push(input) {
+        const body = { markdown: input.markdown };
+        if (input.title)
+            body.title = input.title;
+        if (input.goal)
+            body.goal = input.goal;
+        if (input.lens_doc_type)
+            body.lens_doc_type = input.lens_doc_type;
+        if (input.lens_stage)
+            body.lens_stage = input.lens_stage;
+        if (input.context_brief)
+            body.context_brief = input.context_brief;
+        if (input.document_id)
+            body.document_id = input.document_id;
+        const res = await this.fetch('/api/bridge/documents', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify(body),
+        });
+        if (!res.ok) {
+            throw await this.mapError(res, { documentId: input.document_id });
+        }
+        const data = (await this.json(res));
+        if (!data.id || !data.url) {
+            throw new RemarkError(`Remark returned an unexpected response to the push (HTTP ${res.status}).`);
+        }
+        return { id: data.id, url: data.url };
+    }
+    // GET /api/bridge/documents — the caller's documents, newest first.
+    async list() {
+        const res = await this.fetch('/api/bridge/documents', { method: 'GET' });
+        if (!res.ok) {
+            throw await this.mapError(res, {});
+        }
+        const data = (await this.json(res));
+        return data.documents ?? [];
+    }
+    // GET /api/bridge/documents/[id] — the composed read. `format: 'json'`
+    // returns the structured shape; markdown (default) returns the composed
+    // artifact as a single string.
+    async get(documentId, format) {
+        const suffix = format === 'json' ? '?format=json' : '';
+        const path = `/api/bridge/documents/${encodeURIComponent(documentId)}${suffix}`;
+        const res = await this.fetch(path, { method: 'GET' });
+        if (!res.ok) {
+            throw await this.mapError(res, { documentId });
+        }
+        if (format === 'json') {
+            return { format: 'json', body: await this.json(res) };
+        }
+        return { format: 'markdown', body: await res.text() };
+    }
+    // --- internals ----------------------------------------------------------
+    async fetch(path, init) {
+        const url = `${this.baseUrl}${path}`;
+        try {
+            return await fetch(url, {
+                ...init,
+                headers: {
+                    ...(init.headers ?? {}),
+                    Authorization: `Bearer ${this.token}`,
+                },
+            });
+        }
+        catch {
+            // Network-layer failure (DNS, connection refused, TLS). Name the URL
+            // tried so the user can spot a wrong REMARK_URL or an offline host.
+            throw new RemarkError(`Could not reach Remark at ${this.baseUrl}. Check REMARK_URL and your ` +
+                `network connection. (Tried ${init.method ?? 'GET'} ${url}.)`);
+        }
+    }
+    async json(res) {
+        try {
+            return await res.json();
+        }
+        catch {
+            throw new RemarkError(`Remark returned a response that could not be parsed as JSON (HTTP ${res.status}).`);
+        }
+    }
+    // Maps an HTTP error status to a user-facing message. 401 and 404 are
+    // product surfaces with specific guidance; everything else is reported with
+    // the status and any server-provided message, but never a stack trace.
+    async mapError(res, ctx) {
+        if (res.status === 401) {
+            return new RemarkError('Remark rejected the token (401): it is invalid or has been revoked. ' +
+                'Create a new one in Remark → Settings → Bridge tokens and set it as ' +
+                'REMARK_TOKEN.');
+        }
+        if (res.status === 404) {
+            const which = ctx.documentId ? ` "${ctx.documentId}"` : '';
+            return new RemarkError(`Remark could not find that document${which} (404): the id does not exist or does not belong to your account.`);
+        }
+        // Other statuses: surface the server's message when present, else a
+        // generic line. Read the body defensively — it may be JSON or text.
+        let detail = '';
+        try {
+            const text = await res.text();
+            if (text) {
+                try {
+                    const parsed = JSON.parse(text);
+                    detail = parsed.error ?? text;
+                }
+                catch {
+                    detail = text;
+                }
+            }
+        }
+        catch {
+            // ignore — no readable body
+        }
+        const suffix = detail ? ` — ${detail}` : '';
+        return new RemarkError(`Remark request failed (HTTP ${res.status})${suffix}.`);
+    }
+}

package/dist/config.js

@@ -0,0 +1,30 @@
+// Configuration is env-only. Tokens are NEVER accepted via argv (they would
+// leak into process lists) and NEVER logged.
+export const DEFAULT_REMARK_URL = 'https://remark.freddie.nyc';
+// The eight lens document types the Remark app recognises (mirrors
+// `DOC_TYPES` in the remark repo). `lens_stage` is free text, not an enum.
+export const LENS_DOC_TYPES = [
+    'strategy-memo',
+    'prd',
+    'decision-memo',
+    'launch-plan',
+    'postmortem',
+    'vision-belief',
+    'essay',
+    'other',
+];
+// Reads and validates configuration from the environment. Throws with a
+// user-facing message (no token echoed) when REMARK_TOKEN is absent so the
+// server fails fast at startup.
+export function loadConfig(env = process.env) {
+    const token = env.REMARK_TOKEN?.trim();
+    if (!token) {
+        throw new Error('REMARK_TOKEN is not set. Create a Bridge token in Remark → Settings → ' +
+            'Bridge tokens, then provide it to this server as the REMARK_TOKEN ' +
+            'environment variable (never on the command line).');
+    }
+    const rawUrl = env.REMARK_URL?.trim() || DEFAULT_REMARK_URL;
+    // Strip any trailing slash so path joins are predictable.
+    const baseUrl = rawUrl.replace(/\/+$/, '');
+    return { token, baseUrl };
+}

package/dist/index.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { RemarkClient, RemarkError } from './client.js';
+import { LENS_DOC_TYPES, loadConfig } from './config.js';
+// remark-mcp — a stdio MCP server that connects Claude to Remark. It is a thin
+// wrapper over the Remark Bridge API: push a document in (optionally with a
+// context brief carrying the session's reasoning), list your documents, and
+// pull any document back as a composed markdown artifact including its full
+// provocation trail.
+//
+// This process speaks JSON-RPC over stdout — nothing else may be written
+// there. All diagnostics go to stderr via console.error, and never include
+// document content or token material.
+const VERSION = '0.1.0';
+// Wraps a client call so every thrown error reaches the model as a clean,
+// actionable message (isError result) rather than a transport-level failure.
+async function toolResult(fn) {
+    try {
+        return { content: [{ type: 'text', text: await fn() }] };
+    }
+    catch (err) {
+        const message = err instanceof RemarkError
+            ? err.message
+            : 'Unexpected error talking to Remark. Check REMARK_URL and that the ' +
+                'Remark service is reachable.';
+        return { content: [{ type: 'text', text: message }], isError: true };
+    }
+}
+function buildServer(config) {
+    const client = new RemarkClient(config);
+    const server = new McpServer({ name: 'remark-mcp', version: VERSION });
+    // --- remark_push -------------------------------------------------------
+    server.registerTool('remark_push', {
+        title: 'Push a document to Remark',
+        description: 'Push, send, or transfer a document to Remark for provocation-driven ' +
+            'review. Use this when the user says to "push/send/transfer this to ' +
+            'Remark", or wants a piece of writing (a memo, PRD, strategy doc, ' +
+            'essay, proposal) reviewed in Remark. Pass the full document as ' +
+            'markdown. Strongly prefer to include a `context_brief`: a short ' +
+            'summary of the session that produced the document — what was decided, ' +
+            'which paths were rejected and why, and any open questions — so the ' +
+            "reviewer inherits the session's reasoning. Supply `document_id` to " +
+            'update a document you pushed earlier instead of creating a new one.',
+        inputSchema: {
+            markdown: z
+                .string()
+                .describe('The full document content as markdown. Required.'),
+            title: z
+                .string()
+                .optional()
+                .describe('Document title. Defaults to the first heading or line if omitted.'),
+            goal: z
+                .string()
+                .optional()
+                .describe('What the author wants from this document — e.g. "sharpen the ' +
+                'argument", "find the weak assumptions". Guides the review.'),
+            lens_doc_type: z
+                .enum(LENS_DOC_TYPES)
+                .optional()
+                .describe(`The kind of document, which tunes the review lens. One of: ${LENS_DOC_TYPES.join(', ')}. Omit to let Remark infer it.`),
+            lens_stage: z
+                .string()
+                .optional()
+                .describe('Free-text maturity stage — e.g. "early exploration", ' +
+                '"pre-users", "ready to ship". Optional.'),
+            context_brief: z
+                .string()
+                .optional()
+                .describe('A markdown summary of the session that produced this document: ' +
+                'key decisions, rejected alternatives and why, and open ' +
+                'questions. Highly recommended — it is stored with the document ' +
+                'and gives the review its reasoning trail.'),
+            document_id: z
+                .string()
+                .optional()
+                .describe('The id of an existing Remark document to update in place. Omit ' +
+                'to create a new document.'),
+        },
+    }, (args) => toolResult(async () => {
+        const { id, url } = await client.push(args);
+        const verb = args.document_id ? 'Updated' : 'Pushed to';
+        return `${verb} Remark. Document id: ${id}\nOpen it: ${url}`;
+    }));
+    // --- remark_list -------------------------------------------------------
+    server.registerTool('remark_list', {
+        title: 'List your Remark documents',
+        description: "List the documents in the user's Remark account, newest first. Use " +
+            "this to find a document's id before pulling it back with remark_get, " +
+            'or when the user asks "what\'s in my Remark", "what documents do I ' +
+            'have in Remark", or wants to pick one to reference.',
+        inputSchema: {},
+    }, () => toolResult(async () => {
+        const docs = await client.list();
+        if (docs.length === 0) {
+            return 'No documents in your Remark account yet.';
+        }
+        const lines = docs.map((d) => {
+            const title = d.title?.trim() || 'Untitled';
+            const parts = [`- ${title} — id: ${d.id}`];
+            if (d.goal?.trim())
+                parts.push(`  goal: ${d.goal.trim()}`);
+            if (d.lens?.trim())
+                parts.push(`  lens: ${d.lens.trim()}`);
+            if (d.updated_at)
+                parts.push(`  updated: ${d.updated_at}`);
+            return parts.join('\n');
+        });
+        return `${docs.length} document(s):\n${lines.join('\n')}`;
+    }));
+    // --- remark_get --------------------------------------------------------
+    server.registerTool('remark_get', {
+        title: 'Get a Remark document with its thinking trail',
+        description: 'Get, pull, or reference a Remark document as a composed markdown ' +
+            'artifact: its header, any context briefs, the content, and the full ' +
+            'provocation trail — every remark with its status (kept, dismissed ' +
+            'with reason, suggested, accepted, rejected, resolved) and replies. ' +
+            'Use this when the user says "get/pull/reference my Remark doc", or ' +
+            'asks "what did Remark say about…", "what did the provocations ' +
+            'raise", or "what was dismissed and why". Find the id first with ' +
+            'remark_list if you do not have it.',
+        inputSchema: {
+            document_id: z
+                .string()
+                .describe('The id of the Remark document to fetch. Required.'),
+            format: z
+                .enum(['markdown', 'json'])
+                .optional()
+                .describe('Output format. "markdown" (default) returns the composed ' +
+                'artifact; "json" returns the same data structured.'),
+        },
+    }, (args) => toolResult(async () => {
+        const format = args.format ?? 'markdown';
+        const result = await client.get(args.document_id, format);
+        if (result.format === 'json') {
+            return JSON.stringify(result.body, null, 2);
+        }
+        return result.body;
+    }));
+    return server;
+}
+async function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        // Fail fast with a clear message on stderr; do not start the transport.
+        console.error(`remark-mcp: ${err instanceof Error ? err.message : String(err)}`);
+        process.exit(1);
+    }
+    const server = buildServer(config);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`remark-mcp ${VERSION} ready (target ${config.baseUrl}). Waiting for requests on stdio.`);
+}
+main().catch((err) => {
+    console.error(`remark-mcp: fatal — ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "remark-mcp",
+  "version": "0.1.0",
+  "description": "Connect Claude to Remark — push documents in for provocation-driven review, pull them back with their full thinking trail.",
+  "license": "MIT",
+  "author": "Freddie Wheeler",
+  "mcpName": "io.github.freddie-wheeler/remark-mcp",
+  "type": "module",
+  "homepage": "https://github.com/freddie-wheeler/remark-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freddie-wheeler/remark-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/freddie-wheeler/remark-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "remark",
+    "claude"
+  ],
+  "bin": {
+    "remark-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "format": "biome check --write src/",
+    "start": "bun run src/index.ts",
+    "dev": "bun run src/index.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "1.9.4",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}