sharedoc-mcp

sharedoc-mcp

エージェントが生成した Markdown → 誰にでも渡せるリンク。今は GitHub gist、将来は自分のサーバーで。

英語 | 繁體中文

MCP の stdio サーバーです。Claude Code、Codex CLI、その他すべての MCP クライアントで動作し、エージェントに共有可能なドキュメントの公開、更新、検索、取り消しを行う9つのツールを提供します。1つのインターフェースの背後に、プラグイン可能な2つのバックエンドを備えています。gist（セットアップ不要。ログイン済みの gh CLI を利用）と、selfhost（マシン上の SQLite、パスワード、期限の強制）です。

バックエンドがパラメーター（たとえば gist での password）に対応していない場合、黙って無視するのではなく、明確なエラーを返します。

なぜ？

AI エージェントは、レポート、調査の要約、会議メモなどの Markdown を絶えず生成します。それを別の人に渡すには、通常、長いテキストをチャット画面にコピー＆ペーストする必要があります。

Without sharedoc-mcp                  With sharedoc-mcp
────────────────────                  ─────────────────
copy a wall of text into chat         "share this as a doc"
paste again for each person           one link for everyone
content lives in chat scroll          revoke / extend / append later
"can you password it?"  …no           selfhost backend: bcrypt + expiry

こうした Markdown の要約はどこから来るのでしょうか？別のスキルから生成されることがよくあります。たとえば、 audio-tldr は動画やポッドキャストを Markdown の要約に変換し、sharedoc-mcp はそれをリンクに変換します。

機能

• ✓ 9 個の MCP ツール：作成／コンテンツの追記／更新／拡張／パスワードのリセット／名前変更／取り消し／削除／検索
• ✓ sharedoc-mcp serve デーモンモード — MCP クライアントを閉じた後も、セルフホストのリンクは引き続き機能します
• ✓ コンテンツ検索：タイトルだけでなく、共有リンクの内容から古いリンクを検索できます
• ✓ GET /healthz — 外部監視／再起動の自動化向けの、ID を考慮したヘルスプローブです
• ✓ 2 種類のバックエンドを 1 つのインターフェースで利用できます — 環境変数 1 つで切り替えられ、ツールスキーマは同一です
• ✓ Gist バックエンド（デフォルト）：ログイン済みの gh CLI 経由でシークレット Gist を利用します — 管理するトークンは不要で、新たにホストするものもありません
• ✓ セルフホストバックエンド：ドキュメントはお使いのマシンに保存されます（組み込みの node:sqlite 経由の SQLite — ネイティブモジュールは不要です）
• ✓ サーバー検証パスワード（bcrypt）と試行回数制限 — 5 回／分、HTTP 429。カウンターは SQLite に永続化されるため、再起動してもリセットされません（selfhost）
• ✓ 有効期限の強制（410）と、7 日間のコンテンツ消去猶予期間を設けた取り消し（selfhost）；遅延有効期限クリーンアップ（gist）
• ✓ Markdown は marked + sanitize-html でレンダリングされます — 共有コンテンツ内のスクリプト、イベントハンドラー、javascript: URL は除去されます
• ✓ ビューアーは 127.0.0.1 のみにバインドされ、厳格なセキュリティヘッダー一式（CSP default-src 'none'、nosniff、フレーム表示の DENY、no-referrer、no-store）を付けて応答します — 公開する場合は、ご自身で管理するトンネルを使います（以下のレシピを参照）
• ✓ search_shared_docs 用のローカルインデックスと作成時の重複排除（保護されていない同一の再試行は 5 分以内なら同じ URL を返します。パスワード／有効期限を追加する再試行では必ず新しいドキュメントが作成されます）
• ✓ search_shared_docs はオフセットページネーション（レスポンス内の hasMore）に対応し、selfhost では閲覧統計（viewCount／lastViewedAt、レンダリングに成功した場合のみカウント）も利用できます
• ✓ スタンドアロンの serve デーモンを起動する Docker のワンライナー。デフォルトで、他のすべての環境と同じく 127.0.0.1 のみにバインドされます
• ✓ 2 つの MCP クライアントで 1 つのデータディレクトリを共有できます：SQLite WAL + ビジータイムアウト、正常なポート共有
• ✓ オフラインテスト 110 件；クリーンなチェックアウトで npm test が成功します

