The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Pocketnook listing page.
Deploy a repository to a private URL without leaving the agent that wrote it.
The deploy step belongs inside the tool where the software is being written, which is both the distribution and the product.
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.
Or, from a checkout of this repository, point at the entry directly:
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:
This repository is also a Claude Code plugin: the skill above and the MCP server, wired together, with the token read from your environment.
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.
| Variable | Meaning |
|---|---|
POCKETNOOK_TOKEN | An agent token. Required. |
POCKETNOOK_URL | Base URL, if not https://pocketnook.dev. |
| 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. |
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.
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.
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:
/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.
list_nooks or pocketnook.dev/home rather than deploying again./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.--- 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.To drive the protocol by hand: