MCP-сервер от спеки до npm publish

Ты — orchestrator. Твоя задача: провести MCP-сервер через все 7 фаз — от концепции до публикации в npm. Юзер должен уйти с рабочим пакетом в реестре, который можно подключить к Claude Desktop одной строчкой в конфиге.

Что сервер предоставляет: {{server_purpose}} Целевая аудитория: {{target_audience}}

Когда применять

MCP-сервер уместен когда:

• Есть data source (база, API, файловая система, корпоративный хранилище), которым Claude должен пользоваться через standardized interface.
• Есть tools / actions (создать ticket, отправить email, дёрнуть webhook), которые нужно безопасно дать модели.
• У сервера будет несколько пользователей (твоя команда, клиенты, open-source).
• Нужно, чтобы интеграция работала во всех MCP-клиентах (Claude Desktop, Cursor, Cline, кастомные агенты), а не только в одном.

Когда НЕ применять

• Одноразовый скрипт для себя — обычный CLI или node script.js проще.
• Достаточно /slash-command в Claude Code — не выходи за рамки.
• Единственный пользователь — ты сам, и интеграция не нужна другим инструментам.
• Прототип на 1 вечер без планов на сопровождение — MCP-инфраструктура переплатит за себя.

Phase 1 · Spec

Цель: зафиксировать scope до того, как написана первая строка кода.

Определи:

• Что предоставляет сервер: tools (действия) / resources (read-only данные) / prompts (готовые шаблоны). Можно комбинацию, но один из трёх — основной.
• Success criteria: 3-5 конкретных вещей, которые Claude сможет делать с этим сервером. Формулируй как user story: «Claude может найти все open PR в моём репозитории и сгруппировать по reviewer».
• Non-goals: что сервер не делает (даже если попросят). Минимум 3 пункта. Это защита от scope creep.
• Constraints: rate limits внешних API, auth model (API key / OAuth / local), требования к окружению (Node ≥ 18, нужен ли Docker).

Output фазы 1: 1-страничная спека:

# {server-name}-mcp

## Purpose
{одно предложение, читаемое за 5 секунд}

## Capabilities
- Tools: {список с 1-line описанием}
- Resources: {URI-схема + что доступно}
- Prompts: {если применимо}

## Non-goals
- НЕ делает X
- НЕ хранит Y
- НЕ требует Z

## Target users
{кто, какой их workflow до сервера, что меняется после}

Phase 2 · Scaffold

Цель: базовая структура npm-пакета, готовая для разработки.

Stack:

• @modelcontextprotocol/sdk (официальный SDK от Anthropic).
• zod для валидации входных параметров tools.
• TypeScript (strict mode). ESM-only — MCP клиенты ожидают modern Node.
• tsup или tsc для билда.

Файловая структура:

my-mcp-server/
├── package.json        # bin entry, "type": "module", engines.node >= 18
├── tsconfig.json       # target: ES2022, module: NodeNext
├── src/
│   ├── index.ts        # server bootstrap, регистрация tools/resources
│   ├── tools/          # один файл на tool
│   ├── resources/      # один файл на resource type
│   └── lib/            # shared helpers, API клиенты
├── dist/               # build output (в .gitignore, в "files" package.json)
├── tests/
└── README.md

package.json essentials:

{
  "name": "@scope/my-mcp",
  "version": "0.1.0",
  "type": "module",
  "bin": { "my-mcp": "./dist/index.js" },
  "files": ["dist", "README.md", "LICENSE"],
  "engines": { "node": ">=18" }
}

Output фазы 2: starter-репо (структура + конфиги + минимальный src/index.ts, который запускается через node dist/index.js без ошибок).

Phase 3 · Tools

Цель: дизайн tool-API, который агент сможет правильно использовать.

Для каждого tool:

• Schema (zod): обязательные/опциональные параметры с понятными именами и 1-line описаниями полей.
• Handler: async-функция, возвращающая { content: [...] }. Никаких throw без обработки — всегда возвращай structured error.
• Error handling: rate limit → retry-after, auth fail → внятное сообщение «проверь ENV_VAR», not found → не путай с серверной ошибкой.
• Description: purpose (одной фразой) + when to use (2-3 триггера) + when NOT to use (минимум 1 edge), + 1 пример input/output.

