Определяем ресурсы

У нашего сервера есть инструменты, и модель умеет читать документы сама. Но в уроке про примитивы мы говорили, что есть второй путь: человек заранее прикладывает документ к вопросу, без решения модели и без подтверждения. Это ресурсы. В этом уроке добавим их на сервер, а в следующем — научим клиент ими пользоваться.

Прямой ресурс

Добавьте в docs_server.py:

@mcp.resource("docs://list", mime_type="application/json")
def list_docs() -> list[str]:
    """Список документов проекта."""
    return list(DOCS)

Декоратор @mcp.resource() принимает URI ресурса первым аргументом. Схема docs:// — наша собственная; протокол не ограничивает схемы, и для локальных данных принято придумывать говорящие: docs://, tickets://, config://. Для настоящих файлов используют file:///путь.

Функция возвращает список — SDK сериализует его в JSON и отдаст как текст. Отсюда mime_type="application/json": клиент должен знать, что это не просто строка, а данные, которые можно разобрать. По умолчанию тип text/plain. Строку функция может вернуть как есть, bytes уйдут в base64, словарь и модель Pydantic — в JSON.

Описание, как и у инструментов, берётся из docstring, имя — из имени функции. Здесь они предназначены не модели, а человеку и хосту: именно их покажет список ресурсов в интерфейсе.

Шаблон ресурса

Список — это хорошо, но нужен доступ к каждому документу. Заводить по ресурсу на файл вручную нельзя: файлов может быть сколько угодно. Для этого есть шаблоны:

from mcp.server.mcpserver.exceptions import ResourceNotFoundError


@mcp.resource("docs://{name}", mime_type="text/markdown")
def get_doc(name: str) -> str:
    """Содержимое документа проекта."""
    if name not in DOCS:
        raise ResourceNotFoundError(f"Документа {name!r} нет.")
    return DOCS[name]

{name} в URI — параметр. Он должен точно совпадать с именем аргумента функции, иначе SDK откажется регистрировать ресурс ещё при импорте. Когда клиент запросит docs://risks.md, SDK сопоставит его с шаблоном, вытащит name = "risks.md" и вызовет функцию.

В протоколе прямые ресурсы и шаблоны живут в разных списках: resources/list вернёт docs://list, а resources/templates/list — docs://{name}. Чтение в обоих случаях делается одним методом resources/read с конкретным URI. Хост, получив шаблон, может показать пользователю поле для ввода параметра или подставить значения из контекста.

Обратите внимание: docs://list и шаблон docs://{name} могли бы конфликтовать — list формально подходит под {name}. SDK сначала проверяет точные совпадения, поэтому прямой ресурс побеждает. Но лучше не создавать таких пересечений в настоящих серверах: назовите список docs://index или docs:///, если документ с именем list возможен.

Ошибки

Для ресурсов нет аналога ToolError с флагом is_error: чтение либо удаётся, либо нет. ResourceNotFoundError превращается в ошибку протокола с кодом -32602 и URI в данных ошибки, и клиент получит исключение. Это осмысленно: ресурс читает приложение, а не модель, и «исправлять» тут некому — хост покажет ошибку пользователю.

Из этого следует правило: не давайте ресурсам падать по своим причинам. Если данные недоступны, поднимайте ResourceNotFoundError (или общий ResourceError из того же модуля), а не KeyError.

Ресурс или инструмент?

У нас теперь два пути к содержимому документа: инструмент read_doc и ресурс docs://{name}. Это не дублирование, а два сценария.

Инструмент вызывает модель, когда по ходу задачи понимает, что ей нужен документ. «Проверь, согласуется ли оценка с брифом» — модель сама вызовет read_doc дважды. Каждый вызов — решение модели, подтверждение хоста, отдельный шаг в цикле.

Ресурс подключает человек или приложение до того, как модель что-то решила. «Вот бриф, вот риски — что упущено?» — пользователь прикладывает два документа, и модель получает их в первом же сообщении. Ни решений, ни подтверждений, ни лишних шагов.

Практическое правило: если данные «пассивные» и их часто прикладывают к вопросу целиком — это ресурс. Если получение данных — действие с параметрами, которые модель должна подобрать, — это инструмент. Списки, справочники, схемы, конфигурации почти всегда ресурсы. Поиск, фильтрация, запросы к API — инструменты.

Ещё один довод за ресурсы: их перечисление ничего не стоит. При resources/list функции не выполняются — SDK отдаёт только метаданные. Функция запускается только при чтении конкретного URI.

Проверяем

Дополните check.py:

        for res in (await client.list_resources()).resources:
            print("ресурс:", res.uri, res.mime_type, "—", res.description)
        for tpl in (await client.list_resource_templates()).resource_templates:
            print("шаблон:", tpl.uri_template, tpl.mime_type, "—", tpl.description)

        listing = await client.read_resource("docs://list")
        print("docs://list ->", listing.contents[0].text)

        doc = await client.read_resource("docs://risks.md")
        print("docs://risks.md ->", doc.contents[0].mime_type, doc.contents[0].text[:40])

        try:
            await client.read_resource("docs://nope.md")
        except Exception as e:
            print("нет документа ->", type(e).__name__, e)

read_resource возвращает объект с полем contents — список блоков (ресурс может состоять из нескольких частей). У текстового блока есть text и mime_type, у бинарного — blob. В выводе вы увидите JSON-список для docs://list, начало документа с типом text/markdown и исключение MCPError для несуществующего имени.

Теперь откройте инспектор (uv run mcp dev docs_server.py): во вкладке Resources появятся и прямой ресурс, и шаблон, а рядом с шаблоном — поле для параметра. Прочитайте docs://brief.md и найдите запрос resources/read во вкладке Protocol.