Урок: Създаване на Web Search MCP сървър

Тази глава показва как да изградите реален AI агент, който се интегрира с външни API-та, обработва различни типове данни, управлява грешки и координира множество инструменти – всичко това в готов за продукция формат. Ще видите:

Интеграция с външни API-та, изискващи автентикация
Обработка на разнообразни типове данни от няколко крайни точки
Надеждно управление на грешки и стратегии за логване
Оркестрация на няколко инструмента в един сървър

В края на урока ще имате практически опит с модели и добри практики, които са от съществено значение за напреднали AI и LLM-базирани приложения.

Въведение

В този урок ще научите как да изградите усъвършенстван MCP сървър и клиент, които разширяват възможностите на LLM с данни от уеб в реално време чрез SerpAPI. Това е ключово умение за разработване на динамични AI агенти, които могат да достъпват актуална информация от интернет.

Учебни цели

В края на урока ще можете да:

Интегрирате външни API-та (като SerpAPI) сигурно в MCP сървър
Имплементирате няколко инструмента за търсене в уеб, новини, продукти и въпроси и отговори
Парсвате и форматирате структурирани данни за консумация от LLM
Управлявате грешки и лимити на API заявките ефективно
Създавате и тествате както автоматизирани, така и интерактивни MCP клиенти

Web Search MCP сървър

Този раздел представя архитектурата и функциите на Web Search 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.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 или по-нова версия
SerpAPI API ключ (Регистрирайте се на SerpAPI – има безплатен план)

Инсталация

За да започнете, следвайте тези стъпки за настройка на средата:

Инсталирайте зависимостите с uv (препоръчително) или pip:

# Using uv (recommended)
uv pip install -r requirements.txt

# Using pip
pip install -r requirements.txt

Създайте .env файл в корена на проекта с вашия SerpAPI ключ:

SERPAPI_KEY=your_serpapi_key_here

Използване

Web Search MCP сървърът е основният компонент, който предоставя инструменти за уеб, новини, търсене на продукти и въпроси и отговори чрез интеграция с SerpAPI. Той обработва входящите заявки, управлява API повикванията, парсва отговорите и връща структурирани резултати на клиента.

Можете да разгледате пълната имплементация във файла server.py.

Стартиране на сървъра

За да стартирате MCP сървъра, използвайте следната команда:

python server.py

Сървърът ще работи като stdio-базиран MCP сървър, към който клиентът може да се свърже директно.

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

