feat: add comprehensive icon validation to mcpb validate command

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.
This commit is contained in:
Bryan Thompson 2025-10-28 09:14:12 -05:00
commit ccf9470979
No known key found for this signature in database
GPG key ID: 1D66D91917EE02E6

View file

@ -6,12 +6,12 @@
},
"dxt_version": {
"type": "string",
"const": "0.2",
"const": "0.3",
"description": "@deprecated Use manifest_version instead"
},
"manifest_version": {
"type": "string",
"const": "0.2"
"const": "0.3"
},
"name": {
"type": "string"
@ -80,12 +80,54 @@
"icon": {
"type": "string"
},
"icons": {
"type": "array",
"items": {
"type": "object",
"properties": {
"src": {
"type": "string"
},
"sizes": {
"type": "string",
"pattern": "^\\d+x\\d+$"
},
"theme": {
"type": "string",
"minLength": 1
}
},
"required": [
"src",
"sizes"
],
"additionalProperties": false
}
},
"screenshots": {
"type": "array",
"items": {
"type": "string"
}
},
"localization": {
"type": "object",
"properties": {
"resources": {
"type": "string",
"pattern": "\\$\\{locale\\}"
},
"default_locale": {
"type": "string",
"pattern": "^[A-Za-z0-9]{2,8}(?:-[A-Za-z0-9]{1,8})*$"
}
},
"required": [
"resources",
"default_locale"
],
"additionalProperties": false
},
"server": {
"type": "object",
"properties": {
@ -313,6 +355,13 @@
],
"additionalProperties": false
}
},
"_meta": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {}
}
}
},
"required": [