pocketnook

pocketnook MCP server

リポジトリを、作成したエージェントから離れずに非公開 URL へデプロイします。

> deploy this somewhere private

  owner/studio-board is deployed: https://pocketnook.dev/s/nook-…/
  It is private — only you can open it until you share it. (static, 42 files)

デプロイの手順は、ソフトウェアを作成しているツールの中にあるべきです。そこが配布の場であり、製品そのものでもあります。

インストール

1. トークンを取得します。 pocketnook.dev にサインインし、ホームページで Agent access を開いて作成します。トークンが表示されるのは一度だけです。

2. サーバーを追加します。

claude mcp add pocketnook \
  --env POCKETNOOK_TOKEN=pnka_… \
  -- npx -y @pocketnook/mcp

または、このリポジトリをチェックアウトしている場合は、エントリを直接指定します。

claude mcp add pocketnook \
  --env POCKETNOOK_TOKEN=pnka_… \
  -- node /absolute/path/to/apps/mcp/bin/pocketnook-mcp.mjs

このサーバーには依存関係がなく、Node 22.18 以降で動作します。これは package.json で宣言されている最低バージョンなので、それより古い Node では、気付かないまま中途半端に動作するのではなく、警告が表示されます。どの MCP クライアントでも使えます。上記のコマンドは Claude Code 用です。

3. 必要に応じてスキルを追加します。 このスキルは、ツールの説明だけでは伝えられないことをエージェントに教えます。たとえば、デプロイではディスク上の内容ではなくプッシュされた内容がビルドされること、共有しても誰にも通知されないことなどです。

cp -r skills/pocketnook ~/.claude/skills/

または、Claude Code プラグインとして両方を一度にインストールする

このリポジトリは Claude Code プラグインでもあります。上記のスキルと MCP サーバーが連携しており、トークンは環境から読み取られます。

claude plugin marketplace add shotintoeternity/pocketnook-mcp
claude plugin install pocketnook@pocketnook-mcp

続いて確認します。claude plugin details pocketnook@pocketnook-mcp を実行すると、1 つのスキルと 1 つの MCP サーバーが報告されるはずです。

この確認は実行する価値があります。見た目に明らかな確認だけでは不十分だからです。claude plugin validate は plugin.json とスキルを読み取りますが、.mcp.json はまったく読み取りません。そのため、.mcp.json が JSON として解析できないプラグインでも ✔ Validation passed と報告されます。コンポーネントの数を確認するのは details であり、そのようなプラグインでは MCP servers (0) と報告されます。

マーケットプレイスのマニフェストとプラグインのマニフェストの両方を同じリポジトリに置いているのは、プラグインだけのリポジトリはインストールできないためです。plugin marketplace add は Marketplace file not found で失敗し、plugin install は not found in any configured marketplace と応答します。.claude-plugin/marketplace.json には、このリポジトリのルートが唯一のプラグインとして記載されています。

設定

変数	意味
POCKETNOOK_TOKEN	エージェントのトークンです。必須です。
POCKETNOOK_URL	https://pocketnook.dev 以外の場合のベース URL です。

ツール

ツール	機能
deploy	GitHub リポジトリのデフォルトブランチの先端をデプロイし、非公開 URL を返します。
deploy_directory	このマシン上のディレクトリを、ディスク上にある状態のままデプロイします。リポジトリは不要です。
list_nooks	このアカウントがデプロイしたすべてのものを、URL とステータスとともに表示します。
nook_logs	ビルド出力です。デプロイに失敗したとき、最初に確認するものです。
stop_nook	URL、権限付与、シークレットを保持したまま、nook をオフラインにします。

2 種類のデプロイと、別々のツールである理由

deploy は GitHub にある内容をビルドします。deploy_directory は未コミットの作業も含め、ディスク上にある内容をアップロードします。リポジトリも不要です。このツールがあるのは、エージェントに作成を依頼した人が一度もプッシュしない場合があるためです。

ヒューリスティックを使って 1 つのツールに統合していません。ヒューリスティックには、気付かれないまま起こる失敗が 2 種類あるからです。リポジトリを優先するよう推測すると、午後いっぱいかけた作業がひそかにデプロイされないことがあります。ディレクトリを優先するよう推測すると、未完成のローカル編集が公開されてしまうことがあります。どちらも、それ自体では問題が起きたと知らせてくれません。だからこそ、推測に任せるわけにはいきません。黙ったままの誤答は、質問するよりも悪いのです。

