postmd-mcp-server 2.1.0

package/.env.example

@@ -0,0 +1,14 @@
+# Everything here is optional. With no configuration at all, the server talks to
+# production and can publish and read documents anonymously.
+
+# Where PostMD runs. Defaults to https://postmd.turink.com — set this only for a
+# self-hosted or local instance. Origin only, no trailing slash.
+#POSTMD_BASE_URL=http://localhost:8080
+
+# Needed for managing documents (update/delete), attachments and groups.
+# A signed-in member creates keys at https://postmd.turink.com/account —
+# pick the scopes your tools need (read and write are independent).
+#POSTMD_API_KEY=pmk_your_key_here
+
+# 1 / true / yes → verbose diagnostics on stderr.
+#POSTMD_DEBUG=1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 reinlainer
+
+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,121 @@
+# PostMD MCP Server
+
+stdio [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. Optional groups, document passwords, share expiry 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. An API key adds management: updating and deleting your documents, attachments, and groups.
+
+**HTTP reference:** [postmd.turink.com/docs/api](https://postmd.turink.com/docs/api) · machine-readable spec at [/api-docs](https://postmd.turink.com/api-docs)
+
+## Requirements
+
+- **Node.js** 20 or later
+- Nothing else. An **API key** (`pmk_…`) only for the management tools.
+
+## Configuration
+
+All variables 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
+
+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`:
+
+| Tool | Purpose |
+|------|---------|
+| `postmd_update_document` | Replace content and/or metadata; can clear password / end date |
+| `postmd_update_document_from_file` | Same, body read from a local `filePath` |
+| `postmd_delete_document` | Delete (recoverable for 30 days) |
+| `postmd_upload_attachment` | Upload an image/PDF, get a URL to embed in Markdown |
+| `postmd_create_documents_from_files` | Bulk-publish several `.md` files in one call |
+| `postmd_move_document_to_group` | Move a document into a group / folder |
+
+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. `PRIVATE` notes belong to the key's member; `SHARED` notes are
+comments every reader sees:
+
+| 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 / change expiry |
+| `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.
+
+## Quickstart
+
+```bash
+git clone https://github.com/reinlainer/postmd-mcp-server.git
+cd postmd-mcp-server
+npm ci
+node src/index.js      # normally spawned by the MCP client; use for debugging
+```
+
+## Client configuration
+
+Claude Code:
+
+```bash
+claude mcp add postmd -- node /absolute/path/to/postmd-mcp-server/src/index.js
+```
+
+Cursor (`~/.cursor/mcp.json`) and most other stdio clients:
+
+```json
+{
+  "mcpServers": {
+    "PostMD": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/absolute/path/to/postmd-mcp-server/src/index.js"],
+      "env": { "POSTMD_API_KEY": "pmk_…" }
+    }
+  }
+}
+```
+
+Leave `env` out entirely for publish/read-only use. `cp .env.example .env` works too — the server loads its own `.env`.
+
+## 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.
+
+## Stack
+
+`@modelcontextprotocol/sdk` **1.30.0**, `dotenv`. **License:** MIT.

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "postmd-mcp-server",
+  "version": "2.1.0",
+  "description": "MCP server for PostMD — publish Markdown, get a shareable web page",
+  "mcpName": "io.github.reinlainer/postmd-mcp-server",
+  "type": "module",
+  "main": "src/index.js",
+  "bin": {
+    "postmd-mcp-server": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "smoke": "node scripts/smoke-test.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reinlainer/postmd-mcp-server.git"
+  },
+  "homepage": "https://postmd.turink.com",
+  "keywords": [
+    "mcp",
+    "postmd",
+    "markdown",
+    "publishing"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "dotenv": "16.4.5"
+  }
+}

package/scripts/smoke-test.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * 쓰기 경로를 실제 서버에 대고 한 바퀴 돈다. HTTP 로 직접 부른다 — 여기서 확인하려는
+ * 것은 MCP 프로토콜이 아니라 API 계약(경로·필드·봉투)이다.
+ *
+ * 네 스코프(documents:read/write, groups:read/write)를 모두 가진 키가 필요하다.
+ * 그룹 하나와 문서 하나를 만들었다가 끝에 모두 지운다.
+ */
+import "../src/env.js";
+
+const base = (process.env.POSTMD_BASE_URL || "https://postmd.turink.com").replace(/\/+$/, "");
+const key = process.env.POSTMD_API_KEY;
+if (!key) {
+  console.error("smoke: set POSTMD_API_KEY (scopes: documents:read/write, groups:read/write)");
+  process.exit(1);
+}
+
+const AUTH = { Authorization: `Bearer ${key}` };
+let failures = 0;
+
+function check(label, condition, detail) {
+  if (condition) {
+    console.log(`ok   ${label}`);
+  } else {
+    failures++;
+    console.error(`FAIL ${label}${detail ? ` — ${detail}` : ""}`);
+  }
+}
+
+async function callJson(pathname, init = {}) {
+  const res = await fetch(`${base}/api/v1${pathname}`, {
+    ...init,
+    headers: { ...AUTH, ...(init.headers || {}) },
+  });
+  let json = null;
+  const text = await res.text();
+  try {
+    json = JSON.parse(text);
+  } catch {
+    /* 봉투가 아니면 text 로 판단한다 */
+  }
+  return { status: res.status, json, text };
+}
+
+const stamp = Date.now();
+const PASSWORD = `smoke-${stamp}`;
+const MARKER = `smoke marker ${stamp}`;
+
+// 1. 그룹 만들기
+const created = await callJson("/groups", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: `mcp smoke ${stamp}` }),
+});
+check("create group", created.json?.resultCode === "200", created.text);
+const groupId = created.json?.data?.groupId;
+
+// 2. 비밀번호 걸린 문서를 그 그룹에 올리기
+const form = new FormData();
+form.append(
+  "file",
+  new Blob([`# Smoke\n\n${MARKER}\n`], { type: "text/markdown" }),
+  "smoke.md"
+);
+form.append("title", `mcp smoke ${stamp}`);
+form.append("password", PASSWORD);
+if (groupId != null) form.append("groupId", String(groupId));
+const uploaded = await callJson("/documents", { method: "POST", body: form });
+check("create document", uploaded.json?.resultCode === "200", uploaded.text);
+const docCode = uploaded.json?.data?.docCode;
+
+if (docCode) {
+  // 3. 메타 — 비밀번호가 걸렸다고 말해야 한다
+  const meta = await callJson(`/documents/${docCode}/meta`);
+  check("meta shows password", meta.json?.data?.hasPassword === true, meta.text);
+
+  // 4. 원문 — 비밀번호 헤더로 열리고, 올린 내용 그대로여야 한다
+  const raw = await callJson(`/documents/${docCode}/raw`, {
+    headers: { "X-Document-Password": PASSWORD },
+  });
+  check("raw readable with password", raw.status === 200 && raw.text.includes(MARKER));
+
+  // 5. 고치기 — 제목을 바꾸고 비밀번호를 푼다
+  const patch = new FormData();
+  patch.append("title", `mcp smoke ${stamp} v2`);
+  patch.append("clearPassword", "true");
+  const updated = await callJson(`/documents/${docCode}/update`, { method: "POST", body: patch });
+  check("update document", updated.json?.resultCode === "200", updated.text);
+
+  const meta2 = await callJson(`/documents/${docCode}/meta`);
+  check("password cleared", meta2.json?.data?.hasPassword === false, meta2.text);
+
+  // 6. 그룹 목록에 보이는지
+  if (groupId != null) {
+    const listed = await callJson(`/groups/${groupId}/documents?q=smoke`);
+    const found = (listed.json?.data || []).some((d) => d.docCode === docCode);
+    check("document listed in group", found, listed.text);
+  }
+
+  // 7. 문서 지우기
+  const deleted = await callJson(`/documents/${docCode}/delete`, { method: "POST" });
+  check("delete document", deleted.json?.resultCode === "200", deleted.text);
+}
+
+// 8. 그룹 지우기 — 예전 Agent API 에는 없어서 손으로 지워야 했던 바로 그것
+if (groupId != null) {
+  const dropped = await callJson(`/groups/${groupId}/delete`, { method: "POST" });
+  check("delete group", dropped.json?.resultCode === "200", dropped.text);
+}
+
+console.log(failures ? `\n${failures} failure(s)` : "\nall good");
+process.exit(failures ? 1 : 0);