Жёсткий потолок: 5-7 tools. Больше — agent теряется при выборе, точность падает. Если кажется что нужно 12 — объединяй (search_X с фильтрами лучше, чем 5 get_X_by_*).

Tool naming: snake_case, verb-form (create_issue, не issue). Не префикси именем сервера — у каждого tool уже есть namespace.

Output фазы 3:

1. Таблица: tool | purpose | when to call | when NOT to call.
2. Все zod-схемы в одном блоке.
3. Реализованные handlers с error paths.

Phase 4 · Resources (если применимо)

Цель: дать Claude read-only доступ к данным через URI-схему.

Когда нужны resources:

• Данные, которые модель должна читать, но не модифицировать (документы, конфиги, snapshot базы).
• Контент с MIME types (markdown, json, csv, изображения).
• Когда tool «get X» был бы избыточен — лучше выдать URI и пусть клиент кеширует.

Когда не нужны:

• Любое действие/мутация → tool, не resource.
• Динамические запросы с параметрами → tool с фильтрами.

Implement:

• list_resources handler — возвращает массив { uri, name, mimeType, description }.
• read_resource handler — по URI отдаёт содержимое.
• URI scheme: myserver://category/id (например github://repos/owner/name/pulls/42). Документируй в README.
• MIME types: text/markdown, application/json, text/plain. Не выдумывай свои.
• Кеширование: etag/last-modified если данные стабильны, иначе клиент будет дёргать одно и то же.

Output фазы 4: resource definitions + примеры URI + что вернётся на read_resource. Если решил что resources не нужны — короткое обоснование (1-2 строки) и переходи к Phase 5.

Phase 5 · Tests

Цель: убедиться, что сервер работает не только «у меня на маке».

Три уровня:

1. Unit (handlers): изолированные тесты для каждой tool-функции. Mock внешних API. Покрытие edge cases: пустой input, превышение rate limit, malformed response.
2. Integration (JSON-RPC handshake через stdio): запускаешь сервер как subprocess, отправляешь initialize → tools/list → tools/call, проверяешь корректные ответы. Это то, что делает Claude Desktop при старте.
3. Eval (LLM-as-judge): даёшь Claude задачу, для которой нужен твой сервер. Проверяешь — вызвал ли он правильный tool с правильными параметрами. Если описания tools плохие, Claude промахнётся — это сигнал переписать descriptions.

Smoke script:

# scripts/smoke.sh
node dist/index.js < tests/fixtures/initialize.json

Должен отрабатывать за < 2 секунд без stderr.

Output фазы 5: тестовый набор + smoke script + CI workflow (GitHub Actions: lint → typecheck → unit → integration на каждый PR).

Phase 6 · Docs

Цель: пользователь должен подключить сервер за 60 секунд.

README структура (в этом порядке, потому что 80% юзеров не доскролит до низа):

1. Что это (1 параграф) — purpose + кому полезно.
2. Install — одна команда: npm install -g @scope/my-mcp или npx-вариант.
3. claude_desktop_config snippet (copy-paste готовый):

   {
     "mcpServers": {
       "my-server": {
         "command": "npx",
         "args": ["-y", "@scope/my-mcp"],
         "env": { "MY_API_KEY": "..." }
       }
     }
   }
   

   Путь к файлу: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows).
4. Tools list с примерами user-запросов: «Спроси Claude: Найди все PR, ожидающие моего ревью».
5. Environment variables — таблица: name | required? | description | example.
6. Troubleshooting — топ-5 проблем с решениями (сервер не появляется в Claude Desktop → проверь JSON, перезапусти приложение, смотри логи в ~/Library/Logs/Claude/).
7. Contributing — как локально запустить, как добавить tool, как протестировать.

LICENSE: MIT по умолчанию (если нет причин ужесточать).

Output фазы 6: README + LICENSE + CHANGELOG.md с записью ## 0.1.0 - Initial release.

Phase 7 · Publish

Цель: пакет в npm + пользователи знают, что он существует.

Pre-publish checklist:

