postmd-mcp-server 2.3.0 → 2.5.0

package/.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+.git
+.github
+.env
+.env.*
+*.log
+scripts
+README.md
+LICENSE

package/.github/workflows/publish.yml

@@ -0,0 +1,107 @@
+# 태그를 밀면 npm 과 MCP 레지스트리에 올린다.
+#
+# 두 곳 모두 토큰을 두지 않는다. GitHub 이 발급하는 단기 OIDC 토큰으로 인증한다.
+#
+#   npm            트러스티드 퍼블리셔. npmjs.com 의 패키지 설정에 이 저장소와 이 파일 이름을
+#                  한 번 등록해 두면 된다. 등록한 워크플로에서 온 요청만 받는다.
+#   MCP 레지스트리  io.github.<소유자> 네임스페이스는 그 소유자의 저장소에서 온 OIDC 토큰으로
+#                  증명된다. 별도 설정이 없다.
+#
+# 사람이 브라우저에서 승인하는 단계는 없다. 손으로 올리던 때는 npm 은 보안 키로 2차 인증을,
+# 레지스트리는 GitHub 기기 흐름 승인을 매번 요구했다.
+name: publish
+
+on:
+  push:
+    tags: ['v*']
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      # 두 곳의 인증이 모두 이 토큰으로 이루어진다.
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+
+      # 트러스티드 퍼블리싱은 npm 11.5.1 이상에서만 된다. 러너에 실린 판을 믿지 않는다.
+      - name: Use a recent npm
+        run: npm install -g npm@latest
+
+      # 세 곳의 버전이 어긋나면 레지스트리가 거절한다. 올리기 전에 여기서 잡는다.
+      - name: Versions must match the tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG=$(node -p "require('./package.json').version")
+          SRV=$(node -p "require('./server.json').version")
+          SRVPKG=$(node -p "require('./server.json').packages[0].version")
+          echo "tag=$TAG package.json=$PKG server.json=$SRV server.json/packages=$SRVPKG"
+          for v in "$PKG" "$SRV" "$SRVPKG"; do
+            if [ "$v" != "$TAG" ]; then
+              echo "::error::version mismatch — tag is $TAG"
+              exit 1
+            fi
+          done
+
+      - run: npm ci
+
+      - name: Syntax check
+        run: |
+          node --check src/index.js
+          node --check src/env.js
+          node --check scripts/smoke-test.mjs
+
+      # 이미 올라간 버전을 다시 올리면 npm 이 403 을 준다. 태그를 다시 밀거나 레지스트리
+      # 쪽만 다시 올려야 할 때 이 단계에서 멈추지 않도록 한다.
+      - name: Publish to npm
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          NAME=$(node -p "require('./package.json').name")
+          if npm view "$NAME@$VERSION" version > /dev/null 2>&1; then
+            echo "$NAME@$VERSION is already on npm — skipping"
+          else
+            npm publish --access public
+          fi
+
+      - name: Install mcp-publisher
+        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
+          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/.github/workflows/registry-status.yml

@@ -0,0 +1,47 @@
+# 레지스트리에 올라간 버전의 상태를 바꾼다. 손으로 돌린다.
+#
+# 잘못 올린 버전을 정리하는 데 쓴다. 레지스트리는 semver 가 가장 높은 것을 최신으로 보므로,
+# 실수로 올린 높은 번호를 그냥 두면 그것이 계속 최신으로 남는다.
+#
+# 인증은 발행과 같다. GitHub 이 발급하는 단기 OIDC 토큰이라 사람이 승인할 것이 없다.
+name: registry-status
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: '상태를 바꿀 버전 (예: 3.0.0)'
+        required: true
+      status:
+        description: '바꿀 상태'
+        required: true
+        default: deleted
+        type: choice
+        options: [active, deprecated, deleted]
+      message:
+        description: '이유. 레지스트리에 함께 남는다'
+        required: false
+        default: ''
+
+jobs:
+  status:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Install mcp-publisher
+        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
+
+      - name: Set the version status
+        run: |
+          NAME=$(node -p "require('./server.json').name")
+          ./mcp-publisher login github-oidc
+          ./mcp-publisher status \
+            --status "${{ inputs.status }}" \
+            --message "${{ inputs.message }}" \
+            "$NAME" "${{ inputs.version }}"

package/Dockerfile

@@ -0,0 +1,20 @@
+# 원격(streamable HTTP) 서버 이미지. stdio 로 쓰는 사람은 이 이미지가 필요 없다 —
+# npx 로 바로 돌아간다.
+FROM node:22-alpine
+
+WORKDIR /app
+
+# 의존성 먼저. 소스만 바뀔 때 이 층을 다시 받지 않는다.
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+COPY src ./src
+
+# 루트로 돌릴 이유가 없다. node 사용자는 베이스 이미지에 이미 있다.
+USER node
+
+ENV NODE_ENV=production
+ENV PORT=8080
+EXPOSE 8080
+
+CMD ["node", "src/http.js"]

package/README.md

@@ -1,21 +1,29 @@
 # 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.
