Fastmcp

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

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

Источник	Опционально — установка через vibeos skills install official/mcp/fastmcp
Путь	optional-skills/mcp/fastmcp
Версия	1.0.0
Автор	VibeOS
Лицензия	MIT
Платформы	linux, macos, windows
Теги	MCP, FastMCP, Python, Tools, Resources, Prompts, Deployment
Связанные навыки	native-mcp, mcporter

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

к сведению

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

FastMCP

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

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

Используйте этот навык, когда задача заключается в:

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

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

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

Сначала установите 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 — рабочий процесс CLI FastMCP, цели установки и проверки развёртывания

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

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

Сначала выберите самую узкую полезную поверхность:

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

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

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

Скопируйте шаблон напрямую или используйте вспомогательный скрипт:

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

Доступные шаблоны:

python ~/.vibeos/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. Протестируйте сервер перед интеграцией

Используйте CLI FastMCP для локальной проверки:

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-серверов, уже настроенных на машине.

Когда цель — интеграция с VibeOS, либо:

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

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

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

fastmcp inspect acme_server.py:mcp

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

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

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

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

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

Используйте при предоставлении REST или HTTP API в виде MCP-инструментов.

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

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

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

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

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

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

Используйте при предоставлении безопасных возможностей запросов и инспекции.

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

• list_tables
• describe_table
• один инструмент для ограниченного запроса чтения

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

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

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

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

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

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

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

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

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

Начните с 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

Это обычно выявляет несоответствия в именах, отсутствующие обязательные аргументы или несериализуемые возвращаемые значения.

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

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

Справочники

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