{
  "markdown": "# sharedoc-mcp\n\n> **Agent-generated Markdown → a link you can hand to anyone. GitHub gists today, your own server tomorrow.**\n\nEnglish | [繁體中文](./README.zh-TW.md)\n\n[![npm](https://img.shields.io/npm/v/sharedoc-mcp?color=brightgreen)](https://www.npmjs.com/package/sharedoc-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/sharedoc-mcp?color=brightgreen)](https://www.npmjs.com/package/sharedoc-mcp)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.AugustusW%2Fsharedoc--mcp-orange)](https://registry.modelcontextprotocol.io/v0/servers?search=sharedoc)\n[![Release](https://img.shields.io/github/v/release/AugustusW/sharedoc-mcp?color=brightgreen)](https://github.com/AugustusW/sharedoc-mcp/releases)\n[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%E2%89%A522.13-blue.svg)](https://nodejs.org/)\n[![MCP](https://img.shields.io/badge/MCP-stdio%20server-orange.svg)](https://modelcontextprotocol.io/)\n[![Claude Code](https://img.shields.io/badge/Claude%20Code-compatible-orange.svg)](https://claude.com/claude-code)\n[![Codex](https://img.shields.io/badge/Codex-compatible-black.svg)](https://developers.openai.com/codex/)\n\n[![Add to Cursor](https://img.shields.io/badge/Cursor-Add_MCP_Server-1a1a1a?logo=cursor&logoColor=white)](https://cursor.com/install-mcp?name=sharedoc&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNoYXJlZG9jLW1jcEBeMiJdfQ%3D%3D)\n[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP_Server-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=sharedoc&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22sharedoc-mcp%40%5E2%22%5D%7D)\n\nAn [MCP](https://modelcontextprotocol.io/) stdio server — works in [Claude Code](https://claude.com/claude-code), Codex CLI, and any MCP client — that gives your agent **9 tools to publish, update, search, and revoke shareable documents**. Two pluggable backends behind one interface: **gist** (zero setup, rides your logged-in `gh` CLI) and **selfhost** (SQLite on your machine, passwords, enforced expiry).\n\n> When a backend can't honor a parameter (e.g. `password` on gist), it returns a clear error instead of silently ignoring it.\n\n## Why?\n\nAI agents produce Markdown constantly — reports, research digests, meeting notes. Getting that to another human usually means copy-pasting walls of text into a chat window.\n\n```text\nWithout sharedoc-mcp                  With sharedoc-mcp\n────────────────────                  ─────────────────\ncopy a wall of text into chat         \"share this as a doc\"\npaste again for each person           one link for everyone\ncontent lives in chat scroll          revoke / extend / append later\n\"can you password it?\"  …no           selfhost backend: bcrypt + expiry\n```\n\n> Where do those Markdown digests come from? Often another skill — e.g.\n> [audio-tldr](https://github.com/AugustusW/audio-tldr-skill) turns videos and podcasts into\n> Markdown digests; sharedoc-mcp turns them into links.\n\n## Features\n\n- ✓ 9 MCP tools: create / append / update content / extend / reset password / rename / revoke / delete / search\n- ✓ `sharedoc-mcp serve` daemon mode — selfhost links keep working after your MCP client closes\n- ✓ Content search: find old share links by what's in them, not just the title\n- ✓ `GET /healthz` — identity-aware health probe for external monitoring / restart automation\n- ✓ Two backends, one interface — switch with a single env var, tool schemas stay identical\n- ✓ **Gist backend** (default): secret gists via your logged-in `gh` CLI — no tokens to manage, nothing new to host\n- ✓ **Selfhost backend**: docs stay on your machine (SQLite via built-in `node:sqlite` — zero native modules)\n- ✓ Server-verified passwords (bcrypt) with rate-limited attempts — 5/minute, HTTP 429, counters persisted in SQLite so a restart can't reset them (selfhost)\n- ✓ Enforced expiry (410) and revoke with a 7-day content-purge grace (selfhost); lazy expiry cleanup (gist)\n- ✓ Markdown rendered through `marked` + `sanitize-html` — scripts, event handlers, and `javascript:` URLs in shared content are stripped\n- ✓ Viewer binds **127.0.0.1 only**, answers with a strict security-header set (CSP `default-src 'none'`, nosniff, DENY framing, no-referrer, no-store) — exposure is a tunnel you control (recipes below)\n- ✓ Local index for `search_shared_docs` + create dedup (identical unprotected retries within 5 min return the same URL; a retry that adds a password/expiry always creates a new doc)\n- ✓ `search_shared_docs` supports offset pagination (`hasMore` in the response) and, on selfhost, view stats (`viewCount`/`lastViewedAt`, counted on a successful render only)\n- ✓ [Docker](#docker) one-liner for the standalone `serve` daemon, defaults to the same 127.0.0.1-only binding as everywhere else\n- ✓ Two MCP clients can share one data dir: SQLite WAL + busy timeout, graceful port sharing\n- ✓ 110 offline tests; `npm test` passes on a clean checkout\n\n## Install\n\nRequires Node.js ≥ 22.13.0. Gist backend additionally needs [GitHub CLI](https://cli.github.com) logged in (`gh auth login`).\n\n**Option A — Claude Code (one line):**\n\n```bash\nclaude mcp add sharedoc --scope user -- npx -y sharedoc-mcp@^2\n```\n\n**Option B — Codex CLI** (`~/.codex/config.toml`):\n\n```toml\n[mcp_servers.sharedoc]\ncommand = \"npx\"\nargs = [\"-y\", \"sharedoc-mcp@^2\"]\n```\n\n**Option C — Cursor (one click):** hit [**Add to Cursor**](https://cursor.com/install-mcp?name=sharedoc&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsInNoYXJlZG9jLW1jcEBeMiJdfQ%3D%3D), or merge into `~/.cursor/mcp.json`:\n\n```json\n{ \"mcpServers\": { \"sharedoc\": { \"command\": \"npx\", \"args\": [\"-y\", \"sharedoc-mcp@^2\"] } } }\n```\n\n**Option D — VS Code (one click):** hit [**Install in VS Code**](https://vscode.dev/redirect/mcp/install?name=sharedoc&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22sharedoc-mcp%40%5E2%22%5D%7D), or from a terminal:\n\n```bash\ncode --add-mcp '{\"name\":\"sharedoc\",\"command\":\"npx\",\"args\":[\"-y\",\"sharedoc-mcp@^2\"]}'\n```\n\n**Option E — any other MCP client:** run `npx -y sharedoc-mcp@^2` as a stdio server.\n\n> **Why `@^2`?** A bare `npx -y sharedoc-mcp` resolves the **latest published version** on every cold start — a future 3.0 could change behavior (or remove a tool) under you without warning. `@^2` follows 2.x fixes but never crosses a breaking major; pin an exact version (`@2.2.0`) if you want zero drift.\n\n## Pick your backend\n\n| | 🅰 `gist` (default) | 🅱 `selfhost` |\n|---|---|---|\n| Setup | none — uses your logged-in `gh` CLI | none extra — data stays on your machine |\n| Doc lives on | GitHub (secret gist) | your machine (SQLite) |\n| Link reachable | anywhere, immediately | localhost — add a tunnel to share externally |\n| Password | ✗ (the secret URL is the protection) | ✓ server-verified (bcrypt), rate-limited |\n| Expiry | lazy — expired gists deleted on next use | enforced — expired links return 410 |\n| Revoke | gist deleted immediately, irreversibly | immediate 410, content purged after 7-day grace |\n| View stats | ✗ (GitHub's gist API exposes no view-count data) | ✓ viewCount + lastViewedAt, counted on a successful render only |\n\n### Gist quickstart\n\nAsk your agent to \"share this as a doc\" — it calls `create_shared_doc` and returns a secret gist URL. Secret gists are not listed publicly and the URL is unguessable, but **anyone who has the link can read it** — that's the whole security model of this backend. Need passwords? Use `selfhost`.\n\nA local index (`~/.config/sharedoc-mcp/index.json`) tracks what you've shared, powering search and expiry cleanup. Expiry here is *lazy*: expired gists are deleted the next time any tool runs, not at the exact expiry moment.\n\n### Selfhost quickstart\n\n```bash\nclaude mcp add sharedoc --scope user --env SHAREDOC_BACKEND=selfhost -- npx -y sharedoc-mcp@^2\n```\n\nDocs live in SQLite at `~/.local/share/sharedoc-mcp/`; a viewer serves them at `http://127.0.0.1:8377`. To share beyond your machine, put a tunnel in front and set `SHAREDOC_PUBLIC_URL`:\n\n> **Links that outlive your editor:** in MCP mode the viewer dies with the MCP client — close Claude Code and selfhost links stop answering until the next session (data is safe in SQLite). Run the standalone daemon to keep links alive around the clock:\n>\n> ```bash\n> npx -y sharedoc-mcp@^2 serve   # viewer only, same DB — keep it running via launchd/systemd/tmux (Windows: Task Scheduler or NSSM)\n> ```\n>\n> MCP clients detect the daemon already owns the port and simply use it.\n>\n> **When to set this up:** the moment you first hand a link to someone else — do it together\n> with your tunnel (both should be long-running, e.g. under launchd/systemd). Until then the\n> MCP-mode viewer is enough, and gist-backend users never need it.\n\n| Recipe | Fits you if | Setup |\n|---|---|---|\n| **Tailscale private** (recommended) | recipients are your own devices / people you can invite to your tailnet | `tailscale serve --bg 8377` → `https://<machine>.<tailnet>.ts.net`, reachable **only inside your tailnet** — nothing is exposed to the public internet |\n| **Tailscale Funnel** | share with anyone, no domain | `tailscale funnel 8377` → same stable URL, but public |\n| **Cloudflare named tunnel** | you own a domain | domain on Cloudflare, `cloudflared tunnel create` + route a hostname to `http://127.0.0.1:8377` |\n| **cloudflared quick tunnel** | one-off sharing | `cloudflared tunnel --url http://127.0.0.1:8377` → random URL, changes every restart |\n\n#### Own a domain? Cloudflare named tunnel, step by step\n\nA branded, stable share URL like `https://docs.example.com/docs/<uuid>` — TLS handled by Cloudflare, works from behind NAT:\n\n```bash\n# one-time setup (domain already added to Cloudflare — the free plan is enough)\ncloudflared tunnel login\ncloudflared tunnel create sharedoc\ncloudflared tunnel route dns sharedoc docs.example.com\n```\n\n`~/.cloudflared/config.yml`:\n\n```yaml\ntunnel: sharedoc\ncredentials-file: ~/.cloudflared/<tunnel-id>.json\ningress:\n  - hostname: docs.example.com\n    service: http://127.0.0.1:8377\n  - service: http_status:404\n```\n\nRun `cloudflared tunnel run sharedoc` (or install it as a service for always-on), and register the MCP server with the public URL:\n\n```bash\nclaude mcp add sharedoc --scope user \\\n  --env SHAREDOC_BACKEND=selfhost \\\n  --env SHAREDOC_PUBLIC_URL=https://docs.example.com \\\n  -- npx -y sharedoc-mcp\n```\n\nExtras this unlocks: Cloudflare's DDoS protection comes free; you can layer WAF rules, or put [Cloudflare Access](https://www.cloudflare.com/zero-trust/products/access/) (SSO) in front of everything except the share paths — an \"SSO inside, password-protected shares outside\" split.\n\n**Alternative — always-on without a home machine:** run sharedoc-mcp on a VPS (where your agent also runs) and point nginx/caddy at `127.0.0.1:8377` with your domain and auto-TLS; no tunnel needed.\n\n#### Docker\n\nRuns the same standalone `serve` daemon as above, in a container:\n\n```bash\ndocker build -t sharedoc-mcp .\ndocker run -d --name sharedoc \\\n  -p 8377:8377 \\\n  -e SHAREDOC_BIND_HOST=0.0.0.0 \\\n  -v sharedoc-data:/data \\\n  sharedoc-mcp\n```\n\n- `-v sharedoc-data:/data` persists `docs.db` in a named volume — recreating the container keeps your docs.\n- **`SHAREDOC_BIND_HOST=0.0.0.0` is required to reach the container at all.** The viewer binds `127.0.0.1` by default — same as every other deployment in this README — and inside a container that's unreachable through `docker run -p`, because `-p` forwards to the container's network interface, not its loopback. Without this env var, `docker logs` will show the viewer listening, but the mapped host port will refuse every connection.\n- Setting it to `0.0.0.0` means **any process that can reach the container's exposed port reaches the viewer, unauthenticated by network position** — the same exposure tradeoff as running any other unauthenticated app in a container without a proxy in front. Put it behind the same kind of front door as any other selfhost recipe above (a reverse proxy on the host, a Tailscale sidecar, a Cloudflare tunnel) rather than publishing `-p 8377:8377` straight to the internet. Password-protecting individual docs (this backend's built-in feature) is not a substitute for that.\n- If the address recipients will use differs from `http://<host>:8377` (a reverse proxy, a domain, a tunnel), set `SHAREDOC_PUBLIC_URL` too — the container has no way to infer it.\n- The MCP stdio server itself isn't meant to run in Docker — it needs a local process wired to an MCP client's stdin/stdout. Point your MCP client at `npx -y sharedoc-mcp` on the host as usual; only the standalone viewer daemon belongs in the container.\n\nEnvironment variables:\n\n| Variable | Default | Meaning |\n|---|---|---|\n| `SHAREDOC_BACKEND` | `gist` | `gist` or `selfhost` |\n| `SHAREDOC_PORT` | `8377` | viewer port (selfhost) |\n| `SHAREDOC_BIND_HOST` | `127.0.0.1` | viewer bind address (selfhost) — `0.0.0.0` to reach it from outside a Docker container; see [Docker](#docker) for the exposure tradeoff before changing this |\n| `SHAREDOC_PUBLIC_URL` | `http://127.0.0.1:<port>` | URL prefix in share links — set to your tunnel hostname |\n| `SHAREDOC_DATA_DIR` | `~/.local/share/sharedoc-mcp` | SQLite location (selfhost) |\n| `SHAREDOC_INDEX_PATH` | `~/.config/sharedoc-mcp/index.json` | local index (gist) |\n| `MCP_CALLER` | — | default author attribution for created docs |\n\n## The 9 tools\n\n| Tool | Does |\n|---|---|\n| `create_shared_doc` | title + Markdown (+ optional password / `expires_in_hours` / author) → share URL |\n| `append_to_shared_doc` | append Markdown (not idempotent — a retry appends twice) |\n| `update_shared_doc_content` | replace the entire content (title/password/expiry unchanged) — idempotent, safe to retry |\n| `extend_shared_doc` | extend expiry by N hours |\n| `reset_shared_doc_password` | set / change / remove (null) the password (selfhost only) |\n| `update_shared_doc_title` | rename |\n| `revoke_shared_doc` | kill the link, keep the record (see backend table for semantics) |\n| `delete_shared_doc` | kill the link AND erase the record — irreversible; requires `confirm: true` (agents should get explicit user approval first) |\n| `search_shared_docs` | no args = list newest links; title substring, body-text search (selfhost: full content; gist: opening excerpt), status filter, offset paging (hasMore in the response), view stats on selfhost |\n\n## Privacy\n\nData flow, by backend:\n\n- **Gist backend**: your document content is uploaded to GitHub as a secret gist under your account — GitHub's terms and retention apply. The local index stays in `~/.config/sharedoc-mcp/` — it stores titles, URLs, timestamps, and the first 200 characters of each doc (for local content search); never the full content. Nothing is sent anywhere except GitHub via your own `gh` CLI.\n- **Selfhost backend**: content never leaves your machine unless you attach a tunnel — then it's served to whoever you gave the link (and the tunnel provider relays the traffic). Passwords are stored only as bcrypt hashes.\n- sharedoc-mcp itself has no telemetry and calls no third-party service of its own.\n\n## Security semantics, honestly\n\n- **Gist links are bearer tokens**: anyone with the URL reads the doc. Revoke deletes the gist immediately and irreversibly.\n- Selfhost passwords are verified server-side before content is served; only WRONG attempts are rate-limited (5/minute per source+doc; a correct unlock clears the counter), with counters persisted in SQLite — restarting the server does not reset them. **Behind a tunnel, all external visitors share one source address**, so the practical limit is 5/minute per doc — stricter than per-visitor; one person mistyping can briefly lock a doc for others.\n- There is deliberately **no file-sharing tool**: an arbitrary-path \"share this file\" tool is a prompt-injection exfiltration vector (`.env`, keys) — a hijacked agent could publish secrets. Removed rather than allowlisted.\n- The viewer never binds beyond 127.0.0.1. Whether and how it reaches the internet is entirely your tunnel's configuration.\n\n## Develop\n\n```bash\ngit clone https://github.com/AugustusW/sharedoc-mcp.git\ncd sharedoc-mcp\nnpm install\nnpm test        # builds, then runs 110 offline tests — gh CLI is mocked, HTTP tests hit 127.0.0.1 only\n```\n\nVersioning: every release bumps `version` in `package.json`, adds a [CHANGELOG](./CHANGELOG.md) entry, and is published as a git tag + [GitHub Release](https://github.com/AugustusW/sharedoc-mcp/releases) + [npm](https://www.npmjs.com/package/sharedoc-mcp).\n**To get update notifications**: Watch this repo (Custom → Releases). `npx -y` fetches the latest published version on each cold run; your index and docs DB live outside the package — updating never touches them.\n\n## Status\n\nv2.2.0 ([CHANGELOG](./CHANGELOG.md)) — core logic is covered by 110 offline unit/integration tests (the `gh` CLI is mocked; HTTP tests run against 127.0.0.1 only; no network needed). The full flows have been manually verified (2026-07-25: real secret-gist create/index/delete via the built server over stdio JSON-RPC, and the selfhost password flow end-to-end — form → wrong password 401 → correct password 200 → rate-limit 429 → revoke 410 — plus `lsof` confirmation of the 127.0.0.1-only bind) on:\n\n- macOS (Apple Silicon), Node v25 — gist + selfhost backends\n\nTunnel recipes are documented from the tools' standard behavior; Windows/Linux and real-tunnel end-to-end runs have **not yet been verified** — reports welcome. The manual pass above predates 2.2.0: its additions (`update_shared_doc_content`, view stats, pagination, Docker) are covered by the test suite but have not had an equivalent hands-on run.\n\n## License\n\nMIT © AugustusW\n",
  "bytes": 17806,
  "sha": "0ff6c63cee836fbd8ab577c909259e518f493607e2b75d866704dd9de3c23be9",
  "repo_slug": "augustusw/sharedoc-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_augustusw_sharedoc_mcp_bc3eabdf/readme"
}