Основы FastMCP

FastMCP — это библиотека Python, которая делает создание MCP-серверов максимально простым. Вместо ручной реализации JSON-RPC-протокола вы используете декораторы @mcp.tool(), @mcp.resource() и @mcp.prompt() — FastMCP берёт на себя сериализацию, валидацию и транспорт.

Библиотека автоматически генерирует JSON Schema из аннотаций типов, обрабатывает ошибки и поддерживает два транспортных режима.

#Установка

FastMCP устанавливается из PyPI:

pip install fastmcp

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

poetry add fastmcp

#Первый сервер

Минимальный MCP-сервер на FastMCP занимает несколько строк. Создадим сервер с одним инструментом:

from fastmcp import FastMCP

mcp = FastMCP("HelloServer")

@mcp.tool()
def greet(name: str) -> str:
    """Приветствует пользователя по имени."""
    return f"Привет, {name}!"

if __name__ == "__main__":
    mcp.run()

Разберём по шагам. FastMCP("HelloServer") создаёт экземпляр сервера с именем — это имя передаётся клиенту при подключении. Декоратор @mcp.tool() регистрирует функцию как MCP-инструмент. FastMCP автоматически:

Извлекает docstring как описание инструмента
Генерирует JSON Schema из аннотаций типов (name: str, возврат str)
Регистрирует инструмент в каталоге сервера

Запуск mcp.run() без аргументов запускает stdio-транспорт. Сервер читает JSON-RPC из stdin и пишет в stdout.

#Запуск и тестирование первого сервера

Для локального тестирования можно использовать MCP Inspector — официальный инструмент отладки:

npx @modelcontextprotocol/inspector python hello_server.py

Inspector запустит веб-интерфейс, где можно увидеть зарегистрированные инструменты, вызвать их с разными аргументами и посмотреть raw JSON-RPC-сообщения.

Также можно запустить сервер через Python напрямую:

python hello_server.py

Сервер запустится в stdio-режиме и будет ожидать ввода. Для проверки можно вручную отправить JSON-RPC-запрос:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python hello_server.py

Ответ будет содержать описание инструмента greet с его схемой параметров.

#Транспортные режимы

#stdio (по умолчанию)

Стандартный режим — сервер общается через stdin/stdout. Подходит для локального использования, когда AI-клиент (например, Claude Desktop) запускает сервер как дочерний процесс.

# Явный stdio-режим (то же самое, что mcp.run() без аргументов)
mcp.run(transport="stdio")

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

Локальная разработка и отладка
Десктопные приложения (Claude Desktop, IDE)
Сервер — единственный процесс, один клиент

#SSE (Server-Sent Events)

SSE-режим превращает сервер в HTTP-сервис, доступный по сети:

mcp.run(transport="sse", host="0.0.0.0", port=8000)

Сервер запускает HTTP-сервер (uvicorn под капотом) и обслуживает SSE-соединения. Клиенты подключаются через HTTP-запросы.

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

Продакшен-деплой
Несколько клиентов подключаются к одному серверу
Сервер должен быть доступен по сети (удалённые машины, облако)

#Декоратор `@mcp.tool()`

Декоратор превращает обычную Python-функцию в MCP-инструмент. FastMCP извлекает из функции всё необходимое:

Имя: имя функции (greet)
Описание: docstring функции
Параметры: аннотации типов генерируют JSON Schema
Значения по умолчанию: параметры с default становятся необязательными

@mcp.tool()
def calculate(a: int, b: int, operation: str = "add") -> int:
    """Выполняет арифметическую операцию над двумя числами."""
    if operation == "add":
        return a + b
    elif operation == "multiply":
        return a * b
    else:
        raise ValueError(f"Неизвестная операция: {operation}")

Этот инструмент будет описан в tools/list с тремя параметрами: a (integer, required), b (integer, required), operation (string, default "add").

#Сервер с несколькими инструментами

Нет ограничений на количество инструментов — просто добавляйте декораторы:

from fastmcp import FastMCP

mcp = FastMCP("DataServer")

@mcp.tool()
def get_user(user_id: int) -> str:
    """Возвращает данные пользователя по ID."""
    return f"User data for ID: {user_id}"

@mcp.tool()
def search_users(query: str, limit: int = 10) -> str:
    """Ищет пользователей по текстовому запросу."""
    return f"Search results for '{query}' (limit: {limit})"

@mcp.tool()
def delete_user(user_id: int) -> str:
    """Удаляет пользователя по ID."""
    return f"User {user_id} deleted"

if __name__ == "__main__":
    mcp.run()

Все три инструмента будут доступны клиенту через tools/list. AI-модель клиента прочитает описания и схемы, и решит, какой инструмент вызвать для каждого запроса пользователя.

#Асинхронные инструменты

FastMCP поддерживает async-функции. Это критически важно для I/O-операций — запросы к БД, HTTP-API, файловая система:

import aiohttp

@mcp.tool()
async def fetch_weather(city: str) -> str:
    """Получает текущую погоду для указанного города."""
    url = f"https://api.weather.com/{city}"
    async with aiohttp.ClientSession() as session:
        async with session.get(url) as response:
            data = await response.json()
            return f"Погода в {city}: {data['temperature']}°C"

Асинхронные инструменты не блокируют event loop, что позволяет серверу обрабатывать несколько запросов параллельно. В SSE-режиме это особенно важно — один медленный запрос не должен блокировать остальных клиентов.

#Инструкция и описание

FastMCP позволяет задать подробное описание сервера через параметр instructions:

mcp = FastMCP(
    "DataServer",
    instructions="Этот сервер предоставляет инструменты для работы с пользовательскими данными: поиск, просмотр и удаление."
)

Инструкции передаются клиенту при подключении и помогают AI-модели понять назначение сервера в целом.