On this page Сборка, тестирование, проверка, установка и развёртывание MCP-серверов с FastMCP на Python. Используйте при создании нового MCP-сервера, обёртывании API или базы данных в виде MCP-инструментов, предоставлении ресурсов или промптов, либо при подготовке FastMCP-сервера для Claude Code, Cursor или HTTP-развёртывания.

Информация о навыке¶

|---|---
|Source| Опционально — установка через hermes skills install official/mcp/fastmcp
|Path| optional-skills/mcp/fastmcp
|Version| 1.0.0
|Author| Hermes Agent
|License| MIT
|Tags| MCP, FastMCP, Python, Tools, Resources, Prompts, Deployment
|Related skills| native-mcp, mcporter

Справочник: полный SKILL.md¶

info Ниже приведено полное определение навыка, которое Hermes загружает при его активации. Это те инструкции, которые видит агент, когда навык активен.

FastMCP¶

Сборка MCP-серверов на Python с FastMCP, локальная валидация, установка в MCP-клиенты и развёртывание в виде HTTP-эндпоинтов.

Когда использовать¶

Используйте этот навык, когда задача заключается в: * создании нового MCP-сервера на Python * обёртывании API, базы данных, CLI или workflow обработки файлов в виде MCP-инструментов * предоставлении ресурсов или промптов в дополнение к инструментам * быстрой проверке сервера с помощью FastMCP CLI перед подключением к Hermes или другому клиенту * установке сервера в Claude Code, Claude Desktop, Cursor или аналогичный MCP-клиент * подготовке репозитория FastMCP-сервера для HTTP-развёртывания

Используйте native-mcp, когда сервер уже существует и его нужно только подключить к Hermes. Используйте mcporter, когда цель — ad-hoc CLI-доступ к существующему MCP-серверу вместо создания нового.

Предварительные требования¶

Сначала установите FastMCP в рабочем окружении: [code] pip install fastmcp
fastmcp version

[/code] Для шаблона API установите httpx, если его ещё нет: [code] pip install httpx

[/code]

Включённые файлы¶

Шаблоны¶

templates/api_wrapper.py - обёртка REST API с поддержкой заголовков авторизации
templates/database_server.py - сервер только для чтения SQLite-запросов
templates/file_processor.py - сервер проверки и поиска текстовых файлов

Скрипты¶

scripts/scaffold_fastmcp.py - копирование стартового шаблона и замена плейсхолдера имени сервера

Справочные материалы¶

references/fastmcp-cli.md - рабочий процесс FastMCP CLI, цели установки и проверки развёртывания

Рабочий процесс¶

1. Выберите минимально жизнеспособную форму сервера¶

Сначала выберите наиболее узкую полезную поверхность: * обёртка API: начните с 1–3 наиболее ценных эндпоинтов, а не всего API * сервер базы данных: предоставьте интроспекцию только для чтения и ограниченный путь запросов * обработчик файлов: предоставьте детерминированные операции с явными аргументами путей * промпты/ресурсы: добавляйте только когда клиенту нужны переиспользуемые шаблоны промптов или обнаруживаемые документы

Предпочитайте компактный сервер с хорошими именами, докстрингами и схемами вместо большого сервера с расплывчатыми инструментами.

2. Создайте заготовку из шаблона¶

Скопируйте шаблон напрямую или используйте вспомогательный скрипт: [code] python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py \
--template api_wrapper \
--name "Acme API" \
--output ./acme_server.py

[/code] Доступные шаблоны: [code] python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py --list

[/code] Если копируете вручную, замените __SERVER_NAME__ на реальное имя сервера.

3. Сначала реализуйте инструменты¶

Начните с функций @mcp.tool, прежде чем добавлять ресурсы или промпты. Правила проектирования инструментов: * Давайте каждому инструменту конкретное имя на основе глагола * Пишите докстринги как описания инструментов для пользователя * Делайте параметры явными и типизированными * Возвращайте структурированные JSON-безопасные данные, где это возможно * Проверяйте небезопасные входные данные на раннем этапе * Для первых версий предпочитайте поведение только для чтения

