Agent MCP

Агент МКП

Фреймворк для создания многоагентных систем с использованием MCP (Model Context Protocol) для скоординированного и эффективного взаимодействия искусственного интеллекта.

Краткое руководство пользователя

Примечание: я рекомендую использовать https://github.com/rinadelph/MultipleCursor для запуска разных окон курсора на одной и той же кодовой базе, как показано на снимке экрана выше.

1. Среда установки :
   • Клонировать репозиторий и скопировать .env.example в .env
   • Добавьте свой ключ API OpenAI в .env
   • Установите с помощью uv venv && uv pip install -e .
2. Запустите MCP-сервер :
   uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project
   Важно : токен администратора хранится в базе данных SQLite .agent/mcp_state.db в контексте проекта. Установите расширение SQLite viewer, чтобы получить к нему доступ.
3. Создать основной контекстный документ (MCD) :
   • Создайте подробный MCD.md с архитектурой системы, маршрутами API, моделями данных и т. д.
4. Запустить агента администратора :
   • Начать в одном окне/сеансе
   • Дайте ему токен администратора.
5. Инициализация рабочих агентов :
   • Открыть новое окно/сеанс для каждого работника
   • Копировать приглашение рабочего процесса с автоматическим режимом из раздела 4 ниже
   • Замените на правильный идентификатор агента и токен администратора

Для получения более подробной информации следуйте подробным инструкциям ниже.

Функции

• Многоагентная структура сотрудничества
• Управление задачами и координация
• Контекст и обмен знаниями между агентами
• Графическая визуализация взаимодействия агентов
• Поддержка встраивания и возможностей RAG
• Интерактивная панель управления для визуализации задач, агентов и контекста.

Планирование проекта с основным контекстным документом (MCD)

Перед началом разработки необходимо провести глубокое исследование, чтобы создать Основной Контекстный Документ (MCD) — единственный источник истины для вашего приложения. Этот документ содержит подробный план, в котором подробно описывается:

• Архитектура системы и взаимосвязи компонентов
• UI/UX-дизайн для всех экранов и компонентов
• Маршруты и конечные точки API
• Структуры данных и модели
• Реализационные единицы и задачи
• Зависимости и стек технологий

MCD имеет решающее значение, поскольку:

1. Позволяет агентам понять всю систему, прежде чем приступать к работе над отдельными компонентами.
2. Позволяет осуществлять линейное, скоординированное строительство (подобно строительству дома по чертежам).
3. Уменьшает использование токенов, предоставляя структурированный, релевантный контекст.
4. Предотвращает конфликтующие реализации между агентами

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

• Обзор и цели
• Контекстные и архитектурные диаграммы
• Функциональные требования
• Спецификации дизайна (UI/UX, API, модели данных)
• Подробности реализации
• Разбивка задач для агентов

Благодаря комплексному MCD агенты могут внедрять ваше приложение по частям, четко понимая, как каждая часть вписывается в целое.

Установка

Предпосылки

• Питон 3.8+
• uv (рекомендуется для более быстрой установки пакета)

Настраивать

1. Клонируйте репозиторий:
   git clone https://github.com/your-username/agent-mcp.git cd agent-mcp
2. Настройте переменные среды, скопировав файл примера:
   cp .env.example .env
3. Отредактируйте файл .env и добавьте свой ключ API OpenAI:
   OPENAI_API_KEY=your_openai_api_key_here
4. Установка с помощью uv:
   uv venv uv pip install -e .
   Или с помощью пипа:
   pip install -e .

Многоагентный рабочий процесс

Обзор рабочего процесса

1. Начните с глубокого исследования : перед кодированием используйте ИИ для создания всеобъемлющего основного контекстного документа (MCD)
2. Запустите инфраструктуру : запустите сервер MCP и найдите свой токен администратора в базе данных.
3. Настройка агента администратора : инициализируйте агента администратора с помощью токена и INSTRUCTIONS.md
4. Создание рабочих : администратор создает специализированных рабочих для различных аспектов вашего проекта.
5. Назначение задач : администратор разбивает MCD на отдельные задачи и назначает их работникам.
6. Параллельная разработка : работники выполняют задачи, обмениваясь контекстом через MCP.
7. Сохранение контекста : все агенты хранят свои знания в центральной базе данных.

