postmd-mcp-server 2.4.0 → 2.5.0

package/.github/workflows/publish.yml

@@ -74,7 +74,34 @@ jobs:
         run: |
           curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
 
+      # 레지스트리는 소유권을 npm 으로 확인한다. 방금 올린 판의 메타데이터를 받아 mcpName 이
+      # 서버 이름과 같은지 본다. 그런데 npm 에 올린 직후에는 그 버전이 아직 보이지 않아
+      # 곧바로 부르면 404 로 떨어진다. 2.4.0 이 실제로 이렇게 실패했다 - npm 에는 올라갔는데
+      # 레지스트리만 빠져 두 곳이 어긋났다. 보일 때까지 기다린 다음 넘어간다.
+      - name: Wait until npm serves this version
+        run: |
+          NAME=$(node -p "require('./package.json').name")
+          VERSION=$(node -p "require('./package.json').version")
+          for i in $(seq 1 30); do
+            MCP_NAME=$(curl -fsS "https://registry.npmjs.org/$NAME/$VERSION" 2>/dev/null \
+              | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{process.stdout.write(JSON.parse(s).mcpName||'')}catch(e){}})")
+            if [ -n "$MCP_NAME" ]; then
+              echo "npm serves $NAME@$VERSION with mcpName $MCP_NAME"
+              exit 0
+            fi
+            echo "attempt $i/30: not visible yet"
+            sleep 10
+          done
+          echo "::error::npm did not serve $NAME@$VERSION within 5 minutes"
+          exit 1
+
+      # 기다린 뒤에도 순간적으로 실패할 수 있다. 같은 버전을 다시 올리는 것은 문제가 없다.
       - name: Publish to the MCP registry
         run: |
           ./mcp-publisher login github-oidc
-          ./mcp-publisher publish
+          for i in 1 2 3; do
+            if ./mcp-publisher publish; then exit 0; fi
+            echo "publish failed ($i/3), retrying in 20s"
+            sleep 20
+          done
+          exit 1

package/README.md

@@ -1,12 +1,12 @@
 # PostMD MCP Server
 