Примеры хороших инструментов: * get_customer * search_tickets * describe_table * summarize_text_file

Примеры слабых инструментов: * run * process * do_thing

4. Добавляйте ресурсы и промпты только когда они полезны¶

Добавляйте @mcp.resource, когда клиенту полезно получать стабильное содержимое только для чтения, такое как схемы, политики или сгенерированные отчёты. Добавляйте @mcp.prompt, когда сервер должен предоставить переиспользуемый шаблон промпта для известного рабочего процесса. Не превращайте каждый документ в промпт. Предпочитайте: * инструменты для действий * ресурсы для получения данных/документов * промпты для переиспользуемых инструкций LLM

5. Тестируйте сервер перед интеграцией куда-либо¶

Используйте FastMCP CLI для локальной валидации: [code] fastmcp inspect acme_server.py:mcp
fastmcp list acme_server.py --json
fastmcp call acme_server.py search_resources query=router limit=5 --json

[/code] Для быстрой итеративной отладки запустите сервер локально: [code] fastmcp run acme_server.py:mcp

[/code] Для тестирования HTTP-транспорта локально: [code] fastmcp run acme_server.py:mcp --transport http --host 127.0.0.1 --port 8000
fastmcp list http://127.0.0.1:8000/mcp --json
fastmcp call http://127.0.0.1:8000/mcp search_resources query=router --json

[/code] Всегда выполняйте хотя бы один реальный fastmcp call для каждого нового инструмента, прежде чем утверждать, что сервер работает.

6. Установите в клиент после успешной локальной валидации¶

FastMCP может зарегистрировать сервер в поддерживаемых MCP-клиентах: [code] fastmcp install claude-code acme_server.py
fastmcp install claude-desktop acme_server.py
fastmcp install cursor acme_server.py -e .

[/code] Используйте fastmcp discover для просмотра именованных MCP-серверов, уже настроенных на машине. Когда цель — интеграция с Hermes, либо: * настройте сервер в ~/.hermes/config.yaml с помощью навыка native-mcp, либо * продолжайте использовать команды FastMCP CLI во время разработки, пока интерфейс не стабилизируется

7. Развёртывайте после стабилизации локального контракта¶

Для управляемого хостинга Prefect Horizon — это путь, который FastMCP документирует наиболее прямо. Перед развёртыванием: [code] fastmcp inspect acme_server.py:mcp

[/code] Убедитесь, что репозиторий содержит: * Python-файл с объектом FastMCP-сервера * requirements.txt или pyproject.toml * документацию по переменным окружения, необходимым для развёртывания

Для обычного HTTP-хостинга сначала проверьте HTTP-транспорт локально, затем развёртывайте на любой Python-совместимой платформе, которая может открыть порт сервера.

Типовые шаблоны¶

Шаблон обёртки API¶

Используйте, когда нужно предоставить REST или HTTP API в виде MCP-инструментов. Рекомендуемый первый срез: * один путь чтения * один путь списка/поиска * опционально проверка здоровья

Замечания по реализации: * храните аутентификацию в переменных окружения, не хардкодьте * централизуйте логику запросов в одном помощнике * передавайте ошибки API с кратким контекстом * нормализуйте несогласованные ответы вышестоящих систем перед возвратом

Начните с templates/api_wrapper.py.

Шаблон базы данных¶

Используйте, когда нужно предоставить безопасные возможности запросов и инспекции. Рекомендуемый первый срез: * list_tables * describe_table * один инструмент для ограниченного read-запроса

Замечания по реализации: * по умолчанию используйте доступ к БД только для чтения * отклоняйте не-SELECT SQL в ранних версиях * ограничивайте количество строк * возвращайте строки вместе с именами столбцов

Начните с templates/database_server.py.

Шаблон обработчика файлов¶

