Дизайн MCP-сервера

Спроектируй MCP-сервер для {{domain}}.

Что такое MCP

Model Context Protocol — стандарт от Anthropic для подключения внешних tools/ресурсов к Claude (и другим клиентам). Один сервер — много возможностей.

Capabilities

MCP выставляет три типа:

Шаги дизайна

1. Определи скоуп

• Какой сервис обёртываем?
• Какие use-case'ы решаем?
• Что НЕ входит (важно — чтобы не превратилось в "обёртку всего API")

2. Список tools (актуальные действия)

Для {{domain}} перечисли действия:

• Минимум 3, максимум ~15 tools на сервер
• Каждый — атомарное полезное действие
• Не пересекаются (не два инструмента делают одно и то же)

Пример для domain=GitHub:

list_repos
search_code
create_issue
update_issue
list_pull_requests
get_pull_request
review_pull_request
add_comment

3. Дизайн каждого tool (см. отдельный промт "Дизайн кастомного инструмента")

4. Resources

Resources — это то что агент читает. Хорошо для:

• Файлов
• Документов
• Логов
• Чего-то с уникальным URI

file:///path/to/doc.md
db://customers/12345
api://github/issues/42

Resource ≠ tool: resource просто отдаёт content по URI, tool делает действие.

5. Prompts (шаблоны)

Опционально. Если в твоём домене есть стандартные паттерны промтов — выставь как prompts:

name: review_pr
description: "Review a GitHub PR for issues"
arguments:
  - pr_number: integer
template: |
  Review PR #{{pr_number}}. Focus on:
  - Security
  - Performance
  - Code style
  Use get_pull_request to fetch details.

6. Авторизация

Это критично. MCP-сервер часто работает с чувствительными данными:

• OAuth / Token: на старте сервера
• Scoped permissions: read vs write vs admin
• Per-tool gates: delete_database требует подтверждения
• Audit log: каждый вызов логируется

7. Ошибки и таймауты

• Таймаут на каждый вызов (5-30 сек)
• Структурированные ошибки (см. tool design)
• Идемпотентность для write-операций

8. Тестирование с реальным клиентом

1. Запусти MCP в test-режиме
2. Подключи к Claude Desktop или CLI
3. Дай агенту 5 разных типовых задач
4. Смотри:
   • Правильно ли выбирает инструмент?
   • Правильно ли заполняет параметры?
   • Обрабатывает ли ошибки?
   • Не зацикливается?

Если на простой задаче агент путается — описания tools плохие.

9. Документация для пользователей

Кто будет ставить твой MCP:

• README с установкой (npm i / pip install)
• Конфиг для Claude Desktop / VS Code
• Список tools с примерами
• Известные ограничения

10. Размер и фокус

Лучше много маленьких MCP чем один большой:

• Один сервер = одна цель (GitHub, Stripe, своя БД)
• Не "everything-server" — модель запутается в 50 tools

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

• ❌ run_command(cmd) — даёт shell-доступ, не делай так
• ❌ raw_sql_query(sql) — то же самое
• ❌ Tool который возвращает массив данных длиной 100k токенов
• ❌ Async tools без статуса (агент не знает закончилось ли)
• ❌ Tools без документации — никто не разберётся как использовать

В конце дай

• Список tools / resources / prompts
• Схема каждого
• Auth-flow
• Пример конфига для подключения