• ☐ npm run build без ошибок и warnings.
• ☐ npm pack — проверь содержимое .tgz: только dist/, README.md, LICENSE. Никаких src/, .env, node_modules/.
• ☐ Версия в package.json совпадает с CHANGELOG (semver: 0.x.x пока breaking changes ожидаемы).
• ☐ npm whoami показывает правильный аккаунт.
• ☐ Если scope (@org/name) — у тебя есть права на org.

Publish:

npm publish --access public  # обязательно для scoped packages

Post-publish:

• GitHub release с тегом v0.1.0 и копией changelog.
• Announcement:
  • Twitter/X — короткий тред: проблема → решение → 1 GIF демо → ссылка.
  • Discord MCP-комьюнити (#mcp-servers в Anthropic Discord).
  • Hacker News / r/ClaudeAI если есть основания (релевантность ≥ medium).
• README badges: npm version, downloads, license, MCP-compatible.
• Мониторинг (первая неделя):
  • npm downloads (npm-stat.com).
  • GitHub issues — отвечай в течение 24 часов на первые 10.
  • Логи: что ломается у первых юзеров (попроси в README присылать ~/Library/Logs/Claude/mcp-server-{name}.log).

Output фазы 7: publishing checklist (☐ pre ☐ publish ☐ post) + announcement-шаблон (Twitter + Discord) + ссылка на live-пакет.

Контракт между фазами

Каждая фаза → следующая через checkpoint. Без checkpoint'а следующая блокируется.

Если на фазе N не хватает данных от N-1 — остановись и доделай N-1. Не пиши TODO, не делай заглушки.

Формат вывода

Все 7 фаз в одном response, каждая под ## Phase N · Name. Каждая фаза = минимально полный артефакт, который можно взять и использовать (код, конфиг, текст). В конце — секция ## Готово / Осталось с прямым перечислением.

Anti-patterns

• ❌ Скачать template и сразу publish без Phase 3-4 (дизайн tools) → пользователи получают мусор, удаляют пакет, оставляют 1 звезду на GitHub.
• ❌ 20 tools — agent (Claude) не знает что выбрать, точность падает. Жёсткий потолок: 5-7.
• ❌ Описания tools как «manages X» → не помогает agent'у решать когда использовать. Нужны конкретные триггеры и контр-примеры.
• ❌ Без error handling в handlers → крэшится при первом edge case, Claude Desktop показывает «server disconnected», юзер думает что MCP в целом сломан.
• ❌ Без integration tests (JSON-RPC handshake через stdio) → «работает у меня» → не работает в Claude Desktop, потому что забыл flush stdout или неправильный формат ответа.
• ❌ README без claude_desktop_config snippet → пользователи не могут подключить, идут читать чужие README, не возвращаются.
• ❌ Skip publishing announcements → npm package никто не найдёт, downloads = 3 в месяц, мотивация поддерживать пропадает.
• ❌ Опубликовать 0.1.0 и сразу делать breaking change в 0.1.1 → юзеры не ожидают, конфиги ломаются. Используй 0.x.0 для minor breaking, 1.0.0 когда API стабильно.
• ❌ Сложить весь src/ в опубликованный пакет → npm install качает в 10× больше нужного. files в package.json — обязательно.
• ❌ Хардкод API keys в коде или дефолтных конфигах → они утекут на GitHub, npm их сохранит в кеше навсегда. Только env vars.
• ❌ Tools, которые делают destructive actions без confirmation → Claude вызовет delete_all_issues потому что юзер сказал «почисти бэклог». Требуй явный confirm: true для опасного.

Deliverable

Готовый production-grade MCP-сервер:

1. 1-страничная спека (фаза 1) — основа для всех решений.
2. Scaffold с правильным package.json и build-pipeline (фаза 2).
3. 5-7 tools с zod-схемами, handlers, error paths (фаза 3).
4. Resources с URI-схемой и MIME types — если применимо (фаза 4).
5. Unit + integration + eval тесты, CI workflow (фаза 5).
6. README с copy-paste claude_desktop_config + LICENSE + CHANGELOG (фаза 6).
7. Опубликованный npm пакет + GitHub release + announcement (фаза 7).