インストール

Node.js ≥ 22.13.0 が必要です。Gist バックエンドには、ログイン済みの GitHub CLI（gh auth login）も必要です。

オプション A — Claude Code（1 行）：

claude mcp add sharedoc --scope user -- npx -y sharedoc-mcp@^2

オプション B — Codex CLI（~/.codex/config.toml）：

[mcp_servers.sharedoc]
command = "npx"
args = ["-y", "sharedoc-mcp@^2"]

オプション C — Cursor（ワンクリック）： Cursor に追加 をクリックするか、~/.cursor/mcp.json にマージします：

{ "mcpServers": { "sharedoc": { "command": "npx", "args": ["-y", "sharedoc-mcp@^2"] } } }

オプション D — VS Code（ワンクリック）： VS Code にインストール をクリックするか、ターミナルから実行します：

code --add-mcp '{"name":"sharedoc","command":"npx","args":["-y","sharedoc-mcp@^2"]}'

オプション E — その他の MCP クライアント： npx -y sharedoc-mcp@^2 を stdio サーバーとして実行します。

@^2 を使う理由は？ npx -y sharedoc-mcp のようにバージョンを指定しない場合、コールドスタートのたびに公開済みの最新バージョンが解決されます。将来の 3.0 で、警告なしに動作が変わったり（またはツールが削除されたり）する可能性があります。@^2 なら、破壊的変更を伴うメジャーバージョンを越えずに 2.x の修正を取り込めます。変更を完全に避けたい場合は、正確なバージョン（@2.2.0）を指定してください。

バックエンドを選択する

	🅰 gist（デフォルト）	🅱 selfhost
セットアップ	不要 — ログイン済みの gh CLI を使用します	追加設定不要 — データはお使いのマシンに保存されます
ドキュメントの保存先	GitHub（シークレット Gist）	お使いのマシン（SQLite）
リンクへのアクセス	どこからでもすぐにアクセス可能	localhost — 外部と共有するにはトンネルを追加します
パスワード	✗（シークレット URL が保護手段です）	✓ サーバー検証（bcrypt）、試行回数制限あり
有効期限	遅延方式 — 期限切れの Gist は次回使用時に削除されます	強制 — 期限切れのリンクは 410 を返します
取り消し	Gist はただちに削除され、元に戻せません	ただちに 410 を返し、7 日間の猶予期間後にコンテンツを消去します
閲覧統計	✗（GitHub の Gist API では閲覧回数データを取得できません）	✓ viewCount + lastViewedAt。レンダリングに成功した場合のみカウントします

Gist のクイックスタート

エージェントに「これをドキュメントとして共有して」と頼むと、create_shared_doc を呼び出して、シークレット Gist の URL を返します。シークレット Gist は公開一覧には表示されず、URL も推測できませんが、リンクを知っている人なら誰でも読めます。このバックエンドのセキュリティモデルはこれだけです。パスワードが必要ですか？selfhost を使ってください。

ローカルインデックス（~/.config/sharedoc-mcp/index.json）には、共有したものが記録され、検索や期限切れ項目のクリーンアップに使われます。ここでの有効期限処理は 遅延実行 です。期限切れの Gist は、有効期限ちょうどに削除されるのではなく、次にいずれかのツールが実行されたときに削除されます。

Selfhost のクイックスタート

claude mcp add sharedoc --scope user --env SHAREDOC_BACKEND=selfhost -- npx -y sharedoc-mcp@^2

ドキュメントは ~/.local/share/sharedoc-mcp/ の SQLite に保存され、ビューアーは http://127.0.0.1:8377 で配信されます。マシンの外部と共有するには、前段にトンネルを設置して SHAREDOC_PUBLIC_URL を設定します。