Цикл развития

Обзор архитектуры

Система MCP использует иерархическую структуру с:

• Административный агент : координирует работу других агентов, назначает задачи и поддерживает общее направление проекта.
• Рабочие агенты : специализированные агенты, которые выполняют определенные задачи (фронтэнд, бэкэнд, моделирование данных и т. д.)

Настройка и эксплуатация агента

1. Запуск MCP-сервера

Параметры:

• --port : Порт для запуска сервера (по умолчанию: 8080)
• --project-dir : Базовый каталог проекта

2. Доступ к токену администратора

Токен администратора обеспечивает привилегированный доступ к серверу MCP и необходим для всех операций агента.

Нахождение токена администратора :

1. После запуска сервера автоматически генерируется токен
2. Этот токен хранится в базе данных SQLite .agent/mcp_state.db
3. Установите расширение SQLite Viewer для VS Code или другой инструмент SQLite
4. Откройте базу данных и проверьте таблицу project_context
5. Найдите запись токена администратора.

Токены агента : Токены, специфичные для агента, также хранятся в папке .agent . Эти токены предоставляют каждому агенту его особые разрешения и идентификацию в системе MCP.

3. Запуск агентов

1. Сначала запустите сервер MCP :
   uv run -m mcp_template.main --port 8080 --project-dir /path/to/your/project
   При запуске сервер сгенерирует токен администратора — сохраните этот токен, так как он понадобится вам для аутентификации агента.
2. Агент администратора : запустите одного агента администратора, используя:
   uv run -m mcp_template.mcp_client_runner --admin
   Если вы столкнулись с ошибками импорта, такими как ModuleNotFoundError: No module named 'mcp_client' , убедитесь, что вы запускаете проект из корня и ваш пакет Python установлен правильно.
3. Рабочие агенты : вместо того, чтобы запускать рабочие агенты напрямую, поручите своему агенту администратора создавать и управлять ими. Это делается путем указания агенту администратора:
   "Create a new agent with ID 'frontend-worker' and assign it to implement the login page based on the MCD."
   Административный агент будет заниматься созданием и назначением задач рабочим агентам.

4. Использование режима AUTO с рабочими агентами

Рекомендуемый способ инициализации рабочих агентов — через вашего агента администратора. Когда агент создан, используйте этот точный запрос инициализации рабочего (скопируйте и вставьте его в ваш рабочий агент):

Замените [agent_id] фактическим идентификатором работника (например, «frontend-worker»), а your_admin_token_here — токеном, сгенерированным при запуске сервера MCP.

Это дает команду агенту:

• Работают автономно, без вмешательства пользователя.
• Следуйте рабочему протоколу с отслеживанием статуса задачи
• Используйте память для сохранения контекста во время взаимодействий
• Проактивно запрашивайте систему RAG, чтобы понять контекст задачи

Для достижения наилучших результатов прикрепите инструкции из INSTRUCTIONS.md при инициализации агентов, скопировав и вставив их перед командой AUTO.

Панель инструментов

Откройте панель управления по адресу http://localhost:8080 , чтобы:

• Мониторинг действий агентов в режиме реального времени
• Просмотр статуса задачи и зависимостей
• Наблюдайте за взаимоотношениями и координацией агентов
• Отслеживание файловых операций и обмен контекстом

Альтернативное развитие: сеансы с несколькими агентами

Рекомендуемый подход для сложных проектов:

1. Используйте один разговор для вашего административного агента
2. Начинайте отдельные разговоры/сеансы для каждого рабочего агента
3. Используйте один и тот же токен администратора для всех агентов
4. Используйте Claude Code, RooCode или Cursor с несколькими окнами/сеансами

Такой подход дает каждому агенту собственный контекст разговора, в то время как они взаимодействуют через общую систему MCP.

