plopino 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plopino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# plopino
+
+MCP server for [Plopino](https://plopino.com) — lets an AI agent publish what it just built
+and hand back a public link, without the user touching a browser.
+
+```
+agent writes index.html
+   ↓  publish_html / publish_path
+https://plopino.com/b/xxxxxxxx/
+```
+
+## Tools
+
+| Tool | Use it when |
+|---|---|
+| `publish_html` | You have the page as a string. The most direct path for generated HTML. |
+| `publish_path` | The page needs sibling files (CSS, JS, images), or you are sharing something that is already on disk. Point it at a directory and the structure is preserved — no need to zip first. |
+
+Both take an optional `update_url`: pass a link returned by an earlier publish and that page's
+content is replaced **while the link stays the same**. This needs a token (see below).
+
+Publishing is **anonymous by default**: no account, no configuration, no API key. The returned
+link is public and permanent.
+
+## Authentication (optional)
+
+Set `PLOPINO_TOKEN` to publish to your account instead of anonymously. You get private
+boards, updates that keep the same link, and you are not subject to the anonymous rate limit.
+
+Create a token at **plopino.com/b** (it is shown once — the server only stores a hash), then:
+
+```bash
+claude mcp add plopino --env PLOPINO_TOKEN=plp_xxx -- npx -y plopino
+```
+
+**Leaving it unset is a supported configuration, not a degraded one.** Most users never need
+a token — the anonymous flow is the product.
+
+## Install
+
+
+**Claude Code**
+
+```bash
+claude mcp add plopino -e PLOPINO_TOKEN=plp_xxx -- npx -y plopino
+```
+
+**No npm?** The server also ships as a single self-contained file on the site. Two lines
+instead of one, but nothing to install:
+
+```bash
+curl -fsSL https://plopino.com/plopino-mcp.mjs -o "$HOME/.plopino-mcp.mjs"
+claude mcp add plopino -e PLOPINO_TOKEN=plp_xxx -- node "$HOME/.plopino-mcp.mjs"
+```
+
+> `"$HOME/…"` is expanded by your shell as you paste, so the absolute path is what gets
+> registered. That matters: MCP clients spawn the server from an arbitrary working
+> directory, so a relative path would break.
+
+**Claude Desktop** — add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "plopino": { "command": "npx", "args": ["-y", "plopino"] }
+  }
+}
+```
+
+**Cursor** — add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "plopino": { "command": "npx", "args": ["-y", "plopino"] }
+  }
+}
+```
+
+Then just ask: *"publish this to Plopino"*, or *"give me a link for that page"*.
+
+## Self-hosted / local
+
+Set `PLOPINO_BASE_URL` to point at another instance:
+
+```bash
+PLOPINO_BASE_URL=http://127.0.0.1:8787 npx -y plopino
+```
+
+## Requirements
+
+- Node 18 or newer (uses the built-in `fetch`, `FormData` and `Blob`).
+- The only runtime dependency is the MCP SDK.
+
+## Development
+
+```bash
+npm install
+npm test        # 路径展开的边界 + 协议握手/工具列表（不需要网络）
+```
+
+To exercise the full publish path, run a Plopino instance locally and drive the server
+over stdio:
+
+```bash
+PLOPINO_BASE_URL=http://127.0.0.1:8787 node index.js
+```
+
+> **stdout is the MCP protocol channel.** Anything written there that is not a JSON-RPC
+> message will break the client. All logging must go to stderr — hence `console.error`
+> everywhere and never `console.log`.
+
+## Notes
+
+- `publish_path` walks directories recursively and **skips symbolic links** — following
+  them could escape the directory tree and upload files from elsewhere on the machine.
+- Anonymous uploads are rate-limited per IP by the server side.
+- Nothing is uploaded until a tool is called; the server does no network I/O at startup.

