pocketnook

pocketnook MCP server

Deploy a repository to a private URL without leaving the agent that wrote it.

> 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)

The deploy step belongs inside the tool where the software is being written, which is both the distribution and the product.

Install

1. Get a token. Sign in at pocketnook.dev, open Agent access on the home page, and create one. It is shown once.

2. Add the server.

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

Or, from a checkout of this repository, point at the entry directly:

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

The server has no dependencies and runs on Node 22.18 or newer — the floor package.json declares, so an older Node warns rather than silently half-works. Any MCP client works; the commands above are Claude Code's.

3. Optionally add the skill, which teaches the agent the things the tool descriptions cannot say on their own — that a deploy builds what is pushed rather than what is on disk, and that sharing does not notify anyone:

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

Or install both at once, as a Claude Code plugin

This repository is also a Claude Code plugin: the skill above and the MCP server, wired together, with the token read from your environment.

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

Then check it: claude plugin details pocketnook@pocketnook-mcp should report one skill and one MCP server.

That check is worth running, because the obvious one does not cover it. claude plugin validate reads plugin.json and the skills, and does not read .mcp.json at all — it reports ✔ Validation passed on a plugin whose .mcp.json is not even parseable JSON. details is what counts the components, and it reports MCP servers (0) for exactly that plugin.

The marketplace manifest and the plugin manifest are both here, in one repository, because a plugin-only repository is not installable: plugin marketplace add fails with Marketplace file not found, and plugin install answers not found in any configured marketplace. .claude-plugin/marketplace.json lists this repository's root as its one plugin.

Configuration

Variable	Meaning
POCKETNOOK_TOKEN	An agent token. Required.
POCKETNOOK_URL	Base URL, if not https://pocketnook.dev.

Tools

Tool	What it does
deploy	Deploy a GitHub repository — the tip of its default branch — and return its private URL.
deploy_directory	Deploy a directory from this machine as it is on disk. No repository needed.
list_nooks	Everything this account has deployed, with URLs and status.
nook_logs	Build output — the first thing to read when a deploy went wrong.
stop_nook	Take a nook offline, keeping its URL, grants, and secrets.

The two deploys, and why they are two tools

deploy builds what GitHub has. deploy_directory uploads what is on the disk, including uncommitted work, and needs no repository at all. It exists because the person an agent is writing for may never make a push.

They are not merged into one tool with a heuristic, because the heuristic has two silent failure modes: guess towards the repository and an afternoon of work is quietly not deployed; guess towards the directory and half-finished local edits go live. Neither announces itself, which is what makes the guess unaffordable: a wrong answer that stays quiet is worse than a question.

What is deliberately absent

There is no delete tool. Deleting a nook destroys its grants and secrets and cannot be undone, so it stays a decision made on a page that can say so; stop is the recoverable version of the same intent. There is nothing for managing tokens either — the gateway refuses a token on /api/tokens entirely, so an agent cannot extend its own credential or revoke the one being used to stop it.

share_nook and set_nook_secret were removed on 2026-08-01. They shipped here on 2026-07-27 and then a design decision made both routes session-only — a token deploys, a session administers. They did not become ill-advised, they became impossible: sessionOnly in the gateway answers any bearer token with 401. A tool that can never succeed is worse than no tool, because an agent reads the refusal as transient and retries it. Setting a secret, sharing a nook and deleting one all happen in the browser now, and the server's MCP instructions say so, so a model sends its person there rather than inventing a workaround such as committing the secret into the project.

What the token can and cannot do

An agent token acts as the account that minted it, on that account's own nooks. Three limits are enforced by pocketnook's gateway, and tested there — they are properties of the server, not of this client, so a modified copy of this code cannot widen them:

• It cannot mint or revoke a token. Only a browser session can, so a leaked token cannot renew itself, and revoking always has somewhere to happen from.
• It carries no email or GitHub username claim. Access to someone else's nook is granted to a username or a verified email domain, and a token holds neither — so it can act as an owner but can never become a viewer.
• It cannot open a nook. /s/:id/ reads the session cookie and nothing else. A token is one more way to deploy and no new way to read.

Tokens are stored as a SHA-256 hash, expire after 90 days, and can be revoked from the same panel that created them.

Known limits

• Builds are synchronous. A deploy holds the request until the build finishes, and this client waits up to 15 minutes. Clients apply their own tool timeout on top of that; if a build outlasts it, the build still completes — check list_nooks or pocketnook.dev/home rather than deploying again.
• A disconnecting client cancels a build. Same root cause: there is no queue, so the build lives in the request.
• Root-relative assets. A nook is served under /s/:id/, so an app that requests /logo.png escapes its own prefix. Apps that use relative paths (for example Vite's base: './') are unaffected.
• deploy_directory needs tar on the PATH, and refuses a directory that contains your home directory — packing ~ would upload SSH keys and cloud credentials along with the project. Uploads are capped at 32 MB by the gateway; node_modules, .git and build caches are left out.
• A build log is somebody else's output. Control characters are stripped before it reaches the agent, and it arrives inside --- begin build output --- markers that say whose text it is. That is a mitigation, not a fix: an instruction written into a build log is ordinary text and no escaping removes it. The markers give the model the context to discount it.

Development

npm test          # node --test, no dependencies

To drive the protocol by hand:

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