MCP + LangChain Демо

Проект для начинающих, демонстрирующий, как создавать MCP (Model Context Protocol) серверы и подключать их к LLM агенту с помощью LangChain и LangGraph.

Что такое MCP?

MCP (Model Context Protocol) — это открытый протокол, который позволяет предоставлять LLM пользовательские инструменты (функции) стандартизированным способом. Представьте его как универсальную систему плагинов для ИИ-моделей.

Ключевые понятия:

Related MCP server: Model Context Protocol Multi-Agent Server

Структура проекта

MCPLEARNING/
├── mathserver.py      # MCP Server 1 - Math tools (stdio transport)
├── weather.py         # MCP Server 2 - Weather tool (HTTP transport)
├── client.py          # LangChain agent that connects to both servers
├── .env               # API keys (NOT pushed to GitHub)
├── .gitignore
├── requirements.txt
└── pyproject.toml

Как это работает (Пошагово)

Шаг 1: MCP Сервер — mathserver.py

Этот файл создает MCP сервер с именем "Math", который предоставляет два инструмента:

• add(a, b) — Возвращает сумму двух целых чисел.

• multiply(a, b) — Возвращает произведение двух целых чисел.

Он работает на stdio транспорте, что означает, что клиент запускает его как подпроцесс и общается через stdin/stdout. Порт не требуется.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Math")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Addition of two numbers"""
    return a + b

@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Multiplication of two numbers"""
    return a * b

if __name__ == "__main__":
    mcp.run(transport="stdio")

Шаг 2: MCP Сервер — weather.py

Этот файл создает MCP сервер с именем "Weather", который предоставляет один инструмент:

• get_weather(location) — Возвращает информацию о погоде для указанного местоположения.

Он работает на streamable-http транспорте, что означает, что он запускает веб-сервер на http://127.0.0.1:8000/mcp. Клиент подключается к нему через HTTP.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Weather")

@mcp.tool()
async def get_weather(location: str) -> str:
    """Get the weather"""
    return "It's always raining in California"

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

Шаг 3: Клиент-агент — client.py

Это мозг проекта. Он:

1. Подключается к обоим MCP серверам с помощью MultiServerMCPClient.

2. Обнаруживает все инструменты с обоих серверов (add, multiply, get_weather).

3. Создает Groq LLM (хостированная модель с открытым исходным кодом) и привязывает к ней инструменты.

4. Строит LangGraph агента — конечный автомат, в котором:

   • LLM решает, вызвать инструмент или ответить напрямую.

   • Если инструмент вызван, результат передается обратно LLM для окончательного ответа.

5. Тестирует два запроса:

   • "What is 3 + 5?" → Использует инструмент add.

   • "What is the weather in California?" → Использует инструмент get_weather.

Предварительные требования

• Python 3.13+

• Менеджер пакетов uv (рекомендуется) или pip

• Ключ API Groq — Получите бесплатно на console.groq.com

Настройка

1. Клонируйте репозиторий

git clone https://github.com/<YOUR_USERNAME>/MCPLEARNING.git
cd MCPLEARNING

2. Создайте и активируйте виртуальное окружение

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

# Or using pip
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # Mac/Linux
pip install -r requirements.txt

3. Настройте ключ API

Создайте файл .env в корне проекта:

GROQ_API_KEY=your_groq_api_key_here

ВАЖНО: Никогда не коммитьте файл .env. Он исключен через .gitignore.

Запуск проекта

Вам понадобится два терминала:

Терминал 1 — Запустите MCP сервер погоды

python weather.py

Вы должны увидеть:

INFO: Uvicorn running on http://127.0.0.1:8000

Примечание: Только weather.py нужно запускать вручную. mathserver.py запускается автоматически клиентом (stdio транспорт).

Терминал 2 — Запустите клиент

python client.py

Ожидаемый вывод

Available MCP tools:
- add
- multiply
- get_weather

==============================
Testing Math MCP
==============================

Math Response: 3 + 5 = 8.

==============================
Testing Weather MCP
==============================

Weather Response: It's always raining in California.

Как создать свой собственный MCP сервер

1. Установите библиотеку MCP:

pip install mcp

2. Создайте новый файл Python (например, myserver.py):

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("MyServer")

@mcp.tool()
def my_tool(param: str) -> str:
    """Description of what this tool does."""
    return f"Result: {param}"

if __name__ == "__main__":
    mcp.run(transport="stdio")        # For stdio transport
    # mcp.run(transport="streamable-http")  # For HTTP transport

3. Подключите его в клиенте, добавив в конфигурацию MultiServerMCPClient:

client = MultiServerMCPClient({
    "myserver": {
        "command": "python",
        "args": ["myserver.py"],
        "transport": "stdio",
    },
})

Сравнение транспортов

Используемые ключевые библиотеки

Важные моменты, о которых стоит позаботиться

1. Сервер погоды должен быть запущен до клиента — Поскольку он использует HTTP транспорт, процесс сервера должен быть запущен первым. Математический сервер (stdio) автоматически запускается клиентом.

2. Требуется ключ API Groq — Без него вызовы LLM завершатся ошибкой. Получите бесплатный ключ на console.groq.com.

3. Никогда не коммитьте .env — Всегда добавляйте .env в .gitignore перед отправкой кода.

4. Конфликты портов — Сервер погоды по умолчанию работает на порту 8000. Если другой процесс использует этот порт, сервер не запустится.

5. Проблема с кодировкой в Windows — В Windows консоль может не поддерживать символы UTF-8, возвращаемые LLM. client.py обрабатывает это с помощью sys.stdout.reconfigure(encoding="utf-8").

6. Доступность модели — Имя модели Groq (openai/gpt-oss-120b) должно быть действительным и доступным на платформе Groq. Проверьте список моделей Groq для получения актуальных вариантов.