Доступ к ресурсам

На сервере ресурсы есть, теперь нужно научить клиент ими пользоваться. Напомним, что ресурсы контролирует приложение: модель их не вызывает, она получает содержимое уже в запросе. Значит, клиент должен решить, какие ресурсы приложить, прочитать их и вставить в сообщение. В этом уроке сделаем это через упоминания @имя — так же, как работает @сервер:ресурс в Claude Code.

Перечислить и прочитать

Два метода клиента, которые нам нужны, вы уже видели в check.py:

listing = await client.list_resources()          # прямые ресурсы
templates = await client.list_resource_templates()  # шаблоны
doc = await client.read_resource("docs://brief.md")

read_resource возвращает объект с полем contents — список блоков. Для текстовых ресурсов это TextResourceContents с полями uri, mime_type и text; для бинарных — BlobResourceContents с blob в base64. Один ресурс обычно состоит из одного блока, но протокол разрешает несколько.

Обратите внимание на тип: это TextResourceContents, а не TextContent, который мы использовали для результатов инструментов. Разные примитивы — разные типы блоков. Перепутать легко, и тогда фильтр по isinstance молча отбросит всё содержимое.

Упоминания в запросе

Договоримся о синтаксисе: слово, начинающееся с @, — имя документа, который нужно приложить. «Сравни @brief.md и @risks.md — что не учтено?» должно превратиться в сообщение, где перед вопросом стоят оба документа.

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

from mcp_types import TextContent, TextResourceContents


async def attach_docs(client: Client, query: str) -> str:
    """Заменить упоминания @имя на содержимое ресурсов docs://имя."""
    attachments = []
    for word in query.split():
        if not word.startswith("@"):
            continue
        name = word[1:].strip(",.;:!?")
        resource = await client.read_resource(f"docs://{name}")
        text = "\n".join(c.text for c in resource.contents if isinstance(c, TextResourceContents))
        attachments.append(f"<document name=\"{name}\">\n{text}\n</document>")
    if not attachments:
        return query
    return "\n\n".join(attachments) + "\n\n" + query

И измените вызов в main:

            try:
                content = await attach_docs(client, query)
                print(await run(client, [{"role": "user", "content": content}]))
            except Exception as e:
                print("Ошибка:", e)

Разберём. Для каждого @слова мы собираем URI по шаблону docs://{name} и читаем ресурс. Содержимое оборачиваем в тег <document name="..."> — это не требование протокола, а приём для модели: так она видит, где кончается один документ и начинается другой, и может ссылаться на них по имени. Все вложения ставим перед вопросом: модели удобнее сначала прочитать материалы, потом задание.

Если документа нет, read_resource бросит MCPError, и except в main покажет её пользователю. Модель до этого не дойдёт — и правильно: ошибку в имени файла должен исправлять человек, а не модель.

Запуск

uv run client.py

Спросите: «Сравни @brief.md и @risks.md — какие риски не следуют из брифа?». В stderr не появится ни одного [вызов ...]: модель получила оба документа сразу и ответила без инструментов. Теперь спросите то же самое без @: «Сравни бриф и риски». Появятся два вызова read_doc. Тот же результат, но два лишних шага, два решения модели и — в настоящем хосте — два подтверждения.

Это и есть разница между примитивами в действии. Когда вы знаете, что нужно модели, ресурс дешевле. Когда не знаете — инструменты позволяют ей разобраться самой.

Как это делает Claude Code

В Claude Code синтаксис почти такой же, только с именем сервера: @project-docs:docs://brief.md. Хост делает ровно то, что мы написали: находит клиент нужного сервера, вызывает resources/read, вставляет содержимое в сообщение. Ещё он умеет показать список доступных ресурсов при наборе @ — для этого и нужен resources/list: перечисление бесплатно, а пользователь видит, что можно приложить.

У нас список ресурсов пока не используется. Хорошее упражнение — вывести его при старте, как мы выводим инструменты, и подсказывать имена при вводе.

Что ещё может делать хост с ресурсами

Мы вставили ресурс целиком. Протокол этого не требует; приложение решает само:

• Целиком — как у нас. Подходит для документов разумного размера.
• Фрагмент — найти нужный кусок по ключевым словам или эмбеддингам и приложить только его. Так поступают хосты с большими базами знаний.
• Автоматически — приложить ресурс без упоминания, если он подходит по контексту: например, всегда прикладывать docs://list, чтобы модель знала, какие документы существуют.
• Как документ API — Anthropic API умеет принимать содержимое в блоке document с метаданными и цитированием. Для текстовых ресурсов это даёт модели ссылки на источник.

MIME-тип ресурса помогает выбрать способ: text/markdown можно вставить как есть, application/json — разобрать и показать таблицей, image/png — отправить как картинку.