+[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. 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.
 
-## Requirements
+## Hosted or local
 
-- **Node.js** 20 or later
-- Nothing else. An **API key** (`pmk_…`) only for the management tools.
+| | Hosted | Local |
+|---|---|---|
+| Address | `https://postmd.turink.com/mcp` | `npx -y postmd-mcp-server` |
+| Needs | nothing | Node.js 20 or later |
+| 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. Groups, notes and the tools that read a file from your disk are local-only.
 
 ## Configuration
 
-All variables are optional.
+Local only — the hosted server reads none of these. All are optional.
 
 | Variable | Description |
 |----------|-------------|
@@ -27,6 +35,9 @@ 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`, `postmd_update_document`, and `postmd_delete_document`.
+
 Publishing and reading — no key needed:
 
 | Tool | Purpose |
@@ -36,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
 
@@ -87,23 +109,40 @@ 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.
 
-## Quickstart
+## Client configuration
+
+### Hosted
 
-Nothing to install. `npx` fetches the package and the MCP client spawns it.
+Claude Code:
 
 ```bash
-npx -y postmd-mcp-server
+claude mcp add --transport http postmd https://postmd.turink.com/mcp
 ```
 
-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.
+Clients that take a JSON config:
 
-## Client configuration
+```json
+{
+  "mcpServers": {
+    "PostMD": {
+      "type": "http",
+      "url": "https://postmd.turink.com/mcp"
+    }
+  }
+}
+```
+
+In ChatGPT, add it under **Settings → Apps**; in claude.ai, under **Settings → Connectors**.
+There is nothing to authorize.
+
+### Local
+
+There is nothing to install: `npx` fetches the package and the client spawns it.
 
 Claude Code:
 
@@ -137,6 +176,9 @@ 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`.
 
+Running `npx -y postmd-mcp-server` by hand only checks that it starts. It speaks MCP over
+stdin and stdout, so it will sit there waiting for a client.
+
 ## Smoke test
 
 Runs the full write path against a live server and cleans up after itself. Needs a key with all four scopes.
@@ -146,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.3.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",
@@ -10,6 +10,7 @@
   },
   "scripts": {
     "start": "node src/index.js",
+    "start:http": "node src/http.js",
     "smoke": "node scripts/smoke-test.mjs"
   },
   "engines": {
@@ -24,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.3.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.3.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
         },
@@ -36,5 +36,11 @@
         }
       ]
     }
+  ],
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://postmd.turink.com/mcp"
+    }
   ]
 }

package/src/http.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+/**
+ * 원격 진입점. streamable HTTP 로 받는다.
+ *
+ * 웹에서 도는 클라이언트(ChatGPT, claude.ai)는 로컬 프로세스를 띄우지 못해 stdio 서버에
+ * 붙을 수 없다. 그쪽이 요구하는 것은 고정 HTTPS 주소 하나다.
+ *
+ * 도구는 `server.js` 가 갖고 있고 여기서 여는 것은 그중 자격 증명 없이 되는 다섯 개다
+ * (`REMOTE_TOOLS`). 그래서 이 서버에는 인증이 없다.
+ *
+ * 상태를 두지 않는다(stateless). 요청마다 서버와 전송을 새로 만들고 끝나면 버린다.
+ * 도구가 모두 API 한 번 부르고 끝나는 것이라 요청 사이에 이어 둘 것이 없고, 세션을 들면
+ * 그때부터 메모리에 남는 것이 생겨 컨테이너를 늘릴 때 붙는 자리가 된다.
+ */
+import http from "node:http";
+import process from "node:process";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createMcpServer, VERSION } from "./server.js";
+
+const PORT = Number(process.env.PORT || process.env.POSTMD_MCP_PORT || 8080);
+const MCP_PATH = "/mcp";
+
+/**
+ * 본문 상한. 문서 본문이 JSON 안에 실려 오므로 업로드 상한보다 넉넉해야 하지만, 열어
+ * 두면 아무나 부르는 자리에서 메모리를 밀어 넣을 수 있다. 실제 문서 크기 판정은 API 가
+ * 한다 - 여기는 그 앞의 거친 그물이다.
+ */
+const MAX_BODY = 8 * 1024 * 1024;
+
+function json(res, status, body) {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { "content-type": "application/json" });
+  res.end(payload);
+}
+
+const httpServer = http.createServer(async (req, res) => {
+  const url = new URL(req.url || "/", `http://${req.headers.host || "localhost"}`);
+
+  // 컨테이너와 프록시가 살아 있는지 보는 자리. MCP 와 무관하다.
+  if (url.pathname === "/health") {
+    return json(res, 200, { status: "ok", version: VERSION });
+  }
+
+  if (url.pathname !== MCP_PATH) {
+    return json(res, 404, {
+      error: `Not found. This server speaks MCP over streamable HTTP at ${MCP_PATH}.`,
+    });
+  }
+
+  const length = Number(req.headers["content-length"] || 0);
+  if (length > MAX_BODY) {
+    return json(res, 413, { error: "Request body too large." });
+  }
+
+  // 요청 하나에 서버 하나. 끝나면 둘 다 닫아 아무것도 남기지 않는다.
+  const server = createMcpServer({ remote: true });
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+
+  res.on("close", () => {
+    transport.close().catch(() => {});
+    server.close().catch(() => {});
+  });
+
+  try {
+    await server.connect(transport);
+    await transport.handleRequest(req, res);
+  } catch (e) {
+    process.stderr.write(`mcp request failed: ${e instanceof Error ? e.stack : e}\n`);
+    if (!res.headersSent) json(res, 500, { error: "Internal error." });
+  }
+});
+
+httpServer.listen(PORT, () => {
+  process.stdout.write(`postmd-mcp-server ${VERSION} — streamable HTTP on :${PORT}${MCP_PATH}\n`);
+});