# MCPB CLI Documentation The MCPB CLI provides tools for building MCP Bundles. ## Installation ```bash npm install -g @anthropic-ai/mcpb ``` ``` Usage: mcpb [options] [command] Tools for building MCP Bundles Options: -V, --version output the version number -h, --help display help for command Commands: init [directory] Create a new MCPB extension manifest validate Validate a MCPB manifest file pack [output] Pack a directory into a MCPB extension sign [options] Sign a MCPB extension file verify Verify the signature of a MCPB extension file info Display information about a MCPB extension file unsign Remove signature from a MCPB extension file help [command] display help for command ``` ## Commands ### `mcpb init [directory]` Creates a new MCPB extension manifest interactively. ```bash # Initialize in current directory mcpb init # Initialize in a specific directory mcpb init my-extension/ ``` The command will prompt you for: - Extension name (defaults from package.json or folder name) - Author name (defaults from package.json) - Extension ID (auto-generated from author and extension name) - Display name - Version (defaults from package.json or 1.0.0) - Description - Author email and URL (optional) - Server type (Node.js, Python, or Binary) - Entry point (with sensible defaults per server type) - Tools configuration - Keywords, license, and repository information After creating the manifest, it provides helpful next steps based on your server type. ### `mcpb validate ` Validates a MCPB manifest file against the schema. You can provide either a direct path to a manifest.json file or a directory containing one. ```bash # Validate specific manifest file mcpb validate manifest.json # Validate manifest in directory mcpb validate ./my-extension mcpb validate . ``` ### `mcpb pack [output]` Packs a directory into a MCPB extension file. ```bash # Pack current directory into extension.mcpb mcpb pack . # Pack with custom output filename mcpb pack my-extension/ my-extension-v1.0.mcpb ``` The command automatically: - Validates the manifest.json - Excludes common development files (.git, node_modules/.cache, .DS_Store, etc.) - Creates a compressed .mcpb file (ZIP with maximum compression) ### `mcpb sign ` Signs a MCPB extension file with a certificate. ```bash # Sign with default certificate paths mcpb sign my-extension.mcpb # Sign with custom certificate and key mcpb sign my-extension.mcpb --cert /path/to/cert.pem --key /path/to/key.pem # Sign with intermediate certificates mcpb sign my-extension.mcpb --cert cert.pem --key key.pem --intermediate intermediate1.pem intermediate2.pem # Create and use a self-signed certificate mcpb sign my-extension.mcpb --self-signed ``` Options: - `--cert, -c`: Path to certificate file (PEM format, default: cert.pem) - `--key, -k`: Path to private key file (PEM format, default: key.pem) - `--intermediate, -i`: Paths to intermediate certificate files - `--self-signed`: Create a self-signed certificate if none exists ### `mcpb verify ` Verifies the signature of a signed MCPB extension file. ```bash mcpb verify my-extension.mcpb ``` Output includes: - Signature validity status - Certificate subject and issuer - Certificate validity dates - Certificate fingerprint - Warning if self-signed ### `mcpb info ` Displays information about a MCPB extension file. ```bash mcpb info my-extension.mcpb ``` Shows: - File size - Signature status - Certificate details (if signed) ### `mcpb unsign ` Removes the signature from a MCPB extension file (for development/testing). ```bash mcpb unsign my-extension.mcpb ``` ## Certificate Requirements For signing extensions, you need: 1. **Certificate**: X.509 certificate in PEM format - Should have Code Signing extended key usage - Can be self-signed (for development) or CA-issued (for production) 2. **Private Key**: Corresponding private key in PEM format - Must match the certificate's public key 3. **Intermediate Certificates** (optional): For CA-issued certificates - Required for proper certificate chain validation ## Example Workflows ### Quick Start with Init ```bash # 1. Create a new extension directory mkdir my-awesome-extension cd my-awesome-extension # 2. Initialize the extension mcpb init # 3. Follow the prompts to configure your extension # The tool will create a manifest.json with all necessary fields # 4. Create your server implementation based on the entry point you specified # 5. Pack the extension mcpb pack . # 6. (Optional) Sign the extension mcpb sign my-awesome-extension.mcpb --self-signed ``` ### Development Workflow ```bash # 1. Create your extension mkdir my-extension cd my-extension # 2. Initialize with mcpb init or create manifest.json manually mcpb init # 3. Implement your server # For Node.js: create server/index.js # For Python: create server/main.py # For Binary: add your executable # 4. Validate manifest mcpb validate manifest.json # 5. Pack extension mcpb pack . my-extension.mcpb # 6. (Optional) Sign for testing mcpb sign my-extension.mcpb --self-signed # 7. Verify signature mcpb verify my-extension.mcpb # 8. Check extension info mcpb info my-extension.mcpb ``` ### Production Workflow ```bash # 1. Pack your extension mcpb pack my-extension/ # 2. Sign with production certificate mcpb sign my-extension.mcpb \ --cert production-cert.pem \ --key production-key.pem \ --intermediate intermediate-ca.pem root-ca.pem # 3. Verify before distribution mcpb verify my-extension.mcpb ``` ## Excluded Files When packing an extension, the following files/patterns are automatically excluded: - `.DS_Store`, `Thumbs.db` - `.gitignore`, `.git/` - `*.log`, `npm-debug.log*`, `yarn-debug.log*`, `yarn-error.log*` - `.npm/`, `.npmrc`, `.yarnrc`, `.yarn/`, `.pnp.*` - `node_modules/.cache/`, `node_modules/.bin/` - `*.map` - `.env.local`, `.env.*.local` - `package-lock.json`, `yarn.lock` ### Custom Exclusions with .mcpbignore You can create a `.mcpbignore` file in your extension directory to specify additional files and patterns to exclude during packing. This works similar to `.npmignore` or `.gitignore`: ``` # .mcpbignore example # Comments start with # *.test.js src/**/*.test.ts coverage/ *.log .env* temp/ docs/ ``` The `.mcpbignore` file supports: - **Exact matches**: `filename.txt` - **Simple globs**: `*.log`, `temp/*` - **Directory paths**: `docs/`, `coverage/` - **Comments**: Lines starting with `#` are ignored - **Empty lines**: Blank lines are ignored When a `.mcpbignore` file is found, the CLI will display the number of additional patterns being applied. These patterns are combined with the default exclusion list. ## Technical Details ### Signature Format MCPB uses PKCS#7 (Cryptographic Message Syntax) for digital signatures: - Signatures are stored in DER-encoded PKCS#7 SignedData format - The signature is appended to the MCPB file with markers (`MCPB_SIG_V1` and `MCPB_SIG_END`) - The entire MCPB content (excluding the signature block) is signed - Detached signature format - the original ZIP content remains unmodified ### Signature Structure ``` [Original MCPB ZIP content] MCPB_SIG_V1 [4-byte little-endian length prefix] [DER-encoded PKCS#7 signature] MCPB_SIG_END ``` This approach allows: - Backward compatibility (unsigned MCPB files are valid ZIP files) - Easy signature verification and removal - Support for certificate chains with intermediate certificates