Упаковка MCP-сервера в MCPB

Текст

---
name: build-mcpb
description: Этот скилл следует использовать, когда пользователь хочет «упаковать MCP-сервер», «собрать MCP в пакет», «сделать MCPB», «выпустить локальный MCP-сервер», «распространять локальный MCP», обсуждает «файлы .mcpb», упоминает включение среды выполнения Node или Python в свой MCP-сервер либо нуждается в MCP-сервере, который работает с локальной файловой системой, настольными приложениями или ОС и должен устанавливаться без предварительной настройки Node/Python у пользователя.
version: 0.1.0
---

Создание MCPB (упакованного локального MCP-сервера)

MCPB — это локальный MCP-сервер, упакованный вместе со своей средой выполнения. Пользователь устанавливает один файл; он работает, не требуя на компьютере Node, Python или какого-либо набора инструментов. Это одобренный способ распространять локальные MCP-серверы.

MCPB — второстепенный путь распространения. Для публикации в каталоге Anthropic рекомендует удалённые MCP-серверы — см. https://claude.com/docs/connectors/building/what-to-build.

Используй MCPB, когда сервер обязан работать на компьютере пользователя: читать локальные файлы, управлять настольным приложением, обращаться к сервисам на localhost, использовать API уровня ОС. Если твой сервер обращается только к облачным API, почти наверняка тебе нужен удалённый HTTP-сервер (см. build-mcp-server). Не плати «налог на упаковку» MCPB за то, что могло быть просто адресом.

Что внутри пакета MCPB

my-server.mcpb              (zip-архив)
├── manifest.json           ← имя, точка входа, схема настроек, совместимость
├── server/                 ← код твоего MCP-сервера
│   ├── index.js
│   └── node_modules/       ← вложенные зависимости (или скопированные в проект)
└── icon.png

Хост читает manifest.json, запускает server.mcp_config.command как stdio MCP-сервер и передаёт сообщения. С точки зрения твоего кода это то же самое, что локальный stdio-сервер: отличается только упаковка.

Манифест

{
  "$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 или binary. Носит информационный характер; фактический запуск берётся из mcp_config.

**server.mcp_config** — буквальные команда/аргументы/переменные окружения для запуска. Используй ${__dirname} для путей относительно пакета и ${user_config.<key>} для подстановки настроек, заданных при установке. Автоматического префикса нет: имена переменных окружения, которые читает твой сервер, в точности те, что ты указал в env.

**user_config** — настройки при установке, показываемые в интерфейсе хоста. type: "directory" рисует системное окно выбора папки. sensitive: true сохраняет значение в связке ключей ОС. Все поля смотри в references/manifest-schema.md.

Код сервера: как у локального stdio

Сам сервер — обычный stdio MCP-сервер. В логике инструментов нет ничего специфичного для MCPB.

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);

Изоляция полностью на тебе. Песочницы на уровне манифеста нет: процесс работает с полными правами пользователя. Проверяй пути, отказывайся выходить за пределы ROOT, веди белый список запускаемых процессов. См. references/local-security.md.

Прежде чем жёстко задавать ROOT из переменной окружения конфигурации, проверь, поддерживает ли хост roots/list — предусмотренный спецификацией способ получить каталоги, одобренные пользователем. Приём смотри в references/local-security.md.

Конвейер сборки

Node

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 упаковывает каталог в zip и проверяет manifest.json по схеме.

Python

pip install -t server/vendor -r requirements.txt
npx @anthropic-ai/mcpb pack

Скопируй зависимости в подкаталог и добавь его в начало sys.path в стартовом скрипте. Нативные расширения (numpy и т. п.) нужно собирать под каждую целевую платформу — по возможности избегай нативных зависимостей.

У MCPB нет песочницы: безопасность на тебе

В отличие от магазинов мобильных приложений, MCPB НЕ ограничивает разрешения. В манифесте нет блока permissions: сервер работает с полными правами пользователя. references/local-security.md — обязательное чтение, а не необязательное. Каждый путь нужно проверять, каждый запуск процесса — разрешать по белому списку, потому что на уровне платформы тебя ничто не остановит.

Если ты пришёл сюда в ожидании ограничений доступа к файловой системе и сети в манифесте: их не существует. Строй их сам в обработчиках инструментов.

Если единственная задача твоего сервера — обращаться к облачному API, остановись: это удалённый сервер в костюме MCPB. Пользователь ничего не выигрывает от локального запуска, а ты берёшь на себя груз локальной безопасности без причины.

MCPB + виджеты интерфейса

MCPB-серверы могут отдавать UI-ресурсы так же, как удалённые MCP-приложения: механизм виджетов не зависит от транспорта. Например, локальный выбор файла, просматривающий настоящий диск, или диалог, управляющий встроенным приложением.

Создание виджетов описано в скилле **build-mcp-app**; здесь оно работает так же. Разница только в том, где работает сервер.

Тестирование

# 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

Проверяй на компьютере без твоего набора инструментов разработки, прежде чем выпускать. Сбои вида «у меня работает» в MCPB почти всегда сводятся к зависимости, которая на самом деле не попала в пакет.

Справочные файлы

• references/manifest-schema.md — полный справочник полей manifest.json
• references/local-security.md — обход путей, изоляция, наименьшие привилегии

Перевод: iiuniversitet. Оригинал: https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev/skills/build-mcpb, лицензия Apache-2.0. Изменения: перевод на русский язык.