Claude в Google Vertex AI

Введение в Ресурсы MCP: Доступ к Данным для Claude AI

В мире больших языковых моделей (LLM), таких как Claude, способность получать актуальную и специфическую информацию из внешних источников критически важна для выполнения сложных задач. Anthropic Academy, в рамках курса "Claude with Google Vertex AI", знакомит нас с концепцией Ресурсов в серверах MCP (Managed Compute Platform). Эти ресурсы представляют собой мощный механизм, позволяющий вашему приложению на базе Claude взаимодействовать с внешними данными, делая его более информированным и функциональным.

По своей сути, ресурсы MCP можно сравнить с обработчиками запросов GET в традиционном HTTP-сервере. Их основное назначение — предоставление данных клиентам, а не выполнение каких-либо действий. Это идеальное решение для сценариев, где Claude или другое клиентское приложение нуждается в получении информации, будь то список документов, содержимое файла или структурированные данные.

Что такое Ресурсы и как они работают?

Представьте ресурсы как точки доступа, предназначенные исключительно для чтения, которые могут возвращать данные любого типа: простые строки, объекты JSON, бинарные файлы и многое другое. При определении ресурса вы указываете его mime_type (например, "application/json" или "text/plain"), что служит подсказкой для клиентского приложения о типе возвращаемых данных. Это помогает клиенту правильно интерпретировать и обрабатывать полученную информацию.

Работа ресурсов основана на использовании URI (Uniform Resource Identifier), который действует как уникальный адрес для каждого фрагмента данных. Когда клиентскому приложению (например, Claude, интегрированному через Google Vertex AI) требуется определенная информация, оно отправляет запрос ReadResourceRequest с указанием конкретного URI. В ответ ваш сервер MCP обрабатывает этот запрос и возвращает ReadResourceResult, содержащий запрошенные данные.

Этот механизм обеспечивает четкое и стандартизированное взаимодействие, позволяя Claude беспрепятственно получать доступ к необходимой информации, не "изобретая велосипед" для каждого нового источника данных.

Два Основных Типа Ресурсов

В MCP вы можете создавать два основных типа ресурсов, каждый из которых подходит для разных сценариев доступа к данным:

• Прямые Ресурсы (Direct Resources): Эти ресурсы имеют статические URI, которые не содержат никаких изменяемых параметров. Их URI фиксированы и всегда указывают на один и тот же набор данных. Примером может служить ресурс, который возвращает полный список всех доступных документов, например, "docs://documents". Такие ресурсы идеально подходят для получения общих, неизменяемых списков или конфигураций.
• Шаблонные Ресурсы (Templated Resources): В отличие от прямых ресурсов, шаблонные ресурсы включают параметры в свои URI. Эти параметры парсятся из URI и передаются в вашу функцию в качестве аргументов. Например, URI "docs://documents/{doc_id}" позволяет получить конкретный документ, где {doc_id} будет заменен на фактический идентификатор документа. Python SDK для MCP автоматически анализирует эти параметры из URI и передает их как именованные аргументы в вашу функцию. Важно, чтобы имена параметров в URI точно соответствовали именам параметров в сигнатуре вашей функции. Это обеспечивает гибкий и динамичный доступ к данным, позволяя запрашивать конкретные элементы из большой коллекции.

Создание Ресурсов: Практический Подход

Реализация ресурсов в MCP с использованием Python SDK является интуитивно понятной. Вы используете декоратор @mcp.resource, чтобы объявить функцию как ресурс, указав ее URI и mime_type.

Для прямого ресурса, который, например, возвращает список всех доступных документов, ваша функция может выглядеть следующим образом (концептуально):

@mcp.resource(
    "docs://documents",
    mime_type="application/json"
)
def list_docs() -> list[str]:
    # Здесь логика получения списка ключей документов
    return ["doc_a", "doc_b", "doc_c"]

Эта функция, при запросе по URI "docs://documents", вернет список строк в формате JSON.

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

@mcp.resource(
    "docs://documents/{doc_id}",
    mime_type="text/plain"
)
def fetch_doc(doc_id: str) -> str:
    # Здесь логика получения содержимого документа по doc_id
    if doc_id == "doc_a":
        return "Содержимое документа A."
    elif doc_id == "doc_b":
        return "Содержимое документа B."
    else:
        raise ValueError(f"Документ с ID {doc_id} не найден")

В этом примере, если клиент запросит "docs://documents/doc_a", функция fetch_doc будет вызвана с doc_id="doc_a", и вернет соответствующее текстовое содержимое.

Одним из значительных преимуществ MCP Python SDK является автоматическая сериализация возвращаемых данных. Вам не нужно вручную преобразовывать Python-объекты в строки JSON или другие форматы. Просто верните обычные Python-объекты (списки, словари, строки), и SDK самостоятельно позаботится о их корректной сериализации в соответствии с указанным mime_type перед отправкой клиенту.

Тестирование Ресурсов с MCP Inspector

После создания ресурсов крайне важно убедиться в их корректной работе. Для этого Anthropic предоставляет инструмент MCP Inspector. Запустив ваш сервер MCP локально (например, командой uv run mcp dev mcp_server.py), вы можете подключиться к Inspector через веб-браузер.

Инспектор предоставляет удобный интерфейс для просмотра и тестирования ваших ресурсов. Вы увидите два основных раздела:

• Прямые Ресурсы: Здесь перечислены все ваши статические ресурсы с фиксированными URI. Вы можете просто "кликнуть" на любой из них, чтобы отправить запрос и увидеть немедленный ответ.
• Шаблонные Ресурсы: В этом разделе отображаются ваши ресурсы с параметрами. Для их тестирования вам потребуется ввести значения для каждого параметра в URI (например, doc_id). После ввода параметров инспектор отправит запрос и покажет вам точную структуру ответа, которую получит клиент, включая mime_type и сериализованные данные.

MCP Inspector является незаменимым инструментом для отладки и проверки, позволяя вам убедиться, что ваши ресурсы правильно отдают данные и соответствуют ожиданиям клиентских приложений.

Практические Сценарии Использования Ресурсов

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

1. Автодополнение списка документов: Когда пользователь начинает вводить символ "@" для упоминания документа, ваше приложение может использовать прямой ресурс (например, "docs://documents") для получения полного списка всех доступных документов. Этот список затем может быть использован для предоставления пользователю вариантов автодополнения.
2. Извлечение содержимого документа: Как только пользователь выбирает конкретный документ из списка автодополнения (например, "@МойВажныйДокумент"), ваше приложение может использовать шаблонный ресурс (например, "docs://documents/{doc_id}") для получения полного содержимого этого документа.

Такой подход позволяет превентивно внедрять содержимое документа непосредственно в промпты, которые отправляются Claude. Это означает, что Claude получает всю необходимую информацию о документе еще до того, как начнет обрабатывать запрос пользователя, без необходимости самостоятельно использовать какие-либо "инструменты" для извлечения данных. Это значительно повышает эффективность, точность и скорость ответов Claude, поскольку модель уже обладает полным контекстом. В конечном итоге, Claude, интегрированный через Google Vertex AI, выступает в роли клиента, который делает эти запросы к вашим MCP ресурсам, используя полученные данные для формирования более качественных и релевантных ответов.