Add a new validate-schemas job to the CI workflow that ensures the
committed JSON schemas in the schemas/ directory are up-to-date with
the schema generation script. This prevents drift between the source
code and generated schemas.
The job:
- Runs the schema generation script (yarn build:schema)
- Checks if any schemas were modified
- Fails if changes are detected, prompting developers to regenerate
and commit the schemas
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Apply proper type distinction:
- Reading/validating existing manifests: Use McpbManifest (any version)
- Building/creating new manifests: Use McpbManifestLatest (latest only)
Changes:
- src/shared/config.ts: Revert to McpbManifest for config operations
- src/cli/init.ts: Use McpbManifestLatest for new manifest creation
- test/config.test.ts: Use McpbManifest for testing config operations
This ensures backward compatibility when reading existing manifests
while enforcing latest schema for new builds.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
Update manifest type usage in config and packaging to strictly enforce
the latest schema version (0.3) instead of accepting any version.
Changes:
- src/shared/config.ts: Use McpbManifestLatest instead of McpbManifest
- src/types.ts: Add McpbManifestLatest type export
- test/config.test.ts: Update tests to use McpbManifestLatest
This ensures BUILD manifests are validated against the latest schema
only during packaging, preventing use of older schema versions.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
- Remove duplicate node:path import in test/icon-validation.test.ts
- Replace 4 instances of 'any' type with 'unknown' in error handlers
- Auto-format code with prettier (27 formatting fixes)
Addresses review feedback from PR #136
All 6 errors and 27 warnings resolved
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.
Reverted the discriminated union type change. McpbManifest now uses
the latest schema as before. Consumers can use versioned schemas
directly if they need to validate specific versions.
Remove the generic mcpb-manifest.schema.json export from package.json
in favor of explicit versioned exports.
Changes:
- Removed ./mcpb-manifest.schema.json from package exports
- Stop generating mcpb-manifest.schema.json in dist/
- Keep mcpb-manifest.schema.json in schemas/ for backward compatibility
Consumers should now use:
- mcpb-manifest-latest.schema.json (for latest version)
- mcpb-manifest-v0.1.schema.json (for specific version)
- etc.
This makes versioning explicit and prevents ambiguity about which
schema version is being used.
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'
Changed McpbManifest type from a single version to a discriminated union
of all historical manifest versions (0.1, 0.2, 0.3).
This allows the type system to properly handle manifests from any version
while maintaining type safety through the manifest_version/dxt_version
discriminator field.
Benefits:
- Type-safe handling of multiple manifest versions
- TypeScript can narrow types based on version field
- No need for type assertions when working with versioned manifests
- Maintains backward compatibility with all historical versions
Add exports for versioned schemas to allow consumers to import:
- ./schemas: All versioned schemas (v0_1, v0_2, v0_3, latest)
- ./schemas/*: Specific schema versions (./schemas/0.1, ./schemas/any, etc.)
- ./schemas-loose: Loose validation schemas
This enables cleaner imports like:
import { McpbManifestSchema } from '@anthropic-ai/mcpb/schemas/any'
import * as v0_2 from '@anthropic-ai/mcpb/schemas/0.2'
import * as schemas from '@anthropic-ai/mcpb/schemas'
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.
- 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>
- Add comprehensive contributing guidelines with setup instructions, workflow, and code standards
- Rename LICENSE.md to LICENSE to follow standard naming convention and fix README link
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
