Skip to content

README.md

Latest commit

 

History

History
472 lines (325 loc) · 28.8 KB

README.md

File metadata and controls

472 lines (325 loc) · 28.8 KB

Урок: Создание MCP-сервера для веб-поиска

В этой главе показано, как создать реального AI-агента, который интегрируется с внешними API, обрабатывает разные типы данных, управляет ошибками и координирует работу нескольких инструментов — всё в формате, готовом к промышленному использованию. Вы увидите:

  • Интеграция с внешними API, требующими аутентификации
  • Обработка различных типов данных с нескольких источников
  • Надёжные стратегии обработки ошибок и ведения логов
  • Оркестрация нескольких инструментов в одном сервере

К концу урока у вас будет практический опыт работы с паттернами и лучшими практиками, необходимыми для продвинутых AI-приложений на базе LLM.

Введение

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

Цели обучения

К концу урока вы сможете:

  • Безопасно интегрировать внешние API (например, SerpAPI) в MCP-сервер
  • Реализовать несколько инструментов для веб-поиска, новостей, поиска товаров и вопросов-ответов
  • Парсить и форматировать структурированные данные для использования LLM
  • Эффективно обрабатывать ошибки и управлять лимитами API
  • Создавать и тестировать как автоматизированных, так и интерактивных MCP-клиентов

MCP-сервер для веб-поиска

В этом разделе представлена архитектура и возможности MCP-сервера для веб-поиска. Вы увидите, как FastMCP и SerpAPI работают вместе, расширяя возможности LLM за счёт данных из веба в реальном времени.

Обзор

В реализации используются четыре инструмента, демонстрирующие способность MCP безопасно и эффективно обрабатывать разнообразные задачи с внешними API:

  • general_search: для широкого веб-поиска
  • news_search: для последних новостей
  • product_search: для данных электронной коммерции
  • qna: для вопросов и ответов

Особенности

  • Примеры кода: Включены блоки кода на Python (и легко расширяемые на другие языки) с использованием code pivots для удобства

Python

# Example usage of the general_search tool
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_search():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("general_search", arguments={"query": "open source LLMs"})
            print(result)

Перед запуском клиента полезно понять, что делает сервер. Файл server.py реализует MCP-сервер, предоставляющий инструменты для веб-поиска, новостей, товаров и вопросов-ответов через интеграцию с SerpAPI. Он обрабатывает входящие запросы, управляет вызовами API, парсит ответы и возвращает структурированные результаты клиенту.

Полную реализацию можно посмотреть в server.py.

Ниже приведён краткий пример того, как сервер определяет и регистрирует инструмент:

Python Server

# server.py (excerpt)
from mcp.server import MCPServer, Tool

async def general_search(query: str):
    # ...implementation...

server = MCPServer()
server.add_tool(Tool("general_search", general_search))

if __name__ == "__main__":
    server.run()
  • Интеграция с внешними API: Демонстрирует безопасную работу с API-ключами и внешними запросами
  • Парсинг структурированных данных: Показывает, как преобразовать ответы API в удобный для LLM формат
  • Обработка ошибок: Надёжная обработка ошибок с соответствующим логированием
  • Интерактивный клиент: Включает как автоматические тесты, так и интерактивный режим для тестирования
  • Управление контекстом: Использует MCP Context для логирования и отслеживания запросов

Требования

Перед началом убедитесь, что ваша среда настроена правильно, выполнив следующие шаги. Это гарантирует установку всех зависимостей и корректную настройку API-ключей для беспроблемной разработки и тестирования.

  • Python 3.8 или выше
  • API-ключ SerpAPI (зарегистрируйтесь на SerpAPI — доступен бесплатный тариф)

Установка

Чтобы начать работу, выполните следующие шаги для настройки среды:

  1. Установите зависимости с помощью uv (рекомендуется) или pip:
# Using uv (recommended)
uv pip install -r requirements.txt

# Using pip
pip install -r requirements.txt
  1. Создайте файл .env в корне проекта и добавьте в него ваш ключ SerpAPI:
SERPAPI_KEY=your_serpapi_key_here

Использование

MCP-сервер для веб-поиска — это основной компонент, который предоставляет инструменты для веб-поиска, новостей, товаров и вопросов-ответов через интеграцию с SerpAPI. Он обрабатывает входящие запросы, управляет вызовами API, парсит ответы и возвращает структурированные результаты клиенту.

Полную реализацию можно посмотреть в server.py.

Запуск сервера

Для запуска MCP-сервера используйте следующую команду:

python server.py

Сервер будет работать как MCP-сервер на основе stdio, к которому клиент может подключаться напрямую.

Режимы клиента

Клиент (client.py) поддерживает два режима взаимодействия с MCP-сервером:

  • Обычный режим: Запускает автоматические тесты, которые проверяют все инструменты и их ответы. Это удобно для быстрой проверки корректной работы сервера и инструментов.
  • Интерактивный режим: Запускает меню, где можно вручную выбирать и вызывать инструменты, вводить собственные запросы и видеть результаты в реальном времени. Идеально подходит для изучения возможностей сервера и экспериментов с разными входными данными.

