mirror of
https://github.com/anthropics/claude-plugins-official.git
synced 2026-03-22 00:03:09 +00:00
add(plugin): mcp-server-dev — skills for building MCP servers (#731)
This commit is contained in:
Tobin South
197
plugins/mcp-server-dev/skills/build-mcpb/SKILL.md
Normal file
197
plugins/mcp-server-dev/skills/build-mcpb/SKILL.md
Normal file
@@ -0,0 +1,197 @@
|
||||
---
|
||||
name: build-mcpb
|
||||
description: This skill should be used when the user wants to "package an MCP server", "bundle an MCP", "make an MCPB", "ship a local MCP server", "distribute a local MCP", discusses ".mcpb files", mentions bundling a Node or Python runtime with their MCP server, or needs an MCP server that interacts with the local filesystem, desktop apps, or OS and must be installable without the user having Node/Python set up.
|
||||
version: 0.1.0
|
||||
---
|
||||
|
||||
# Build an MCPB (Bundled Local MCP Server)
|
||||
|
||||
MCPB is a local MCP server **packaged with its runtime**. The user installs one file; it runs without needing Node, Python, or any toolchain on their machine. It's the sanctioned way to distribute local MCP servers.
|
||||
|
||||
**Use MCPB when the server must run on the user's machine** — reading local files, driving a desktop app, talking to localhost services, OS-level APIs. If your server only hits cloud APIs, you almost certainly want a remote HTTP server instead (see `build-mcp-server`). Don't pay the MCPB packaging tax for something that could be a URL.
|
||||
|
||||
---
|
||||
|
||||
## What an MCPB bundle contains
|
||||
|
||||
```
|
||||
my-server.mcpb (zip archive)
|
||||
├── manifest.json ← identity, entry point, config schema, compatibility
|
||||
├── server/ ← your MCP server code
|
||||
│ ├── index.js
|
||||
│ └── node_modules/ ← bundled dependencies (or vendored)
|
||||
└── icon.png
|
||||
```
|
||||
|
||||
The host reads `manifest.json`, launches `server.mcp_config.command` as a **stdio** MCP server, and pipes messages. From your code's perspective it's identical to a local stdio server — the only difference is packaging.
|
||||
|
||||
---
|
||||
|
||||
## Manifest
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://raw.githubusercontent.com/anthropics/mcpb/main/schemas/mcpb-manifest-v0.4.schema.json",
|
||||
"manifest_version": "0.4",
|
||||
"name": "local-files",
|
||||
"version": "0.1.0",
|
||||
"description": "Read, search, and watch files on the local filesystem.",
|
||||
"author": { "name": "Your Name" },
|
||||
"server": {
|
||||
"type": "node",
|
||||
"entry_point": "server/index.js",
|
||||
"mcp_config": {
|
||||
"command": "node",
|
||||
"args": ["${__dirname}/server/index.js"],
|
||||
"env": {
|
||||
"ROOT_DIR": "${user_config.rootDir}"
|
||||
}
|
||||
}
|
||||
},
|
||||
"user_config": {
|
||||
"rootDir": {
|
||||
"type": "directory",
|
||||
"title": "Root directory",
|
||||
"description": "Directory to expose. Defaults to ~/Documents.",
|
||||
"default": "${HOME}/Documents",
|
||||
"required": true
|
||||
}
|
||||
},
|
||||
"compatibility": {
|
||||
"claude_desktop": ">=1.0.0",
|
||||
"platforms": ["darwin", "win32", "linux"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**`server.type`** — `node`, `python`, or `binary`. Informational; the actual launch comes from `mcp_config`.
|
||||
|
||||
**`server.mcp_config`** — the literal command/args/env to spawn. Use `${__dirname}` for bundle-relative paths and `${user_config.<key>}` to substitute install-time config. **There's no auto-prefix** — the env var names your server reads are exactly what you put in `env`.
|
||||
|
||||
**`user_config`** — install-time settings surfaced in the host's UI. `type: "directory"` renders a native folder picker. `sensitive: true` stores in OS keychain. See `references/manifest-schema.md` for all fields.
|
||||
|
||||
---
|
||||
|
||||
## Server code: same as local stdio
|
||||
|
||||
The server itself is a standard stdio MCP server. Nothing MCPB-specific in the tool logic.
|
||||
|
||||
```typescript
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
||||
import { z } from "zod";
|
||||
import { readFile, readdir } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
import { homedir } from "node:os";
|
||||
|
||||
// ROOT_DIR comes from what you put in manifest's server.mcp_config.env — no auto-prefix
|
||||
const ROOT = (process.env.ROOT_DIR ?? join(homedir(), "Documents"));
|
||||
|
||||
const server = new McpServer({ name: "local-files", version: "0.1.0" });
|
||||
|
||||
server.registerTool(
|
||||
"list_files",
|
||||
{
|
||||
description: "List files in a directory under the configured root.",
|
||||
inputSchema: { path: z.string().default(".") },
|
||||
annotations: { readOnlyHint: true },
|
||||
},
|
||||
async ({ path }) => {
|
||||
const entries = await readdir(join(ROOT, path), { withFileTypes: true });
|
||||
const list = entries.map(e => ({ name: e.name, dir: e.isDirectory() }));
|
||||
return { content: [{ type: "text", text: JSON.stringify(list, null, 2) }] };
|
||||
},
|
||||
);
|
||||
|
||||
server.registerTool(
|
||||
"read_file",
|
||||
{
|
||||
description: "Read a file's contents. Path is relative to the configured root.",
|
||||
inputSchema: { path: z.string() },
|
||||
annotations: { readOnlyHint: true },
|
||||
},
|
||||
async ({ path }) => {
|
||||
const text = await readFile(join(ROOT, path), "utf8");
|
||||
return { content: [{ type: "text", text }] };
|
||||
},
|
||||
);
|
||||
|
||||
const transport = new StdioServerTransport();
|
||||
await server.connect(transport);
|
||||
```
|
||||
|
||||
**Sandboxing is entirely your job.** There is no manifest-level sandbox — the process runs with full user privileges. Validate paths, refuse to escape `ROOT`, allowlist spawns. See `references/local-security.md`.
|
||||
|
||||
Before hardcoding `ROOT` from a config env var, check if the host supports `roots/list` — the spec-native way to get user-approved directories. See `references/local-security.md` for the pattern.
|
||||
|
||||
---
|
||||
|
||||
## Build pipeline
|
||||
|
||||
### Node
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npx esbuild src/index.ts --bundle --platform=node --outfile=server/index.js
|
||||
# or: copy node_modules wholesale if native deps resist bundling
|
||||
npx @anthropic-ai/mcpb pack
|
||||
```
|
||||
|
||||
`mcpb pack` zips the directory and validates `manifest.json` against the schema.
|
||||
|
||||
### Python
|
||||
|
||||
```bash
|
||||
pip install -t server/vendor -r requirements.txt
|
||||
npx @anthropic-ai/mcpb pack
|
||||
```
|
||||
|
||||
Vendor dependencies into a subdirectory and prepend it to `sys.path` in your entry script. Native extensions (numpy, etc.) must be built for each target platform — avoid native deps if you can.
|
||||
|
||||
---
|
||||
|
||||
## MCPB has no sandbox — security is on you
|
||||
|
||||
Unlike mobile app stores, MCPB does NOT enforce permissions. The manifest has no `permissions` block — the server runs with full user privileges. `references/local-security.md` is mandatory reading, not optional. Every path must be validated, every spawn must be allowlisted, because nothing stops you at the platform level.
|
||||
|
||||
If you came here expecting filesystem/network scoping from the manifest: it doesn't exist. Build it yourself in tool handlers.
|
||||
|
||||
If your server's only job is hitting a cloud API, stop — that's a remote server wearing an MCPB costume. The user gains nothing from running it locally, and you're taking on local-security burden for no reason.
|
||||
|
||||
---
|
||||
|
||||
## MCPB + UI widgets
|
||||
|
||||
MCPB servers can serve UI resources exactly like remote MCP apps — the widget mechanism is transport-agnostic. A local file picker that browses the actual disk, a dialog that controls a native app, etc.
|
||||
|
||||
Widget authoring is covered in the **`build-mcp-app`** skill; it works the same here. The only difference is where the server runs.
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
```bash
|
||||
# Interactive manifest creation (first time)
|
||||
npx @anthropic-ai/mcpb init
|
||||
|
||||
# Run the server directly over stdio, poke it with the inspector
|
||||
npx @modelcontextprotocol/inspector node server/index.js
|
||||
|
||||
# Validate manifest against schema, then pack
|
||||
npx @anthropic-ai/mcpb validate
|
||||
npx @anthropic-ai/mcpb pack
|
||||
|
||||
# Sign for distribution
|
||||
npx @anthropic-ai/mcpb sign dist/local-files.mcpb
|
||||
|
||||
# Install: drag the .mcpb file onto Claude Desktop
|
||||
```
|
||||
|
||||
Test on a machine **without** your dev toolchain before shipping. "Works on my machine" failures in MCPB almost always trace to a dependency that wasn't actually bundled.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- `references/manifest-schema.md` — full `manifest.json` field reference
|
||||
- `references/local-security.md` — path traversal, sandboxing, least privilege
|
||||
@@ -0,0 +1,149 @@
|
||||
# Local MCP Security
|
||||
|
||||
**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.
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Path traversal
|
||||
|
||||
The #1 bug in local MCP servers. If you take a path parameter and join it to a root, **resolve and check containment**.
|
||||
|
||||
```typescript
|
||||
import { resolve, relative, isAbsolute } from "node:path";
|
||||
|
||||
function safeJoin(root: string, userPath: string): string {
|
||||
const full = resolve(root, userPath);
|
||||
const rel = relative(root, full);
|
||||
if (rel.startsWith("..") || isAbsolute(rel)) {
|
||||
throw new Error(`Path escapes root: ${userPath}`);
|
||||
}
|
||||
return full;
|
||||
}
|
||||
```
|
||||
|
||||
`resolve` normalizes `..`, symlink segments, etc. `relative` tells you if the result left the root. Don't just `String.includes("..")` — that misses encoded and symlink-based escapes.
|
||||
|
||||
**Python equivalent:**
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
def safe_join(root: Path, user_path: str) -> Path:
|
||||
full = (root / user_path).resolve()
|
||||
if not full.is_relative_to(root.resolve()):
|
||||
raise ValueError(f"Path escapes root: {user_path}")
|
||||
return full
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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**.
|
||||
|
||||
```typescript
|
||||
// ❌ catastrophic
|
||||
exec(`git log ${branch}`);
|
||||
|
||||
// ✅ array-args, no shell
|
||||
execFile("git", ["log", branch]);
|
||||
```
|
||||
|
||||
If you're wrapping a CLI, build the full argv as an array. Validate each flag against an allowlist if the tool accepts flags at all.
|
||||
|
||||
---
|
||||
|
||||
## Read-only by default
|
||||
|
||||
Split read and write into separate tools. Most workflows only need read. A tool that's read-only can't be weaponized into data loss no matter what Claude is tricked into calling it with.
|
||||
|
||||
```
|
||||
list_files ← safe to call freely
|
||||
read_file ← safe to call freely
|
||||
write_file ← separate tool, separate scrutiny
|
||||
delete_file ← consider not shipping this at all
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Resource limits
|
||||
|
||||
Claude will happily ask to read a 4GB log file. Cap everything:
|
||||
|
||||
```typescript
|
||||
const MAX_BYTES = 1_000_000;
|
||||
const buf = await readFile(path);
|
||||
if (buf.length > MAX_BYTES) {
|
||||
return {
|
||||
content: [{
|
||||
type: "text",
|
||||
text: `File is ${buf.length} bytes — too large. Showing first ${MAX_BYTES}:\n\n`
|
||||
+ buf.subarray(0, MAX_BYTES).toString("utf8"),
|
||||
}],
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
Same for directory listings (cap entry count), search results (cap matches), and anything else unbounded.
|
||||
|
||||
---
|
||||
|
||||
## Secrets
|
||||
|
||||
- **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.
|
||||
|
||||
---
|
||||
|
||||
## Checklist before shipping
|
||||
|
||||
- [ ] Every path parameter goes through containment check
|
||||
- [ ] No `exec()` / `shell=True` — `execFile` / array-argv only
|
||||
- [ ] Write/delete split from read tools; `readOnlyHint`/`destructiveHint` annotations set
|
||||
- [ ] Size caps on file reads, listing lengths, search results
|
||||
- [ ] Secrets never logged or returned in tool results
|
||||
- [ ] Tested with adversarial inputs: `../../etc/passwd`, `; rm -rf ~`, 10GB file
|
||||
@@ -0,0 +1,156 @@
|
||||
# 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`.
|
||||
Reference in New Issue
Block a user