エディターを閉じても有効なリンク： MCP モードでは、ビューアーは MCP クライアントとともに終了します。Claude Code を閉じると、次のセッションまで selfhost のリンクに応答できなくなります（データは SQLite に安全に保存されています）。リンクを常時有効にするには、スタンドアロンのデーモンを実行してください。

npx -y sharedoc-mcp@^2 serve   # ビューアーのみ。同じ DB を使用します。launchd/systemd/tmux で実行し続けてください（Windows の場合はタスク スケジューラまたは NSSM）

MCP クライアントは、デーモンがすでにポートを使用していることを検出し、そのまま利用します。

設定するタイミング： 初めて誰かにリンクを渡すときに、トンネルと一緒に設定してください（どちらも launchd/systemd などで長時間実行する必要があります）。それまでは MCP モードのビューアーで十分です。Gist バックエンドのユーザーは設定不要です。

方法	適しているケース	設定
Tailscale プライベート（推奨）	共有相手が自分のデバイス、または自分の tailnet に招待できる人	tailscale serve --bg 8377 → https://<machine>.<tailnet>.ts.net。自分の tailnet 内でのみアクセス可能で、パブリックインターネットには何も公開されません
Tailscale Funnel	ドメインなしで誰とでも共有したい場合	tailscale funnel 8377 → 同じ安定した URL ですが、公開されます
Cloudflare の名前付きトンネル	独自ドメインを所有している場合	ドメインを Cloudflare に設定し、cloudflared tunnel create を実行して、ホスト名を http://127.0.0.1:8377 にルーティングします
cloudflared クイックトンネル	一度限りの共有	cloudflared tunnel --url http://127.0.0.1:8377 → ランダムな URL が発行され、再起動のたびに変わります

独自ドメインをお持ちですか？ Cloudflare の名前付きトンネルを順を追って設定する

https://docs.example.com/docs/<uuid> のような、ブランドを反映した安定した共有 URL を利用できます。TLS は Cloudflare が処理するため、NAT の内側からも動作します。

# one-time setup (domain already added to Cloudflare — the free plan is enough)
cloudflared tunnel login
cloudflared tunnel create sharedoc
cloudflared tunnel route dns sharedoc docs.example.com

~/.cloudflared/config.yml：

tunnel: sharedoc
credentials-file: ~/.cloudflared/<tunnel-id>.json
ingress:
  - hostname: docs.example.com
    service: http://127.0.0.1:8377
  - service: http_status:404

cloudflared tunnel run sharedoc を実行するか、常時稼働させる場合はサービスとしてインストールし、公開 URL を指定して MCP サーバーを登録します。

claude mcp add sharedoc --scope user \
  --env SHAREDOC_BACKEND=selfhost \
  --env SHAREDOC_PUBLIC_URL=https://docs.example.com \
  -- npx -y sharedoc-mcp

さらに利用できる機能：Cloudflare の DDoS 保護を無料で利用できます。また、WAF ルールを追加したり、共有パス以外すべての前段に Cloudflare Access（SSO）を配置したりできます。これにより、「内部は SSO、外部向け共有はパスワード保護」という分け方ができます。

代替案 — 自宅のマシンなしで常時稼働させる： sharedoc-mcp を VPS（エージェントも実行する環境）で実行し、ドメインと自動 TLS を設定して、nginx/caddy から 127.0.0.1:8377 に接続します。トンネルは不要です。

Docker

上記と同じスタンドアロンの serve デーモンを、コンテナー内で実行します：

docker build -t sharedoc-mcp .
docker run -d --name sharedoc \
  -p 8377:8377 \
  -e SHAREDOC_BIND_HOST=0.0.0.0 \
  -v sharedoc-data:/data \
  sharedoc-mcp

