plopino
Official# plopino
## CLI: publish with one command
```bash
npx -y plopino publish ./index.html
npx -y plopino publish ./dist --json
npx -y plopino login
npx -y plopino publish ./dist --update https://plopino.com/b/YOUR_BOARD_ID/
npx -y plopino whoami
npx -y plopino logout
```
`login` prompts for an email and a hidden password. Create an account on the website
first if needed. Login claims available anonymous uploads made with this CLI's saved
identity, reports how many were claimed, and saves a session for future uploads.
An existing `PLOPINO_TOKEN` overrides the saved session for publishing.
For Google/GitHub-only accounts, use an API token for future uploads; CLI password
login requires an account with a password.
Cookies are stored as unencrypted JSON per server origin under `~/.config/plopino/`.
The directory is created with mode `0700` and cookie files are written with `0600`;
this restricts access to your OS user but is not encryption. Override the directory with
`PLOPINO_CONFIG_DIR`.
Keep this directory to retain the ability to claim anonymous uploads. Passwords are
never stored. Logging out revokes the saved account session but preserves the anonymous
identity; log out before handing a shared OS account to someone else. Browser and MCP
sessions are separate: logging in on the website alone does not claim CLI uploads.
For non-interactive login, use `login --email you@example.com --password-stdin`, supplying
the password through standard input from your secret manager. Do not pass passwords as
command-line arguments. `--json` gives structured results and errors; errors exit with
status 1. Default publishing writes only the URL to stdout and status to stderr.
Both CLI and MCP directory uploads skip `.git`, `.env*`, `node_modules`, `.ssh`, `.aws`,
and symbolic links. Other files are included; publish the output directory you intend to
share. A single explicitly selected file is uploaded as requested, so never select
credentials or other secrets. Symlink inputs are rejected.
CLI commands for the same server cannot run concurrently; after a forcibly terminated
process, the next command identifies any stale lock to remove once no command is running.
For development before the npm release, replace `npx -y plopino` with
`node /path/to/boards/mcp/index.js` in the examples above.
## MCP
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 — or has a report / spreadsheet / markdown on disk
↓ publish_page / publish_path
https://plopino.com/b/xxxxxxxx/
```
Documents are first-class: Word (doc/docx), Excel (xls/xlsx) and Markdown
render as readable pages, code and data files get syntax-highlighted previews, and images
and video display inline. The recipient opens a link; they never download a file.
## Tools
| Tool | Use it when |
|---|---|
| `publish_page` | You have the content as a string — generated HTML, or a Markdown / CSV / code document. The `filename` decides how it renders: leave it at `index.html` for a page, pass `report.md` and it renders as a document. |
| `publish_path` | The page needs sibling files (CSS, JS, images), or you are sharing something that is already on disk — including any document, and including binary formats (docx, xlsx, pdf) that cannot be sent as a string. Point it at a directory and the structure is preserved — no need to zip first. |
| `publish_files` | Remote endpoint only. Same job as `publish_path` for clients that cannot hand over a local path: you send the file contents inline (a relative path plus its content, per entry). |
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; without a token the page is kept for a month, with a token it is permanent and
can be updated in place.
The stdio MCP server reuses the CLI's per-origin anonymous cookie in
`~/.config/plopino/` (override with `PLOPINO_CONFIG_DIR`). Repeated publishes and MCP restarts
therefore keep the same anonymous identity, and `plopino login` can claim those uploads. MCP
does not use the saved CLI login session; account publishing and updates still require
`PLOPINO_TOKEN`.
Anonymous creates also return `claimUrl`. It is a private browser link for the publisher:
open it yourself, sign in, and confirm the claim to keep that page in your account. Do not
append it to the public URL or share it with page viewers. JSON output includes it as
`claimUrl`; human output prints it on stderr for CLI publishes and inside the MCP tool result
for agent publishes.
## 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** — the panel hands you a ready-made command with the token
already in it (the server keeps an encrypted copy, so you can come back for it any time), 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
Also listed in the [official MCP registry](https://registry.modelcontextprotocol.io) as
`io.github.plopino/plopino-mcp`, and on [Smithery](https://smithery.ai/servers/plopino/plopino)
as an installable bundle.
### Claude Code plugin
This repository is also a Claude Code plugin marketplace:
```bash
claude plugin marketplace add plopino/plopino-mcp
claude plugin install plopino@plopino
```
The plugin connects to Plopino's remote MCP endpoint, so it works without a local Node
process. A token is optional; leave it empty to publish anonymously.
### OpenAI Codex / ChatGPT plugin
`codex-plugin/` is the OpenAI-format package and `.agents/plugins/marketplace.json` is
its Codex marketplace entry:
```bash
codex plugin marketplace add plopino/plopino-mcp
codex plugin add plopino@plopino
```
It uses the remote MCP endpoint with mixed authentication: anonymous by default, or
Plopino OAuth 2.1 (DCR + PKCE) for account publishing and in-place updates. The same
folder is the single-plugin-root package for the OpenAI directory ZIP submission.
### Claude Desktop extension
Download the latest [plopino.mcpb](https://github.com/plopino/plopino-mcp/releases/latest/download/plopino.mcpb),
then open it or drag it into Claude Desktop. This is the local stdio server, with an optional
`PLOPINO_TOKEN` in the extension settings.
**Anything that speaks stdio MCP works** — the server is a plain stdio process, so the only
difference between clients is how you register it. All of the below are the clients' own
documented forms (verified 2026-09). Wherever you see `plp_xxx`, paste a token from
**plopino.com/b** — the panel there fills it in for you and lets you pick your client.
If your client would rather not run a local process at all, skip to
[Remote endpoint](#remote-endpoint--nothing-to-install) — same tools, one URL.
**Claude Code**
```bash
claude mcp add plopino -e PLOPINO_TOKEN=plp_xxx -- npx -y plopino
```
**Codex** (CLI and IDE extension share `~/.codex/config.toml`)
```bash
codex mcp add plopino --env PLOPINO_TOKEN=plp_xxx -- npx -y plopino
```
**Gemini CLI**
```bash
gemini mcp add -e PLOPINO_TOKEN=plp_xxx plopino npx -y plopino
```
**WorkBuddy** — `~/.workbuddy/mcp.json` (`%USERPROFILE%\.workbuddy\mcp.json` on Windows;
needs WorkBuddy 5.3+), then restart WorkBuddy:
```json
{
"mcpServers": {
"plopino": {
"command": "npx",
"args": ["-y", "plopino"],
"env": { "PLOPINO_TOKEN": "plp_xxx" }
}
}
}
```
**Cursor** — the same JSON in `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global).
**Windsurf** — the same JSON in `~/.codeium/windsurf/mcp_config.json`.
**Claude Desktop** — the same JSON in `claude_desktop_config.json`.
**VS Code** — same idea in `.vscode/mcp.json`, but the key is `servers`, not `mcpServers`:
```json
{
"servers": {
"plopino": {
"command": "npx",
"args": ["-y", "plopino"],
"env": { "PLOPINO_TOKEN": "plp_xxx" }
}
}
}
```
**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.
Then just ask: *"publish this to Plopino"*, or *"give me a link for that page"*.
## Remote endpoint — nothing to install
Everything above runs on your machine. There is also a **hosted Streamable HTTP endpoint**
serving the same tools, for clients that support remote MCP servers and would rather not run
a local process at all:
```
https://plopino.com/mcp
```
```bash
claude mcp add --transport http plopino https://plopino.com/mcp
```
Any client that accepts a remote server URL takes that same address. Authentication works the
same way: send a token as `Authorization: Bearer plp_xxx` if you have one, and publish
anonymously if you don't.
Two differences from the stdio build, both deliberate:
- **`publish_path` is not available remotely.** It takes a path on the machine the server
runs on — which, remotely, is not your machine. Use `publish_files` and send the contents.
- The endpoint is stateless: each request is handled on its own, no session to keep alive.
## Self-hosted / local
The instance the server publishes to defaults to `https://plopino.com`. Set `PLOPINO_BASE_URL`
to point at another one — a staging host, or your own deployment:
```bash
PLOPINO_BASE_URL=https://plopino.com npx -y plopino
```
## Requirements
- Node 20 or newer (required by the MCP TypeScript SDK v2).
- The only runtime dependency is the MCP SDK.
## Development
```bash
npm install
npm test # 路径展开的边界 + 协议握手/工具列表(不需要网络)
```
To exercise the full publish path, run a Plopino instance and drive the server over stdio
against it:
```bash
PLOPINO_BASE_URL=https://plopino.com 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`.
## Privacy Policy
### Optional acquisition labels
If you want to tell Plopino which tutorial introduced the tool, set
`PLOPINO_ACQUISITION_SOURCE` (for example `devto`), optionally with
`PLOPINO_ACQUISITION_CAMPAIGN` and `PLOPINO_ACQUISITION_CONTENT`.
These labels are sent with publish requests and stored separately from browser
referrals, with their capture time. They do not affect publishing or login.
Use only letters, digits, underscores and hyphens, at most 64 characters;
start with a letter or digit. Do not put secrets, URLs or personal data in labels.
Leave them unset to send no acquisition labels. Supported by CLI and stdio MCP.
Full policy: **https://plopino.com/privacy**
- **What is collected.** Optional acquisition labels are described above. Publishing sends the file contents and file names you
pass to a tool, the destination URL, and — for anonymous publishes — the requesting IP
address (used for the daily rate limit). The MCP server itself collects nothing and sends
no background telemetry; it runs locally and logs only to stderr. Anonymous publishing writes the local
identity cookie described above.
- **How it is used and stored.** Uploaded content is stored on Plopino's servers and served
from the returned public link. A `PLOPINO_TOKEN` is stored locally in your MCP client
configuration; the server keeps only its SHA-256 hash.
- **Third parties.** No content or usage data is sold, shared or sent to third parties for
advertising. Plopino uses Cloudflare as its CDN/reverse proxy and self-hosted Umami for
aggregate, cookieless visit counts.
- **Retention.** Anonymous uploads are deleted after **30 days**; a link can also be removed
earlier from the account page. Uploads made with a token are kept until you delete them
or the account is closed. Request deletion or report abuse at **abuse@plopino.com**.
- **Contact.** abuse@plopino.com (abuse and privacy requests), or https://plopino.com/abuse.
## 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.
TDQS
Scored across 2 tools
The split is clear in principle: publish_page takes in-hand content, publish_path takes a local file or directory. However, the descriptions overlap substantially — both claim to handle HTML, Markdown, code, and data files — which could make an agent hesitate over which to pick when content already exists as a local file.
Both tools follow the same verb_noun pattern (publish_page, publish_path) with a shared prefix that signals a common action family. Fully predictable and readable.
Two tools is on the thin side, but the server has a narrow, well-defined purpose (publishing artifacts to a public URL), and each tool covers a genuinely different input shape. Neither feels redundant.
The surface covers publishing but stops there: no update, list, or delete/unpublish operation, despite descriptions mentioning that token-backed pages can be updated in place and storage managed. An agent that wants to refresh or revoke a link has no tool for it.