-[Model Context Protocol](https://modelcontextprotocol.io) server for **[PostMD](https://postmd.turink.com)** — publish a Markdown document, get a web page you share by link. 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.
+[Model Context Protocol](https://modelcontextprotocol.io) server for **[PostMD](https://postmd.turink.com)** — publish a Markdown document, get a web page you share by link, and add a document graph that the viewer draws beside the text: the reading order, the bodies and rules a document names, a procedure spread over its chapters. Optional groups, document passwords and viewer themes. This server wraps PostMD's public API (`/api/v1`) so assistants can publish, read, update and organize documents.
 
-**Publishing needs no account and no key.** With zero configuration this server can already turn Markdown into a shareable page, and the hosted server at `https://postmd.turink.com/mcp` needs no install either. An API key adds management: updating and deleting your documents, attachments, and groups.
+**Publishing needs no account and no key.** With zero configuration this server can already turn Markdown into a shareable page, and the hosted server at `https://postmd.turink.com/mcp` needs no install either. An API key adds management: organizing documents in groups, and notes.
 
-**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.
+**30-day retention.** Documents have a 30-day retention period (`data.retainedUntil`) that extends by 30 days whenever the document is read (at most once per day). Documents without a password can be updated or deleted by anyone; password-protected documents require the password or the owner's API key.
 
-**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)
+**Where things are written down:** [/llms.txt](https://postmd.turink.com/llms.txt) lists what the service can do and which page answers each thing; it is the place to start. [/docs/api](https://postmd.turink.com/docs/api) is the HTTP reference and [/api-docs](https://postmd.turink.com/api-docs) the machine-readable spec.
 
 ## Hosted or local
 
@@ -14,13 +14,12 @@
 |---|---|---|
 | Address | `https://postmd.turink.com/mcp` | `npx -y postmd-mcp-server` |
 | Needs | nothing | Node.js 20 or later |
-| Tools | 5 | all 21 |
-| API key | not accepted | optional, for the management tools |
+| Tools | 5 | all 20 |
+| API key | not accepted | optional, for member-scoped tools |
 | Clients | any, including web-only ones such as ChatGPT and claude.ai | any that can run a local process |
 
 The hosted server has no way to receive an API key, so it carries only the tools that need
-none. Attachments, groups, notes and the tools that read a file from your disk are
-local-only.
+none. Groups, notes and the tools that read a file from your disk are local-only.
 
 ## Configuration
 
@@ -37,8 +36,7 @@ Load order: this repo's `.env` (if present) is applied via `dotenv` without over
 ## Tools
 
 Every tool below works on the local server. The hosted server carries five of them:
-`postmd_create_document`, `postmd_get_document`, `postmd_get_document_raw`, and — with a
-`controlToken` instead of a key — `postmd_update_document` and `postmd_delete_document`.
+`postmd_create_document`, `postmd_get_document`, `postmd_get_document_raw`, `postmd_update_document`, and `postmd_delete_document`.
 
 Publishing and reading — no key needed:
 
@@ -49,18 +47,29 @@ Publishing and reading — no key needed:
 | `postmd_get_document` | Metadata by `docCode` |
 | `postmd_get_document_raw` | Stored Markdown body (optional `password`) |
 
-Managing documents — key with `documents:write`:
-
-Each of the first three also accepts `controlToken` instead of a key, for a document published anonymously.
+Managing documents — key with `documents:write` (or password / no credential for unowned documents without password):
 
 | Tool | Purpose |
 |------|---------|
-| `postmd_update_document` | Replace content and/or metadata; can clear password / end date |
+| `postmd_update_document` | Replace content and/or metadata; can clear password |
 | `postmd_update_document_from_file` | Same, body read from a local `filePath` |
 | `postmd_delete_document` | Delete a document (no undo) |
-| `postmd_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 |
+| `postmd_move_document_to_group` | Move a document into a group |
+
+### Graphs
+
+A PostMD document can carry graph data that the viewer draws in a panel beside the text, showing
+how the parts of the document relate. No tool here creates or edits a graph, because there is no
+endpoint for one: the data sits in the Markdown as an HTML comment and travels with the body.
+
+Adding a graph to an existing document therefore means reading it with `postmd_get_document_raw`,
+inserting the comment, and sending the whole body back with `postmd_update_document`. Publishing a
+new document with a graph is an ordinary `postmd_create_document` call.
+
+The format is at <https://postmd.turink.com/docs/graph>. Working out what the nodes are and how
+they connect requires reading the document, which is the calling agent's part; PostMD only draws
+what it finds.
 
 ### Replacing content on a document that has notes
 
@@ -100,7 +109,7 @@ Groups — key with `groups:read` / `groups:write`:
 | `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_update_group` | Rename group |
 | `postmd_delete_group` | Delete a group (documents survive) |
 
 For uploads: either pass the full Markdown as the `markdown` argument, or pass a local `filePath` only so this server reads the file. The path must exist on the machine running the MCP server.
@@ -179,7 +188,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. It also publishes one document with no credential and removes it with the control token.
+Creates a group and a passworded document, reads it back, updates it, clears the password, then deletes both. It also publishes one document with no credential and removes it without a token.
 
 ## Stack
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postmd-mcp-server",
-  "version": "2.4.0",
-  "description": "MCP server for PostMD — publish Markdown, get a shareable web page",
+  "version": "2.5.0",
+  "description": "MCP server for PostMD — publish Markdown as a shareable web page, with document graphs beside the text",
   "mcpName": "io.github.reinlainer/postmd-mcp-server",
   "type": "module",
   "main": "src/index.js",
@@ -25,7 +25,8 @@
     "mcp",
     "postmd",
     "markdown",
-    "publishing"
+    "publishing",
+    "document-graph"
   ],
   "license": "MIT",
   "dependencies": {

package/scripts/smoke-test.mjs

@@ -125,10 +125,9 @@ if (groupId != null) {
 }
 
 /*
-  9. 익명 발행과 제어 토큰.
+  9. 익명 발행 (비밀번호 없는 문서).
 
-  자격 증명을 붙이지 않고 부른다. 키를 실으면 그 회원 소유가 되어 토큰이 나오지 않으므로,
-  여기서만 Authorization 헤더를 뺀다.
+  자격 증명을 붙이지 않고 부른다.
 */
 const anonForm = new FormData();
 anonForm.append(
@@ -141,32 +140,22 @@ 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 carries a retention date", typeof anon?.data?.retainedUntil === "string");
 check("answer explains the terms", typeof anon?.message === "string" && anon.message.length > 0);
 
-if (anonCode && controlToken) {
+if (anonCode) {
   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");
+  check("anyone can update a document without password", (await changed.json().catch(() => null))?.resultCode === "200");
 
   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");
+  check("anyone can delete a document without password", (await removed.json().catch(() => null))?.resultCode === "200");
 }
 
 console.log(failures ? `\n${failures} failure(s)` : "\nall good");

package/server.json

@@ -1,8 +1,8 @@
 {
   "$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.4.0",
+  "description": "Publish Markdown as a shareable web page, with document graphs drawn beside the text",
+  "version": "2.5.0",
   "repository": {
     "url": "https://github.com/reinlainer/postmd-mcp-server",
     "source": "github"
@@ -11,7 +11,7 @@
     {
       "registryType": "npm",
       "identifier": "postmd-mcp-server",
-      "version": "2.4.0",
+      "version": "2.5.0",
       "transport": {
         "type": "stdio"
       },
@@ -24,7 +24,7 @@
         },
         {
           "name": "POSTMD_API_KEY",
-          "description": "Needed only for managing documents, attachments and groups. Publishing and reading work without it.",
+          "description": "Needed only for managing documents and groups. Publishing and reading work without it.",
           "isRequired": false,
           "isSecret": true
         },

package/src/server.js

@@ -32,13 +32,11 @@ const DEFAULT_BASE_URL = "https://postmd.turink.com";
 /** initialize 때 클라이언트에 전달되어, 모델이 도구를 고르기 전에 읽는다. */
 const INSTRUCTIONS_LOCAL =
   "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. " +
-  "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.";
+  "the HTTP API directly. Documents are kept for 30 days from publication or their last read. " +
+  "Documents without a password can be updated or deleted by anyone; password-protected " +
+  "documents require the password or the owner's API key. 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. What else the service can do, and which page describes it, is listed at https://postmd.turink.com/llms.txt — including graph data, which is carried inside the Markdown rather than through a tool.";
 
 /**
  * 원격에는 키를 건네줄 길이 없고 서버 기계에 사용자의 파일도 없다. 그래서 그 둘을 말하지
@@ -46,12 +44,11 @@ const INSTRUCTIONS_LOCAL =
  */
 const INSTRUCTIONS_REMOTE =
   "PostMD publishes Markdown as web pages. Use the postmd_* tools instead of calling " +
-  "the HTTP API directly. Nothing here needs an account, a sign-in or an API key. Pass " +
-  "the full Markdown in `markdown`. A successful create returns data.shareUrl - hand " +
-  "that URL to people. It 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 before then. It is shown once and cannot be reissued, so report it to the " +
-  "person along with the URL, and pass it back as `controlToken` to update or delete.";
+  "the HTTP API directly. Nothing here needs an account, a sign-in or an API key. " +
+  "Documents are kept for 30 days from publication or their last read. Documents without a " +
+  "password can be updated or deleted by anyone. If a document has a password, provide it to " +
+  "update or delete. Pass the full Markdown in `markdown`. A successful create returns " +
+  "data.shareUrl - hand that URL to people. What else the service can do, and which page describes it, is listed at https://postmd.turink.com/llms.txt - including graph data, which is carried inside the Markdown rather than through a tool.";
 
 /**
  * 원격에서 여는 도구. 자격 증명 없이 끝까지 가는 것만 남겼다 - 발행과 조회, 그리고 발행할
@@ -61,7 +58,7 @@ const INSTRUCTIONS_REMOTE =
  * 실패하고, `filePath` 를 받는 도구는 그 파일이 이 서버가 도는 기계에 없다.
  *
  * 목록에 적은 것만 열린다. 새 도구가 생겨도 여기 이름을 적기 전에는 원격으로 나가지
- * 않는다 - 반대로 두면 키가 필요한 도구가 조용히 딸려 나간다.
+ * 않는다. 반대로 두면 키가 필요한 도구가 의도치 않게 외부에 노출된다.
  */
 const REMOTE_TOOLS = new Set([
   "postmd_create_document",
@@ -141,10 +138,8 @@ function missingKey(ctx, scopes) {
   if (ctx.key) return null;
   if (ctx.remote) {
     return textErr(
-      "This server has no way to receive an API key. Pass `controlToken` instead — the " +
-        "token returned when the document was published, which is what an anonymous " +
-        "publisher uses to change or remove it. For the key-based tools, run the local " +
-        "server: npx -y postmd-mcp-server, with POSTMD_API_KEY set."
+      "This tool requires an API key, which cannot be passed to the remote server. " +
+        "Run the local server: npx -y postmd-mcp-server, with POSTMD_API_KEY set."
     );
   }
   return textErr(
@@ -219,17 +214,6 @@ async function readLocalFile(filePath) {
 }
 
 /** 첨부는 서버가 확장자로 받아 준다. 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",
-};
-
 /**
  * 만든 문서에는 나눠 줄 주소를 붙여 준다. 에이전트의 다음 행동이 바로 그것이다.
  *
@@ -254,7 +238,6 @@ function documentForm(a, markdownBuffer) {
   }
   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;
 }
@@ -267,10 +250,14 @@ async function createDocument(ctx, a, markdownBuffer) {
   return fromEnvelope(r);
 }
 
+function passwordHeader(a) {
+  const pwd = a.currentPassword ?? a.password;
+  return pwd ? { "X-Document-Password": String(pwd) } : {};
+}
+
 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.");
   }
@@ -291,18 +278,12 @@ async function updateDocument(ctx, a, markdownBuffer) {
   }
   const r = await apiFetch(ctx, `/documents/${encodeURIComponent(a.docCode)}/update`, {
     method: "POST",
-    headers: tokenHeader(a),
+    headers: passwordHeader(a),
     body: form,
   });
   return fromEnvelope(r);
 }
 
-/**
- * 익명 발행 문서의 제어 토큰 인자.
- *
- * 키를 대신하는 것이 아니라 그 문서 하나에만 듣는다. 그래서 키가 없어도 이 값이 있으면
- * 도구를 부를 수 있고, 키가 있어도 남의 익명 문서에는 이 값이 있어야 한다.
- */
 const NOTES_ON_REPLACE_PROP = {
   type: "string",
   enum: ["keep", "abort"],
@@ -314,35 +295,9 @@ const NOTES_ON_REPLACE_PROP = {
     "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." },
-  shareEndDate: {
-    type: "string",
-    description: "yyyyMMdd. The document stops being served after this date. Omit for no end date.",
-  },
   viewerStyle: {
     type: "string",
     description:
@@ -355,18 +310,21 @@ 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. 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).",
+      "Returns docCode and data.shareUrl; hand shareUrl to people. Documents have a " +
+      "30-day retention period (data.retainedUntil) that extends on each read. Documents " +
+      "without a password can be updated or deleted by anyone; password-protected documents " +
+      "require the password or the owner's API key. With an API key the document belongs to " +
+      "that member; groupId files it into that group (key with documents:write).",
+    annotations: { title: "Publish document", destructiveHint: false },
     inputSchema: {
       type: "object",
       properties: {
         markdown: {
           type: "string",
-          description: "Full Markdown document as one UTF-8 string (the entire source, not a summary).",
+          description:
+            "Full Markdown document as one UTF-8 string (the entire source, not a summary). " +
+            "May include graph data in an HTML comment, which the viewer draws beside the text; " +
+            "the format is at /docs/graph.",
         },
         title: {
           type: "string",
@@ -383,8 +341,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. " +
-      "Without an API key it returns data.controlToken and data.retainedUntil, same as above.",
+      "running this MCP server — use it for large files instead of pasting the body.",
+    annotations: { title: "Publish document from file", destructiveHint: false },
     inputSchema: {
       type: "object",
       properties: {
@@ -406,6 +364,7 @@ const TOOL_DEFS = [
       "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.",
+    annotations: { title: "Publish documents from files", destructiveHint: false },
     inputSchema: {
       type: "object",
       properties: {
@@ -423,10 +382,10 @@ const TOOL_DEFS = [
   {
     name: "postmd_get_document",
     description:
-      "Get document metadata by docCode: title, fileName, hasPassword, shareEndDate, " +
+      "Get document metadata by docCode: title, fileName, hasPassword, " +
       "viewerStyle, timestamps. Public — no API key needed. Content is not included; " +
       "use postmd_get_document_raw for the Markdown source.",
-    annotations: { readOnlyHint: true },
+    annotations: { title: "Get document info", readOnlyHint: true },
     inputSchema: {
       type: "object",
       properties: { docCode: { type: "string", description: "Document code, e.g. P-123-456-789." } },
@@ -437,8 +396,8 @@ const TOOL_DEFS = [
     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 },
+      "Password-protected documents need `password`.",
+    annotations: { title: "Get document source", readOnlyHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -451,26 +410,31 @@ const TOOL_DEFS = [
   {
     name: "postmd_update_document",
     description:
-      "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.",
+      "Update a document. Password-protected documents require the password or the owner's API key; " +
+      "documents without a password can be updated by anyone. Include `markdown` to replace " +
+      "the stored content; any metadata field replaces that field. clearPassword removes the password. " +
+      "Replacing the content requires notesOnReplace.",
+    annotations: { title: "Update document", destructiveHint: true },
     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.",
+          description:
+            "Full new Markdown body as one UTF-8 string. Omit if only metadata changes. " +
+            "Adding or revising a graph means sending the whole body with the graph comment in it; " +
+            "the format is at /docs/graph.",
         },
         title: { type: "string" },
         fileName: { type: "string", description: "Upload filename when replacing content. Default document.md." },
         ...DOC_META_PROPS,
+        currentPassword: {
+          type: "string",
+          description: "Current password to authenticate if the document is password-protected.",
+        },
         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"],
     },
@@ -479,7 +443,8 @@ 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. Takes `controlToken` the same way.",
+      "machine running this MCP server.",
+    annotations: { title: "Update document from file", destructiveHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -491,10 +456,12 @@ const TOOL_DEFS = [
         title: { type: "string" },
         fileName: { type: "string", description: "Upload filename. Defaults to the basename of filePath." },
         ...DOC_META_PROPS,
+        currentPassword: {
+          type: "string",
+          description: "Current password to authenticate if the document is password-protected.",
+        },
         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", "notesOnReplace"],
     },
@@ -502,33 +469,19 @@ const TOOL_DEFS = [
   {
     name: "postmd_delete_document",
     description:
-      "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" }, controlToken: CONTROL_TOKEN_PROP },
-      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.",
+      "Delete a document. Password-protected documents require the password or the owner's API key; " +
+      "documents without a password can be deleted by anyone.",
+    annotations: { title: "Delete document", destructiveHint: true },
     inputSchema: {
       type: "object",
       properties: {
-        filePath: {
+        docCode: { type: "string" },
+        password: {
           type: "string",
-          description: "Path to the file on the MCP server host. Prefer an absolute path.",
+          description: "Document password if the document has one and you are not authenticated as its owner.",
         },
-        fileName: { type: "string", description: "Upload filename. Defaults to the basename of filePath." },
       },
-      required: ["filePath"],
+      required: ["docCode"],
     },
   },
   {
@@ -538,7 +491,7 @@ const TOOL_DEFS = [
       "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 },
+    annotations: { title: "List notes on a document", readOnlyHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -557,6 +510,7 @@ const TOOL_DEFS = [
       "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.",
+    annotations: { title: "Add note or highlight", destructiveHint: false },
     inputSchema: {
       type: "object",
       properties: {
@@ -580,6 +534,7 @@ const TOOL_DEFS = [
       "Edit a note you wrote. Requires an API key with documents:write. Omitting scope " +
       "keeps the current one; a scope you do send follows the ownership rule above. The " +
       "note must keep text or a colour.",
+    annotations: { title: "Edit note", destructiveHint: false },
     inputSchema: {
       type: "object",
       properties: {
@@ -599,6 +554,7 @@ const TOOL_DEFS = [
       "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.",
+    annotations: { title: "Resolve or reopen note", destructiveHint: false },
     inputSchema: {
       type: "object",
       properties: {
@@ -614,6 +570,7 @@ const TOOL_DEFS = [
     description:
       "Delete a note: your own, or a SHARED note on a document you own. Requires an API " +
       "key with documents:write.",
+    annotations: { title: "Delete note", destructiveHint: true },
     inputSchema: {
       type: "object",
       properties: { docCode: { type: "string" }, noteId: { type: "number" } },
@@ -625,13 +582,13 @@ const TOOL_DEFS = [
     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 },
+    annotations: { title: "List my notes", 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 },
+    annotations: { title: "List groups", readOnlyHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -646,13 +603,11 @@ const TOOL_DEFS = [
     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 },
+    annotations: { title: "List documents in a group", 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",
@@ -667,15 +622,14 @@ const TOOL_DEFS = [
   {
     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.",
+      "Move a document you own into a group. A document belongs to exactly one group, so this " +
+      "replaces its current group. Requires an API key with documents:write.",
+    annotations: { title: "Move document to a group", destructiveHint: false },
     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"],
     },
@@ -683,13 +637,12 @@ const TOOL_DEFS = [
   {
     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.",
+      "Create a group. Requires an API key with groups:write. Documents can then be filed into it.",
+    annotations: { title: "Create group", destructiveHint: false },
     inputSchema: {
       type: "object",
       properties: {
         name: { type: "string" },
-        expireDate: { type: "string", description: "yyyyMMdd. The group stops working after this date." },
       },
       required: ["name"],
     },
@@ -697,15 +650,13 @@ const TOOL_DEFS = [
   {
     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.",
+      "Rename a group. Owner only. Requires an API key with groups:write.",
+    annotations: { title: "Update group", destructiveHint: false },
     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"],
     },
@@ -715,6 +666,7 @@ const TOOL_DEFS = [
     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.",
+    annotations: { title: "Delete group", destructiveHint: true },
     inputSchema: {
       type: "object",
       properties: { groupId: { type: "number" } },
@@ -757,7 +709,6 @@ async function runTool(ctx, name, args) {
         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 });
@@ -787,13 +738,9 @@ async function runTool(ctx, name, args) {
       }
     }
     case "postmd_update_document": {
-      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 = missingKeyUnlessToken(ctx, a, "documents:write");
-      if (denied) return denied;
       try {
         const { buffer, suggestedName } = await readLocalFile(a.filePath);
         return await updateDocument(ctx, { ...a, fileName: a.fileName ?? suggestedName }, buffer);
@@ -802,30 +749,12 @@ async function runTool(ctx, name, args) {
       }
     }
     case "postmd_delete_document": {
-      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),
+        headers: passwordHeader(a),
       });
       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;
@@ -907,8 +836,6 @@ async function runTool(ctx, name, args) {
       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,
@@ -921,7 +848,6 @@ async function runTool(ctx, name, args) {
       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" },
@@ -933,7 +859,6 @@ async function runTool(ctx, name, args) {
       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" },
@@ -946,8 +871,6 @@ async function runTool(ctx, name, args) {
       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" },