mcp-bundle

A Claude Code plugin and GitHub Actions workflow for generating MCPB (MCP Bundle) packages from MCP server projects.

Prerequisites

• An MCP server project using stdio transport
• Node.js 20+ (for Node.js server types and the mcpb CLI)
• jq installed (used by validation scripts)
• For local testing: npm install -g @anthropic-ai/mcpb

What It Does

• /mcpb skill: Detects MCP server projects, generates manifest.json, creates bundle directory structure, validates against the MCPB spec, and wires in CI/CD
• Reusable GitHub Actions workflow: Full CI/CD pipeline for MCPB packaging with build, test, validate, package, and release steps
• Composite GitHub Action: Marketplace-published action for validate, package, checksum, and upload steps within an existing workflow

Installation

As a Claude Code Plugin

Add this repository as a plugin dependency in your Claude Code project, then use /mcpb in any MCP server project.

As a GitHub Actions Reusable Workflow

Reference the reusable workflow at the job level in your caller workflow:

name: Package MCP Bundle
on:
  push:
    tags: ['v*']

jobs:
  package:
    uses: zircote/mcp-bundle/.github/workflows/mcp-bundle.yml@v1
    with:
      source-files: "src/**"

As a GitHub Actions Composite Action (Marketplace)

Reference the action at the step level within an existing job:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: actions/setup-node@v6
        with:
          node-version: '20'
      - run: npm ci && npm run build && npm test
      - uses: zircote/mcp-bundle@v1

Reusable Workflow vs. Composite Action

| Feature | Reusable Workflow | Composite Action | |---------|-------------------|------------------| | Usage | uses: at job level | uses: at step level | | Checkout & setup | Handled automatically | You handle in prior steps | | Build & test | Configurable via inputs | You handle in prior steps | | File selection | Via source-files, config-files, additional-artifacts inputs | Bundles working directory; use .mcpbignore to exclude | | Manifest validation | Full (11 checks) | Full (11 checks) | | Bundle packaging | Yes | Yes | | SHA-256 checksum | Yes | Yes | | Artifact upload | Yes | Yes | | Release attachment | Yes | Yes | | Best for | Standalone CI/CD pipeline | Integration into existing workflows |

/mcpb Skill Usage

Run /mcpb in a project directory containing an MCP server. The skill will:

1. Detect the MCP server implementation (Node.js, Python, UV, or binary)
2. Generate a valid manifest.json following the MANIFEST.md spec
3. Create the bundle directory structure
4. Validate the manifest against schema rules
5. Wire in a CI/CD caller workflow that invokes the reusable packaging workflow

Detection Signals

| Language | Detection Criteria | |----------|-------------------| | Node.js | @modelcontextprotocol/sdk in dependencies, StdioServerTransport usage | | Python | mcp package imports, stdio_server() usage, pyproject.toml with MCP deps | | Python UV | pyproject.toml with mcp dep, no server/lib/ or server/venv/ | | Binary | Compiled server executables, Cargo.toml/go.mod with MCP dependencies |

Reusable Workflow Reference

Inputs

