MCP Demo — Python-инструментарий для агентов с нуля

Что такое MCP?

MCP (Model Context Protocol) — это стандартизированный протокол, который позволяет AI-приложениям обнаруживать и использовать внешние инструменты, ресурсы и промпты через единый интерфейс.

Вместо того чтобы каждая AI-платформа изобретала свою интеграцию для каждой базы данных, API, файловой системы или внутреннего сервиса, MCP-хост может подключиться к MCP-серверу и использовать одну и ту же поверхность протокола.

Проблемы, которые решает MCP

На проводе MCP использует сообщения JSON-RPC 2.0 через такие транспорты, как stdio и HTTP-транспорты (SSE/Streamable HTTP). Этот репозиторий использует stdio: клиент запускает сервер как подпроцесс, отправляет сообщения протокола через stdin и получает ответы через stdout.

Related MCP server: Weather MCP Server

Архитектура

flowchart TD
    A[User: "What's the weather in London?"] --> B[AI Agent<br/>OpenAI Responses API]
    B --> C[1. Discovers MCP tools]
    B --> D[2. Decides whether to call]
    B --> E[3. Emits function call]
    E --> F[MCP Client<br/>ClientSession + stdio]
    F --> G[initialize]
    F --> H[tools/list]
    F --> I[tools/call]
    I --> J[JSON-RPC 2.0<br/>stdin/stdout]
    J --> K[MCP Server subprocess]
    K --> L[get_current_weather tool]
    K --> M[greeting://{name} resource]

Почему официальный SDK?

В этом репозитории используется официальный Python MCP SDK вместо повторной реализации протокола. SDK предоставляет:

• Жизненный цикл и валидацию протокола

• Абстракцию транспорта (stdio, HTTP/SSE)

• Типизированные API клиента/сервера

Код приложения по-прежнему делает важные концепции MCP явными: регистрация сервера, схемы инструментов, initialize, tools/list, tools/call, чтение ресурсов и управление stdio-процессом.

Стабильный API v2 текущего SDK использует MCPServer для создания сервера и ClientSession/stdio_client для stdio-клиентов.

Структура проекта

mcp-demo/
├── README.md
├── requirements.txt
├── .env.example
├── pyproject.toml
├── src/
│   ├── mcp_server/
│   │   ├── __init__.py
│   │   ├── server.py      # MCP server entry point
│   │   ├── tools.py       # Tool implementations
│   │   ├── handlers.py    # Request handlers
│   │   └── utils.py       # Shared utilities
│   ├── mcp_client/
│   │   ├── __init__.py
│   │   ├── client.py      # MCP client wrapper
│   │   ├── agent.py       # OpenAI agent integration
│   │   └── runner.py      # Demo runner
│   └── shared/
│       ├── __init__.py
│       └── types.py       # Shared Pydantic models
├── tests/
│   ├── test_server.py
│   └── test_client.py
├── examples/
│   └── demo.ipynb
└── scripts/
    └── run_demo.sh

Требования

• Python 3.10+

• Ключ OpenAI API (для демо AI-агента)

• Ключ API погоды не требуется — инструмент погоды использует детерминированные примеры данных, чтобы MCP-путь работал офлайн

Быстрый старт

1. Создание виртуального окружения

python -m venv .venv
source .venv/bin/activate        # Linux/macOS
.venv\Scripts\Activate.ps1       # Windows PowerShell

2. Установка зависимостей

python -m pip install --upgrade pip
pip install -r requirements.txt

3. Настройка OpenAI

cp .env.example .env

Отредактируйте .env с вашими учетными данными:

OPENAI_API_KEY=your_api_key_here
OPENAI_MODEL=gpt-4.1-mini

Сам сервер не нуждается в ключе OpenAI.

Запуск демо

Из корня репозитория

python src/mcp_client/runner.py

Что делает запускающий скрипт:

Альтернатива: оболочка (shell wrapper)

bash scripts/run_demo.sh

Ожидаемый вывод

Точная формулировка зависит от модели, но поток логов выглядит так:

INFO mcp_client.client: -> MCP initialize
INFO mcp_client.client: <- MCP initialize: server=mcp-demo-server
INFO mcp_client.client: -> MCP tools/list
INFO mcp_client.client: <- MCP tools/list: ["get_current_weather"]
INFO mcp_client.agent: User: What's the weather in London?
INFO mcp_client.agent: OpenAI requested tool: get_current_weather {"city":"London","units":"metric"}
INFO mcp_client.client: -> MCP tools/call name=get_current_weather arguments={"city":"London","units":"metric"}
INFO mcp_server.tools: weather lookup city=London units=metric
INFO mcp_client.client: <- MCP tools/call result={"city":"London","temperature":18.0,...}
INFO mcp_client.agent: Final: London is 18°C and partly cloudy.

Логи намеренно показывают семантические сообщения MCP на границе приложения. SDK обрабатывает кадрирование JSON-RPC внутри.

Запуск MCP-сервера отдельно

python src/mcp_server/server.py

Stdio MCP-сервер может показаться «зависшим» — это ожидаемо. Он ждет сообщений протокола на stdin. Хост/клиент должен запустить его и владеть stdio-каналами.

Интерактивная проверка протокола

pip install "mcp[cli]"
mcp dev src/mcp_server/server.py

Продемонстрированные методы MCP

Официальный SDK обрабатывает жизненный цикл JSON-RPC:

Клиент явно вызывает initialize() перед перечислением или вызовом возможностей. Декораторы сервера генерируют схемы инструментов/ресурсов из аннотаций типов Python.

Инструмент: get_current_weather

get_current_weather(
    city: str,
    units: Literal["metric", "imperial"] = "metric"
) -> WeatherResponse

Возвращает структурированные данные на основе Pydantic:

{
  "city": "London",
  "temperature": 18.0,
  "units": "metric",
  "condition": "partly cloudy",
  "humidity_percent": 72
}

Неизвестные города завершаются контролируемой ошибкой инструмента MCP, а не падением сервера.

Поток интеграции агента

Агент использует обычный вызов функций OpenAI (без дополнительных фреймворков), чтобы демо оставалось сфокусированным:

flowchart LR
    A[MCP Tool Schema] --> B[OpenAI Function Tool]
    B --> C[Model Chooses Function]
    C --> D[MCP ClientSession.call_tool]
    D --> E[MCP Server Executes Tool]
    E --> F[Function Call Output]
    F --> G[Final Model Answer]

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

Тестирование

pytest -q

Тестовый набор покрывает:

• ✅ Выполнение инструмента (метрическая погода)

• ✅ Выполнение инструмента (имперская погода)

• ✅ Поведение валидации/ошибок (неизвестный город)

• ✅ Обнаружение и вызов инструментов MCP-клиентом в процессе

Тесты используют встроенный клиент SDK, где это возможно — избегают нестабильности подпроцессов, одновременно проверяя реальный уровень протокола MCP.

Форматирование и линтинг

В этом проекте используется Ruff:

# Check
ruff check .
ruff format --check .

# Format
ruff format .

Заметки о продакшене

Это демо намеренно небольшое, но представляет несколько производственных аспектов:

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

Ментальная модель протокола

Упрощенная последовательность JSON-RPC:

// Client -> Server
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}

// Server -> Client
{"jsonrpc":"2.0","id":1,"result":{...}}

// Client -> Server
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

// Server -> Client
{"jsonrpc":"2.0","id":2,"result":{"tools":[...]}}

// Client -> Server
{"jsonrpc":"2.0","id":3,"method":"tools/call",
 "params":{"name":"get_current_weather","arguments":{"city":"London"}}}

// Server -> Client
{"jsonrpc":"2.0","id":3,"result":{"content":[...],"structuredContent":{...}}}

Точная схема протокола поддерживается спецификацией MCP и SDK. Вышеприведенное намеренно упрощено для обучения.

Ссылки

• Официальный MCP Python SDK: https://py.sdk.modelcontextprotocol.io/

• Спецификация MCP: https://modelcontextprotocol.io/specification/

• Вызов функций OpenAI: https://platform.openai.com/docs/guides/function-calling