Agent MCP

Агент МКП

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

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

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

1. Настройка среды

• Клонировать репозиторий и скопировать .env.example в .env
• Добавьте свой ключ API OpenAI в .env
• Установите с помощью uv venv && uv pip install -e .

2. Запустите MCP-сервер

ВАЖНО : Когда сервер запустится, он создаст базу данных в папке .agent вашего проекта. Ваш токен администратора хранится в этой базе данных. Чтобы найти его:

1. Установите расширение SQLite Viewer в вашем редакторе кода.
2. Откройте базу данных по адресу /path/to/your/project/.agent/mcp_state.db
3. Проверьте таблицу project_context на наличие токена администратора.

3. Создать основной контекстный документ (MCD)

• Создайте в своем проекте подробный файл MCD.md с архитектурой, маршрутами API, моделями данных и т. д.
• Это может быть один файл или несколько файлов (для сложных проектов).
• Шаблоны смотрите в папке MCD-EXAMPLE.

4. Запустите агента администратора

1. Откройте помощника по кодированию ИИ (Claude Code, Cursor и т. д.) в папке вашего проекта.
2. Скопируйте токен администратора, который вы нашли на шаге 2.
3. Попросите ИИ «Инициализироваться как агент администратора с этим токеном: [ваш-токен]»
4. Попросите административного агента добавить ваш MCD в контекст проекта с помощью:
   Please add the MCD.md file to the project context. Don't summarize it.

5. Создание и управление рабочими агентами через администратора

1. Попросите своего административного агента создать рабочего агента:
   Create a worker agent with ID "frontend-worker" to implement the login page.
2. Откройте новое окно/сеанс в вашем ИИ-помощнике (та же кодовая база)
3. Инициализируйте воркер с помощью этого точного запроса:
   You are [worker-id] agent, your Admin Token: "[admin-token]" Look at your tasks and ask the project RAG agent at least 5-7 questions to understand what you need to do. I want you to critically think when asking a question, then criticize yourself before asking that question. How you criticize yourself is by proposing an idea, criticizing it, and based on that criticism you pull through with that idea. AUTO --worker --memory
4. Работник автоматически найдет назначенные ему задачи и приступит к работе.

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

Функции

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

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

Посмотрите видеоурок: Как добавить контекст MCD в Agent MCP

Перед началом разработки необходимо провести глубокое исследование, чтобы создать Основной Контекстный Документ (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. Настройка агента администратора : инициализируйте агента администратора с помощью токена и docs/INSTRUCTIONS.md
4. Создание рабочих : администратор создает специализированных рабочих для различных аспектов вашего проекта.
5. Назначение задач : администратор разбивает MCD на отдельные задачи и назначает их работникам.
6. Параллельная разработка : работники выполняют задачи, обмениваясь контекстом через MCP.
7. Сохранение контекста : все агенты хранят свои знания в центральной базе данных.

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

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

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

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

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

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

Параметры:

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

2. Понимание токенов MCP

Система MCP использует для аутентификации два типа токенов:

Токен администратора :

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

Рабочие токены :

1. Когда агент администратора создает рабочего агента, генерируется определенный рабочий токен.
2. Агент администратора предоставит этот токен работника при запросе на создание работника.
3. Каждый работник имеет свой уникальный токен с определенными разрешениями.
4. Токены рабочих также хранятся в базе данных .agent/mcp_state.db

ВАЖНО : НЕ используйте токен администратора для рабочих агентов. Всегда используйте конкретный токен рабочего, предоставленный административным агентом при создании рабочего.

3. Рабочий процесс агента (ВАЖНО)

Примечание : Все агенты создаются и управляются через чат с вашим помощником на основе искусственного интеллекта — для создания агентов НЕ используются инструменты командной строки.

MCP Server — это ЕДИНСТВЕННЫЙ компонент, который запускается с помощью команды:

Агент администратора — создайте его, сказав своему помощнику-ИИ:

Рабочие агенты — создаются через агента администратора с помощью:

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

Панель управления ( http://localhost:8080 ):

• Это просто для наглядности — здесь вы не создаете агентов.
• Вся фактическая работа происходит через окна чата вашего помощника ИИ.
• Панель инструментов показывает связи между агентами и задачами.

4. Инициализация рабочих агентов (скопировать/вставить это)

После того, как ваш агент администратора создаст работника, откройте новое окно помощника ИИ и инициализируйте работника с помощью ТОЧНОГО запроса:

Сделайте эти две замены:

1. Замените [agent_id] на идентификатор работника, который вы указали администратору создать (например, «frontend-worker»).
2. Замените your_worker_token_here на конкретный токен работника, предоставленный агентом администратора при создании этого работника (НЕ токен администратора)

После инициализации рабочий процесс выполнит следующие действия:

1. Проверьте наличие задач, назначенных его идентификатору.
2. Задайте системе RAG вопрос о контексте проекта
3. Начните работать над своими задачами автономно
4. Хранить детали реализации в системе общей памяти

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

Панель инструментов и пользовательский интерфейс терминала

Панель инструментов (визуализация)

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

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

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

Несколько сеансов агента: визуальное руководство

Для сложных проектов у вас будет открыто несколько сеансов чата одновременно:

Как это работает:

1. Одно окно/сеанс для вашего административного агента
2. Отдельные окна/сеансы для каждого рабочего агента
3. Администратор использует токен администратора, работники используют свои собственные токены работников.
4. Каждый работник имеет УНИКАЛЬНЫЙ идентификатор агента и токен.

Пример настройки с 3 агентами:

Вы можете использовать Claude Code, RooCode или MultipleCursor для управления несколькими окнами/сеансами, работающими на одной и той же кодовой базе.

Полный пример рабочего процесса

Вот пошаговый пример использования Agent MCP от начала до конца:

Шаг 1: Создайте свой проект

Шаг 2: Установка агента MCP

Шаг 3: Создайте свой MCD

Шаг 4: Запустите MCP-сервер

Шаг 5: Найдите токен администратора

1. Установите SQLite Viewer в свой редактор кода
2. Открыть .agent/mcp_state.db
3. Найдите токен в таблице project_context

Шаг 6: Инициализация агента администратора

1. Откройте своего помощника ИИ (Claude Code, Cursor и т. д.)
2. Расскажите ему:

Шаг 7: Создание рабочего агента

1. Сообщите администратору:

2. Административный агент предоставит вам рабочий токен для этого нового агента.

Шаг 8: Инициализация рабочего агента

1. Открыть новое окно помощника ИИ
2. Расскажите ему:

Теперь работник автоматически приступит к выполнению поставленных задач!

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

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

Токены выполняют несколько функций в системе 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 и База знаний (Центральная система памяти)

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

Как работает система памяти

1. Сервер MCP поддерживает центральную базу данных для всего контекста проекта.
2. При запуске сервера он создает папку .agent в каталоге вашего проекта.
3. Ваш агент администратора добавляет ваш MCD в эту базу данных при его инициализации.
4. Рабочие агенты автоматически запрашивают эту базу данных, чтобы понять свои задачи.
5. Все детали реализации сохраняются в этой базе данных, чтобы другие агенты могли получить к ним доступ.

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

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

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

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

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

Сообщество

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