MCP server exposing Backblaze B2 Cloud Storage operations as tools
Strong tool definitions with complete schemas, clear descriptions, and proper error handling. All 9 tools have explicit registrations with inputSchema and descriptions. Tool names follow verb_noun pattern (list_*, upload_*, download_*, delete_*, hide_*, unhide_*). Descriptions are detailed (100-250 chars) and explain WHAT, WHEN, and consequences. Parameters are typed with Zod and have descriptions. Key strength: security-conscious design (path sandboxing, fileId requirement for deletion). Weakness: output schemas are not formally documented, responses are JSON-stringified but structure is not declared in tool definitions. Error handling returns actionable messages via toMessage() helper. Tool annotations (readOnlyHint, destructiveHint, idempotentHint) are present and accurate.
Reports storage used per bucket against a budget. B2 exposes no usage endpoint, so this is computed by summing file versions. The figure EXCLUDES unfinished large-file parts, which B2 does bill for; the count of such uploads is reported beside the bytes so a caller knows what the number leaves out. It is a floor, not a ceiling.
Permanently destroys one version of a file. B2 cannot undo this. The caller must supply the exact fileId; this function never resolves one from a file name. That is the safety mechanism: an id has to come from b2_list_files, where a human can see which version is at stake, so a vague or injected instruction cannot cascade into destruction nobody reviewed.
Downloads a file from a bucket to the local filesystem and returns where it landed, its size, type, and SHA-1. The destination must sit inside the directory named by B2_DOWNLOAD_ROOT. An existing file is not replaced unless overwrite is true. File content is never returned, only the path it was written to.
Hides a file so it stops appearing in b2_list_files. Reversible: the data stays in version history and b2_unhide_file restores it. Prefer this over deleting when the goal is to remove something from view.
Output schemas not formally documented in tool definitions. Responses are JSON-stringified but structure (fields, types, required properties) is not declared. LLMs cannot plan downstream operations or validate response structure.
Pagination not explicitly documented for b2_list_files. Description mentions 'truncated' and 'nextFileName' in response but tool definition lacks limit/offset parameters in schema description. Agents may not know how to fetch subsequent pages.
b2_bucket_usage has optional bucketName parameter but description does not clarify behavior when omitted ('scan every bucket'). Agents may not understand the scope change.
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | C | 61 | 2026-07-28+ | v2 |
Lists the buckets the configured application key can see, as JSON objects with bucketId, bucketName, and bucketType. A key restricted to one bucket sees only that bucket; the result reports scopedToBucketId so a narrowed listing is never mistaken for the whole account.
Lists one page of current files in a bucket, as JSON objects with fileName, fileId, contentLength, contentType, and uploadedAt. Optionally filtered by name prefix. The result reports truncated and nextFileName when more files exist beyond the page.
Lists the account's application keys as plain data, sorted by name. The B2 list response contains NO key secrets. Listing costs one extra call to resolve bucket ids to names, which turns an opaque hex restriction into something a person can read.
Removes the latest hide marker, making a hidden file visible again. If the file was not hidden, this reports restored false rather than failing.
Uploads a file from the local filesystem into a bucket and returns the stored file id, name, size, and type. The local path must sit inside the directory named by B2_UPLOAD_ROOT; uploads are refused otherwise. Uploading an existing name adds a new version rather than replacing the old one.
Error recovery guidance is minimal. toMessage() helper extracts error details but tool descriptions do not suggest recovery steps (e.g., 'If bucket not found, call b2_list_buckets to verify name').
b2_upload_file and b2_download_file rely on environment variables (B2_UPLOAD_ROOT, B2_DOWNLOAD_ROOT) for path sandboxing but these are not documented in tool descriptions. Agents cannot know the constraints without reading server code.