mirror of
https://github.com/anthropics/claude-plugins-official.git
synced 2026-03-20 11:33:08 +00:00
48a018f27a
Corrects fabricated/deprecated APIs: ext-apps App class model (not embedded resources), real MCPB v0.4 manifest (no permissions block exists), registerTool (not server.tool), @anthropic-ai/mcpb package name, CIMD preferred over DCR. Adds missing spec coverage: resources, prompts, elicitation (with capability check + fallback), sampling, roots, tool annotations, structured output, instructions field, progress/cancellation.
157 lines
5.2 KiB
Markdown
157 lines
5.2 KiB
Markdown
# MCPB Manifest Schema (v0.4)
|
|
|
|
Validated against `github.com/anthropics/mcpb/schemas/mcpb-manifest-v0.4.schema.json`. The schema uses `additionalProperties: false` — unknown keys are rejected. Add `"$schema"` to your manifest for editor validation.
|
|
|
|
---
|
|
|
|
## Top-level fields
|
|
|
|
| Field | Required | Description |
|
|
|---|---|---|
|
|
| `manifest_version` | ✅ | Schema version. Use `"0.4"`. |
|
|
| `name` | ✅ | Package identifier (lowercase, hyphens). Must be unique. |
|
|
| `version` | ✅ | Semver version of YOUR package. |
|
|
| `description` | ✅ | One-line summary. Shown in marketplace. |
|
|
| `author` | ✅ | `{name, email?, url?}` |
|
|
| `server` | ✅ | Entry point and launch config. See below. |
|
|
| `display_name` | | Human-friendly name. Falls back to `name`. |
|
|
| `long_description` | | Markdown. Shown on detail page. |
|
|
| `icon` / `icons` | | Path(s) to icon file(s) in the bundle. |
|
|
| `homepage` / `repository` / `documentation` / `support` | | URLs. |
|
|
| `license` | | SPDX identifier. |
|
|
| `keywords` | | String array for search. |
|
|
| `user_config` | | Install-time config fields. See below. |
|
|
| `compatibility` | | Host/platform/runtime requirements. See below. |
|
|
| `tools` / `prompts` | | Optional declarative list for marketplace display. Not enforced at runtime. |
|
|
| `tools_generated` / `prompts_generated` | | `true` if tools/prompts are dynamic (can't list statically). |
|
|
| `screenshots` | | Array of image paths. |
|
|
| `localization` | | i18n bundles. |
|
|
| `privacy_policies` | | URLs. |
|
|
|
|
---
|
|
|
|
## `server` — launch configuration
|
|
|
|
```json
|
|
"server": {
|
|
"type": "node",
|
|
"entry_point": "server/index.js",
|
|
"mcp_config": {
|
|
"command": "node",
|
|
"args": ["${__dirname}/server/index.js"],
|
|
"env": {
|
|
"API_KEY": "${user_config.apiKey}",
|
|
"ROOT_DIR": "${user_config.rootDir}"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
| Field | Description |
|
|
|---|---|
|
|
| `type` | `"node"`, `"python"`, or `"binary"` |
|
|
| `entry_point` | Relative path to main file. Informational. |
|
|
| `mcp_config.command` | Executable to launch. |
|
|
| `mcp_config.args` | Argv array. Use `${__dirname}` for bundle-relative paths. |
|
|
| `mcp_config.env` | Environment variables. Use `${user_config.KEY}` to substitute user config. |
|
|
|
|
**Substitution variables** (in `args` and `env` only):
|
|
- `${__dirname}` — absolute path to the unpacked bundle directory
|
|
- `${user_config.<key>}` — value the user entered at install time
|
|
- `${HOME}` — user's home directory
|
|
|
|
**There are no auto-prefixed env vars.** The env var names your server reads are exactly what you declare in `mcp_config.env`. If you write `"ROOT_DIR": "${user_config.rootDir}"`, your server reads `process.env.ROOT_DIR`.
|
|
|
|
---
|
|
|
|
## `user_config` — install-time settings
|
|
|
|
```json
|
|
"user_config": {
|
|
"apiKey": {
|
|
"type": "string",
|
|
"title": "API Key",
|
|
"description": "Your service API key. Stored encrypted.",
|
|
"sensitive": true,
|
|
"required": true
|
|
},
|
|
"rootDir": {
|
|
"type": "directory",
|
|
"title": "Root directory",
|
|
"description": "Directory to expose to the server.",
|
|
"default": "${HOME}/Documents"
|
|
},
|
|
"maxResults": {
|
|
"type": "number",
|
|
"title": "Max results",
|
|
"description": "Maximum items returned per query.",
|
|
"default": 50,
|
|
"min": 1,
|
|
"max": 500
|
|
}
|
|
}
|
|
```
|
|
|
|
| Field | Required | Description |
|
|
|---|---|---|
|
|
| `type` | ✅ | `"string"`, `"number"`, `"boolean"`, `"directory"`, `"file"` |
|
|
| `title` | ✅ | Form label. |
|
|
| `description` | ✅ | Help text under the input. |
|
|
| `default` | | Pre-filled value. Supports `${HOME}`. |
|
|
| `required` | | If `true`, install blocks until filled. |
|
|
| `sensitive` | | If `true`, stored in OS keychain + masked in UI. **NOT `secret`** — that field doesn't exist. |
|
|
| `multiple` | | If `true`, user can enter multiple values (array). |
|
|
| `min` / `max` | | Numeric bounds (for `type: "number"`). |
|
|
|
|
`directory` and `file` types render native OS pickers — prefer these over free-text paths for UX and validation.
|
|
|
|
---
|
|
|
|
## `compatibility` — gate installs
|
|
|
|
```json
|
|
"compatibility": {
|
|
"claude_desktop": ">=1.0.0",
|
|
"platforms": ["darwin", "win32", "linux"],
|
|
"runtimes": { "node": ">=20" }
|
|
}
|
|
```
|
|
|
|
| Field | Description |
|
|
|---|---|
|
|
| `claude_desktop` | Semver range. Install blocked if host is older. |
|
|
| `platforms` | OS allowlist. Subset of `["darwin", "win32", "linux"]`. |
|
|
| `runtimes` | Required runtime versions, e.g. `{"node": ">=20"}` or `{"python": ">=3.11"}`. |
|
|
|
|
---
|
|
|
|
## Minimal valid manifest
|
|
|
|
```json
|
|
{
|
|
"$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
|
|
"manifest_version": "0.4",
|
|
"name": "hello",
|
|
"version": "0.1.0",
|
|
"description": "Minimal MCPB server.",
|
|
"author": { "name": "Your Name" },
|
|
"server": {
|
|
"type": "node",
|
|
"entry_point": "server/index.js",
|
|
"mcp_config": {
|
|
"command": "node",
|
|
"args": ["${__dirname}/server/index.js"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## What MCPB does NOT have
|
|
|
|
- **No `permissions` block.** There is no manifest-level filesystem/network/process scoping. The server runs with full user privileges. Enforce boundaries in your tool handlers — see `local-security.md`.
|
|
- **No auto env var prefix.** No `MCPB_CONFIG_*` convention. You wire config → env explicitly in `server.mcp_config.env`.
|
|
- **No `entry` field.** It's `server` with `entry_point` inside.
|
|
- **No `minHostVersion`.** It's `compatibility.claude_desktop`.
|