MCP-сервер с нуля

Построй MCP-сервер для {{service}} на {{stack}}. Цель — рабочий бинарник, подключаемый к Claude Code за 90 минут.

0. Прочитай нужное из SDK

Перед написанием кода открой документацию SDK для своего стека. Список tools/resources и сигнатуры могут меняться от версии к версии. Не пиши по памяти.

1. Концепция (10 минут, не больше)

Ответь письменно на 4 вопроса:

• Какие 3-7 действий хочу выставить агенту?
• Какие read-only данные имеют URI? (это будущие resources)
• Какой доступ нужен — read / write / admin?
• Где живёт авторизация — env var, OAuth-flow, локальный keychain?

Если ответы расплываются — урежь скоуп до одного use-case. Лучше маленький честный сервер, чем большой "когда-нибудь".

2. Скелет проекта

mcp-{{service}}/
  package.json | pyproject.toml
  src/
    index.ts | __main__.py    # точка входа, регистрация
    tools/                    # по файлу на tool
    resources/                # по файлу на resource
    auth.ts                   # token / OAuth
  README.md

Зависимость одна: официальный MCP SDK (@modelcontextprotocol/sdk для TS, mcp для Python). Не тащи фреймворк.

3. Дизайн одного tool

Шаблон:

{
  name: "create_issue",
  description: "Create a GitHub issue in the given repo. Use when the user explicitly asks to file or open an issue.",
  inputSchema: {
    type: "object",
    properties: {
      repo: { type: "string", description: "owner/name format" },
      title: { type: "string", minLength: 1, maxLength: 200 },
      body: { type: "string" },
      labels: { type: "array", items: { type: "string" } }
    },
    required: ["repo", "title"]
  }
}

Правила:

• Описание включает когда вызывать, не только что делает
• Параметры с валидацией (длина, enum, pattern)
• Никаких run_command или raw_sql — это shell, а не tool
• Ответ ограничен по размеру (truncate с пометкой если > N токенов)

4. Resources (опционально)

Если у тебя есть данные с уникальным URI — выстави как resource:

{{service}}://issues/12345
{{service}}://users/by-id/42

Resource = pure read, без побочек. Если нужна параметризация — это tool, не resource.

5. Auth

Не храни секреты в коде. Не логируй секреты. Падай явно если auth не настроен.

6. Локальный запуск

# stdio-режим (для Claude Code и Desktop)
npx tsx src/index.ts
# или
python -m mcp_{{service}}

Проверь руками через MCP inspector (есть в SDK) — что server отдаёт правильный capability list.

7. Регистрация в Claude Code

{
  "mcpServers": {
    "{{service}}": {
      "command": "npx",
      "args": ["-y", "mcp-{{service}}"],
      "env": { "{{SERVICE}}_TOKEN": "..." }
    }
  }
}

Положи в ~/.claude/mcp.json (или указанный в твоей версии путь). Перезапусти Claude Code. Проверь что tools появились в списке.

8. Smoke-тесты с реальным агентом

Дай Claude 5 типовых задач и наблюдай:

• Выбирает ли правильный tool с первого раза?
• Корректно ли заполняет параметры?
• Что делает при ошибке от сервера?

Если на простой задаче агент путается — описания tools слабые. Перепиши description.

9. Деплой

• Личный: оставь как локальный stdio-сервер
• Командный: упакуй как npm-пакет / pip-модуль
• Публичный: добавь в реестр MCP-серверов с README, конфигом для Claude Desktop, списком tools и known limits

Анти-паттерны

• Tools, дублирующие друг друга
• Описания вида "performs operation"
• Возврат сырого 100k JSON
• Async tool без полла статуса
• Один "everything-server" с 40 tools

На выходе

• Работающий бинарник
• README с установкой и конфигом
• 3-5 tools с тестами
• Запись в ~/.claude/mcp.json