--- name: mcp-builder description: Руководство по созданию качественных серверов MCP (Model Context Protocol), позволяющих большим языковым моделям взаимодействовать с внешними сервисами с помощью хорошо спроектированных инструментов. Используй при создании серверов MCP для интеграции внешних API или сервисов как на Python (FastMCP), так и на Node/TypeScript (MCP SDK). license: Полные условия в LICENSE.txt --- # Руководство по разработке серверов MCP ## Обзор Создавай серверы MCP (Model Context Protocol), позволяющие большим языковым моделям взаимодействовать с внешними сервисами с помощью хорошо спроектированных инструментов. Качество сервера MCP определяется тем, насколько хорошо он позволяет большим языковым моделям выполнять реальные задачи. --- # Процесс ## 🚀 Рабочий процесс в общих чертах Создание качественного сервера MCP включает четыре основных этапа: ### Этап 1: глубокое исследование и планирование #### 1.1 Разберись в современном проектировании MCP **Охват API и инструменты рабочих процессов:** Уравновешивай всесторонний охват конечных точек API со специализированными инструментами рабочих процессов. Инструменты рабочих процессов могут быть удобнее для конкретных задач, тогда как всесторонний охват даёт агентам гибкость при составлении операций. Эффективность различается в зависимости от клиента: некоторым клиентам полезно выполнение кода, объединяющего базовые инструменты, а другие лучше работают с рабочими процессами более высокого уровня. При неопределённости отдавай приоритет всестороннему охвату API. **Именование и обнаруживаемость инструментов:** Ясные, описательные имена инструментов помогают агентам быстро находить нужные инструменты. Используй единообразные префиксы (например, `github_create_issue`, `github_list_repos`) и именование, ориентированное на действия. **Управление контекстом:** Агентам полезны краткие описания инструментов и возможность фильтровать результаты и получать их постранично. Проектируй инструменты, возвращающие целевые, релевантные данные. Некоторые клиенты поддерживают выполнение кода, что может помочь агентам эффективно фильтровать и обрабатывать данные. **Сообщения об ошибках, подсказывающие действия:** Сообщения об ошибках должны направлять агентов к решениям с помощью конкретных предложений и дальнейших шагов. #### 1.2 Изучи документацию протокола MCP **Ориентируйся в спецификации MCP:** Начни с карты сайта, чтобы найти нужные страницы: `https://modelcontextprotocol.io/sitemap.xml` Затем загружай конкретные страницы с суффиксом `.md` для формата Markdown (например, `https://modelcontextprotocol.io/specification/draft.md`). Ключевые страницы для изучения: - Обзор спецификации и архитектуры - Транспортные механизмы (потоковый HTTP, stdio) - Определения инструментов, ресурсов и промптов #### 1.3 Изучи документацию фреймворков **Рекомендуемый стек:** - **Язык**: TypeScript (высококачественная поддержка SDK и хорошая совместимость со многими средами выполнения, например MCPB. Кроме того, модели ИИ хорошо генерируют код TypeScript благодаря его широкому использованию, статической типизации и хорошим инструментам линтинга) - **Транспорт**: потоковый HTTP для удалённых серверов с использованием JSON без состояния (проще масштабировать и сопровождать, чем сессии с состоянием и потоковые ответы). stdio для локальных серверов. **Загрузи документацию фреймворков:** - **Лучшие практики MCP**: [📋 Посмотреть лучшие практики](./reference/mcp_best_practices.md) — основные рекомендации **Для TypeScript (рекомендуется):** - **TypeScript SDK**: используй WebFetch, чтобы загрузить `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` - [⚡ Руководство по TypeScript](./reference/node_mcp_server.md) — паттерны и примеры TypeScript **Для Python:** - **Python SDK**: используй WebFetch, чтобы загрузить `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` - [🐍 Руководство по Python](./reference/python_mcp_server.md) — паттерны и примеры Python #### 1.4 Спланируй реализацию **Разберись в API:** Изучи документацию API сервиса, чтобы определить ключевые конечные точки, требования к аутентификации и модели данных. При необходимости используй веб-поиск и WebFetch. **Выбор инструментов:** Отдавай приоритет всестороннему охвату API. Перечисли конечные точки для реализации, начиная с наиболее распространённых операций. --- ### Этап 2: реализация #### 2.1 Настрой структуру проекта Смотри руководства для конкретных языков по настройке проекта: - [⚡ Руководство по TypeScript](./reference/node_mcp_server.md) — структура проекта, package.json, tsconfig.json - [🐍 Руководство по Python](./reference/python_mcp_server.md) — организация модулей, зависимости #### 2.2 Реализуй основную инфраструктуру Создай общие утилиты: - API-клиент с аутентификацией - Вспомогательные функции обработки ошибок - Форматирование ответов (JSON/Markdown) - Поддержка пагинации #### 2.3 Реализуй инструменты Для каждого инструмента: **Схема входных данных:** - Используй Zod (TypeScript) или Pydantic (Python) - Включай ограничения и ясные описания - Добавляй примеры в описания полей **Схема выходных данных:** - По возможности определяй `outputSchema` для структурированных данных - Используй `structuredContent` в ответах инструментов (возможность TypeScript SDK) - Помогает клиентам понимать и обрабатывать результаты инструментов **Описание инструмента:** - Краткое описание функциональности - Описания параметров - Схема возвращаемого типа **Реализация:** - Async/await для операций ввода-вывода - Корректная обработка ошибок с сообщениями, подсказывающими действия - Поддержка пагинации, где применимо - Возвращай и текстовое содержимое, и структурированные данные при использовании современных SDK **Аннотации:** - `readOnlyHint`: true/false - `destructiveHint`: true/false - `idempotentHint`: true/false - `openWorldHint`: true/false --- ### Этап 3: проверка и тестирование #### 3.1 Качество кода Проверь: - Отсутствие дублирующегося кода (принцип DRY) - Единообразную обработку ошибок - Полное покрытие типами - Ясные описания инструментов #### 3.2 Сборка и тестирование **TypeScript:** - Запусти `npm run build` для проверки компиляции - Протестируй с помощью MCP Inspector: `npx @modelcontextprotocol/inspector` **Python:** - Проверь синтаксис: `python -m py_compile your_server.py` - Протестируй с помощью MCP Inspector Подробные подходы к тестированию и контрольные списки качества смотри в руководствах для конкретных языков. --- ### Этап 4: создание оценочных заданий После реализации сервера MCP создай всесторонние оценочные задания для проверки его эффективности. **Загрузи [✅ Руководство по оценке](./reference/evaluation.md), чтобы получить полные рекомендации по оцениванию.** #### 4.1 Пойми цель оценки Используй оценочные задания, чтобы проверить, могут ли большие языковые модели эффективно использовать твой сервер MCP для ответов на реалистичные сложные вопросы. #### 4.2 Создай 10 оценочных вопросов Для создания эффективных оценочных заданий следуй процессу, описанному в руководстве по оценке: 1. **Изучение инструментов**: перечисли доступные инструменты и разберись в их возможностях 2. **Исследование содержимого**: используй операции ТОЛЬКО ДЛЯ ЧТЕНИЯ, чтобы изучить доступные данные 3. **Генерация вопросов**: создай 10 сложных реалистичных вопросов 4. **Проверка ответов**: самостоятельно реши каждый вопрос, чтобы проверить ответы #### 4.3 Требования к оценочным заданиям Убедись, что каждый вопрос: - **Независимый**: не зависит от других вопросов - **Только для чтения**: требует лишь неразрушающих операций - **Сложный**: требует нескольких вызовов инструментов и глубокого исследования - **Реалистичный**: основан на реальных сценариях использования, важных для людей - **Проверяемый**: имеет один ясный ответ, который можно проверить сравнением строк - **Стабильный**: ответ не изменится со временем #### 4.4 Формат вывода Создай XML-файл с такой структурой: ```xml Найди обсуждения запусков моделей ИИ с кодовыми именами животных. Для одной модели нужно было определить специальное обозначение безопасности в формате ASL-X. Какое число X определяли для модели, названной в честь пятнистой дикой кошки? 3 ``` --- # Справочные файлы ## 📚 Библиотека документации Загружай эти ресурсы по мере необходимости во время разработки: ### Основная документация MCP (загрузи сначала) - **Протокол MCP**: начни с карты сайта `https://modelcontextprotocol.io/sitemap.xml`, затем загружай конкретные страницы с суффиксом `.md` - [📋 Лучшие практики MCP](./reference/mcp_best_practices.md) — универсальные рекомендации по MCP, включая: - Соглашения об именовании серверов и инструментов - Рекомендации по формату ответа (JSON и Markdown) - Лучшие практики пагинации - Выбор транспорта (потоковый HTTP или stdio) - Стандарты безопасности и обработки ошибок ### Документация SDK (загружай на этапах 1/2) - **Python SDK**: загрузи из `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md` - **TypeScript SDK**: загрузи из `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md` ### Руководства по реализации для конкретных языков (загружай на этапе 2) - [🐍 Руководство по реализации на Python](./reference/python_mcp_server.md) — полное руководство по Python/FastMCP с: - Паттернами инициализации сервера - Примерами моделей Pydantic - Регистрацией инструментов с помощью `@mcp.tool` - Полными работающими примерами - Контрольным списком качества - [⚡ Руководство по реализации на TypeScript](./reference/node_mcp_server.md) — полное руководство по TypeScript с: - Структурой проекта - Паттернами схем Zod - Регистрацией инструментов с помощью `server.registerTool` - Полными работающими примерами - Контрольным списком качества ### Руководство по оценке (загружай на этапе 4) - [✅ Руководство по оценке](./reference/evaluation.md) — полное руководство по созданию оценочных заданий с: - Рекомендациями по созданию вопросов - Стратегиями проверки ответов - Спецификациями формата XML - Примерами вопросов и ответов - Запуском оценки с помощью предоставленных скриптов