Клиентът (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 сървъра. Вместо да е формален unit тест, този скрипт ви позволява програмно да се свържете със сървъра, да извикате някой от инструментите с параметри по ваш избор и да разгледате резултатите. Този подход е полезен за:

Прототипиране и експериментиране с извиквания на инструменти
Валидация на отговорите на сървъра при различни входни данни
Автоматизиране на повтарящи се извиквания на инструменти
Създаване на собствени работни потоци или интеграции върху MCP сървъра

Можете да използвате тестови скриптове, за да пробвате бързо нови заявки, да отстранявате грешки в поведението на инструментите или дори като отправна точка за по-сложна автоматизация. По-долу е пример как да използвате MCP Python SDK за създаване на такъв скрипт:

Описания на инструментите

Можете да използвате следните инструменти, предоставени от сървъра, за извършване на различни видове търсения и заявки. Всеки инструмент е описан по-долу с параметрите си и пример за използване.

Този раздел предоставя подробности за всеки наличен инструмент и техните параметри.

general_search

Извършва общо уеб търсене и връща форматирани резултати.

Как да извикате този инструмент:

Можете да извикате general_search от собствен скрипт, използвайки MCP Python SDK, или интерактивно чрез Inspector или интерактивния режим на клиента. Ето пример с код, използващ SDK:

Python Example

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 (string): Търсена заявка

Примерна заявка:

{
  "query": "latest AI trends"
}

news_search

Търси за последни новинарски статии, свързани с дадена заявка.

Как да извикате този инструмент:

Можете да извикате news_search от собствен скрипт, използвайки MCP Python SDK, или интерактивно чрез Inspector или интерактивния режим на клиента. Ето пример с код, използващ SDK:

Python Example

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 (string): Търсена заявка

Примерна заявка:

{
  "query": "AI policy updates"
}

product_search

Търси продукти, съответстващи на заявка.

Как да извикате този инструмент:

Можете да извикате product_search от собствен скрипт, използвайки MCP Python SDK, или интерактивно чрез Inspector или интерактивния режим на клиента. Ето пример с код, използващ SDK:

Python Example

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 (string): Търсена заявка за продукт

Примерна заявка:

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

qna

Връща директни отговори на въпроси от търсачки.

Как да извикате този инструмент:

Можете да извикате qna от собствен скрипт, използвайки MCP Python SDK, или интерактивно чрез Inspector или интерактивния режим на клиента. Ето пример с код, използващ SDK:

Python Example

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 (string): Въпрос, за който търсите отговор

Примерна заявка:

{
  "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 не връща очакваното. Възстановяването при грешки означава, че кодът ви може да се справи с тези проблеми и все пак да даде полезна обратна връзка, вместо да се срине.
Валидация на параметри: Това е проверка дали всички входни данни към инструментите са правилни и безопасни за използване. Включва задаване на стойности по подразбиране и проверка на типовете, което помага да се избегнат грешки и объркване.

Този раздел ще ви помогне да диагностицирате и решите често срещани проблеми, които може да срещнете при работа с Web Search MCP сървъра. Ако се сблъскате с грешки или неочаквано поведение, този раздел за отстраняване на проблеми предлага решения на най-често срещаните проблеми. Прегледайте тези съвети преди да потърсите допълнителна помощ – те често решават проблемите бързо.

Отстраняване на проблеми

При работа с Web Search MCP сървъра понякога може да срещнете проблеми – това е нормално при разработка с външни API-та и нови инструменти. Този раздел предлага практични решения на най-често срещаните проблеми, за да можете бързо да се върнете към работа. Ако получите грешка, започнете от тук: съветите по-долу адресират проблемите, с които повечето потребители се сблъскват, и често могат да решат проблема без допълнителна помощ.

Чести проблеми

По-долу са някои от най-често срещаните проблеми, с които потребителите се сблъскват, заедно с ясни обяснения и стъпки за решаването им:

Липсва SERPAPI_KEY в .env файла
- Ако видите грешка SERPAPI_KEY environment variable not found, това означава, че приложението ви не може да намери API ключа, необходим за достъп до SerpAPI. За да го поправите, създайте файл с име .env в корена на проекта (ако все още не съществува) и добавете ред като SERPAPI_KEY=your_serpapi_key_here. Уверете се, че сте заменили your_serpapi_key_here с вашия реален ключ от сайта на SerpAPI.
Грешки за липсващи модули
- Грешки като ModuleNotFoundError: No module named 'httpx' показват, че липсва необходим Python пакет. Това обикновено се случва, ако не сте инсталирали всички зависимости. За да го решите, изпълнете pip install -r requirements.txt в терминала, за да инсталирате всичко необходимо за проекта.
Проблеми с връзката
- Ако получите грешка като Error during client execution, това често означава, че клиентът не може да се свърже със сървъра или сървърът не работи както трябва. Проверете дали клиентът и сървърът са съвместими версии и дали файлът server.py е наличен и стартиран в правилната директория. Рестартирането и на двата може също да помогне.
Грешки от SerpAPI
- Ако видите Search API returned error status: 401 За да активирате 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"
)

Какво следва

5.10 Реално време стрийминг

Отказ от отговорност:
Този документ е преведен с помощта на AI преводаческа услуга Co-op Translator. Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи могат да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или неправилни тълкувания, произтичащи от използването на този превод.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Урок: Създаване на Web Search MCP сървър

Въведение

Учебни цели

Web Search MCP сървър

Преглед

Функции

Python

Python сървър

Предварителни изисквания

Инсталация

Използване

Стартиране на сървъра

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

Стартиране на клиента

Тестване с различни методи

Писане на собствени тестови скриптове с MCP Python SDK

Python

Описания на инструментите

general_search

Python Example

news_search

Python Example

product_search

Python Example

qna

Python Example

Подробности за кода

Python

Разширени концепции в този урок

Отстраняване на проблеми

Чести проблеми

Python

Какво следва

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Урок: Създаване на Web Search MCP сървър

Въведение

Учебни цели

Web Search MCP сървър

Преглед

Функции

Python

Python сървър

Предварителни изисквания

Инсталация

Използване

Стартиране на сървъра

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

Стартиране на клиента

Тестване с различни методи

Писане на собствени тестови скриптове с MCP Python SDK

Python

Описания на инструментите

general_search

Python Example

news_search

Python Example

product_search

Python Example

qna

Python Example

Подробности за кода

Python

Разширени концепции в този урок

Отстраняване на проблеми

Чести проблеми

Python

Какво следва