postmd-mcp-server 2.1.0 → 2.2.0

package/README.md

@@ -4,6 +4,8 @@ stdio [Model Context Protocol](https://modelcontextprotocol.io) server for **[Po
 
 **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.
 
+**Anonymous documents come with a control token.** Publishing without a key returns `data.controlToken` and `data.retainedUntil`: the document is deleted at that instant, and the token is the only way to update or delete it before then. It is shown once and cannot be reissued, so keep it with the `docCode`. Pass it as `controlToken` to the update and delete tools and they work without an API key.
+
 **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
@@ -36,19 +38,22 @@ Publishing and reading — no key needed:
 
 Managing documents — key with `documents:write`:
 
+Each of the first three also accepts `controlToken` instead of a key, for a document published anonymously.
+
 | 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_delete_document` | Delete a document (no undo) |
 | `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:
+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 |
 |------|---------|
@@ -73,19 +78,21 @@ For uploads: either pass the full Markdown as the `markdown` argument, or pass a
 
 ## Quickstart
 
+Nothing to install. `npx` fetches the package and the MCP client spawns it.
+
 ```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
+npx -y postmd-mcp-server
 ```
 
+Run it by hand only to check that it starts — it speaks MCP over stdin and stdout, so it
+will sit there waiting for a client.
+
 ## Client configuration
 
 Claude Code:
 
 ```bash
-claude mcp add postmd -- node /absolute/path/to/postmd-mcp-server/src/index.js
+claude mcp add postmd -- npx -y postmd-mcp-server
 ```
 
 Cursor (`~/.cursor/mcp.json`) and most other stdio clients:
@@ -95,14 +102,23 @@ Cursor (`~/.cursor/mcp.json`) and most other stdio clients:
   "mcpServers": {
     "PostMD": {
       "type": "stdio",
-      "command": "node",
-      "args": ["/absolute/path/to/postmd-mcp-server/src/index.js"],
+      "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`.
 
 ## Smoke test
@@ -114,7 +130,7 @@ 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.
+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 with the control token.
 
 ## Stack
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postmd-mcp-server",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP server for PostMD — publish Markdown, get a shareable web page",
   "mcpName": "io.github.reinlainer/postmd-mcp-server",
   "type": "module",

package/scripts/smoke-test.mjs

@@ -108,5 +108,50 @@ if (groupId != null) {
   check("delete group", dropped.json?.resultCode === "200", dropped.text);
 }
 
+/*
+  9. 익명 발행과 제어 토큰.
+
+  자격 증명을 붙이지 않고 부른다. 키를 실으면 그 회원 소유가 되어 토큰이 나오지 않으므로,
+  여기서만 Authorization 헤더를 뺀다.
+*/
+const anonForm = new FormData();
+anonForm.append(
+  "file",
+  new Blob([`# Smoke anon\n\n${MARKER}\n`], { type: "text/markdown" }),
+  "smoke-anon.md"
+);
+const anonRes = await fetch(`${base}/api/v1/documents`, { method: "POST", body: anonForm });
+const anon = await anonRes.json().catch(() => null);
+check("publish without a credential", anon?.resultCode === "200", JSON.stringify(anon));
+
+const anonCode = anon?.data?.docCode;
+const controlToken = anon?.data?.controlToken;
+check("answer carries a control token", typeof controlToken === "string" && controlToken.startsWith("pmt_"));
+check("answer carries a deletion date", typeof anon?.data?.retainedUntil === "string");
+check("answer explains the terms", typeof anon?.message === "string" && anon.message.length > 0);
+
+if (anonCode && controlToken) {
+  const titled = new FormData();
+  titled.append("title", `mcp smoke anon ${stamp}`);
+  const changed = await fetch(`${base}/api/v1/documents/${anonCode}/update`, {
+    method: "POST",
+    headers: { "X-Document-Token": controlToken },
+    body: titled,
+  });
+  check("token updates the document", (await changed.json().catch(() => null))?.resultCode === "200");
+
+  const refused = await fetch(`${base}/api/v1/documents/${anonCode}/delete`, {
+    method: "POST",
+    headers: { "X-Document-Token": "pmt_wrong" },
+  });
+  check("a wrong token is refused", (await refused.json().catch(() => null))?.resultCode === "E_DOC_0008");
+
+  const removed = await fetch(`${base}/api/v1/documents/${anonCode}/delete`, {
+    method: "POST",
+    headers: { "X-Document-Token": controlToken },
+  });
+  check("token deletes the document", (await removed.json().catch(() => null))?.resultCode === "200");
+}
+
 console.log(failures ? `\n${failures} failure(s)` : "\nall good");
 process.exit(failures ? 1 : 0);

package/server.json

@@ -2,7 +2,7 @@
   "$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",
+  "version": "2.2.0",
   "repository": {
     "url": "https://github.com/reinlainer/postmd-mcp-server",
     "source": "github"
@@ -11,7 +11,7 @@
     {
       "registryType": "npm",
       "identifier": "postmd-mcp-server",
-      "version": "2.1.0",
+      "version": "2.2.0",
       "transport": {
         "type": "stdio"
       },

package/src/index.js

@@ -17,7 +17,7 @@ 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 VERSION = "2.2.0";
 
 /** 기본은 운영이다. 대부분의 사용자는 설정 없이 바로 쓰면 된다. */
 const DEFAULT_BASE_URL = "https://postmd.turink.com";
@@ -28,7 +28,10 @@ const SERVER_INSTRUCTIONS =
   "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.";
+  "itself. A successful create returns data.shareUrl — hand that URL to people. " +
+  "Creating without a key also returns data.controlToken and data.retainedUntil: the " +
+  "document is deleted at that instant, and the token is the only way to update or " +
+  "delete it. It is shown once, so report it to the person along with the URL.";
 
 function isDebug() {
   const v = process.env.POSTMD_DEBUG;
@@ -176,9 +179,18 @@ const ATTACHMENT_MIME = {
   pdf: "application/pdf",
 };
 
-/** 만든 문서에는 나눠 줄 주소를 붙여 준다. 에이전트의 다음 행동이 바로 그것이다. */
+/**
+ * 만든 문서에는 나눠 줄 주소를 붙여 준다. 에이전트의 다음 행동이 바로 그것이다.
+ *
+ * 서버가 이미 `shareUrl` 을 돌려주면 그것을 쓴다. 서버는 요청이 실제로 들어온 주소를
+ * 보고 만들고, 여기서는 `POSTMD_BASE_URL` 을 보고 만든다. 자체 호스팅에서 그 둘이
+ * 다르면 값이 갈리는데, 사람에게 건너가는 주소는 서버가 아는 쪽이 맞다.
+ *
+ * 그래도 이 함수를 남겨 둔다. `shareUrl` 을 돌려주지 않는 구 버전 서버를 가리키는
+ * 설정이 있을 수 있고, 그때도 에이전트는 건넬 주소를 받아야 한다.
+ */
 function addShareUrl(ctx, data) {
-  if (data && typeof data.docCode === "string" && data.docCode) {
+  if (data && typeof data.docCode === "string" && data.docCode && !data.shareUrl) {
     data.shareUrl = `${ctx.base}/share/${encodeURIComponent(data.docCode)}`;
   }
 }
@@ -213,11 +225,40 @@ async function updateDocument(ctx, a, markdownBuffer) {
   }
   const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/update`, {
     method: "POST",
+    headers: tokenHeader(a),
     body: form,
   });
   return fromEnvelope(r);
 }
 
+/**
+ * 익명 발행 문서의 제어 토큰 인자.
+ *
+ * 키를 대신하는 것이 아니라 그 문서 하나에만 듣는다. 그래서 키가 없어도 이 값이 있으면
+ * 도구를 부를 수 있고, 키가 있어도 남의 익명 문서에는 이 값이 있어야 한다.
+ */
+const CONTROL_TOKEN_PROP = {
+  type: "string",
+  description:
+    "Control token from an anonymous publish answer (pmt_...). Lets you act on that one " +
+    "document without an API key.",
+};
+
+/** 제어 토큰을 헤더로 옮긴다. 서버는 회원 인증 헤더와 나눠서 받는다. */
+function tokenHeader(a) {
+  return a.controlToken ? { "X-Document-Token": String(a.controlToken) } : {};
+}
+
+/**
+ * 키가 없어도 제어 토큰이 있으면 통과시킨다.
+ *
+ * 토큰만으로 되는 일에 키를 요구하면, 방금 익명으로 발행하고 토큰을 받은 쪽이 자기 문서를
+ * 손대지 못한다.
+ */
+function missingKeyUnlessToken(ctx, a, scopes) {
+  return a.controlToken ? null : missingKey(ctx, scopes);
+}
+
 /** 문서 메타데이터 공통 속성. 만들기·고치기 스키마가 나눠 쓴다. */
 const DOC_META_PROPS = {
   password: { type: "string", description: "Readers must supply this password to see the content." },
@@ -237,8 +278,11 @@ 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 " +
+      "Returns docCode and data.shareUrl; hand shareUrl to people. Without a key the " +
+      "document is anonymous: data.retainedUntil is when it is deleted and " +
+      "data.controlToken is the only way to update or delete it, shown once and never " +
+      "reissued — report both to the person. With an API key the document belongs to that " +
+      "member, has no expiry, needs no token and can collect notes; groupId files it into " +
       "that group instead of the default one (key with documents:write).",
     inputSchema: {
       type: "object",
@@ -262,7 +306,8 @@ const TOOL_DEFS = [
     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.",
+      "running this MCP server — use it for large files instead of pasting the body. " +
+      "Without an API key it returns data.controlToken and data.retainedUntil, same as above.",
     inputSchema: {
       type: "object",
       properties: {
@@ -329,9 +374,11 @@ const TOOL_DEFS = [
   {
     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.",
+      "Update a document. Requires an API key with documents:write for a document you own, " +
+      "or `controlToken` for an anonymously published one. Include `markdown` to replace " +
+      "the stored content; any metadata field replaces that field. clearPassword / " +
+      "clearShareEndDate remove the password / end date. Updating does not push back the " +
+      "deletion date of an anonymous document.",
     inputSchema: {
       type: "object",
       properties: {
@@ -345,6 +392,7 @@ const TOOL_DEFS = [
         ...DOC_META_PROPS,
         clearPassword: { type: "boolean", description: "true removes the password." },
         clearShareEndDate: { type: "boolean", description: "true removes the end date, making sharing open-ended." },
+        controlToken: CONTROL_TOKEN_PROP,
       },
       required: ["docCode"],
     },
@@ -353,7 +401,7 @@ const TOOL_DEFS = [
     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.",
+      "machine running this MCP server. Takes `controlToken` the same way.",
     inputSchema: {
       type: "object",
       properties: {
@@ -367,6 +415,7 @@ const TOOL_DEFS = [
         ...DOC_META_PROPS,
         clearPassword: { type: "boolean", description: "true removes the password." },
         clearShareEndDate: { type: "boolean", description: "true removes the end date, making sharing open-ended." },
+        controlToken: CONTROL_TOKEN_PROP,
       },
       required: ["docCode", "filePath"],
     },
@@ -374,11 +423,13 @@ const TOOL_DEFS = [
   {
     name: "postmd_delete_document",
     description:
-      "Delete a document you own (recoverable for 30 days, then purged). Requires an API " +
-      "key with documents:write.",
+      "Delete a document. Requires an API key with documents:write for a document you own, " +
+      "or `controlToken` for an anonymously published one. There is no endpoint to undo " +
+      "this: the document stops being served at once and its stored content is erased about " +
+      "a month later.",
     inputSchema: {
       type: "object",
-      properties: { docCode: { type: "string" } },
+      properties: { docCode: { type: "string" }, controlToken: CONTROL_TOKEN_PROP },
       required: ["docCode"],
     },
   },
@@ -423,9 +474,10 @@ const TOOL_DEFS = [
     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.",
+      "`quotedContent` is required — a highlight must point at a passage). Visibility comes " +
+      "from ownership: on the key member's own document choose PRIVATE (only they see it) or " +
+      "SHARED; on anyone else's document every note is SHARED, so omit scope. Documents " +
+      "nobody owns — anonymous uploads and service-owned pages — take no notes at all.",
     inputSchema: {
       type: "object",
       properties: {
@@ -447,7 +499,8 @@ const TOOL_DEFS = [
     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.",
+      "keeps the current one; a scope you do send follows the ownership rule above. The " +
+      "note must keep text or a colour.",
     inputSchema: {
       type: "object",
       properties: {
@@ -655,12 +708,12 @@ async function runTool(ctx, name, args) {
       }
     }
     case "postmd_update_document": {
-      const denied = missingKey(ctx, "documents:write");
+      const denied = missingKeyUnlessToken(ctx, a, "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");
+      const denied = missingKeyUnlessToken(ctx, a, "documents:write");
       if (denied) return denied;
       try {
         const { buffer, suggestedName } = await readLocalFile(a.filePath);
@@ -670,10 +723,11 @@ async function runTool(ctx, name, args) {
       }
     }
     case "postmd_delete_document": {
-      const denied = missingKey(ctx, "documents:write");
+      const denied = missingKeyUnlessToken(ctx, a, "documents:write");
       if (denied) return denied;
       const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/delete`, {
         method: "POST",
+        headers: tokenHeader(a),
       });
       return fromEnvelope(r);
     }