意図的に用意していないもの

delete ツールはありません。nook を削除すると、その権限付与とシークレットが破棄され、元に戻せないため、その操作は実行することを明示できるページ上で行うようにしています。stop は、同じ意図を取り消し可能な形で実現するものです。トークンを管理する機能もありません。ゲートウェイは /api/tokens へのトークンを全面的に拒否するため、エージェントが自分の認証情報を延長したり、自身を停止するために使っているトークンを無効化したりすることはできません。

share_nook と set_nook_secret は 2026-08-01 に削除されました。 これらは 2026-07-27 にここで提供されましたが、その後の設計上の判断により、どちらのルートもセッション限定になりました。トークンはデプロイに使い、セッションは管理に使います。 これらの機能が推奨されなくなったのではなく、実行不可能になったのです。ゲートウェイの sessionOnly は、ベアラートークンからのリクエストに常に 401 を返します。決して成功しないツールは、ツールがない場合よりも厄介です。エージェントは拒否を一時的な問題と受け取り、再試行するからです。シークレットの設定、nook の共有、削除はすべて現在ブラウザーで行います。サーバーの MCP instructions にもその旨が記載されているため、モデルは回避策としてシークレットをプロジェクトにコミットするのではなく、ユーザーをブラウザーに誘導します。

トークンでできること、できないこと

エージェントトークンは、そのトークンを発行したアカウントとして、そのアカウント自身の nook に対して動作します。pocketnook のゲートウェイでは 3 つの制限が適用され、そこでテストされています。これらはこのクライアントではなくサーバーの特性であるため、このコードを改変しても制限を広げることはできません。

• トークンを発行または無効化することはできません。 それができるのはブラウザーセッションだけなので、漏えいしたトークンが自分自身を更新することはなく、無効化は常にブラウザーから行えます。
• メールアドレスや GitHub のユーザー名のクレームは含まれません。 他のユーザーの nook へのアクセスは、ユーザー名または検証済みのメールドメインに付与されますが、トークンはどちらも保持しないため、オーナーとして動作することはできても、閲覧者になることはできません。
• nook を開くことはできません。 /s/:id/ はセッション Cookie のみを参照します。トークンはデプロイ方法を 1 つ増やすものであり、新たな閲覧方法を追加するものではありません。

トークンは SHA-256 ハッシュとして保存され、90 日後に期限切れになります。また、作成したのと同じパネルから無効化できます。

既知の制限

• ビルドは同期的に実行されます。 デプロイではビルドが完了するまでリクエストが保留され、このクライアントは最大 15 分待機します。クライアント側でさらに独自のツールタイムアウトが適用されます。ビルドがその時間を超えてもビルド自体は完了するため、再度デプロイするのではなく、list_nooks または pocketnook.dev/home を確認してください。
• クライアントが切断されるとビルドはキャンセルされます。 原因は同じです。キューがないため、ビルドはリクエスト内で実行されます。
• ルート相対のアセット。 nook は /s/:id/ 以下で配信されるため、/logo.png をリクエストするアプリは自身のプレフィックスから外れてしまいます。相対パスを使うアプリ（たとえば Vite の base: './'）には影響しません。
• deploy_directory には PATH 上の tar が必要です。また、ホームディレクトリを含むディレクトリは拒否されます。~ をパッキングすると、プロジェクトと一緒に SSH キーやクラウドの認証情報までアップロードされるためです。アップロードサイズはゲートウェイによって 32 MB に制限されています。node_modules、.git、ビルドキャッシュは除外されます。
• ビルドログは他者が出力したテキストです。 エージェントに届く前に制御文字が取り除かれ、誰のテキストかを示す --- begin build output --- マーカーで囲まれて届きます。これは軽減策であり、解決策ではありません。ビルドログに書かれた指示は通常のテキストであり、どのようにエスケープしても取り除けません。マーカーによってモデルは、それを割り引いて扱うための文脈を得られます。

開発

npm test          # node --test, no dependencies

プロトコルを手動で操作するには：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node bin/pocketnook-mcp.mjs