Полную реализацию можно посмотреть в client.py.

Запуск клиента

Для запуска автоматических тестов (при этом сервер запустится автоматически):

python client.py

Или запустите в интерактивном режиме:

python client.py --interactive

Тестирование разными способами

Существует несколько способов тестировать и взаимодействовать с инструментами сервера в зависимости от ваших задач и рабочего процесса.

Написание собственных тестовых скриптов с MCP Python SDK

Вы также можете создавать свои тестовые скрипты с помощью MCP Python SDK:

Python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_custom_query():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            # Call tools with your custom parameters
            result = await session.call_tool("general_search", 
                                           arguments={"query": "your custom query"})
            # Process the result

В данном контексте «тестовый скрипт» — это ваша собственная программа на Python, которая выступает в роли клиента MCP-сервера. Вместо формального юнит-теста этот скрипт позволяет программно подключаться к серверу, вызывать любые инструменты с нужными параметрами и анализировать результаты. Такой подход полезен для:

  • Прототипирования и экспериментов с вызовами инструментов
  • Проверки реакции сервера на разные входные данные
  • Автоматизации повторяющихся вызовов инструментов
  • Создания собственных рабочих процессов или интеграций поверх MCP-сервера

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

Описание инструментов

Вы можете использовать следующие инструменты, предоставляемые сервером, для различных видов поиска и запросов. Каждый инструмент описан ниже с параметрами и примером использования.

В этом разделе приведены подробности по каждому доступному инструменту и их параметрам.

general_search

Выполняет общий веб-поиск и возвращает отформатированные результаты.

Как вызвать этот инструмент:

Вы можете вызвать general_search из собственного скрипта с помощью MCP Python SDK или интерактивно через Inspector или интерактивный режим клиента. Вот пример кода с использованием SDK:

Пример на Python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_general_search():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("general_search", arguments={"query": "latest AI trends"})
            print(result)

Или в интерактивном режиме выберите general_search в меню и введите запрос, когда появится приглашение.

Параметры:

  • query (строка): поисковый запрос

Пример запроса:

{
  "query": "latest AI trends"
}

news_search

Ищет последние новости по заданному запросу.

Как вызвать этот инструмент:

Вы можете вызвать news_search из собственного скрипта с помощью MCP Python SDK или интерактивно через Inspector или интерактивный режим клиента. Вот пример кода с использованием SDK:

Пример на Python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_news_search():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("news_search", arguments={"query": "AI policy updates"})
            print(result)

Или в интерактивном режиме выберите news_search в меню и введите запрос, когда появится приглашение.

Параметры:

  • query (строка): поисковый запрос

Пример запроса:

{
  "query": "AI policy updates"
}

product_search

Ищет товары, соответствующие запросу.

Как вызвать этот инструмент:

Вы можете вызвать product_search из собственного скрипта с помощью MCP Python SDK или интерактивно через Inspector или интерактивный режим клиента. Вот пример кода с использованием SDK:

Пример на Python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_product_search():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("product_search", arguments={"query": "best AI gadgets 2025"})
            print(result)

Или в интерактивном режиме выберите product_search в меню и введите запрос, когда появится приглашение.

Параметры:

  • query (строка): поисковый запрос для товаров

Пример запроса:

{
  "query": "best AI gadgets 2025"
}

qna

Получает прямые ответы на вопросы из поисковых систем.

Как вызвать этот инструмент:

Вы можете вызвать qna из собственного скрипта с помощью MCP Python SDK или интерактивно через Inspector или интерактивный режим клиента. Вот пример кода с использованием SDK:

Пример на Python

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def run_qna():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )
    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()
            result = await session.call_tool("qna", arguments={"question": "what is artificial intelligence"})
            print(result)

Или в интерактивном режиме выберите qna в меню и введите вопрос, когда появится приглашение.

Параметры:

  • question (строка): вопрос, на который нужно найти ответ

Пример запроса:

{
  "question": "what is artificial intelligence"
}

Детали кода

В этом разделе приведены фрагменты кода и ссылки на реализации сервера и клиента.

Python

Смотрите server.py и client.py для полной реализации.

# Example snippet from server.py:
import os
import httpx
# ...existing code...

Продвинутые концепции в этом уроке