package/index.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+// Plopino MCP server（stdio）。
+//
+// 让 agent 自己把产出发布出去：用户说一句"发布这个"，agent 调这里的工具，
+// 拿回一个公开链接。用户不需要知道 plopino.com 怎么用——这正是它作为分发渠道的价值。
+//
+// 认证是**可选**的：不配 PLOPINO_TOKEN 就匿名发布（免注册是这个产品的卖点之一），
+// 配了就发到账号下——可私有、可更新（同一个链接换内容）、不受匿名限流。
+//
+// ⚠️ stdout 是 MCP 协议通道，绝不能往里写日志。任何调试输出都走 stderr
+//（console.error），否则会污染协议、让客户端解析失败。
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { publishFiles, filesFromHtml, filesFromPath, boardIdFromUrl, DEFAULT_BASE } from './upload.js';
+
+// 自建实例或本地验证时覆盖。默认走正式站。
+const BASE = process.env.PLOPINO_BASE_URL || DEFAULT_BASE;
+// 在 plopino.com/b 生成（服务端只存哈希，明文只显示一次）
+const TOKEN = (process.env.PLOPINO_TOKEN || '').trim();
+
+const server = new McpServer({ name: 'plopino', version: '0.1.0' });
+
+// 工具描述是给**模型**看的，不是给人看的——要写清楚「什么时候该用」，
+// 否则模型不知道有这个能力，集成了也不会被调用。
+const ok = (url, note) => ({ content: [{ type: 'text', text: `${url}\n\n${note}` }] });
+const fail = (err) => ({
+  content: [{ type: 'text', text: `Could not publish: ${err?.message || err}` }],
+  isError: true,
+});
+
+const UPDATE_PARAM = z.string().optional().describe(
+  'A URL returned by an earlier publish. When given, the content of that page is replaced '
+  + 'and the link stays the same. Requires the server to be configured with a Plopino token.',
+);
+
+// update_url 给了就走更新。没有 token 时更新必被服务端拒（401），
+// 与其让用户看到 authentication 报错，不如在这里说清楚缺什么。
+function resolveTarget(updateUrl) {
+  if (!updateUrl) return { boardId: null };
+  if (!TOKEN) {
+    throw new Error(
+      'Updating an existing page requires a Plopino token. '
+      + 'Create one at plopino.com/b and set PLOPINO_TOKEN in this server\'s environment.',
+    );
+  }
+  const boardId = boardIdFromUrl(updateUrl);
+  if (!boardId) throw new Error(`Not a Plopino page URL: ${updateUrl}`);
+  return { boardId };
+}
+
+server.registerTool('publish_html', {
+  title: 'Publish an HTML page and get a link',
+  description:
+    'Publish an HTML page to a public URL. Use this whenever the user asks to share, send, '
+    + 'publish, or "give me a link to" a page — for example a dashboard, report, chart, or '
+    + 'interactive page you just generated. Returns a permanent public link that opens on any '
+    + 'device. No account or configuration needed. Prefer this over telling the user to save '
+    + 'the file and upload it somewhere themselves.',
+  inputSchema: {
+    html: z.string().describe('The complete HTML document to publish, including the <html> tag.'),
+    update_url: UPDATE_PARAM,
+  },
+}, async ({ html, update_url: updateUrl }) => {
+  try {
+    const { boardId } = resolveTarget(updateUrl);
+    const data = await publishFiles(filesFromHtml(html), { baseUrl: BASE, token: TOKEN, boardId });
+    return ok(data.url, boardId
+      ? 'Updated — the link is unchanged.'
+      : 'Public and permanent. Anyone with this link can open it.');
+  } catch (err) {
+    return fail(err);
+  }
+});
+
+server.registerTool('publish_path', {
+  title: 'Publish a local file or folder and get a link',
+  description:
+    'Publish a local file, a zip, or a whole directory to a public URL, preserving the '
+    + 'directory structure. Use this when the page needs sibling files (CSS, JS, images) — '
+    + 'write them into a directory first, then publish that directory. Also use it for '
+    + 'non-HTML files the user wants to share (Markdown, images, PDF, Office documents).',
+  inputSchema: {
+    path: z.string().describe('Absolute path to a file or directory on this machine.'),
+    update_url: UPDATE_PARAM,
+  },
+}, async ({ path: p, update_url: updateUrl }) => {
+  try {
+    const { boardId } = resolveTarget(updateUrl);
+    const files = await filesFromPath(p);
+    const data = await publishFiles(files, { baseUrl: BASE, token: TOKEN, boardId });
+    return ok(data.url, boardId
+      ? `Updated with ${files.length} file${files.length > 1 ? 's' : ''} — the link is unchanged.`
+      : `Published ${files.length} file${files.length > 1 ? 's' : ''}. Public and permanent.`);
+  } catch (err) {
+    return fail(err);
+  }
+});
+
+await server.connect(new StdioServerTransport());

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "plopino",
+  "version": "0.1.0",
+  "description": "MCP server: publish an HTML page, a file, or a folder to Plopino and get a public URL.",
+  "type": "module",
+  "bin": {
+    "plopino": "index.js"
+  },
+  "files": [
+    "index.js",
+    "upload.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AILogbook/boards.git",
+    "directory": "mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.6.5"
+  },
+  "scripts": {
+    "test": "node --test",
+    "build": "esbuild index.js --bundle --platform=node --format=esm --target=node18 --outfile=dist/plopino-mcp.mjs --log-level=warning"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.2"
+  }
+}