Используйте, когда серверу нужно проверять или преобразовывать файлы по запросу. Рекомендуемый первый срез: * суммаризация содержимого файлов * поиск внутри файлов * извлечение детерминированных метаданных

Замечания по реализации: * принимайте явные пути к файлам * проверяйте на отсутствие файлов и ошибки кодировок * ограничивайте предпросмотры и количество результатов * избегайте вызова внешних команд, если не требуется конкретный внешний инструмент

Начните с templates/file_processor.py.

Планка качества¶

Перед передачей FastMCP-сервера проверьте всё следующее: * сервер импортируется без ошибок * fastmcp inspect <file.py:mcp> выполняется успешно * fastmcp list <server spec> --json выполняется успешно * каждый новый инструмент имеет хотя бы один реальный fastmcp call * переменные окружения задокументированы * поверхность инструментов достаточно мала, чтобы её можно было понять без догадок

Устранение неполадок¶

Команда FastMCP не найдена¶

Установите пакет в активном окружении: [code] pip install fastmcp
fastmcp version

[/code]

`fastmcp inspect` завершается ошибкой¶

Проверьте, что: * файл импортируется без побочных эффектов, вызывающих сбой * экземпляр FastMCP назван правильно в <file.py:object> * установлены опциональные зависимости из шаблона

Инструмент работает в Python, но не через CLI¶

Выполните: [code] fastmcp list server.py --json
fastmcp call server.py your_tool_name --json

[/code] Обычно это выявляет несоответствия имён, отсутствующие обязательные аргументы или несериализуемые возвращаемые значения.

Hermes не видит развёрнутый сервер¶

Часть сборки сервера может быть корректной, а конфигурация Hermes — нет. Загрузите навык native-mcp и настройте сервер в ~/.hermes/config.yaml, затем перезапустите Hermes.

Ссылки¶

Для получения подробной информации о CLI, целях установки и проверках развёртывания прочитайте references/fastmcp-cli.md. * Информация о навыке * Справочник: полный SKILL.md * Когда использовать * Предварительные требования * Включённые файлы * Шаблоны * Скрипты * Справочные материалы * Рабочий процесс * 1. Выберите минимально жизнеспособную форму сервера * 2. Создайте заготовку из шаблона * 3. Сначала реализуйте инструменты * 4. Добавляйте ресурсы и промпты только когда они полезны * 5. Тестируйте сервер перед интеграцией куда-либо * 6. Установите в клиент после успешной локальной валидации * 7. Развёртывайте после стабилизации локального контракта * Типовые шаблоны * Шаблон обёртки API * Шаблон базы данных * Шаблон обработчика файлов * Планка качества * Устранение неполадок * Команда FastMCP не найдена * fastmcp inspect завершается ошибкой * Инструмент работает в Python, но не через CLI * Hermes не видит развёрнутый сервер * Ссылки

Информация о навыке​¶

Справочник: полный SKILL.md​¶

FastMCP¶

Когда использовать​¶

Предварительные требования​¶

Включённые файлы​¶

Шаблоны​¶

Скрипты​¶

Справочные материалы​¶

Рабочий процесс​¶

1. Выберите минимально жизнеспособную форму сервера​¶

2. Создайте заготовку из шаблона​¶

3. Сначала реализуйте инструменты​¶

4. Добавляйте ресурсы и промпты только когда они полезны​¶

5. Тестируйте сервер перед интеграцией куда-либо​¶

6. Установите в клиент после успешной локальной валидации​¶

7. Развёртывайте после стабилизации локального контракта​¶

Типовые шаблоны​¶

Шаблон обёртки API​¶

Шаблон базы данных​¶

Шаблон обработчика файлов​¶

Планка качества​¶

Устранение неполадок​¶

Команда FastMCP не найдена​¶

fastmcp inspect завершается ошибкой​¶

Инструмент работает в Python, но не через CLI​¶

Hermes не видит развёрнутый сервер​¶

Ссылки​¶