Публикация MCP-сервера: npm-layout, README, semver, deprecation

Подготовь релиз MCP-сервера {{package_name}} ({{server_purpose}}) в npm. MCP-сервер — это HTTP/stdio-процесс, который Claude Desktop / Claude Code запускает локально и зовёт по протоколу MCP. Цель — сделать релиз так, чтобы пользователь установил, добавил 5 строк в config и пошёл работать.

1. Layout npm-пакета

{{package_name}}/
├── package.json
├── README.md
├── LICENSE
├── CHANGELOG.md
├── src/
│   ├── index.ts          // entry, регистрирует tools/resources
│   ├── server.ts         // MCP server setup
│   └── tools/
│       └── *.ts          // по одному файлу на tool
├── dist/                 // compiled JS + .d.ts (в .gitignore, в npm — в files)
│   ├── index.js
│   ├── index.d.ts
│   └── ...
└── bin/
    └── cli.js            // executable shim

package.json — обязательные поля

{
  "name": "{{package_name}}",
  "version": "0.1.0",
  "description": "[1 строка purpose]",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "bin": {
    "{{package_name}}": "./bin/cli.js"
  },
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "types": "./dist/index.d.ts"
    }
  },
  "files": ["dist", "bin", "README.md", "LICENSE"],
  "engines": { "node": ">=18.0.0" },
  "scripts": {
    "build": "tsc",
    "prepublishOnly": "npm run build && npm test"
  },
  "keywords": ["mcp", "model-context-protocol", "claude"],
  "repository": { "type": "git", "url": "git+https://github.com/..." },
  "license": "MIT"
}

Подводные:

• "files" явно — иначе в tarball попадёт всё, включая src/, .env и node_modules через ошибку
• "type": "module" — MCP-протокол на ESM, без этого import сломается
• bin shebang: первая строка #!/usr/bin/env node, файл с правами +x

2. README — essentials

Структура из 6 секций, в этом порядке:

a) Что это (1 параграф)

Что делает, на каких задачах применим. Без "powerful", "flexible", "easy-to-use".

b) Installation

npm install -g {{package_name}}
# или через npx без установки
npx {{package_name}} --help

c) Claude Desktop config — копипаст snippet

{
  "mcpServers": {
    "[short-name]": {
      "command": "npx",
      "args": ["-y", "{{package_name}}"],
      "env": {
        "API_KEY": "..."
      }
    }
  }
}

Где лежит config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

d) Tools list — таблица

e) Configuration / env vars

Все env vars с дефолтами и required vs optional.

f) Troubleshooting

3-5 типичных проблем: "sever not connecting", "401 from API", "tool not appearing". Под каждой — команда для диагностики (logs path для Claude Desktop, mcp-inspector).

НЕ надо в README:

• Архитектурные диаграммы — в docs/
• Длинный roadmap — в Issues
• Скриншоты IDE — устаревают

3. SemVer для MCP-сервера

MCP — это публичный контракт tools/resources. Меняешь его — это API change.

Для pre-1.0 (0.x): breaking changes — это minor, не major. Но пиши явно в CHANGELOG: BREAKING:.

Версионирование самого MCP-протокола

В коде указывай, какую версию MCP-protocol спецификации поддерживаешь (@modelcontextprotocol/sdk версия). При обновлении SDK — bump minor и упомяни в CHANGELOG.

4. Deprecation tools

Когда tool становится не нужен:

1. Mark as deprecated в description: [DEPRECATED in 1.2.0, use 'new_tool'. Removed in 2.0.0]
2. Lifecycle: оставь работающим минимум 2 minor-релиза. Не выпиливай сразу.
3. Warning в stderr при первом вызове: Tool 'old_tool' is deprecated, use 'new_tool'
4. CHANGELOG: каждый релиз с deprecated tool явно его упоминает в секции Deprecated
5. Major version: только в major bump физически удаляй tool

5. Pre-publish чек-лист

• npm pack --dry-run — посмотри, что попадает в tarball, нет лишнего (.env, src/, node_modules)
• bin/cli.js с #!/usr/bin/env node и chmod +x
• Локальный тест: npm pack && claude_desktop_config указывает на /path/to/{{package_name}}-x.y.z.tgz через npm install -g
• mcp-inspector проходит: tools видны, schema валидна
• CHANGELOG обновлён, версия в package.json совпадает с git tag
• README имеет рабочий copy-paste snippet
• License включён в tarball (files)
• npm publish --access public (для scoped packages по умолчанию private)

6. Anti-patterns

• ❌ Публикация без "files" — в npm уезжает весь src/, .env, заметки разработчика
• ❌ bin без shebang #!/usr/bin/env node — на Linux/macOS не запустится
• ❌ README без копипастного claude_desktop_config snippet — пользователь не поймёт куда вставлять
• ❌ Tool с описанием меньше 3 строк — агент не знает, когда звать
• ❌ Breaking change без bump в major (после 1.0) — поломаешь чужие интеграции
• ❌ Удалить deprecated tool в patch-релизе — 0.1.5 → 0.1.6 ломает всех
• ❌ Env vars без дефолтов и без явного списка required — "works on my machine"
• ❌ Логи tool'ов идут в stdout — ломает MCP-протокол (stdout = transport)
• ❌ Использовать console.log — то же самое: всё на stdout. Логи только в stderr или в файл
• ❌ Релиз без CHANGELOG — невозможно понять, что изменилось
• ❌ Hardcoded API keys в коде вместо env vars — leak через GitHub
• ❌ npm publish без prepublishOnly build — релиз сломанной версии
• ❌ Поддержка одной версии Node без указания в engines — рандомные ошибки на Node 16

Deliverable

• Файловая структура §1 для {{package_name}}, реальные пути
• package.json с полями из §1 (заполнен)
• README.md по структуре §2 (6 секций)
• SemVer-таблица в CONTRIBUTING.md для будущих контрибьюторов
• Скрипт pre-publish-check, который проходит §5 автоматически
• Тест-прогон: установка через npx, добавление в claude_desktop_config, вызов через Claude Desktop, screenshot работы