AggreGate MCP Server

MCP (Model Context Protocol) сервер для работы с AggreGate через AI-ассистентов (Cursor, Claude Desktop и др.).

📋 Описание

Этот проект предоставляет MCP сервер, который позволяет AI-ассистентам взаимодействовать с сервером AggreGate через стандартизированный протокол. Сервер предоставляет набор инструментов для управления контекстами, переменными, функциями, событиями, устройствами, пользователями и другими элементами AggreGate.

Для ИИ-агентов (качество разработки на AggreGate)

Обязательный контекст senior-уровня: сначала AGENTS.md, затем docs/README.md (карта всех гайдов). Без этого легко ошибиться в контейнере (models vs alerts), в modelType или в форматах Data Table.

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

Настройка в Cursor

1. Скомпилируйте проект:

   ./gradlew build
   

2. Добавьте конфигурацию MCP сервера в ~/.cursor/mcp.json:

   {
     "mcpServers": {
       "aggregate": {
         "command": "java",
         "args": [
           "-jar",
           "C:\\mcp-server\\build\\libs\\aggregate-mcp-server-1.0.0.jar"
         ]
       }
     }
   }
   

3. Перезапустите Cursor для применения изменений.

Подробные инструкции: MCP_CURSOR_SETUP.md

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

Основные руководства

• AGENTS.md - Старт для ИИ: senior-контекст AggreGate + MCP (читать первым)
• MCP_CURSOR_SETUP.md - Настройка MCP сервера в Cursor
• AI_WORKFLOW_RULES.md - Правила рабочего процесса для ИИ
• AI_AUTO_TESTING_GUIDE.md - Руководство по автоматическому тестированию
• README_AI_AUTO_TESTING.md - Обзор автоматического тестирования

Руководства по моделям

Источник истины по кодам modelType для API: 0 = относительная, 1 = абсолютная, 2 = экземплярная — docs/MCP_MODEL_TYPES_GUIDE.md.

• docs/MCP_MODEL_TYPES_GUIDE.md - Полное руководство по типам моделей (абсолютные, относительные, экземплярные)
• docs/MCP_MODEL_COOKBOOKS.md — пошаговые примеры относительной и экземплярной модели (MCP)

Примеры использования

• ALL_TASKS_MCP_GUIDE.md - Руководство по выполнению задач через MCP
• EXECUTE_TASKS_VIA_MCP.md - Примеры выполнения задач

Документация в папке docs/

Единая карта и полный перечень файлов: docs/README.md. Ниже — только самые частые точки входа.

• docs/MCP_AGGREGATE_CONTEXTS_GUIDE.md — куда создавать объекты в дереве AggreGate
• docs/MCP_SERVER_USAGE_GUIDE.md — использование MCP-сервера (в т.ч. запись переменных)
• docs/MCP_MODEL_TYPES_GUIDE.md — типы моделей 0 / 1 / 2
• docs/MCP_AI_QUICK_REFERENCE.md — короткая шпаргалка по вызовам
• docs/AGGREGATE_API_GUIDE.md — API и типичные ошибки
• docs/platform/README.md — конспекты платформы (Markdown)
• docs/MCP_OPTIONAL_TOOLS.md — расширенный набор tools (AGGREGATE_MCP_EXTENDED_TOOLS)

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

aggregate_mcp/
├── docs/                    # Документация
│   ├── MCP_*.md            # Руководства по MCP
│   ├── AGGREGATE_*.md      # Руководства по AggreGate API
│   └── examples/           # Примеры кода
├── mcp-server/             # Основной модуль MCP сервера
├── modules/                # Дополнительные модули
├── build.gradle.kts        # Конфигурация сборки
└── README.md               # Этот файл

🔧 Сборка

# Сборка проекта
./gradlew build

# Запуск тестов
./gradlew test

# Создание JAR файла
./gradlew jar

📝 Основные возможности

MCP сервер предоставляет инструменты для:

• Подключение и аутентификация: подключение к серверу AggreGate, вход в систему
• Управление контекстами: создание, удаление, получение информации о контекстах
• Работа с переменными: создание, установка значений, получение описаний
• Работа с функциями: создание Expression/Query функций, тестирование, вызов
• Работа с событиями: создание и генерация событий
• Управление устройствами: создание, удаление, получение статуса устройств
• Управление пользователями: создание, обновление, удаление пользователей
• Работа с агентами: создание агентов, отправка событий
• Работа с виджетами и дашбордами: создание и настройка виджетов и дашбордов
• Работа с моделями: создание относительных, абсолютных и экземплярных моделей

🎯 Ключевые правила для ИИ

При работе с MCP сервером через ИИ важно следовать правилам:

1. ⚠️ ВСЕГДА используйте правильный контекст! - Тревоги создаются в alerts, а не в models! См. MCP_AGGREGATE_CONTEXTS_GUIDE.md
2. Всегда тестировать функции после создания - используйте aggregate_test_function
3. Получать описание переменных перед установкой - используйте aggregate_describe_variable
4. Проверять создание элементов - используйте aggregate_list_* функции
5. Использовать правильные форматы - для Expression функций используйте aggregate_build_expression
6. Создавать привязки для моделей - относительные модели требуют привязок с относительными ссылками

Подробнее: AI_WORKFLOW_RULES.md

📖 Дополнительные ресурсы

• Репозиторий проекта
• JavaDoc документация - автоматически сгенерированная документация API
• Справочник AggreGate - CHM файл (только для Windows)

⚙️ Требования

• Java 11 или выше
• AggreGate Server (для подключения)
• Cursor или другой AI-ассистент с поддержкой MCP

👤 Автор

Свиридов Михаил Юрьевич
LCC IoT Solutions

📄 Лицензия

Этот проект распространяется под лицензией MIT. Подробности см. в файле LICENSE.

MIT License - это разрешительная open source лицензия, которая позволяет свободно использовать, изменять, распространять и использовать программное обеспечение в коммерческих и некоммерческих целях, при условии сохранения уведомления об авторских правах и текста лицензии.

---

Версия: 1.0.0
Последнее обновление: 2025-01-27