| Input | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | source-files | string | no | src/** | Glob pattern(s) for source files (comma-separated). Fails if no files match — ensure patterns match your project layout | | manifest-path | string | no | manifest.json | Path to manifest.json | | config-files | string | no | "" | Glob pattern(s) for config files to include | | additional-artifacts | string | no | "" | Glob pattern(s) for extra files to bundle | | node-version | string | no | "20" | Node.js version for build environment | | build-command | string | no | npm run build | Shell command via bash -c before packaging. Arbitrary code execution — never set from untrusted input | | test-command | string | no | npm test | Shell command via bash -c before packaging (empty to skip). Arbitrary code execution | | bundle-name | string | no | "" | Override bundle output filename | | upload-artifact | boolean | no | true | Upload bundle as GitHub Actions artifact | | create-release-asset | boolean | no | false | Attach bundle to GitHub Release (tag pushes only) | | mcpb-version | string | no | latest | Version of mcpb toolchain | | runs-on | string | no | ubuntu-latest | Runner label for the packaging job |

Outputs

| Output | Description | |--------|-------------| | bundle-path | Path to the generated .mcpb bundle file | | bundle-sha256 | SHA-256 checksum of the bundle | | manifest-valid | Whether manifest validation passed (true/false) |

Composite Action Reference

The composite action bundles the entire working directory (you handle checkout, build, and file selection in prior steps). Use .mcpbignore to exclude files.

Inputs

| Input | Type | Required | Default | Description | |-------|------|----------|---------|-------------| | manifest-path | string | no | manifest.json | Path to manifest.json | | bundle-name | string | no | "" | Override bundle output filename | | upload-artifact | string | no | "true" | Upload bundle as GitHub Actions artifact | | create-release-asset | string | no | "false" | Attach bundle to GitHub Release (tag pushes only) | | mcpb-version | string | no | latest | Version of mcpb toolchain |

Outputs

| Output | Description | |--------|-------------| | bundle-path | Path to the generated .mcpb bundle file | | bundle-sha256 | SHA-256 checksum of the bundle | | manifest-valid | Whether manifest validation passed (true/false) |

Manifest Validation Checks

Both the reusable workflow and composite action perform these 11 validation checks:

1. All required fields present (manifest_version, name, version, description, author.name, server.type, server.entry_point)
2. server.type is one of: node, python, binary, uv
3. version is valid semver
4. UV server type requires manifest_version: "0.4"
5. compatibility.platforms values are valid (darwin, win32, linux)
6. server.entry_point file exists (warning if missing, expected when build produces it)
7. user_config field types are valid (string, number, boolean, directory, file)
8. All ${user_config.*} variable references have matching user_config entries
9. No duplicate tool names in tools array
10. Each tool entry has both name and description
11. JSON is well-formed and parseable

Example Caller Workflows

See the examples/ directory for complete caller workflow files:

• minimal-caller.yml — bare minimum
• standard-caller.yml — with config files and Node.js 20
• advanced-caller.yml — with release assets and custom build
• binary-caller.yml — pre-compiled binary server packaging

Bundle Structure

Generated bundles follow the MCPB spec. Structure varies by server type:

bundle.mcpb (ZIP)
├── manifest.json          # Required
├── server/
│   └── index.js           # Node.js entry point
│       main.py            # Python entry point
│       <binary>           # Binary entry point
├── node_modules/          # Node.js only
├── package.json           # Node.js only (optional)
├── pyproject.toml         # UV runtime only
├── requirements.txt       # Python only (optional)
├── icon.png               # Optional
└── .mcpbignore            # Exclusion rules

Testing

Run the test suite:

./tests/test-manifest-validation.sh

The test suite covers:

• Manifest validation: required fields, semver, server types, UV version constraint, platforms, config types, variable substitution refs, duplicate tools
• JSON structure validation for all fixtures
• Workflow and action YAML structure verification
• Glob pattern sanitization and shell metacharacter rejection
• Bundle filename sanitization (path-traversal and empty-name guards)
• Bundle structure validation (manifest.json at root, entry_point presence)
• .mcpbignore pattern matching: basename, path-relative, directory, negation handling
• copy_glob() fail-fast behavior and zero-match detection
• Security audit: GH_TOKEN sourcing, bash -c vs eval, VERSION/BNAME sanitization
• Skill file structure and content completeness
• Example workflow presence and references

.mcpbignore

Create a .mcpbignore file in your repository root to exclude files from the bundle. Format is similar to .gitignore:

# Comments start with #
*.log                # basename: matches *.log at any depth
dist/debug.log       # path-relative: only dist/debug.log
tests/               # directory: removes tests/ anywhere
__pycache__/         # directory: removes all __pycache__ dirs

• Blank lines and lines starting with # are ignored
• Patterns ending with / match directories anywhere in the bundle (e.g. __pycache__/)
• Patterns containing / (not trailing) match path-relative files (e.g. dist/debug.log)
• All other patterns match by filename at any depth (e.g. *.log)
• Negation patterns (!pattern) are not supported and are skipped with a warning

Security Considerations

Note: The reusable workflow uses bash -c to execute user-provided build-command and test-command inputs. These values are passed via environment variables (not interpolated directly into shell), so they are not subject to YAML injection. However, they come from workflow_call inputs (set by the calling workflow author), so avoid passing untrusted values through these inputs.

License

MIT