postmd-mcp-server 2.3.0 → 2.4.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,80 @@
+# 태그를 밀면 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
+
+      - name: Publish to the MCP registry
+        run: |
+          ./mcp-publisher login github-oidc
+          ./mcp-publisher publish

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,30 @@
 # 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. Optional groups, document passwords, share expiry and viewer themes. This server wraps PostMD's public API (`/api/v1`) so assistants can publish, read, update and organize documents.
 
-**Publishing needs no account and no key.** With zero configuration this server can already turn Markdown into a shareable page. An API key adds management: updating and deleting your documents, attachments, and groups.
+**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.
 
 **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
+## 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 21 |
+| API key | not accepted | optional, for the management 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.
 
 ## Configuration
 
-All variables are optional.
+Local only — the hosted server reads none of these. All are optional.
 
 | Variable | Description |
 |----------|-------------|
@@ -27,6 +36,10 @@ 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`.
+
 Publishing and reading — no key needed:
 
 | Tool | Purpose |
@@ -92,18 +105,35 @@ Groups — key with `groups:read` / `groups:write`:
 
 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
 
-Nothing to install. `npx` fetches the package and the MCP client spawns it.
+### Hosted
+
+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 +167,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postmd-mcp-server",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "MCP server for PostMD — publish Markdown, get a shareable web page",
   "mcpName": "io.github.reinlainer/postmd-mcp-server",
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "scripts": {
     "start": "node src/index.js",
+    "start:http": "node src/http.js",
     "smoke": "node scripts/smoke-test.mjs"
   },
   "engines": {

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.3.0",
+  "version": "2.4.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.4.0",
       "transport": {
         "type": "stdio"
       },
@@ -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`);
+});