package/server.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.reinlainer/postmd-mcp-server",
+  "description": "Publish Markdown to PostMD and get a shareable web page",
+  "version": "2.1.0",
+  "repository": {
+    "url": "https://github.com/reinlainer/postmd-mcp-server",
+    "source": "github"
+  },
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "postmd-mcp-server",
+      "version": "2.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "POSTMD_BASE_URL",
+          "description": "Where PostMD runs. Defaults to https://postmd.turink.com; set it only for a self-hosted instance.",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "POSTMD_API_KEY",
+          "description": "Needed only for managing documents, attachments and groups. Publishing and reading work without it.",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "POSTMD_DEBUG",
+          "description": "Set to 1 for verbose diagnostics on stderr.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

package/src/env.js

@@ -0,0 +1,10 @@
+/**
+ * 이 패키지 루트(`package.json`과 같은 디렉터리)의 `.env`를 로드한다 (실행 cwd와 무관).
+ * 이미 설정된 process.env 값은 덮어쓰지 않는다.
+ */
+import { config } from "dotenv";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+config({ path: join(root, ".env") });

package/src/index.js

@@ -0,0 +1,866 @@
+#!/usr/bin/env node
+/**
+ * PostMD 공개 API(/api/v1) — MCP stdio 서버.
+ *
+ * 필수 환경변수는 없다. POSTMD_BASE_URL 이 없으면 운영(https://postmd.turink.com)을
+ * 부르고, POSTMD_API_KEY 가 없으면 발행과 읽기만 할 수 있다 — 그것만으로도 PostMD 의
+ * 기본 쓰임은 다 된다. 문서 관리(수정·삭제)·첨부·그룹에는 키가 필요하며, 키 없이
+ * 그런 도구를 부르면 어느 스코프가 왜 필요한지 알려 준다.
+ *
+ * 도구 설명과 오류 문구는 영어다. 이 문장들은 사람이 아니라 에이전트가 읽는다.
+ */
+import "./env.js";
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+
+const VERSION = "2.1.0";
+
+/** 기본은 운영이다. 대부분의 사용자는 설정 없이 바로 쓰면 된다. */
+const DEFAULT_BASE_URL = "https://postmd.turink.com";
+
+/** initialize 때 클라이언트에 전달되어, 모델이 도구를 고르기 전에 읽는다. */
+const SERVER_INSTRUCTIONS =
+  "PostMD publishes Markdown as web pages. Use the postmd_* tools instead of calling " +
+  "the HTTP API directly. Creating a document needs no API key; updating, deleting, " +
+  "attachments and groups need POSTMD_API_KEY with the matching scope. Pass the full " +
+  "Markdown in `markdown`, or pass a local `filePath` so this server reads the file " +
+  "itself. A successful create returns data.shareUrl — hand that URL to people.";
+
+function isDebug() {
+  const v = process.env.POSTMD_DEBUG;
+  if (!v) return false;
+  const s = String(v).toLowerCase();
+  return s === "1" || s === "true" || s === "yes";
+}
+
+function debugStderr(line) {
+  if (isDebug()) process.stderr.write(`[postmd-mcp-server] ${line}\n`);
+}
+
+/** 로그에는 호스트와 경로만. 쿼리에 비밀이 실릴 수 있다. */
+function safeUrlForLog(urlString) {
+  try {
+    const u = new URL(urlString);
+    return `${u.protocol}//${u.host}${u.pathname}`;
+  } catch {
+    return "(invalid url)";
+  }
+}
+
+/** fetch·TLS·DNS 실패의 message·cause·code 를 한 줄로 편다. */
+function formatNetworkError(err) {
+  const parts = [];
+  let e = err;
+  let depth = 0;
+  while (e != null && depth < 10) {
+    if (e instanceof Error) {
+      let line = e.message;
+      if (typeof e.code === "string" && e.code) line += ` [code=${e.code}]`;
+      parts.push(line);
+      e = e.cause;
+    } else {
+      parts.push(String(e));
+      break;
+    }
+    depth++;
+  }
+  return parts.length ? parts.join(" | ") : String(err);
+}
+
+function normalizeBaseUrl(url) {
+  if (!url || typeof url !== "string") return "";
+  return url.trim().replace(/\/+$/, "");
+}
+
+function resolveConfig() {
+  const base = normalizeBaseUrl(process.env.POSTMD_BASE_URL) || DEFAULT_BASE_URL;
+  const key = (process.env.POSTMD_API_KEY || "").trim() || null;
+  return { base, key };
+}
+
+function textOk(text) {
+  return { content: [{ type: "text", text }] };
+}
+
+function textErr(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+/** 키가 필요한 도구의 문지기. 키가 없으면 네트워크에 나가지 않고 여기서 알려 준다. */
+function missingKey(ctx, scopes) {
+  if (ctx.key) return null;
+  return textErr(
+    `This tool requires an API key with scope ${scopes}. ` +
+      `Set POSTMD_API_KEY — a signed-in member creates keys at ${ctx.base}/account.`
+  );
+}
+
+function truncate(text, max = 2000) {
+  const s = String(text ?? "");
+  return s.length > max ? `${s.slice(0, max)}… (${s.length} chars total)` : s;
+}
+
+/**
+ * /api/v1 호출. 키가 있으면 실어 보낸다 — 익명 발행 엔드포인트도 키를 받으면
+ * 그 회원 소유로 만들어 주므로, 있는 키를 숨길 이유가 없다.
+ */
+async function apiFetch(ctx, apiPath, init = {}) {
+  const url = `${ctx.base}/api/v1${apiPath}`;
+  const headers = new Headers(init.headers);
+  if (ctx.key) headers.set("Authorization", `Bearer ${ctx.key}`);
+  try {
+    const res = await fetch(url, { ...init, headers });
+    const ct = res.headers.get("content-type") || "";
+    const bodyText = await res.text();
+    if (ct.includes("application/json")) {
+      try {
+        return { status: res.status, json: JSON.parse(bodyText), bodyText };
+      } catch {
+        return { status: res.status, json: null, bodyText };
+      }
+    }
+    return { status: res.status, json: null, bodyText };
+  } catch (e) {
+    const diag = formatNetworkError(e);
+    debugStderr(`fetch ${safeUrlForLog(url)} → ${diag}`);
+    return { status: 0, json: null, bodyText: "", networkError: diag };
+  }
+}
+
+/**
+ * 응답 봉투를 도구 결과로 바꾼다.
+ *
+ * API 는 실패도 JSON 봉투로 준다. HTTP 상태가 아니라 resultCode 로 갈라야 하고,
+ * 실패는 isError 로 표시해야 에이전트가 성공으로 오독하지 않는다 — 예전 서버는
+ * 오류 봉투를 성공처럼 돌려주는 문제가 있었다.
+ */
+function fromEnvelope(r) {
+  if (r.networkError) return textErr(`Request failed: ${r.networkError}`);
+  if (!r.json) return textErr(`HTTP ${r.status}: ${truncate(r.bodyText)}`);
+  const text = JSON.stringify(r.json, null, 2);
+  return r.json.resultCode === "200" ? textOk(text) : { ...textErr(text) };
+}
+
+function query(params) {
+  const qs = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== undefined && v !== null) qs.set(k, String(v));
+  }
+  const s = qs.toString();
+  return s ? `?${s}` : "";
+}
+
+/** 이 서버가 도는 기기의 파일을 읽는다. 원격 경로가 아니다. */
+async function readLocalFile(filePath) {
+  const raw = String(filePath ?? "").trim();
+  if (!raw) throw new Error("filePath is required");
+  const resolved = path.resolve(raw);
+  const st = await fs.stat(resolved);
+  if (!st.isFile()) throw new Error(`Not a regular file: ${resolved}`);
+  return { buffer: await fs.readFile(resolved), suggestedName: path.basename(resolved) };
+}
+
+/** 첨부는 서버가 확장자로 받아 준다. Content-Type 은 예의상 맞춰 보낸다. */
+const ATTACHMENT_MIME = {
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  svg: "image/svg+xml",
+  bmp: "image/bmp",
+  pdf: "application/pdf",
+};
+
+/** 만든 문서에는 나눠 줄 주소를 붙여 준다. 에이전트의 다음 행동이 바로 그것이다. */
+function addShareUrl(ctx, data) {
+  if (data && typeof data.docCode === "string" && data.docCode) {
+    data.shareUrl = `${ctx.base}/share/${encodeURIComponent(data.docCode)}`;
+  }
+}
+
+function documentForm(a, markdownBuffer) {
+  const form = new FormData();
+  if (markdownBuffer != null) {
+    const fileName = a.fileName || "document.md";
+    form.append("file", new Blob([markdownBuffer], { type: "text/markdown" }), fileName);
+  }
+  if (a.title != null) form.append("title", String(a.title));
+  if (a.password != null) form.append("password", String(a.password));
+  if (a.shareEndDate != null) form.append("shareEndDate", String(a.shareEndDate));
+  if (a.viewerStyle != null) form.append("viewerStyle", String(a.viewerStyle));
+  return form;
+}
+
+async function createDocument(ctx, a, markdownBuffer) {
+  const form = documentForm(a, markdownBuffer);
+  if (a.groupId != null) form.append("groupId", String(a.groupId));
+  const r = await apiFetch(ctx, "/documents", { method: "POST", body: form });
+  if (r.json?.resultCode === "200") addShareUrl(ctx, r.json.data);
+  return fromEnvelope(r);
+}
+
+async function updateDocument(ctx, a, markdownBuffer) {
+  const form = documentForm(a, markdownBuffer);
+  if (a.clearPassword === true) form.append("clearPassword", "true");
+  if (a.clearShareEndDate === true) form.append("clearShareEndDate", "true");
+  if ([...form.keys()].length === 0) {
+    return textErr("Nothing to update: pass new markdown, or at least one metadata field.");
+  }
+  const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/update`, {
+    method: "POST",
+    body: form,
+  });
+  return fromEnvelope(r);
+}
+
+/** 문서 메타데이터 공통 속성. 만들기·고치기 스키마가 나눠 쓴다. */
+const DOC_META_PROPS = {
+  password: { type: "string", description: "Readers must supply this password to see the content." },
+  shareEndDate: {
+    type: "string",
+    description: "yyyyMMdd. The document stops being served after this date. Omit for no end date.",
+  },
+  viewerStyle: {
+    type: "string",
+    description:
+      "Viewer theme: readable (default), github, minimal, report, pamphlet or dark. Unknown values fall back to readable.",
+  },
+};
+
+const TOOL_DEFS = [
+  {
+    name: "postmd_create_document",
+    description:
+      "Publish Markdown as a PostMD web page. No API key required — anyone can publish. " +
+      "Returns docCode and data.shareUrl; hand shareUrl to people. With an API key the " +
+      "document belongs to that member and can be updated later; groupId files it into " +
+      "that group instead of the default one (key with documents:write).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        markdown: {
+          type: "string",
+          description: "Full Markdown document as one UTF-8 string (the entire source, not a summary).",
+        },
+        title: {
+          type: "string",
+          description: "Shown in the viewer and link previews. Defaults to fileName without .md.",
+        },
+        fileName: { type: "string", description: "Upload filename, must end in .md. Default document.md." },
+        ...DOC_META_PROPS,
+        groupId: { type: "number", description: "File the document in this group instead of the default group (needs an API key)." },
+      },
+      required: ["markdown"],
+    },
+  },
+  {
+    name: "postmd_create_document_from_file",
+    description:
+      "Same as postmd_create_document, but reads the Markdown from filePath on the machine " +
+      "running this MCP server — use it for large files instead of pasting the body.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePath: {
+          type: "string",
+          description: "Path to a .md file on the MCP server host, read as UTF-8. Prefer an absolute path.",
+        },
+        title: { type: "string", description: "Defaults to the file name without .md." },
+        fileName: { type: "string", description: "Upload filename. Defaults to the basename of filePath." },
+        ...DOC_META_PROPS,
+        groupId: { type: "number", description: "File the document in this group instead of the default group (needs an API key)." },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "postmd_create_documents_from_files",
+    description:
+      "Publish several .md files in one call (bulk upload). Requires an API key with " +
+      "documents:write. The outer resultCode is 200 even if some files failed — check " +
+      "data.succeeded and each entry in data.results.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePaths: {
+          type: "array",
+          items: { type: "string" },
+          description: "Paths to .md files on the MCP server host. Each becomes its own document.",
+        },
+        ...DOC_META_PROPS,
+        groupId: { type: "number", description: "File every document in this group instead of the default group." },
+      },
+      required: ["filePaths"],
+    },
+  },
+  {
+    name: "postmd_get_document",
+    description:
+      "Get document metadata by docCode: title, fileName, hasPassword, shareEndDate, " +
+      "viewerStyle, timestamps. Public — no API key needed. Content is not included; " +
+      "use postmd_get_document_raw for the Markdown source.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      type: "object",
+      properties: { docCode: { type: "string", description: "Document code, e.g. P-123-456-789." } },
+      required: ["docCode"],
+    },
+  },
+  {
+    name: "postmd_get_document_raw",
+    description:
+      "Get the stored Markdown source of a document. Public — no API key needed. " +
+      "Password-protected documents need `password`; expired documents cannot be read.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        docCode: { type: "string" },
+        password: { type: "string", description: "Plain document password, if the document has one." },
+      },
+      required: ["docCode"],
+    },
+  },
+  {
+    name: "postmd_update_document",
+    description:
+      "Update a document you own. Requires an API key with documents:write. Include " +
+      "`markdown` to replace the stored content; any metadata field replaces that field. " +
+      "clearPassword / clearShareEndDate remove the password / end date.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        docCode: { type: "string" },
+        markdown: {
+          type: "string",
+          description: "Full new Markdown body as one UTF-8 string. Omit if only metadata changes.",
+        },
+        title: { type: "string" },
+        fileName: { type: "string", description: "Upload filename when replacing content. Default document.md." },
+        ...DOC_META_PROPS,
+        clearPassword: { type: "boolean", description: "true removes the password." },
+        clearShareEndDate: { type: "boolean", description: "true removes the end date, making sharing open-ended." },
+      },
+      required: ["docCode"],
+    },
+  },
+  {
+    name: "postmd_update_document_from_file",
+    description:
+      "Same as postmd_update_document, but reads the new Markdown from filePath on the " +
+      "machine running this MCP server.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        docCode: { type: "string" },
+        filePath: {
+          type: "string",
+          description: "Path to a .md file on the MCP server host, read as UTF-8. Prefer an absolute path.",
+        },
+        title: { type: "string" },
+        fileName: { type: "string", description: "Upload filename. Defaults to the basename of filePath." },
+        ...DOC_META_PROPS,
+        clearPassword: { type: "boolean", description: "true removes the password." },
+        clearShareEndDate: { type: "boolean", description: "true removes the end date, making sharing open-ended." },
+      },
+      required: ["docCode", "filePath"],
+    },
+  },
+  {
+    name: "postmd_delete_document",
+    description:
+      "Delete a document you own (recoverable for 30 days, then purged). Requires an API " +
+      "key with documents:write.",
+    inputSchema: {
+      type: "object",
+      properties: { docCode: { type: "string" } },
+      required: ["docCode"],
+    },
+  },
+  {
+    name: "postmd_upload_attachment",
+    description:
+      "Upload an image or PDF to reference from a document. Requires an API key with " +
+      "documents:write. Allowed types: png, jpg, jpeg, gif, webp, svg, bmp, pdf. Use the " +
+      "returned data.url as the image/link target in your Markdown, then publish the " +
+      "Markdown with postmd_create_document.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        filePath: {
+          type: "string",
+          description: "Path to the file on the MCP server host. Prefer an absolute path.",
+        },
+        fileName: { type: "string", description: "Upload filename. Defaults to the basename of filePath." },
+      },
+      required: ["filePath"],
+    },
+  },
+  {
+    name: "postmd_list_notes",
+    description:
+      "List notes and highlights on a document: your own plus every SHARED one, newest " +
+      "first. Requires an API key with documents:read. Each note carries mine and " +
+      "manageable flags — trust them instead of re-deriving permissions. Pass `password` " +
+      "for a password-protected document.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        docCode: { type: "string" },
+        password: { type: "string", description: "Plain document password, if the document has one." },
+      },
+      required: ["docCode"],
+    },
+  },
+  {
+    name: "postmd_add_note",
+    description:
+      "Attach a note or highlight to a document. Requires an API key with documents:write. " +
+      "Give `content` for a note, `color` alone for a colour-only highlight (then " +
+      "`quotedContent` is required — a highlight must point at a passage). scope PRIVATE " +
+      "(default) is visible only to the key's member; SHARED is visible to every reader " +
+      "and only allowed on documents owned by a person.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        docCode: { type: "string" },
+        content: { type: "string", description: "Note text, up to 4000 characters. Omit for a colour-only highlight." },
+        quotedContent: {
+          type: "string",
+          description: "Passage of the body this note points to, up to 4000 characters. Matched by text, so it survives edits elsewhere.",
+        },
+        scope: { type: "string", description: "PRIVATE (default) or SHARED." },
+        color: { type: "string", description: "YELLOW, GREEN, BLUE or PURPLE." },
+        textStart: { type: "number", description: "Character offset where the quote starts in the body. Optional; speeds up re-anchoring." },
+        password: { type: "string", description: "Plain document password, if the document has one." },
+      },
+      required: ["docCode"],
+    },
+  },
+  {
+    name: "postmd_update_note",
+    description:
+      "Edit a note you wrote. Requires an API key with documents:write. Omitting scope " +
+      "keeps the current one. The note must keep text or a colour.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        docCode: { type: "string" },
+        noteId: { type: "number" },
+        content: { type: "string" },
+        quotedContent: { type: "string" },
+        scope: { type: "string", description: "PRIVATE or SHARED. Omit to keep the current scope." },
+        color: { type: "string", description: "YELLOW, GREEN, BLUE or PURPLE." },
+      },
+      required: ["docCode", "noteId"],
+    },
+  },
+  {
+    name: "postmd_resolve_note",
+    description:
+      "Mark a note as settled, or undo it with resolved=false. Meaningful on SHARED " +
+      "notes; the author or the document owner may set it. Requires an API key with " +
+      "documents:write.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        docCode: { type: "string" },
+        noteId: { type: "number" },
+        resolved: { type: "boolean", description: "true marks it settled; false reopens it." },
+      },
+      required: ["docCode", "noteId", "resolved"],
+    },
+  },
+  {
+    name: "postmd_delete_note",
+    description:
+      "Delete a note: your own, or a SHARED note on a document you own. Requires an API " +
+      "key with documents:write.",
+    inputSchema: {
+      type: "object",
+      properties: { docCode: { type: "string" }, noteId: { type: "number" } },
+      required: ["docCode", "noteId"],
+    },
+  },
+  {
+    name: "postmd_list_my_notes",
+    description:
+      "List every note the key's member wrote, across all documents, with docCode and " +
+      "documentTitle beside each one. Requires an API key with documents:read.",
+    annotations: { readOnlyHint: true },
+    inputSchema: { type: "object", properties: {}, required: [] },
+  },
+  {
+    name: "postmd_list_groups",
+    description: "List groups the key's member belongs to. Requires an API key with groups:read. Paged.",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        page: { type: "number", description: "1-based page number." },
+        size: { type: "number", description: "Items per page." },
+      },
+      required: [],
+    },
+  },
+  {
+    name: "postmd_list_group_documents",
+    description:
+      "List documents in a group. Requires an API key with groups:read and documents:read. " +
+      "Paged; q searches title and file name (substring, case-insensitive).",
+    annotations: { readOnlyHint: true },
+    inputSchema: {
+      type: "object",
+      properties: {
+        groupId: { type: "number" },
+        folderId: { type: "number", description: "Only documents filed in this folder." },
+        rootOnly: { type: "boolean", description: "true → only documents not in any folder." },
+        q: { type: "string", description: "Search text for title and file name." },
+        sort: {
+          type: "string",
+          description: "recent (default), oldest, name, name_desc, created or created_asc.",
+        },
+        page: { type: "number" },
+        size: { type: "number" },
+      },
+      required: ["groupId"],
+    },
+  },
+  {
+    name: "postmd_move_document_to_group",
+    description:
+      "Move a document you own into a group you can use, optionally into a folder of that " +
+      "group. A document belongs to exactly one group, so this replaces its current group. " +
+      "Requires an API key with documents:write.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        docCode: { type: "string" },
+        groupId: { type: "number" },
+        folderId: { type: "number", description: "File it into this folder of that group." },
+      },
+      required: ["docCode", "groupId"],
+    },
+  },
+  {
+    name: "postmd_create_group",
+    description:
+      "Create a group. Requires an API key with groups:write. Documents can then be filed " +
+      "into it and members invited from the web app.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        expireDate: { type: "string", description: "yyyyMMdd. The group stops working after this date." },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "postmd_update_group",
+    description:
+      "Rename a group or change its expiry. Owner only. Requires an API key with " +
+      "groups:write. clearExpireDate removes the expiry.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        groupId: { type: "number" },
+        name: { type: "string" },
+        expireDate: { type: "string", description: "yyyyMMdd." },
+        clearExpireDate: { type: "boolean", description: "true removes the expiry date." },
+      },
+      required: ["groupId"],
+    },
+  },
+  {
+    name: "postmd_delete_group",
+    description:
+      "Delete a group. Owner only; the default group cannot be deleted. Documents in it " +
+      "are not deleted. Requires an API key with groups:write.",
+    inputSchema: {
+      type: "object",
+      properties: { groupId: { type: "number" } },
+      required: ["groupId"],
+    },
+  },
+];
+
+async function runTool(ctx, name, args) {
+  const a = args && typeof args === "object" ? args : {};
+
+  switch (name) {
+    case "postmd_create_document": {
+      if (typeof a.markdown !== "string" || a.markdown.length === 0) {
+        return textErr("markdown is required: the full document source as one string.");
+      }
+      return await createDocument(ctx, a, a.markdown);
+    }
+    case "postmd_create_document_from_file": {
+      try {
+        const { buffer, suggestedName } = await readLocalFile(a.filePath);
+        return await createDocument(ctx, { ...a, fileName: a.fileName ?? suggestedName }, buffer);
+      } catch (e) {
+        return textErr(e instanceof Error ? e.message : String(e));
+      }
+    }
+    case "postmd_create_documents_from_files": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      if (!Array.isArray(a.filePaths) || a.filePaths.length === 0) {
+        return textErr("filePaths is required: one path per document.");
+      }
+      const form = new FormData();
+      try {
+        for (const p of a.filePaths) {
+          const { buffer, suggestedName } = await readLocalFile(p);
+          form.append("files", new Blob([buffer], { type: "text/markdown" }), suggestedName);
+        }
+      } catch (e) {
+        return textErr(e instanceof Error ? e.message : String(e));
+      }
+      if (a.password != null) form.append("password", String(a.password));
+      if (a.shareEndDate != null) form.append("shareEndDate", String(a.shareEndDate));
+      if (a.viewerStyle != null) form.append("viewerStyle", String(a.viewerStyle));
+      if (a.groupId != null) form.append("groupId", String(a.groupId));
+      const r = await apiFetch(ctx, "/documents/bulk", { method: "POST", body: form });
+      if (r.json?.resultCode === "200" && Array.isArray(r.json.data?.results)) {
+        for (const item of r.json.data.results) addShareUrl(ctx, item);
+      }
+      return fromEnvelope(r);
+    }
+    case "postmd_get_document": {
+      const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/meta`);
+      return fromEnvelope(r);
+    }
+    case "postmd_get_document_raw": {
+      const url = `${ctx.base}/api/v1/documents/${encodeURIComponent(a.docCode)}/raw`;
+      const headers = {};
+      if (ctx.key) headers.Authorization = `Bearer ${ctx.key}`;
+      if (a.password) headers["X-Document-Password"] = String(a.password);
+      try {
+        const res = await fetch(url, { headers });
+        const t = await res.text();
+        if (!res.ok) return textErr(`HTTP ${res.status}: ${truncate(t)}`);
+        return textOk(t);
+      } catch (e) {
+        const diag = formatNetworkError(e);
+        debugStderr(`fetch ${safeUrlForLog(url)} → ${diag}`);
+        return textErr(`Request failed: ${diag}`);
+      }
+    }
+    case "postmd_update_document": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      return await updateDocument(ctx, a, a.markdown ?? null);
+    }
+    case "postmd_update_document_from_file": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      try {
+        const { buffer, suggestedName } = await readLocalFile(a.filePath);
+        return await updateDocument(ctx, { ...a, fileName: a.fileName ?? suggestedName }, buffer);
+      } catch (e) {
+        return textErr(e instanceof Error ? e.message : String(e));
+      }
+    }
+    case "postmd_delete_document": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/delete`, {
+        method: "POST",
+      });
+      return fromEnvelope(r);
+    }
+    case "postmd_upload_attachment": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      try {
+        const { buffer, suggestedName } = await readLocalFile(a.filePath);
+        const fileName = a.fileName || suggestedName;
+        const ext = path.extname(fileName).slice(1).toLowerCase();
+        const mime = ATTACHMENT_MIME[ext] || "application/octet-stream";
+        const form = new FormData();
+        form.append("file", new Blob([buffer], { type: mime }), fileName);
+        const r = await apiFetch(ctx, "/documents/uploads", { method: "POST", body: form });
+        return fromEnvelope(r);
+      } catch (e) {
+        return textErr(e instanceof Error ? e.message : String(e));
+      }
+    }
+    case "postmd_list_notes": {
+      const denied = missingKey(ctx, "documents:read");
+      if (denied) return denied;
+      const headers = {};
+      if (a.password) headers["X-Document-Password"] = String(a.password);
+      const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/notes`, { headers });
+      return fromEnvelope(r);
+    }
+    case "postmd_add_note": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      const body = {};
+      if (a.content != null) body.content = String(a.content);
+      if (a.quotedContent != null) body.quotedContent = String(a.quotedContent);
+      if (a.scope != null) body.scope = String(a.scope);
+      if (a.color != null) body.color = String(a.color);
+      if (a.textStart != null) body.textStart = Number(a.textStart);
+      const headers = { "Content-Type": "application/json" };
+      if (a.password) headers["X-Document-Password"] = String(a.password);
+      const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/notes`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body),
+      });
+      return fromEnvelope(r);
+    }
+    case "postmd_update_note": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      const body = {};
+      if (a.content != null) body.content = String(a.content);
+      if (a.quotedContent != null) body.quotedContent = String(a.quotedContent);
+      if (a.scope != null) body.scope = String(a.scope);
+      if (a.color != null) body.color = String(a.color);
+      const r = await apiFetch(
+        ctx,
+        `/documents/${encodeURIComponent(a.docCode)}/notes/${Number(a.noteId)}/update`,
+        { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }
+      );
+      return fromEnvelope(r);
+    }
+    case "postmd_resolve_note": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      const r = await apiFetch(
+        ctx,
+        `/documents/${encodeURIComponent(a.docCode)}/notes/${Number(a.noteId)}/resolve`,
+        {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ resolved: a.resolved === true }),
+        }
+      );
+      return fromEnvelope(r);
+    }
+    case "postmd_delete_note": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      const r = await apiFetch(
+        ctx,
+        `/documents/${encodeURIComponent(a.docCode)}/notes/${Number(a.noteId)}/delete`,
+        { method: "POST" }
+      );
+      return fromEnvelope(r);
+    }
+    case "postmd_list_my_notes": {
+      const denied = missingKey(ctx, "documents:read");
+      if (denied) return denied;
+      const r = await apiFetch(ctx, "/notes");
+      return fromEnvelope(r);
+    }
+    case "postmd_list_groups": {
+      const denied = missingKey(ctx, "groups:read");
+      if (denied) return denied;
+      const r = await apiFetch(ctx, `/groups${query({ page: a.page, size: a.size })}`);
+      return fromEnvelope(r);
+    }
+    case "postmd_list_group_documents": {
+      const denied = missingKey(ctx, "groups:read and documents:read");
+      if (denied) return denied;
+      const qs = query({
+        folderId: a.folderId,
+        rootOnly: a.rootOnly,
+        q: a.q,
+        sort: a.sort,
+        page: a.page,
+        size: a.size,
+      });
+      const r = await apiFetch(ctx, `/groups/${Number(a.groupId)}/documents${qs}`);
+      return fromEnvelope(r);
+    }
+    case "postmd_move_document_to_group": {
+      const denied = missingKey(ctx, "documents:write");
+      if (denied) return denied;
+      const body = { groupId: a.groupId };
+      if (a.folderId != null) body.folderId = a.folderId;
+      const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/group`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      return fromEnvelope(r);
+    }
+    case "postmd_create_group": {
+      const denied = missingKey(ctx, "groups:write");
+      if (denied) return denied;
+      const body = { name: a.name };
+      if (a.expireDate != null) body.expireDate = a.expireDate;
+      const r = await apiFetch(ctx, "/groups", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      return fromEnvelope(r);
+    }
+    case "postmd_update_group": {
+      const denied = missingKey(ctx, "groups:write");
+      if (denied) return denied;
+      const body = {};
+      if (a.name != null) body.name = a.name;
+      if (a.expireDate != null) body.expireDate = a.expireDate;
+      if (a.clearExpireDate === true) body.clearExpireDate = true;
+      const r = await apiFetch(ctx, `/groups/${Number(a.groupId)}/update`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      return fromEnvelope(r);
+    }
+    case "postmd_delete_group": {
+      const denied = missingKey(ctx, "groups:write");
+      if (denied) return denied;
+      const r = await apiFetch(ctx, `/groups/${Number(a.groupId)}/delete`, { method: "POST" });
+      return fromEnvelope(r);
+    }
+    default:
+      return textErr(`Unknown tool: ${name}`);
+  }
+}
+
+async function main() {
+  const ctx = resolveConfig();
+  debugStderr(
+    `debug on | base ${ctx.base} | key ${ctx.key ? "set" : "not set (publish/read only)"}`
+  );
+
+  const server = new Server(
+    { name: "postmd-mcp-server", version: VERSION },
+    { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFS }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+      return await runTool(ctx, name, args);
+    } catch (e) {
+      const msg = formatNetworkError(e);
+      debugStderr(`tool ${name} threw: ${msg}`);
+      return textErr(msg);
+    }
+  });
+
+  await server.connect(new StdioServerTransport());
+}
+
+main().catch((e) => {
+  process.stderr.write(String(e instanceof Error ? e.stack : e) + "\n");
+  process.exit(1);
+});