Implements icon validation to catch common issues that prevent icons from
displaying in Claude Desktop. Uses a non-blocking warning approach for
remote URLs to maintain flexibility for MCPB's evolving multi-platform
ecosystem.
## Changes
### Core Implementation (src/node/validate.ts)
- Add `isPNG()` helper to validate PNG file signatures via magic bytes
- Add `validateIcon()` function with comprehensive checks:
- **Warn** about remote URLs (non-blocking, best practice guidance)
- **Reject** ${__dirname} variable usage in icon field (doesn't work)
- **Reject** absolute paths (not portable)
- Verify icon file exists at specified path
- Verify icon file is valid PNG format
- Recommend 512×512 size for Claude Desktop
- Integrate icon validation into `validateManifest()` after schema validation
### Test Coverage
- Update `test/icon-validation.test.ts` - Remote URL test now expects warning
- Update `test/cli.test.ts` - Integration test updated for warnings
- All 109 tests passing
### Documentation Updates
- Update examples/hello-world-node/manifest.json to v0.3
## Validation Behavior
**Remote URLs (WARNING - non-blocking):**
```
Icon path uses a remote URL. Best practice for local MCP servers:
Use local files like "icon": "icon.png" for maximum compatibility.
Claude Desktop currently only supports local icon files in bundles.
```
**Result:** Validation passes, developer is informed
**Other Issues (ERROR - blocking):**
- ${__dirname} usage: Rejects (doesn't work)
- Absolute paths: Rejects (not portable)
- Missing files: Rejects (broken reference)
- Non-PNG files: Rejects (wrong format)
## Rationale
**Non-Blocking Approach:**
- Doesn't prevent valid bundles from being created
- Educates developers about best practices
- Maintains flexibility as MCPB evolves beyond Claude Desktop
- Future-proof if remote URL support is added
**Still Protective:**
- Blocks truly broken configurations (missing files, wrong formats)
- Provides actionable error messages for fixable issues
Based on real-world findings from investigating icon display issues in
Claude Desktop with production MCPB bundles.
Removed the non-versioned mcpb-manifest.schema.json from schemas/
directory. All schemas are now explicitly versioned.
Available schemas:
- mcpb-manifest-v0.1.schema.json
- mcpb-manifest-v0.2.schema.json
- mcpb-manifest-v0.3.schema.json
- mcpb-manifest-latest.schema.json
Consumers should use -latest or specific version to be explicit
about which schema version they're validating against.
Updated build script to generate JSON schemas for all historical manifest
versions (v0.1, v0.2, v0.3) in addition to the latest version.
Changes:
- Generate mcpb-manifest-v0.1.schema.json
- Generate mcpb-manifest-v0.2.schema.json
- Generate mcpb-manifest-v0.3.schema.json
- Generate mcpb-manifest-latest.schema.json
- Keep mcpb-manifest.schema.json as alias for latest
- All schemas generated to both dist/ and schemas/ directories
- Added exports in package.json for all versioned schemas
Benefits:
- Tools can validate against specific manifest versions
- Backwards compatibility for all historical versions
- Latest schema always available at predictable path
- JSON schema files match the Zod schema versions
Usage:
import manifestSchema from '@anthropic-ai/mcpb/mcpb-manifest-v0.2.schema.json'
import latestSchema from '@anthropic-ai/mcpb/mcpb-manifest-latest.schema.json'
- Refactor JSON schema generation to use zod-to-json-schema
- Publish manifest schema to schemas/ directory
- Update package.json exports for schema files
- Add WIP version 0.3 support
- Clean up schema generation scripts
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