package/upload.js

@@ -0,0 +1,72 @@
+// 与 Plopino 上传接口的对接。只用 Node 内置的 fetch / FormData / Blob（Node 18+ 自带），
+// 所以这个包除了 MCP SDK 之外没有别的运行时依赖。
+
+import { readFile, readdir, stat } from 'node:fs/promises';
+import path from 'node:path';
+
+export const DEFAULT_BASE = 'https://plopino.com';
+
+// 上传一组文件，返回展板 JSON（含链接）。
+// files: [{ name, data }]，name 是**相对路径**——接口按它还原目录结构，
+// 所以目录上传不需要先打包成 zip。
+//
+// token 给了就走认证（展板归到账号下，可私有、可更新、不受匿名限流）；
+// 不给就匿名发布。**认证是可选的**——"不用注册"是这个产品的卖点之一，
+// 不能因为接了 MCP 就把它变成必须品。
+// boardId 给了就是**更新已有展板**（链接不变），只有认证用户能做。
+export async function publishFiles(files, { baseUrl = DEFAULT_BASE, token = '', boardId = null, fetchImpl = fetch, signal } = {}) {
+  const form = new FormData();
+  for (const f of files) form.append('file', new Blob([f.data]), f.name);
+  const route = boardId
+    ? `/api/boards/${encodeURIComponent(boardId)}/upload`
+    : '/api/boards/upload';
+  const res = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}${route}`, {
+    method: 'POST',
+    headers: token ? { Authorization: `Bearer ${token}` } : undefined,
+    body: form,
+    signal,
+  });
+  const text = await res.text();
+  let data = null;
+  try { data = JSON.parse(text); } catch { /* 非 JSON 响应（如反代错误页） */ }
+  // 新建时链接在顶层，更新时在 board 里——统一取一次，调用方不必知道这个差别
+  const url = data?.url || data?.board?.url;
+  if (!res.ok || !url) {
+    throw new Error(data?.error || `Upload failed (HTTP ${res.status})`);
+  }
+  return { ...data, url };
+}
+
+// 从之前返回的链接里取出展板 id。agent 手里通常只有 URL、没有 id，
+// 所以更新入口收 URL 比收 id 自然。服务端仍会校验归属，猜来的 id 只会 404。
+export function boardIdFromUrl(url) {
+  const m = /\/b\/([A-Za-z0-9_-]+)/.exec(String(url ?? ''));
+  return m ? m[1] : null;
+}
+
+// 一个 HTML 字符串 → 单文件展板。文件名固定 index.html，展板根链接才能直接渲染它。
+export function filesFromHtml(html) {
+  return [{ name: 'index.html', data: Buffer.from(html, 'utf8') }];
+}
+
+// 本地路径 → 文件列表。目录递归展开，name 取相对路径。
+export async function filesFromPath(input) {
+  const abs = path.resolve(input);
+  const st = await stat(abs); // 路径不存在时抛出原始错误，比"上传失败"可诊断
+  if (st.isFile()) return [{ name: path.basename(abs), data: await readFile(abs) }];
+  if (!st.isDirectory()) throw new Error(`Not a file or directory: ${input}`);
+
+  const out = [];
+  async function walk(dir, prefix) {
+    for (const e of await readdir(dir, { withFileTypes: true })) {
+      const rel = prefix ? `${prefix}/${e.name}` : e.name;
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) await walk(full, rel);
+      // 符号链接直接跳过：跟随可能绕出目录树，上传过去也没有意义
+      else if (e.isFile()) out.push({ name: rel, data: await readFile(full) });
+    }
+  }
+  await walk(abs, '');
+  if (!out.length) throw new Error(`Directory is empty: ${input}`);
+  return out;
+}