postmd-mcp-server 2.1.1 → 2.3.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,38 @@ 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 |
 
+### 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. `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 |
 |------|---------|
@@ -125,7 +146,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.1",
+  "version": "2.3.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

@@ -90,6 +90,22 @@ if (docCode) {
   const meta2 = await callJson(`/documents/${docCode}/meta`);
   check("password cleared", meta2.json?.data?.hasPassword === false, meta2.text);
 
+  // 5b. 본문을 갈아 끼울 때는 붙어 있는 메모를 어떻게 할지 골라야 한다
+  const bodyOnly = new FormData();
+  bodyOnly.append("file", new Blob([`# ${MARKER} v2\n\n다른 문장\n`], { type: "text/markdown" }), "v2.md");
+  const undecided = await callJson(`/documents/${docCode}/update`, { method: "POST", body: bodyOnly });
+  check(
+    "replacing content without notesOnReplace is refused",
+    undecided.json?.resultCode === "E_DOC_0009",
+    undecided.text,
+  );
+
+  const decided = new FormData();
+  decided.append("file", new Blob([`# ${MARKER} v2\n\n다른 문장\n`], { type: "text/markdown" }), "v2.md");
+  decided.append("notesOnReplace", "keep");
+  const replaced = await callJson(`/documents/${docCode}/update`, { method: "POST", body: decided });
+  check("replacing content with keep succeeds", replaced.json?.resultCode === "200", replaced.text);
+
   // 6. 그룹 목록에 보이는지
   if (groupId != null) {
     const listed = await callJson(`/groups/${groupId}/documents?q=smoke`);
@@ -108,5 +124,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.1",
+  "version": "2.3.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.1",
+      "version": "2.3.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;
@@ -220,13 +223,68 @@ async function updateDocument(ctx, a, markdownBuffer) {
   if ([...form.keys()].length === 0) {
     return textErr("Nothing to update: pass new markdown, or at least one metadata field.");
   }
+  /*
+    Replacing the content needs a decision about the notes anchored to it. Checked here so the
+    caller reads it as a missing argument rather than an HTTP error from the server.
+  */
+  if (markdownBuffer !== null) {
+    if (a.notesOnReplace !== "keep" && a.notesOnReplace !== "abort") {
+      return textErr(
+        "notesOnReplace is required when replacing the content: keep or abort. " +
+          "Notes are located by the text they quote, so replacing the body moves or loses " +
+          "where they point. keep replaces anyway; abort refuses when the document has notes " +
+          "anchored to its text.",
+      );
+    }
+    form.append("notesOnReplace", a.notesOnReplace);
+  }
   const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/update`, {
     method: "POST",
+    headers: tokenHeader(a),
     body: form,
   });
   return fromEnvelope(r);
 }
 
+/**
+ * 익명 발행 문서의 제어 토큰 인자.
+ *
+ * 키를 대신하는 것이 아니라 그 문서 하나에만 듣는다. 그래서 키가 없어도 이 값이 있으면
+ * 도구를 부를 수 있고, 키가 있어도 남의 익명 문서에는 이 값이 있어야 한다.
+ */
+const NOTES_ON_REPLACE_PROP = {
+  type: "string",
+  enum: ["keep", "abort"],
+  description:
+    "Required when replacing the content. Notes are located by the text they quote, so " +
+    "replacing the body 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. " +
+    "keep replaces anyway and leaves the notes. abort refuses when the document has notes " +
+    "anchored to its text, and the answer says how many.",
+};
+
+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." },
@@ -246,8 +304,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",
@@ -271,7 +332,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: {
@@ -338,9 +400,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. Replacing the content requires notesOnReplace.",
     inputSchema: {
       type: "object",
       properties: {
@@ -354,6 +418,8 @@ 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." },
+        notesOnReplace: NOTES_ON_REPLACE_PROP,
+        controlToken: CONTROL_TOKEN_PROP,
       },
       required: ["docCode"],
     },
@@ -362,7 +428,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: {
@@ -376,18 +442,22 @@ 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." },
+        notesOnReplace: NOTES_ON_REPLACE_PROP,
+        controlToken: CONTROL_TOKEN_PROP,
       },
-      required: ["docCode", "filePath"],
+      required: ["docCode", "filePath", "notesOnReplace"],
     },
   },
   {
     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"],
     },
   },
@@ -432,9 +502,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: {
@@ -456,7 +527,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: {
@@ -664,12 +736,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);
@@ -679,10 +751,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);
     }