Перед началом разработки обратите внимание на важные продвинутые концепции, которые будут встречаться в этой главе. Их понимание поможет вам лучше усвоить материал, даже если вы с ними не знакомы:

  • Оркестрация нескольких инструментов: означает запуск нескольких разных инструментов (например, веб-поиск, новости, поиск товаров и вопросы-ответы) в одном MCP-сервере. Это позволяет серверу выполнять разнообразные задачи, а не только одну.
  • Обработка лимитов API: многие внешние API (например, SerpAPI) ограничивают количество запросов за определённое время. Хороший код проверяет эти лимиты и корректно с ними работает, чтобы приложение не ломалось при достижении лимита.
  • Парсинг структурированных данных: ответы API часто сложные и вложенные. Эта концепция — о том, как преобразовать такие ответы в чистый, удобный для LLM или других программ формат.
  • Восстановление после ошибок: иногда что-то идёт не так — например, сбой сети или API возвращает неожиданные данные. Восстановление после ошибок означает, что ваш код умеет справляться с такими проблемами и выдавать полезную информацию, а не просто падать.
  • Валидация параметров: проверка, что все входные данные для инструментов корректны и безопасны. Включает установку значений по умолчанию и проверку типов, что помогает избежать багов и путаницы.

Этот раздел поможет вам диагностировать и решать распространённые проблемы при работе с MCP-сервером для веб-поиска. Если вы столкнётесь с ошибками или неожиданным поведением, этот раздел с советами поможет быстро найти решение. Ознакомьтесь с ним перед тем, как обращаться за дополнительной помощью — часто это позволяет быстро устранить проблему.

Устранение неполадок

При работе с MCP-сервером для веб-поиска иногда могут возникать проблемы — это нормально при разработке с внешними API и новыми инструментами. В этом разделе приведены практические решения самых распространённых проблем, чтобы вы могли быстро вернуться к работе. Если вы столкнулись с ошибкой, начните отсюда: советы ниже охватывают типичные ситуации, с которыми сталкиваются пользователи, и часто помогают решить проблему без дополнительной помощи.

Распространённые проблемы

Ниже перечислены наиболее частые проблемы с понятными объяснениями и шагами для их решения:

  1. Отсутствует SERPAPI_KEY в файле .env

    • Если вы видите ошибку SERPAPI_KEY environment variable not found, значит приложение не может найти API-ключ для доступа к SerpAPI. Чтобы исправить это, создайте файл .env в корне проекта (если его ещё нет) и добавьте строку вида SERPAPI_KEY=ваш_ключ_serpapi. Обязательно замените ваш_ключ_serpapi на ваш реальный ключ с сайта SerpAPI.

  2. Ошибки «Module not found»

    • Ошибки вроде ModuleNotFoundError: No module named 'httpx' означают, что не установлен необходимый пакет Python. Обычно это происходит, если вы не установили все зависимости. Чтобы исправить, выполните в терминале pip install -r requirements.txt для установки всех нужных библиотек.

  3. Проблемы с подключением

    • Если появляется ошибка типа Error during client execution, это часто значит, что клиент не может подключиться к серверу или сервер не запущен должным образом. Проверьте, что версии клиента и сервера совместимы, и что файл server.py находится в нужной директории и запущен. Перезапуск сервера и клиента тоже может помочь.

  4. Ошибки SerpAPI

    • Сообщение Search API returned error status: 401 означает, что ключ SerpAPI отсутствует, неверен или истёк. Зайдите в панель управления SerpAPI, проверьте ключ и обновите файл .env при необходимости. Если ключ верный, но ошибка сохраняется, проверьте, не исчерпан ли бесплатный лимит.

Режим отладки

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

Пример: обычный вывод

2025-06-01 10:15:23,456 - __main__ - INFO - Calling general_search with params: {'query': 'open source LLMs'}
2025-06-01 10:15:24,123 - __main__ - INFO - Successfully called general_search

GENERAL_SEARCH RESULTS:
... (search results here) ...

Пример: вывод в режиме DEBUG

2025-06-01 10:15:23,456 - __main__ - INFO - Calling general_search with params: {'query': 'open source LLMs'}
2025-06-01 10:15:23,457 - httpx - DEBUG - HTTP Request: GET https://serpapi.com/search ...
2025-06-01 10:15:23,458 - httpx - DEBUG - HTTP Response: 200 OK ...
2025-06-01 10:15:24,123 - __main__ - INFO - Successfully called general_search

GENERAL_SEARCH RESULTS:
... (search results here) ...

Обратите внимание, что в режиме DEBUG добавляются строки с информацией о HTTP-запросах, ответах и других внутренних деталях. Это очень полезно для устранения неполадок. Чтобы включить режим DEBUG, установите уровень логирования в DEBUG в начале вашего файла client.py или server.py:

Python

# At the top of your client.py or server.py
import logging
logging.basicConfig(
    level=logging.DEBUG,  # Change from INFO to DEBUG
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)

Что дальше

Отказ от ответственности:
Этот документ был переведен с помощью сервиса автоматического перевода Co-op Translator. Несмотря на наши усилия по обеспечению точности, просим учитывать, что автоматический перевод может содержать ошибки или неточности. Оригинальный документ на его исходном языке следует считать авторитетным источником. Для получения критически важной информации рекомендуется обращаться к профессиональному переводу, выполненному человеком. Мы не несем ответственности за любые недоразумения или неправильные толкования, возникшие в результате использования данного перевода.