Пример рабочего процесса:

1. Запустите сервер MCP и запишите токен администратора.
2. Создать агента администратора в одном окне
3. Для каждого рабочего агента откройте новое окно и инициализируйте его с помощью приглашения рабочего агента, указанного выше.
4. Дайте каждому работнику свой собственный идентификатор агента, но тот же самый токен администратора.

Система токенов и управление ресурсами

Понимание токенов

Токены выполняют несколько функций в системе MCP:

1. Токены аутентификации : используются для идентификации агента и административного доступа.
2. Токены RAG : используются для встраивания и извлечения контекста из базы знаний.
3. Токены OpenAI : потребляются во время операций агента (использование модели)

Управление токенами

Для мониторинга и управления использованием токенов:

1. Установите плагин SQLite Viewer или используйте командную строку:
   sqlite3 /path/to/project/.agent/mcp_state.db
2. Использование токена запроса:
   SELECT * FROM token_usage;
3. Монитор на панели управления на вкладке «Ресурсы»

Оптимизация ресурсов

Для крупных проектов:

1. Используйте специализированные агенты с целевыми возможностями для уменьшения размера контекста
2. Разбейте задачи на более мелкие части с четкими зависимостями
3. Используйте систему RAG для эффективного поиска контекста
4. Сохраняйте общую информацию в контексте проекта, а не повторяйте ее в сообщениях.

Проект RAG и База знаний

Создание проекта RAG

Система поиска и расширенной генерации (RAG) позволяет агентам эффективно получать доступ к соответствующим знаниям проекта:

1. Индексировать файлы проекта:
   python -m mcp_template.rag_indexer --project-dir /path/to/project
2. Добавить документацию в базу знаний:
   python -m mcp_template.rag_indexer --add-doc /path/to/document.md

Использование RAG в рабочих процессах агентов

Агенты могут запрашивать базу знаний, используя:

Это возвращает релевантный контекст без загрузки целых файлов, что экономит токены и повышает качество ответа.

Стратегия назначения задач агенту

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

1. Детализация задач : разбивайте большие задачи на атомарные единицы с четкими входами/выходами.
2. Отслеживание зависимостей : четкое определение зависимостей задач в назначении
3. Сопоставление возможностей : назначайте задачи агентам с соответствующими возможностями.
4. Мониторинг хода выполнения : используйте явные обновления статуса для отслеживания хода выполнения задач.
5. Обмен контекстом : предоставление необходимого контекста во время задания для сокращения последующих поисков.

Пример назначения задачи от администратора работнику:

При создании нового рабочего агента:

1. Сообщите своему агенту-администратору: «Создайте нового агента с идентификатором 'frontend-worker' и назначьте его для реализации страницы входа на основе MCD».
2. Откройте новое окно/сеанс и инициализируйте рабочий агент с помощью приглашения AUTO, описанного ранее.
3. Обязательно включите токен администратора, чтобы работник мог получить доступ к назначенным ему задачам.

Компоненты

• main.py : реализация сервера MCP
• mcp_client.py : Клиентская библиотека для подключения агентов к MCP
• dashboard_api.py : конечные точки API для визуализации
• rag_agent_test.py : Пример агента с поддержкой RAG
• INSTRUCTIONS.md : Руководство по эксплуатации для агентов

Переменные среды

• OPENAI_API_KEY : ваш ключ API OpenAI.
• MCP_SERVER_URL : URL-адрес сервера MCP
• MCP_ADMIN_TOKEN : (Необязательно) токен администратора для прямого доступа
• MCP_PROJECT_DIR : Путь к каталогу проекта

Лицензия

Лицензия Массачусетского технологического института

Сообщество

Присоединяйтесь к нашему сообществу Discord, чтобы обсудить Agent MCP, поделиться своими проектами, получить помощь и связаться с другими разработчиками, работающими с инструментами ИИ. Мы — растущее сообщество, сосредоточенное на расширении границ возможностей многоагентных систем и совместной работы ИИ.