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.
376 lines
No EOL
7.7 KiB
JSON
376 lines
No EOL
7.7 KiB
JSON
{
|
|
"type": "object",
|
|
"properties": {
|
|
"$schema": {
|
|
"type": "string"
|
|
},
|
|
"dxt_version": {
|
|
"type": "string",
|
|
"const": "0.3",
|
|
"description": "@deprecated Use manifest_version instead"
|
|
},
|
|
"manifest_version": {
|
|
"type": "string",
|
|
"const": "0.3"
|
|
},
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"display_name": {
|
|
"type": "string"
|
|
},
|
|
"version": {
|
|
"type": "string"
|
|
},
|
|
"description": {
|
|
"type": "string"
|
|
},
|
|
"long_description": {
|
|
"type": "string"
|
|
},
|
|
"author": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"email": {
|
|
"type": "string",
|
|
"format": "email"
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "uri"
|
|
}
|
|
},
|
|
"required": [
|
|
"name"
|
|
],
|
|
"additionalProperties": false
|
|
},
|
|
"repository": {
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string"
|
|
},
|
|
"url": {
|
|
"type": "string",
|
|
"format": "uri"
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"url"
|
|
],
|
|
"additionalProperties": false
|
|
},
|
|
"homepage": {
|
|
"type": "string",
|
|
"format": "uri"
|
|
},
|
|
"documentation": {
|
|
"type": "string",
|
|
"format": "uri"
|
|
},
|
|
"support": {
|
|
"type": "string",
|
|
"format": "uri"
|
|
},
|
|
"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": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"python",
|
|
"node",
|
|
"binary"
|
|
]
|
|
},
|
|
"entry_point": {
|
|
"type": "string"
|
|
},
|
|
"mcp_config": {
|
|
"type": "object",
|
|
"properties": {
|
|
"command": {
|
|
"type": "string"
|
|
},
|
|
"args": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"env": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"platform_overrides": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"properties": {
|
|
"command": {
|
|
"$ref": "#/properties/server/properties/mcp_config/properties/command"
|
|
},
|
|
"args": {
|
|
"$ref": "#/properties/server/properties/mcp_config/properties/args"
|
|
},
|
|
"env": {
|
|
"$ref": "#/properties/server/properties/mcp_config/properties/env"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"command"
|
|
],
|
|
"additionalProperties": false
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"entry_point",
|
|
"mcp_config"
|
|
],
|
|
"additionalProperties": false
|
|
},
|
|
"tools": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"description": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"name"
|
|
],
|
|
"additionalProperties": false
|
|
}
|
|
},
|
|
"tools_generated": {
|
|
"type": "boolean"
|
|
},
|
|
"prompts": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string"
|
|
},
|
|
"description": {
|
|
"type": "string"
|
|
},
|
|
"arguments": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"text": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"text"
|
|
],
|
|
"additionalProperties": false
|
|
}
|
|
},
|
|
"prompts_generated": {
|
|
"type": "boolean"
|
|
},
|
|
"keywords": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"license": {
|
|
"type": "string"
|
|
},
|
|
"privacy_policies": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string",
|
|
"format": "uri"
|
|
}
|
|
},
|
|
"compatibility": {
|
|
"type": "object",
|
|
"properties": {
|
|
"claude_desktop": {
|
|
"type": "string"
|
|
},
|
|
"platforms": {
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string",
|
|
"enum": [
|
|
"darwin",
|
|
"win32",
|
|
"linux"
|
|
]
|
|
}
|
|
},
|
|
"runtimes": {
|
|
"type": "object",
|
|
"properties": {
|
|
"python": {
|
|
"type": "string"
|
|
},
|
|
"node": {
|
|
"type": "string"
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
}
|
|
},
|
|
"additionalProperties": false
|
|
},
|
|
"user_config": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"properties": {
|
|
"type": {
|
|
"type": "string",
|
|
"enum": [
|
|
"string",
|
|
"number",
|
|
"boolean",
|
|
"directory",
|
|
"file"
|
|
]
|
|
},
|
|
"title": {
|
|
"type": "string"
|
|
},
|
|
"description": {
|
|
"type": "string"
|
|
},
|
|
"required": {
|
|
"type": "boolean"
|
|
},
|
|
"default": {
|
|
"anyOf": [
|
|
{
|
|
"type": "string"
|
|
},
|
|
{
|
|
"type": "number"
|
|
},
|
|
{
|
|
"type": "boolean"
|
|
},
|
|
{
|
|
"type": "array",
|
|
"items": {
|
|
"type": "string"
|
|
}
|
|
}
|
|
]
|
|
},
|
|
"multiple": {
|
|
"type": "boolean"
|
|
},
|
|
"sensitive": {
|
|
"type": "boolean"
|
|
},
|
|
"min": {
|
|
"type": "number"
|
|
},
|
|
"max": {
|
|
"type": "number"
|
|
}
|
|
},
|
|
"required": [
|
|
"type",
|
|
"title",
|
|
"description"
|
|
],
|
|
"additionalProperties": false
|
|
}
|
|
},
|
|
"_meta": {
|
|
"type": "object",
|
|
"additionalProperties": {
|
|
"type": "object",
|
|
"additionalProperties": {}
|
|
}
|
|
}
|
|
},
|
|
"required": [
|
|
"name",
|
|
"version",
|
|
"description",
|
|
"author",
|
|
"server"
|
|
],
|
|
"additionalProperties": false,
|
|
"$schema": "http://json-schema.org/draft-07/schema#"
|
|
} |