Allows deploying a local folder to a cPanel host over SFTP, with backup-before-overwrite, one-command restore/undo, drift detection, and safe agent-driven deploys.
Allows deploying a local folder to a Plesk host over SFTP, with backup-before-overwrite, one-command restore/undo, drift detection, and safe agent-driven deploys.
Let the agent deploy. Keep the undo.
It's late, and the agent says "Deployed ✓". Then the client's contact form is gone. The agent overwrote a
file someone had fixed by hand in cPanel last week, and shared hosting has no git revert.
Shipback deploys a folder to any SFTP host: cPanel, Plesk, DirectAdmin, a plain VPS. Every deploy can be undone with one command. You can run it yourself, script it, or hand it to Claude Code, Cursor or any MCP client.
Backup before every overwrite. The server's copy of each file a deploy replaces is saved into
_backup-<time>/ on the server, before the upload starts.
One-command undo. --restore puts those files back and removes the files that deploy added.
It won't undo over a live edit. If someone changed a file on the server after the deploy, restore
stops and names the file. Nothing is touched unless you pass --force, and even then the edited copy is
backed up first.
Restores can be undone too. A restore backs up what it replaces, the same way a deploy does.
Safe for agents. The MCP server has no switch to delete server files or skip the backup. A deploy only runs the exact plan the agent previewed: if a file changed in between, it refuses.
Spots the drift. --pull --dry-run shows what changed on the server since your last deploy, so
edits made live in cPanel don't get overwritten by accident.
No git or SSH shell is needed on the server, just SFTP. It needs Node 18+. The tests run on Windows, macOS and Linux with Node 18, 20 and 22 on every push. Passwords are kept in the OS keychain and never pass through the model.
It has run in production. The deploy engine underneath has shipped aldo.today 235 times since September 2026 (2,907 files to a cPanel host). Restore and the MCP server are new in 0.1.
npm install -g shipback-sftp # installs the shipback and shipback-mcp commands
cd ~/sites # any folder with a sites.json in it (format below)
shipback mysite --dry-run # see the plan; asks for the password once and stores it
shipback mysite # deploy
shipback mysite --restore # changed your mind? undo itNo global install? npx -p shipback-sftp shipback mysite --dry-run works the same way. --sites <file>
points at a sites.json in another folder.
From source: git clone https://github.com/aldohushi1-stack/shipback-sftp.git, npm install, then
node bin/cli.js wherever these docs say shipback.
sites.json, one entry per site:
{
"sites": [
{
"name": "mysite",
"host": "server123.example-host.com",
"port": 22,
"username": "cpaneluser",
"remoteRoot": "/home/cpaneluser/public_html",
"localDir": "/Users/you/sites/mysite",
"ignore": ["drafts/", "*.psd"]
}
]
}Many shared hosts run SFTP on their own port rather than 22 (check SSH Access in your control panel),
and some only accept connections from allow-listed IPs. If a connection times out, check those two
first. Use "privateKeyPath" instead of a password if your host has your key.
Related MCP server: WebsiteOps MCP Server
shipback <site> --dry-run # what a deploy would upload
shipback <site> # deploy: backup, upload, record
shipback <site> --local <folder> # deploy a different folder than localDir
shipback <site> --pull --dry-run # what changed on the server since the last deploy?
shipback <site> --pull # bring those changes down (local copies backed up first)
shipback <site> --backups # list backups: what each run overwrote, added, deleted
shipback <site> --restore --dry-run # what an undo of the latest deploy would do
shipback <site> --restore [<backup>] # undo it (or name an older _backup-… folder)
shipback <site> --prune --keep 10 # tidy old backups; refuses any holding the only copy of a file
shipback --history [site] # what went up, when, from whereAdd --json to any command for machine-readable output. A refused restore exits with code 4.
--mirror (delete server files that aren't in the local folder) and --no-backup exist for humans who
know they want them. The agent tools don't offer them, and the guard hook
blocks Claude from typing them.
Each deploy writes _backup-YYYY-MM-DD-HHMM/ in the remote root. It holds:
the server's copy of every file the deploy overwrote or deleted
.backup.json, a record of what the deploy added, and a SHA-256 of every file it left on the server
--restore reads that record and checks each live file first:
Live file now | Restore does |
exactly what the deploy uploaded | puts the old copy back (or removes it, if the deploy added it) |
already the old copy | nothing; it counts as already right |
different from both | conflict: stops, names the file, changes nothing ( |
Before writing anything, restore saves the current live files into a new _backup-… folder with its own
record, so --restore on that folder takes you forward again. It also clears the restored paths from
.deploy-manifest.json, so the next deploy compares them by content instead of trusting stale hashes.
Backup folders are skipped by deploys and pulls, and are never deleted except by --prune.
shipback-mcp (bin/mcp.js) is an MCP server over stdio.
Claude Code
claude mcp add shipback-sftp -- npx -y -p shipback-sftp shipback-mcp --sites /path/to/sites.jsonCursor, Claude Desktop, and others (mcp.json / claude_desktop_config.json):
{
"mcpServers": {
"shipback-sftp": {
"command": "npx",
"args": ["-y", "-p", "shipback-sftp", "shipback-mcp", "--sites", "/path/to/sites.json"]
}
}
}On Windows, if the client can't start npx, use "command": "cmd" with "/c", "npx" at the front of
args. After a global install, "command": "shipback-mcp" works too, and from a clone it's node with
bin/mcp.js as the first arg.
Run any CLI command for a site once first (for example shipback mysite --backups). That stores
the password in the OS keychain, where the MCP server reads it. The model never sees it. For CI you can set
SFTP_PASSWORD in the server's environment instead.
Tool | Does |
| the configured sites (no passwords) |
| what would upload; returns a |
| uploads that plan; refuses if anything changed since the preview |
| files edited or added on the live server since the last deploy |
| brings those down into the local folder (local copies backed up) |
| backups, newest first, with what each run changed |
| what an undo would put back and remove, plus any conflicts; returns a |
| runs that undo; refuses on conflicts unless |
| recent deploys, pulls and restores |
What the tools leave out is deliberate: there is no mirror/delete, no way to skip the backup, and no pruning of backups.
Some agent setups can write files but can't run commands. While the local app is running
(npm start, or start.bat on Windows), anything that can write a file can queue a job:
queue/<name>.request.json { "action": "deploy", "site": "mysite", "dryRun": true, "note": "new homepage" }
queue/<name>.result.json ← written when it finishes, with a .log.txt beside itActions: deploy, preview, pull, restore, backups, prune.
npm start opens a small UI on http://127.0.0.1:4646: add sites, preview, deploy, pull, drag in
one-off uploads, browse the server, and see history. It only answers requests from your own machine.
If Claude also runs the CLI directly, add bin/claude-guard.js as a PreToolUse hook. It blocks
--mirror and --no-backup in shell commands, queue files and API calls, and tells Claude why. You can
still run them yourself in a terminal. After npm install -g shipback-sftp, the file is in the folder
npm root -g prints, under shipback-sftp/bin/.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|PowerShell|Write|Edit|MultiEdit",
"hooks": [{ "type": "command", "command": "node /path/to/shipback-sftp/bin/claude-guard.js" }]
}
]
}
}npm testThe suite uses node:test and needs no network. Deploy, restore, the CLI and the MCP server are each
also exercised end to end against a real SFTP server started inside the test run.
It compares by size and SHA-256. The first deploy to a site that already has files reads the server copies of any same-size files to compare them.
Backups live on the same server as the site. They protect against bad deploys, not against losing the hosting account. Keep your host's own backups too.
Files over 8 MB with the same size on both sides are assumed unchanged when there is no manifest hash to compare.
MIT © 2026 Aldo Hushi
Runs aldo.today. Made at BlueprintAU.
Before editing a site's local files: list files that are different or only on the server (someone edited the live site). Changes nothing.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Site name from sites.json (see list_sites) | |
| localDir | No | Local folder to deploy from / compare with. Defaults to the site's localDir. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden; it usefully discloses read-only behavior ('Changes nothing') and why differences exist (someone edited the live site). It says nothing about comparison method (hash vs mtime), output format, or error/permission behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence that front-loads the precondition before the action and ends on the safety guarantee. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read tool with no annotations and no output schema, the description conveys both purpose and the shape of the result (differing/server-only files) plus the non-mutating guarantee. Return format and failure behavior are the only notable omissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters are already documented in the schema, including the localDir default. The description adds no syntax or format detail beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (list) plus precise resource (files that differ or exist only on the server), scoped to a site's local files. The clause 'Changes nothing' implicitly separates it from write-capable siblings like deploy, pull, and restore.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Before editing a site's local files' gives a clear triggering context for when to call it. It does not name the alternative (e.g., pull to sync the changes), so the routing guidance is contextual rather than exhaustive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload the previewed plan. Every file it overwrites is backed up on the server first, and the whole deploy can be undone with restore. Never deletes server files. Refuses if the plan changed since preview_deploy.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Site name from sites.json (see list_sites) | |
| planId | Yes | planId from preview_deploy | |
| localDir | No | Local folder to deploy from / compare with. Defaults to the site's localDir. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full safety burden and does so well: it discloses automatic server-side backups of overwritten files, full undo via restore, that server files are never deleted, and a staleness guard against a changed plan. It omits permissions/auth requirements and any indication of the return/confirmation format, which keeps it out of the top band.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four short sentences, front-loaded with the action, then the safety guarantees, then the blocking precondition. Every sentence carries distinct, relevant information with no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description adequately covers backup, rollback, deletion behavior, and staleness refusal. The main remaining gap is what a successful deploy returns (confirmation/result shape), which is left entirely implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so site, planId, and localDir are already documented in the schema. The description reinforces the planId's origin ('the previewed plan') but adds no format, constraint, or default detail beyond the structured fields; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Upload the previewed plan') and implicitly scopes it apart from preview_deploy (which produces the plan) and restore (which undoes it). An agent can identify this as the commit step of a preview/commit workflow without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Establishes the prerequisite ('the previewed plan' from preview_deploy) and a hard precondition ('Refuses if the plan changed since preview_deploy'), and points to restore as the rollback path. It stops short of an explicit 'use X instead of Y' routing statement, but the workflow context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent deploys, pulls and restores from this machine.
| Name | Required | Description | Default |
|---|---|---|---|
| site | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. 'Recent' hints at reverse-chronological ordering and 'this machine' indicates the data source, but there is no disclosure of default limits, pagination, retention window, or required permissions for a read operation that may span deploy/restore credentials.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with no filler and the identifying content front-loaded. It earns its place, though its brevity is part of the under-specification problem rather than concision discipline.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter, no-output-schema, no-annotation listing tool, the description leaves the parameter roles, result ordering, and result size entirely unexplained. Too little is said for an agent to invoke this confidently alongside eight sibling tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for both 'site' and 'limit', and the description says nothing about either — not that site filters history to one site, nor what limit bounds or defaults to. An agent has no basis for setting these parameters from the description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The fragment names the recorded resource types (deploys, pulls, restores) and the source ('this machine'), which does separate it from the action siblings like deploy and restore. But there is no verb and no scope statement — it never says it lists/queries records, nor whether it covers one site or all sites. Purpose is inferable, not stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance and no mention of alternatives such as list_backups or check_server_changes, which an agent could easily confuse with this historical log. The only contextual cue is 'from this machine', which is about source, not selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the backups on the server, newest first, with what each run overwrote, added and deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Site name from sites.json (see list_sites) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It usefully discloses ordering ('newest first') and the per-run content ('what each run overwrote, added and deleted'), which substitutes for the absent output schema. It says nothing about permissions, pagination, or scope limits on large backup sets.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, front-loaded with the action and resource, with every clause adding information about ordering or returned content. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read tool with no output schema, the description covers the essentials of what is returned and in what order. It stops short of describing pagination or result size limits, which an agent might need on a server with many backups.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'site' parameter is already fully documented in the schema. The description adds no extra meaning about the parameter, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List the backups on the server') plus sort order and the content included per entry. However, it does not distinguish itself from potentially overlapping siblings like 'history' or 'check_server_changes', leaving sibling differentiation to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus alternatives such as 'history', 'preview_restore' or 'restore'. The workflow context (e.g. inspecting backups before a restore) is only implicitly suggested by the tool's existence, not articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the configured sites: name, host, remote root and default local folder. No passwords.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does disclose the returned field set plus the notable negative constraint 'No passwords' — an agent knows it cannot retrieve credentials here. It does not explicitly state read-only/no-side-effects or behavior when no sites are configured, but 'List' strongly conveys the safe-read profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, scope front-loaded, no filler. Every clause adds information: the resource, the returned fields, and the security caveat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description compensates by naming the returned fields, and the zero-parameter schema needs no further explanation. Only minor gaps remain: whether the list is filtered/paginated and what happens when no sites exist.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; baseline 4 applies. The field list that follows the colon describes the return payload rather than inputs, which is the right allocation of words here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (List) plus a specific resource (configured sites), and it enumerates the fields returned (name, host, remote root, default local folder). It is clearly distinguishable from every sibling (history, deploy, pull, restore, etc.), none of which enumerate configured sites.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies when to use it — inventory/discovery of configured sites before deploying or pulling — but the description never states that, nor does it name alternatives or exclusions. Usage is only inferable from the verb.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show what a deploy would upload (new and changed files). Changes nothing. Returns a planId that deploy needs.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Site name from sites.json (see list_sites) | |
| localDir | No | Local folder to deploy from / compare with. Defaults to the site's localDir. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: 'Changes nothing' declares the read-only, non-mutating nature, and it discloses a key output artifact (planId) despite there being no output schema. It omits auth/permission requirements and idempotency details, so it is not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short, front-loaded sentences with no filler. The non-destructive guarantee and the deploy dependency are both stated immediately and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with full schema coverage and no output schema, the description supplies everything an agent needs: what is compared, that nothing is mutated, and the planId return that deploy consumes. No meaningful gap remains.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (site, localDir) are already documented in the schema, including the defaulting behavior for localDir. The description adds no syntax or format meaning beyond that, which is the expected baseline when the schema does the work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Show what a deploy would upload') plus the exact scope (new and changed files), which cleanly separates it from siblings like deploy, preview_restore, and check_server_changes. An agent can tell what it does without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The line 'Returns a planId that deploy needs' tells the agent this is a prerequisite step that feeds deploy, which is strong implied usage guidance. It stops short of an explicit when/when-not rule or naming an alternative it should not be used in place of.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show what restoring a backup would put back and remove, and any conflicts (live files edited after that run). Changes nothing. Returns a planId that restore needs.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Site name from sites.json (see list_sites) | |
| backup | No | Backup folder name, e.g. _backup-2026-10-18-1400. Default: the newest. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it declares the operation is non-mutating, specifies the conflict condition ('live files edited after that run'), and discloses a required output artifact (planId) consumed by restore. It omits auth/permission needs and whether a planId expires, which keeps it short of 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, zero waste. The non-mutating guarantee is front-loaded right after the purpose, and the planId handoff closes the loop with restore.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, so the description must convey return semantics; it names both the conflict information and the planId, which are the two things an agent needs. A brief note on the plan's shape (added/removed/conflicted file counts) or permission requirements would make it fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both 'site' and 'backup' are fully documented in the schema (including the newest-backup default and the list_sites cross-reference). The description adds no additional parameter detail, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('show what restoring a backup would put back and remove'), and immediately distinguishes it from the sibling restore by declaring 'Changes nothing.' An agent can tell this is the dry-run counterpart to restore without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'Changes nothing' plus 'Returns a planId that restore needs' effectively encodes the workflow: call this preview before invoking restore. It does not explicitly state exclusions or prerequisites (e.g., must a backup exist first), but the sibling routing is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download the server-side changes into the local folder, so local is the truth before editing. Local files it overwrites are backed up in /_backup-/. Never deletes local files.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Site name from sites.json (see list_sites) | |
| localDir | No | Local folder to deploy from / compare with. Defaults to the site's localDir. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does most of it well: it discloses that local files get overwritten, that overwritten files are preserved in <localDir>/_backup-<stamp>/, and that local files are never deleted. It says nothing about permission/auth requirements or what the call reports back, which is the remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the action and followed by the safety guarantees. Each sentence earns its place; nothing is padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter tool with no output schema and no annotations, the description covers direction, side effects, and rollback safety. It leaves conflict/merge behavior and the result of the call unstated, which keeps it just short of complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so both parameters are already documented in the schema, making 3 the baseline. The description references <localDir> and thereby reinforces how the parameter is used, but adds no new format or default semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Download the server-side changes into the local folder') and the directionality makes it unmistakable next to siblings like deploy and restore, which push the other way. An agent can pick this over check_server_changes without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'so local is the truth before editing' gives a clear situational trigger for when to run it. There is no explicit when-not guidance and no sibling named as an alternative, so it stops short of a full 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Undo a deploy: put the backed-up files back and remove the files that run added. Backs up the current live files first, so the restore can itself be restored. Refuses on conflicts unless force is true; only pass force when the user has seen the conflicts and said to go ahead.
| Name | Required | Description | Default |
|---|---|---|---|
| site | Yes | Site name from sites.json (see list_sites) | |
| force | No | Restore over files edited on the server since that run (they are backed up first) | |
| backup | Yes | Backup folder name from preview_restore | |
| planId | Yes | planId from preview_restore |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the destructive action (removing files the run added), the reversibility guarantee (live files are backed up first, so the restore itself can be restored), and conflict behavior (refuses unless force is true). It omits permissions/auth requirements and what happens on partial failure, but the safety profile is genuinely well covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences with no filler, led by the core purpose. Each subsequent sentence adds distinct value: scope of file changes, reversibility, and the force precondition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter mutation tool with no annotations and no output schema, the description covers destruction, reversibility, and conflict handling adequately. Losing the point for the missing dependency on preview_restore (only discoverable via schema text) and any mention of permissions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the mechanical parameter docs are already handled (baseline 3). The description adds safe-use semantics for force beyond the schema's terse 'restore over files edited on the server,' by tying it to a user-confirmation precondition, which meaningfully qualifies how the parameter should be set.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Undo a deploy') and then spells out exactly what that means operationally: backed-up files return and files added by the run are removed. This clearly separates it from deploy and preview_deploy, though it never names preview_restore as the required predecessor even though the schema depends on it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit when-to-use rule for the force flag ('only pass force when the user has seen the conflicts and said to go ahead'), which is a real constraint. However, it offers no guidance on the overall workflow (e.g., that preview_restore must run first) or when to prefer it over pull/check_server_changes, leaving the tool-selection context implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0check_server_changesdeployhistorylist_backupslist_sitespreview_deploypreview_restorepullrestoreScored across 9 tools
Tools are clearly delineated: preview/deploy and preview/restore form explicit two-step pairs, while check_server_changes vs pull are complementary but distinct. No overlapping purposes or ambiguous boundaries.
Mostly action-oriented and consistent with list_*, preview_*, check_*, and bare verbs like deploy, pull, restore. 'history' is the lone noun, and mixing bare verbs with verb_noun is a minor deviation.
9 tools is well within the ideal range. Each maps to a distinct step in the deploy/pull/restore workflow with no filler or redundancy.
Core lifecycle is covered: list sites, preview/deploy, preview/restore, pull, check changes, and list backups. Gaps include no management of local backups created by pull and no add/edit/remove site operations (only list_sites).
Agent-first web hosting: deploy sites, apps, databases and domains over MCP.
Agent-native web hosting — deploy sites, manage DNS, register domains, scale infrastructure
Agent-to-agent cloud service: deploys and runs your apps and services — domains, logs, real status.
App hosting your agent runs: git, deploys, staging/production, Postgres. Owner approves risky steps.
