mcpb

Validates MCP extension manifests against multiple schema versions (0.1, 0.2, 0.3) using Zod runtime validation. Provides dual validation modes: strict schemas enforce exact manifest structure for production bundles, while loose schemas allow passthrough and auto-correction during bundle cleaning operations. Schemas are versioned independently to support backward compatibility and gradual migration paths for extension developers.

Packages MCP extensions into self-contained .mcpb files (ZIP archives with maximum compression level 9 via fflate library) that include manifest.json, server code, all runtime dependencies (node_modules, Python venv, or server/lib), visual assets, and localization files. Preserves Unix file permissions for executable binaries and includes SHA1 hash metadata for integrity verification. Supports configurable entry points and platform-specific dependency inclusion.

Provides optional cryptographic signature system for .mcpb bundles to verify integrity and authenticity. Supports signing bundles with private keys and verifying signatures with public keys. Stores signature metadata in bundle manifest or separate signature files. Enables marketplace platforms to verify that bundles come from trusted publishers and haven't been tampered with. Uses industry-standard cryptographic algorithms (RSA, ECDSA, or similar).

Enables MCP extensions to define user-configurable settings through manifest.json userConfiguration field with type-safe schemas. Supports various configuration types (string, number, boolean, enum, object) with validation rules (min/max, pattern, required). Generates configuration UI hints for desktop apps and web interfaces. Validates user-provided configuration values against schema before passing to server. Supports configuration persistence and default values.

Enables MCP extensions to declare available tools (functions the server exposes) and prompts (pre-written prompts for LLM interaction) in manifest.json with full schema validation. Tools include name, description, input schema, and output schema. Prompts include name, description, and template text. Manifest system validates that declared tools and prompts match actual server implementation. Enables client applications to discover and display available tools/prompts without executing server.

Manages visual assets (icons, screenshots, banners) and localization files (translations for multiple languages) within bundles through manifest.json asset specifications. Supports multiple icon sizes and formats, screenshot galleries, and localized manifest fields (name, description in different languages). Validates asset file references and formats. Enables marketplace platforms to display localized extension information and assets. Supports asset compression and optimization within bundles.

Extracts .mcpb ZIP archives with automatic restoration of Unix file permissions from ZIP extra fields, selective file extraction based on manifest specifications, and validation of bundle structure during unpacking. Supports extracting to custom directories and preserves the original bundle structure (manifest.json at root, server code in specified directory, dependencies in node_modules/venv). Includes integrity checks to ensure no files were corrupted during extraction.

Enables MCP bundles to define platform-specific server configurations, dependencies, and assets through manifest.json platform overrides (e.g., separate Node.js entry points for macOS vs Windows, different Python venv paths). Supports variable substitution syntax for dynamic values like ${HOME}, ${PLATFORM}, ${ARCH} that are resolved at installation time. Allows conditional inclusion of dependencies and assets based on target platform, reducing bundle size and ensuring correct runtime configuration.

Validates complete .mcpb bundles by checking manifest.json conformance to schema, verifying required files exist (server code, dependencies), confirming SHA1 hashes match, and validating asset references (icons, screenshots, localization files). Performs structural validation to ensure bundle ZIP format is correct and all referenced paths are present. Returns detailed error reports identifying missing files, schema violations, and hash mismatches.

Automatically corrects and normalizes manifest.json files using loose schema validation, removing extraneous fields, fixing common formatting issues, and ensuring all required fields are present with valid values. Uses loose Zod schemas that allow passthrough to capture unexpected fields, then reconstructs a clean manifest conforming to strict schema. Supports in-place cleaning of bundles or generating cleaned copies. Useful for migrating legacy manifests or fixing malformed bundles.

Provides command-line interface with five core commands: mcpb init (scaffold new extension), mcpb pack (create bundle), mcpb unpack (extract bundle), mcpb validate (check bundle integrity), mcpb clean (auto-correct manifest). Each command maps to underlying programmatic APIs and supports flags for configuration (--output, --platform, --strict). Commands can be chained in build scripts and CI/CD pipelines. Supports both global and local installation via npm.

Exports TypeScript/JavaScript APIs for all bundle operations (pack, unpack, validate, clean, init) as importable functions from @anthropic-ai/mcpb package. Enables programmatic bundle creation and manipulation in Node.js applications, build tools, and desktop app installers. Provides type-safe interfaces for manifest objects, configuration, and validation results. Supports both CommonJS and ES module imports.

Provides browser-compatible JavaScript API for reading and validating .mcpb bundles in web applications, without requiring Node.js. Uses browser-compatible ZIP parsing libraries to extract and inspect bundle contents. Enables web-based bundle viewers, marketplace interfaces, and validation tools. Supports manifest validation and asset preview (icon display, localization inspection) in browser context.

Automatically generates Zod validation schemas from TypeScript type definitions, enabling type-safe manifest validation without manually writing schema definitions. Uses TypeScript compiler API to parse type definitions and generate corresponding Zod schemas. Supports schema versioning and evolution by generating separate schemas for each manifest version. Enables strict and loose schema variants from single type definition.