Fastmcp

Собирайте, тестируйте и деплойте MCP-серверы на Python.

Метаданные навыка

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

FastMCP

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

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

Навык подходит, когда задача — это:

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

Если сервер уже существует и нужно лишь подключить его к Hermes — используйте native-mcp. Если цель — разовый доступ к готовому MCP-серверу через CLI без его сборки — используйте mcporter.

Требования

Сначала установите FastMCP в рабочее окружение:

pip install fastmcp
fastmcp version

Для шаблона API-обёртки установите httpx, если его ещё нет:

pip install httpx

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

Шаблоны

• 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. Создайте структуру из шаблона

Скопируйте шаблон напрямую или через хелпер:

python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py \
  --template api_wrapper \
  --name "Acme API" \
  --output ./acme_server.py

Список доступных шаблонов:

python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py --list

При ручном копировании замените __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 для локальной проверки:

fastmcp inspect acme_server.py:mcp
fastmcp list acme_server.py --json
fastmcp call acme_server.py search_resources query=router limit=5 --json

Для быстрой итеративной отладки запустите сервер локально:

fastmcp run acme_server.py:mcp

Чтобы проверить HTTP-транспорт локально:

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

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

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

FastMCP умеет регистрировать сервер в поддерживаемых MCP-клиентах:

fastmcp install claude-code acme_server.py
fastmcp install claude-desktop acme_server.py
fastmcp install cursor acme_server.py -e .

Команда fastmcp discover позволяет посмотреть уже настроенные MCP-серверы на машине.

Для интеграции с Hermes есть два пути:

• настройте сервер в ~/.hermes/config.yaml с помощью навыка native-mcp, или
• продолжайте использовать команды FastMCP CLI во время разработки, пока интерфейс не стабилизируется

7. Деплойте только после стабилизации локального контракта

Для управляемого хостинга FastMCP в первую очередь документирует путь через Prefect Horizon. Перед деплоем выполните:

fastmcp inspect acme_server.py:mcp

Убедитесь, что репозиторий содержит:

• Python-файл с объектом FastMCP-сервера
• requirements.txt или pyproject.toml
• документацию по переменным окружения, необходимым для деплоя

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

Типовые паттерны

Паттерн API-обёртки

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

Рекомендуемый первый срез:

• один путь чтения
• один путь листинга/поиска
• опциональная проверка работоспособности (health check)

Замечания по реализации:

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

Отправная точка: templates/api_wrapper.py.

Паттерн базы данных

Используется для безопасного доступа к запросам и интроспекции БД.

Рекомендуемый первый срез:

• list_tables
• describe_table
• один ограниченный инструмент для чтения данных

Замечания по реализации:

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

Отправная точка: templates/database_server.py.

Паттерн файлового процессора

Используется, когда серверу нужно проверять или преобразовывать файлы по запросу.

Рекомендуемый первый срез:

• суммаризация содержимого файла
• поиск внутри файлов
• извлечение детерминированных метаданных

Замечания по реализации:

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

Отправная точка: templates/file_processor.py.

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

Перед сдачей FastMCP-сервера проверьте всё из списка:

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

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

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

Установите пакет в активное окружение:

pip install fastmcp
fastmcp version

fastmcp inspect падает

Проверьте:

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

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

Запустите:

fastmcp list server.py --json
fastmcp call server.py your_tool_name --json

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

Hermes не видит задеплоенный сервер

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

Справочники

Подробности по CLI, целям установки и проверкам перед деплоем — в references/fastmcp-cli.md.