• -v sharedoc-data:/data は、名前付きボリュームに docs.db を保持します。コンテナーを作り直しても、ドキュメントは保持されます。
• コンテナーに接続するには、SHAREDOC_BIND_HOST=0.0.0.0 の設定が必須です。 ビューアーはデフォルトで 127.0.0.1 にバインドされます。これは、この README に記載されているほかのすべてのデプロイ方法と同じですが、コンテナー内では -p がループバックではなくコンテナーのネットワークインターフェースに転送するため、docker run -p 経由では接続できません。この環境変数を設定しないと、docker logs にはビューアーがリッスン中と表示されますが、ポートを割り当てたホスト側では、すべての接続が拒否されます。
• 0.0.0.0 に設定すると、公開ポートに接続できるあらゆるプロセスが、ネットワーク上の場所を問わず認証なしでビューアーにアクセスできることになります。これは、前段にプロキシを置かずに認証なしのアプリをコンテナー内で実行する場合と同じ公開上のトレードオフです。-p 8377:8377 でインターネットに直接公開するのではなく、上記のほかのセルフホスト構成と同様の入口（ホスト上のリバースプロキシ、Tailscale サイドカー、Cloudflare トンネルなど）の背後に配置してください。個々のドキュメントをパスワードで保護する機能（このバックエンドの組み込み機能）は、その代わりにはなりません。
• 共有相手が使用するアドレスが http://<host>:8377 と異なる場合（リバースプロキシ、ドメイン、トンネルなど）は、SHAREDOC_PUBLIC_URL も設定してください。コンテナー側では、そのアドレスを推定できません。
• MCP の stdio サーバー自体は、Docker での実行を想定していません。MCP クライアントの stdin/stdout に接続されたローカルプロセスが必要です。通常どおり、ホスト上の npx -y sharedoc-mcp を MCP クライアントの接続先に指定してください。コンテナーで実行するのは、スタンドアロンのビューアーデーモンのみです。

環境変数：

変数	デフォルト	説明
SHAREDOC_BACKEND	gist	gist または selfhost
SHAREDOC_PORT	8377	ビューアーのポート（selfhost）
SHAREDOC_BIND_HOST	127.0.0.1	ビューアーのバインドアドレス（selfhost）。Docker コンテナーの外部から接続するには 0.0.0.0 を指定します。変更する前に、公開上のトレードオフについて Docker を参照してください
SHAREDOC_PUBLIC_URL	http://127.0.0.1:<port>	共有リンクの URL プレフィックス。トンネルのホスト名を設定します
SHAREDOC_DATA_DIR	~/.local/share/sharedoc-mcp	SQLite の保存場所（selfhost）
SHAREDOC_INDEX_PATH	~/.config/sharedoc-mcp/index.json	ローカルインデックス（gist）
MCP_CALLER	—	作成するドキュメントのデフォルトの作成者情報

9 つのツール

ツール	機能
create_shared_doc	タイトル＋Markdown（＋オプションのパスワード／expires_in_hours／作成者）→ 共有 URL
append_to_shared_doc	Markdown を追記します（冪等ではありません。再試行すると二重に追記されます）
update_shared_doc_content	コンテンツ全体を置き換えます（タイトル／パスワード／有効期限は変更されません）。冪等なので安全に再試行できます
extend_shared_doc	有効期限を N 時間延長します
reset_shared_doc_password	パスワードを設定／変更／削除（null）します（selfhost のみ）
update_shared_doc_title	名前を変更します
revoke_shared_doc	リンクを無効にし、記録は保持します（詳細はバックエンドの表を参照）
delete_shared_doc	リンクを無効にし、記録も削除します。取り消せません。confirm: true が必要です（エージェントは事前にユーザーから明示的な承認を得てください）
search_shared_docs	引数なしの場合は、最新のリンクを一覧表示します。タイトルの部分一致、本文検索（selfhost：全文、gist：冒頭の抜粋）、ステータスでの絞り込み、オフセットによるページング（レスポンスに hasMore を含む）、selfhost での表示統計に対応します

プライバシー

バックエンド別のデータフロー：

