Настройка проекта

Начинаем практику. В этом уроке мы создадим проект, установим Python SDK для MCP и напишем каркас сервера: пока без инструментов, но уже запускающийся и отвечающий клиенту. Инструменты добавим в следующем уроке, ресурсы и промпты — в модуле про клиент.

Установка uv

Официальная документация MCP использует uv — быстрый менеджер пакетов и окружений для Python. Установка одной командой:

curl -LsSf https://astral.sh/uv/install.sh | sh

На Windows — команда из документации на docs.astral.sh/uv. После установки перезапустите терминал и проверьте: uv --version.

Если uv не хочется, всё в курсе работает и с обычным pip. Мы будем давать команды для uv, а в конце раздела — их аналог для pip.

Создаём проект

uv init project-docs
cd project-docs
rm main.py
uv add "mcp[cli]"

uv init создаёт папку с pyproject.toml и заглушкой main.py, которая нам не нужна. uv add "mcp[cli]" ставит SDK; часть [cli] добавляет утилиту mcp с командами mcp dev, mcp run и mcp install — они пригодятся в следующих уроках. Кавычки нужны, чтобы оболочка не пыталась раскрыть квадратные скобки.

Виртуальное окружение uv создаст сам в папке .venv, активировать его не нужно: команды запускаем через uv run.

Аналог для pip:

mkdir project-docs && cd project-docs
python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]"

Дальше везде, где написано uv run docs_server.py, читайте python docs_server.py в активированном окружении.

Проверьте, что установилась вторая мажорная версия SDK: uv run mcp version. Курс написан под SDK 2.x. Если вы найдёте в интернете примеры с from mcp.server.fastmcp import FastMCP — это первая версия; класс переименован в MCPServer, и старый импорт в 2.x не работает. Остальные отличия перечислены в руководстве по миграции.

Каркас сервера

Создайте файл docs_server.py:

import logging

from mcp.server import MCPServer

logger = logging.getLogger(__name__)

mcp = MCPServer("project-docs")

DOCS: dict[str, str] = {
    "brief.md": (
        "# Бриф\n\nКлиент: сеть кофеен. Задача: мобильное приложение лояльности "
        "с картой заведений и предзаказом."
    ),
    "estimate.md": (
        "# Оценка\n\nАналитика — 2 недели, дизайн — 3 недели, "
        "разработка iOS и Android — 10 недель, тестирование — 3 недели."
    ),
    "risks.md": (
        "# Риски\n\n1. Интеграция с кассовой системой клиента не описана.\n"
        "2. У клиента нет аккаунта разработчика в App Store."
    ),
}

if __name__ == "__main__":
    logging.basicConfig(level=logging.INFO)
    mcp.run(transport="stdio")

Разберём по частям.

MCPServer("project-docs") — объект сервера. Имя увидит клиент при подключении; в Claude Code оно будет фигурировать в списке /mcp. Через этот объект мы будем регистрировать инструменты, ресурсы и промпты декораторами.

DOCS — наше хранилище. Словарь «имя файла → содержимое», три учебных документа. Он живёт в памяти процесса: правки будут действовать, пока сервер запущен, и пропадут после перезапуска. Для курса этого достаточно. Если захотите настоящие файлы — замените словарь на чтение папки docs/, и остальной код не изменится: мы везде будем обращаться к документам через две-три функции.

mcp.run(transport="stdio") — запуск. Сервер начинает читать JSON-RPC из стандартного ввода и писать ответы в стандартный вывод. Другие транспорты — "streamable-http" и устаревший "sse" — включаются тем же параметром.

logging.basicConfig — единственный допустимый способ что-то вывести из stdio-сервера. Модуль logging пишет в стандартный поток ошибок, а он не мешает протоколу. Правило из урока про архитектуру: ни одного print() в stdio-сервере. Заведите себе привычку сразу, пока сервер маленький.

Запуск и первая проверка

Запустите сервер:

uv run docs_server.py

Ничего не произойдёт: сервер ждёт сообщений на стандартном вводе, а мы ничего не пишем. Это правильное поведение. Остановите его через Ctrl+C.

Чтобы убедиться, что сервер живой, напишем крошечного клиента. SDK умеет подключаться к серверу прямо в том же процессе, без запуска подпроцесса — так удобно проверять и писать тесты. Создайте check.py:

import asyncio

from mcp import Client

from docs_server import mcp


async def main() -> None:
    async with Client(mcp) as client:
        print("Сервер:", client.server_info.name)
        print("Возможности:", client.server_capabilities.model_dump(exclude_none=True))
        tools = await client.list_tools()
        print("Инструменты:", [t.name for t in tools.tools])


asyncio.run(main())

Запустите: uv run check.py. Вы увидите имя сервера, его возможности и пустой список инструментов. Здесь print допустим: это клиент, а не сервер, и его стандартный вывод ничем не занят.

async with Client(mcp) — вся жизнь соединения. Вход в блок устанавливает соединение и договаривается о версии протокола, выход закрывает. Асинхронность (async, await) здесь обязательна: SDK построен на ней, потому что клиент одновременно ждёт ответов и может получать уведомления. Если вы не писали асинхронный код раньше, правило простое: вызовы методов клиента предваряются await, а всё вместе запускается через asyncio.run.

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

К концу курса в папке будет:

project-docs/
  pyproject.toml     — зависимости
  docs_server.py     — сервер: инструменты, ресурсы, промпты
  check.py           — быстрая проверка в том же процессе
  client.py          — клиент с Claude (модуль «Подключаем клиент»)
  .env               — ключ API для клиента, в git не попадает

Добавьте .env и .venv в .gitignore прямо сейчас.