pocketnook

pocketnook MCP 服务

无需离开编写代码的 Agent，即可将仓库部署到专属 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. 可选：添加技能，以教会 Agent 工具描述本身无法说明的事项——部署会构建已推送的内容，而非磁盘上的内容；分享也不会通知任何人：

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 应显示一个技能和一个 MCP 服务。

值得运行此检查，因为看似显而易见的检查并不能覆盖这一点。 claude plugin validate 会读取 plugin.json 和技能，完全不会读取 .mcp.json——即使插件的 .mcp.json 根本不是可解析的 JSON，它也会报告 ✔ Validation passed。统计组件数量的是 details；对于这样的插件，它会报告 MCP servers (0)。

marketplace 清单和插件清单都放在这里，位于同一个仓库中，因为只有插件的仓库无法安装：plugin marketplace add 会报错 Marketplace file not found，而 plugin install 会提示 not found in any configured marketplace。.claude-plugin/marketplace.json 将本仓库的根目录列为唯一插件所在位置。

配置

变量	含义
POCKETNOOK_TOKEN	Agent 令牌。必填。
POCKETNOOK_URL	基础 URL；若不是 https://pocketnook.dev，则需设置。

工具

工具	功能
deploy	部署 GitHub 仓库——即默认分支的最新提交，并返回其专属 URL。
deploy_directory	按磁盘上的现状部署此计算机上的目录。无需仓库。
list_nooks	列出此账户部署的所有内容，包括 URL 和状态。
nook_logs	构建输出——部署出错时首先应查看的内容。
stop_nook	使 nook 离线，同时保留其 URL、授权和密钥。

两种部署方式，以及为什么它们是两个工具

deploy 构建 GitHub 上的内容。deploy_directory 上传磁盘上的内容， 包括未提交的工作，而且完全不需要仓库。之所以提供这种方式，是因为 Agent 的服务对象可能永远不会推送代码。

我们没有将它们合并成一个带启发式判断的工具，因为这种判断有两种隐蔽的失败方式：若倾向于仓库，整整一个下午的工作可能会悄无声息地没有部署；若倾向于目录，尚未完成的本地修改就会上线。这两种情况都不会主动提醒，而这正是猜测不可接受的原因：悄无声息的错误答案比提出问题更糟。

刻意缺少的功能

这里没有 delete 工具。删除一个 nook 会销毁其授权和密钥，且无法撤销，因此这项操作仍由能够明确说明此事的页面来处理；stop 是同一意图的可恢复版本。这里也没有任何用于管理令牌的功能——网关会完全拒绝 /api/tokens 上的令牌，因此 Agent 无法扩展自己的凭据，也无法撤销用于停止它的令牌。

share_nook 和 set_nook_secret 已于 2026-08-01 移除。 它们于 2026-07-27 在此处上线，随后一项设计决策将这两个路由都设为仅限会话访问——令牌用于部署，会话用于管理。 它们并非变得不明智，而是变得无法使用：网关中的 sessionOnly 会对任何 bearer 令牌返回 401。永远无法成功的工具比没有工具更糟，因为 Agent 会将拒绝视为暂时情况并重试。现在，设置密钥、分享 nook 和删除 nook 都需要在浏览器中完成；服务器的 MCP instructions 也说明了这一点，因此模型会引导用户前往那里，而不是另想变通办法，例如将密钥提交到项目中。

令牌能做什么，不能做什么

Agent 令牌在签发该令牌的账户自己的 nook 上，以该账户的身份执行操作。pocketnook 的网关强制执行以下三项限制，并在网关中进行测试——这些是服务器的属性，而非此客户端的属性，因此修改这份代码的副本也无法放宽限制：

• 它无法签发或撤销令牌。 只有浏览器会话才能执行此操作，因此泄露的令牌无法续期，而且始终有地方可以撤销令牌。
• 它不包含电子邮件或 GitHub 用户名声明。 访问他人的 nook 需要授予某个用户名或已验证的电子邮件域名权限，而令牌两者都不包含——因此它可以作为所有者执行操作，但永远无法成为查看者。
• 它无法打开 nook。 /s/:id/ 只读取会话 Cookie。令牌只是另一种部署方式，并没有提供新的读取方式。

令牌以 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 和构建缓存会被排除在外。
• 构建日志是他人的输出。 控制字符会在内容送达 Agent 前被剥除，日志也会包含在 --- 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