• Gist バックエンド：ドキュメントの内容は、アカウントの非公開 gist として GitHub にアップロードされます。GitHub の利用規約とデータ保持方針が適用されます。ローカルインデックスは ~/.config/sharedoc-mcp/ に保存され、タイトル、URL、タイムスタンプ、および各ドキュメントの先頭 200 文字（ローカルでのコンテンツ検索用）が記録されます。全文が保存されることはありません。ご自身の gh CLI を介した GitHub 以外には、何も送信されません。
• セルフホストバックエンド：トンネルを設定しない限り、コンテンツがマシンの外部に出ることはありません。トンネルを設定した場合は、リンクを共有した相手がコンテンツを閲覧でき、トンネルプロバイダーが通信を中継します。パスワードは bcrypt ハッシュとしてのみ保存されます。
• sharedoc-mcp 自体はテレメトリーを収集せず、独自にサードパーティーサービスを呼び出すこともありません。

セキュリティの仕様について

• Gist のリンクはベアラートークンです：URL を知っている人は誰でもドキュメントを閲覧できます。取り消すと、gist は即座に、かつ取り消し不能な形で削除されます。
• セルフホストのパスワードは、コンテンツが提供される前にサーバー側で検証されます。レート制限の対象は不正解の試行のみです（送信元とドキュメントの組み合わせごとに 5 回／分。正しいパスワードでロックを解除するとカウンターがクリアされます）。カウンターは SQLite に保存されるため、サーバーを再起動してもリセットされません。トンネル経由の場合、外部からの訪問者は全員、同じ送信元アドレスを共有します。そのため、実際の制限は訪問者ごとではなくドキュメントごとに 5 回／分となり、より厳しくなります。1 人がパスワードを間違えると、ほかの人も一時的にドキュメントを閲覧できなくなることがあります。
• 意図的にファイル共有ツールはありません。任意のパスを指定して「このファイルを共有する」ツールを設けると、プロンプトインジェクションによって .env やキーなどを流出させる可能性があります。乗っ取られたエージェントが秘密情報を公開しかねないため、許可リスト方式にするのではなく、ツール自体を削除しています。
• ビューアーが 127.0.0.1 以外にバインドされることはありません。インターネットに公開されるかどうか、またその方法は、すべてトンネルの設定に依存します。

開発

git clone https://github.com/AugustusW/sharedoc-mcp.git
cd sharedoc-mcp
npm install
npm test        # builds, then runs 110 offline tests — gh CLI is mocked, HTTP tests hit 127.0.0.1 only

バージョン管理：リリースごとに package.json の version を更新し、CHANGELOG に項目を追加したうえで、git タグ、GitHub Release、npm として公開します。 更新通知を受け取るには：このリポジトリをウォッチしてください（Custom → Releases）。npx -y は、起動のたびに（コールドスタート時）最新の公開バージョンを取得します。インデックスとドキュメントデータベースはパッケージの外部にあるため、更新によってこれらに影響が及ぶことはありません。

ステータス

v2.2.0（CHANGELOG）— コアロジックは 110 件のオフライン単体テスト／統合テストでカバーされています（gh CLI はモック化され、HTTP テストは 127.0.0.1 のみを対象に実行されるため、ネットワークは不要です）。一連のフローは手動でも検証済みです（2026-07-25：ビルド済みサーバーを介し、stdio JSON-RPC 経由で実際の secret gist の作成／インデックス登録／削除を実施。また、セルフホストのパスワードフローをエンドツーエンドで検証し、フォーム → 不正なパスワード 401 → 正しいパスワード 200 → レート制限 429 → 取り消し 410 を確認。さらに lsof で 127.0.0.1 のみへのバインドを確認）。検証環境：

• macOS（Apple Silicon）、Node v25 — Gist およびセルフホストバックエンド

トンネルの設定例は、各ツールの標準的な動作をもとに記載しています。Windows／Linux および実際のトンネルを使ったエンドツーエンドの実行はまだ検証されていません。報告をお待ちしています。上記の手動検証は 2.2.0 より前に実施したものです。追加機能（update_shared_doc_content、閲覧統計、ページネーション、Docker）はテストスイートでカバーされていますが、同等の手動実行はまだ行っていません。

ライセンス

MIT © AugustusW