mirror of
https://github.com/anthropics/claude-plugins-official.git
synced 2026-03-20 11:33:08 +00:00
fix(plugin): mcp-server-dev — correct APIs against spec, add missing primitives
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.
This commit is contained in:
Den Delimarsky
@@ -1,8 +1,10 @@
|
||||
# Local MCP Security
|
||||
|
||||
An MCPB server runs as the user, with whatever permissions the manifest was granted. Claude drives it. That combination means: **tool inputs are untrusted**, even though they come from an AI the user trusts. A prompt-injected web page can make Claude call your `delete_file` tool with a path you didn't intend.
|
||||
**MCPB provides no sandbox.** There's no `permissions` block in the manifest, no filesystem scoping, no network allowlist enforced by the platform. The server process runs with the user's full privileges — it can read any file the user can, spawn any process, hit any network endpoint.
|
||||
|
||||
Defense in depth. Manifest permissions are the outer wall; validation in your tool handlers is the inner wall.
|
||||
Claude drives it. That combination means: **tool inputs are untrusted**, even though they come from an AI the user trusts. A prompt-injected web page can make Claude call your `delete_file` tool with a path you didn't intend.
|
||||
|
||||
Your tool handlers are the only defense. Everything below is about building that defense yourself.
|
||||
|
||||
---
|
||||
|
||||
@@ -39,6 +41,41 @@ def safe_join(root: Path, user_path: str) -> Path:
|
||||
|
||||
---
|
||||
|
||||
## Roots — ask the host, don't hardcode
|
||||
|
||||
Before hardcoding `ROOT` from a config env var, check if the host supports `roots/list`. This is the spec-native way to get user-approved workspace boundaries.
|
||||
|
||||
```typescript
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
|
||||
const server = new McpServer({ name: "...", version: "..." });
|
||||
|
||||
let allowedRoots: string[] = [];
|
||||
server.server.oninitialized = async () => {
|
||||
const caps = server.getClientCapabilities();
|
||||
if (caps?.roots) {
|
||||
const { roots } = await server.server.listRoots();
|
||||
allowedRoots = roots.map(r => new URL(r.uri).pathname);
|
||||
} else {
|
||||
allowedRoots = [process.env.ROOT_DIR ?? process.cwd()];
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
```python
|
||||
# fastmcp — inside a tool handler
|
||||
async def my_tool(ctx: Context) -> str:
|
||||
try:
|
||||
roots = await ctx.list_roots()
|
||||
allowed = [urlparse(r.uri).path for r in roots]
|
||||
except Exception:
|
||||
allowed = [os.environ.get("ROOT_DIR", os.getcwd())]
|
||||
```
|
||||
|
||||
If roots are available, use them. If not, fall back to config. Either way, validate every path against the allowed set.
|
||||
|
||||
---
|
||||
|
||||
## Command injection
|
||||
|
||||
If you spawn processes, **never pass user input through a shell**.
|
||||
@@ -62,11 +99,13 @@ Split read and write into separate tools. Most workflows only need read. A tool
|
||||
```
|
||||
list_files ← safe to call freely
|
||||
read_file ← safe to call freely
|
||||
write_file ← separate tool, separate permission, separate scrutiny
|
||||
write_file ← separate tool, separate scrutiny
|
||||
delete_file ← consider not shipping this at all
|
||||
```
|
||||
|
||||
If you ship write/delete, consider requiring a confirmation widget (see `build-mcp-app`) so the user explicitly approves each destructive call.
|
||||
Pair this with tool annotations — `readOnlyHint: true` on every read tool, `destructiveHint: true` on delete/overwrite tools. Hosts surface these in permission UI (auto-approve reads, confirm-dialog destructive). See `../build-mcp-server/references/tool-design.md`.
|
||||
|
||||
If you ship write/delete, consider requiring explicit confirmation via elicitation (see `../build-mcp-server/references/elicitation.md`) or a confirmation widget (see `build-mcp-app`) so the user approves each destructive call.
|
||||
|
||||
---
|
||||
|
||||
@@ -94,7 +133,7 @@ Same for directory listings (cap entry count), search results (cap matches), and
|
||||
|
||||
## Secrets
|
||||
|
||||
- **Config secrets** (`secret: true` in manifest): host stores in OS keychain, delivers via env var. Don't log them. Don't include them in tool results.
|
||||
- **Config secrets** (`sensitive: true` in manifest `user_config`): host stores in OS keychain, delivers via env var. Don't log them. Don't include them in tool results.
|
||||
- **Never store secrets in plaintext files.** If the host's keychain integration isn't enough, use `keytar` (Node) / `keyring` (Python) yourself.
|
||||
- **Tool results flow into the chat transcript.** Anything you return, the user (and any log export) can see. Redact before returning.
|
||||
|
||||
@@ -104,8 +143,7 @@ Same for directory listings (cap entry count), search results (cap matches), and
|
||||
|
||||
- [ ] Every path parameter goes through containment check
|
||||
- [ ] No `exec()` / `shell=True` — `execFile` / array-argv only
|
||||
- [ ] Write/delete split from read tools
|
||||
- [ ] Write/delete split from read tools; `readOnlyHint`/`destructiveHint` annotations set
|
||||
- [ ] Size caps on file reads, listing lengths, search results
|
||||
- [ ] Manifest permissions match actual code behavior (no over-requesting)
|
||||
- [ ] Secrets never logged or returned in tool results
|
||||
- [ ] Tested with adversarial inputs: `../../etc/passwd`, `; rm -rf ~`, 10GB file
|
||||
|
||||
@@ -1,119 +1,127 @@
|
||||
# MCPB Manifest Schema
|
||||
# MCPB Manifest Schema (v0.4)
|
||||
|
||||
Every `.mcpb` bundle has a `manifest.json` at its root. The host validates it before install.
|
||||
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 | Type | Required | Notes |
|
||||
|---|---|---|---|
|
||||
| `name` | string | ✅ | Unique identifier. Lowercase, hyphens only. Shown in settings. |
|
||||
| `version` | string | ✅ | Semver. Host compares for update prompts. |
|
||||
| `description` | string | ✅ | One line. Shown in the install prompt. |
|
||||
| `entry` | object | ✅ | How to launch the server — see below. |
|
||||
| `permissions` | object | ✅ | What the server needs — see below. |
|
||||
| `config` | object | — | User-settable values surfaced in settings UI. |
|
||||
| `icon` | string | — | Path to PNG inside the bundle. 256×256 recommended. |
|
||||
| `homepage` | string | — | URL shown in settings. |
|
||||
| `minHostVersion` | string | — | Refuse install on older hosts. |
|
||||
|
||||
---
|
||||
|
||||
## `entry`
|
||||
|
||||
```json
|
||||
{ "type": "node", "main": "server/index.js" }
|
||||
```
|
||||
|
||||
| `type` | `main` points at | Runtime resolution |
|
||||
| Field | Required | Description |
|
||||
|---|---|---|
|
||||
| `node` | `.js` or `.mjs` file | `runtime/node` if present, else host-bundled Node |
|
||||
| `python` | `.py` file | `runtime/python` if present, else host-bundled Python |
|
||||
| `binary` | executable | Run directly. Must be built per-platform. |
|
||||
|
||||
**`args`** (optional array) — extra argv passed to the entry. Rarely needed.
|
||||
|
||||
**`env`** (optional object) — static env vars set at launch. For user-configurable values use `config` instead.
|
||||
| `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. |
|
||||
|
||||
---
|
||||
|
||||
## `permissions`
|
||||
## `server` — launch configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"filesystem": { "read": true, "write": false },
|
||||
"network": { "allow": ["localhost:*", "127.0.0.1:*"] },
|
||||
"process": { "spawn": false }
|
||||
}
|
||||
```
|
||||
|
||||
### `filesystem`
|
||||
|
||||
| Value | Meaning |
|
||||
|---|---|
|
||||
| `false` or omitted | No filesystem access beyond the bundle itself |
|
||||
| `{ "read": true }` | Read anywhere the OS user can |
|
||||
| `{ "read": true, "write": true }` | Read and write |
|
||||
|
||||
There's no path scoping at the manifest level — scope in your code. The manifest permission is a coarse consent gate, not a sandbox.
|
||||
|
||||
### `network`
|
||||
|
||||
| Value | Meaning |
|
||||
|---|---|
|
||||
| `false` or omitted | No network (most local-first servers) |
|
||||
| `{ "allow": ["host:port", ...] }` | Allowlisted destinations. `*` wildcards ports. |
|
||||
| `true` | Unrestricted. Heavy scrutiny — explain why in `description`. |
|
||||
|
||||
### `process`
|
||||
|
||||
| Value | Meaning |
|
||||
|---|---|
|
||||
| `false` or omitted | Can't spawn child processes |
|
||||
| `{ "spawn": true }` | Can spawn. Needed for wrapping CLIs. |
|
||||
| `{ "spawn": true, "allow": ["git", "ffmpeg"] }` | Spawn only allowlisted binaries |
|
||||
|
||||
---
|
||||
|
||||
## `config`
|
||||
|
||||
User-editable settings, surfaced in the host UI. Each key becomes an env var: `MCPB_CONFIG_<UPPERCASE_KEY>`.
|
||||
|
||||
```json
|
||||
{
|
||||
"config": {
|
||||
"rootDir": {
|
||||
"type": "string",
|
||||
"description": "Directory to expose",
|
||||
"default": "~/Documents"
|
||||
},
|
||||
"maxFileSize": {
|
||||
"type": "number",
|
||||
"description": "Skip files larger than this (MB)",
|
||||
"default": 10,
|
||||
"min": 1,
|
||||
"max": 500
|
||||
},
|
||||
"includeHidden": {
|
||||
"type": "boolean",
|
||||
"description": "Include dotfiles in listings",
|
||||
"default": false
|
||||
},
|
||||
"apiKey": {
|
||||
"type": "string",
|
||||
"description": "Optional API key for the sync feature",
|
||||
"secret": true
|
||||
"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}"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**`type`** — `string`, `number`, `boolean`. Enums: use `string` with `"enum": ["a", "b", "c"]`.
|
||||
| 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. |
|
||||
|
||||
**`secret: true`** — host masks the value in UI and stores it in the OS keychain instead of a plain config file.
|
||||
**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
|
||||
|
||||
**`required: true`** — host blocks server launch until the user sets it. Use sparingly — a server that won't start until configured is a bad first-run experience.
|
||||
**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"}`. |
|
||||
|
||||
---
|
||||
|
||||
@@ -121,12 +129,28 @@ User-editable settings, surfaced in the host UI. Each key becomes an env var: `M
|
||||
|
||||
```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.",
|
||||
"entry": { "type": "node", "main": "server/index.js" },
|
||||
"permissions": {}
|
||||
"author": { "name": "Your Name" },
|
||||
"server": {
|
||||
"type": "node",
|
||||
"entry_point": "server/index.js",
|
||||
"mcp_config": {
|
||||
"command": "node",
|
||||
"args": ["${__dirname}/server/index.js"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Empty `permissions` means no filesystem, no network, no spawn — pure computation only. Valid, if unusual.
|
||||
---
|
||||
|
||||
## 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`.
|
||||
|
||||
Reference in New Issue
Block a user