MCP File Server + AI Agent

Проект демонстрирует интеграцию Model Context Protocol (MCP) сервера с AI-агентом, работающим на базе GPT-4. Агент может автономно использовать инструменты файлового сервера для чтения и перечисления файлов.

📋 Описание

Проект реализует паттерн ReAct (Reasoning + Acting):

• AI Agent анализирует запросы пользователя
• MCP Client подключается к MCP серверу
• MCP File Server предоставляет инструменты для работы с файлами в изолированной директории
• OpenAI API используется для логики принятия решений

🏗️ Архитектура

┌─────────────┐
│   main.py   │ (точка входа)
└──────┬──────┘
       │
       ├─► MCPClient ─────► stdio процесс
       │                        │
       │                        └─► mcp_file_server.py
       │
       └─► AgentHost (ReAct цикл)
            │
            ├─► OpenAI API (GPT-4)
            │
            └─► Использует MCP инструменты

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

.
├── agent_host.py          # Агент с ReAct логикой
├── mcp_client.py          # MCP клиент (подключение к серверу)
├── mcp_file_server.py     # MCP сервер с инструментами
├── main.py                # Точка входа приложения
├── pyproject.toml         # Конфигурация проекта
├── demo_files/            # Рабочая директория для тестирования
│   ├── demo.py
│   └── demo.txt
└── README.md              # Этот файл

🚀 Быстрый старт

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

• Python 3.12+
• OpenAI API ключ

Установка зависимостей

Конфигурация

Создайте файл

Запуск

Ожидаемый результат:

--- Запускаем сервер: mcp_file_server.py ---
✅ Сервер подключен

Вопрос: Какие файлы лежат в рабочей папке? Если есть текстовые, прочитай любой из них.

--- Ответ ИИ ---
[Агент перечислит файлы и прочитает один из них]

--- Соединение закрыто ---

📚 Компоненты

1. mcp_file_server.py — MCP Сервер

Предоставляет два инструмента:

• list_files()
  — возвращает список файлов в
  demo_files/
• read_file(filename)
  — читает содержимое файла (с проверкой безопасности)

2. mcp_client.py — MCP Клиент

Управляет подключением к MCP серверу:

• Запускает сервер как подпроцесс (stdio)
• Инициализирует JSON-RPC сессию
• Предоставляет методы для вызова инструментов:
  • connect()
    — подключение к серверу
  • list_tools()
    — получить доступные инструменты
  • call_tool(name, arguments)
    — вызвать инструмент
  • cleanup()
    — корректное завершение

3. agent_host.py — AI Agent

Реализует ReAct цикл (Рассуждение + Действие):

Процесс:

1. Получить список инструментов от сервера
2. Отправить запрос пользователя в OpenAI с описанием инструментов
3. Если LLM выбрал инструмент — вызвать его
4. Добавить результат в контекст и повторить
5. Когда LLM вернет финальный ответ — завершить

4. main.py — Точка входа

Демонстрационный скрипт, который:

• Инициализирует MCPClient
• Подключается к серверу
• Создает AgentHost
• Выполняет фиксированный запрос

🔒 Безопасность

• Изоляция файлов: Сервер работает только в директории
  demo_files/
• Проверка пути: Использется
  os.path.join()
  для предотвращения path traversal
• Обработка ошибок: Все исключения перехватываются и возвращаются как строки

🧪 Демо-файлы

В

• demo.txt
  — текстовый файл
• demo.py
  — Python скрипт

📖 Документация MCP

• Model Context Protocol
• MCP Python SDK

🛠️ Требования к окружению

Python: 3.12+
Dependencies:
  - mcp >= 0.1.0
  - openai >= 1.0.0
  - python-dotenv >= 1.0.0

👥 Автор

Проект создан как демонстрация интеграции MCP с AI агентами.