ATLAS: Система управления задачами

ATLAS (Адаптивная система автоматизации задач и логики) — это система управления проектами, знаниями и задачами для агентов LLM.

Построена на 3-узловой архитектуре:

                  +-------------------------------------------+

                  |                PROJECT                    |
                  |-------------------------------------------|
                  | id: string                                |
                  | name: string                              |
                  | description: string                       |
                  | status: string                            |
                  | urls?: Array<{title: string, url: string}>|
                  | completionRequirements: string            |
                  | outputFormat: string                      |
                  | taskType: string                          |
                  | createdAt: string                         |
                  | updatedAt: string                         |
                  +----------------+--------------------------+

                            |                    |
                            |                    |
                            v                    v
+----------------------------------+ +----------------------------------+

|               TASK               | |            KNOWLEDGE             |
|----------------------------------| |----------------------------------|
| id: string                       | | id: string                       |
| projectId: string                | | projectId: string                |
| title: string                    | | text: string                     |
| description: string              | | tags?: string[]                  |
| priority: string                 | | domain: string                   |
| status: string                   | | citations?: string[]             |
| assignedTo?: string              | | createdAt: string                |
| urls?: Array<{title: string,     | |                                  |
|   url: string}>                  | | updatedAt: string                |
| tags?: string[]                  | |                                  |
| completionRequirements: string   | |                                  |
| outputFormat: string             | |                                  |
| taskType: string                 | |                                  |
| createdAt: string                | |                                  |
| updatedAt: string                | |                                  |
+----------------------------------+ +----------------------------------+

Реализован как сервер Протокола Контекста Моделей (MCP), ATLAS позволяет агентам LLM взаимодействовать с базой данных управления проектами, давая им возможность управлять проектами, задачами и элементами знаний.

Важное примечание о версии: Версия 1.5.4 — последняя версия, использующая SQLite в качестве базы данных. Версия 2.0 и выше полностью переписана для использования Neo4j, что требует либо:

• Самостоятельного развертывания с использованием Docker (файл docker-compose включен в репозиторий)
• Использования облачного сервиса Neo4j AuraDB: https://neo4j.com/product/auradb/

Версия 2.5.0 вводит новую 3-узловую систему (Проекты, Задачи, Знания), которая заменяет предыдущую структуру.

Содержание

• Обзор
• Возможности
• Установка
• Запуск сервера
• Веб-интерфейс (экспериментальный)
• Конфигурация
• Структура проекта
• Инструменты
• Ресурсы
• Резервное копирование и восстановление базы данных
• Примеры
• Лицензия

Обзор

ATLAS реализует Протокол Контекста Моделей (MCP), обеспечивая стандартизированную коммуникацию между LLM и внешними системами через:

• Клиенты: Claude Desktop, IDE и другие совместимые с MCP клиенты.
• Серверы: Инструменты и ресурсы для управления проектами, задачами и знаниями.
• Агенты LLM: AI-модели, использующие возможности управления сервера.

Интеграция систем

Платформа Atlas интегрирует эти компоненты в единую систему:

• Связь Проект-Задача: Проекты содержат задачи, представляющие конкретные шаги для достижения целей проекта. Задачи наследуют контекст от родительского проекта, обеспечивая детализированное отслеживание отдельных элементов работы.
• Интеграция знаний: И проекты, и задачи могут быть обогащены элементами знаний, предоставляя участникам необходимую информацию и контекст.
• Управление зависимостями: Как проекты, так и задачи поддерживают отношения зависимостей, позволяя создавать сложные рабочие процессы с предварительными требованиями и последовательным выполнением.
• Единый поиск: Платформа предоставляет возможности поиска по сущностям, позволяя пользователям находить соответствующие проекты, задачи или знания по различным критериям.

Возможности

Установка

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

   bash git clone https://github.com/cyanheads/atlas-mcp-server.git cd atlas-mcp-server

2. Установите зависимости:

   bash npm install

3. Настройте Neo4j: Убедитесь, что экземпляр Neo4j запущен и доступен. Вы можете запустить его, используя предоставленную конфигурацию Docker:

   bash docker-compose up -d

   Обновите ваш файл .env с данными для подключения к Neo4j (см. Конфигурация).

4. Соберите проект: bash npm run build

Запуск сервера

Большинство MCP-клиентов запускают сервер автоматически, но вы также можете запустить его вручную для тестирования или целей разработки, используя следующие команды.

ATLAS MCP Server поддерживает несколько транспортных механизмов для коммуникации:

• Стандартный ввод-вывод (stdio): Это режим по умолчанию, обычно используемый для прямой интеграции с локальными MCP-клиентами (например, расширениями IDE).

bash npm run start:stdio

Используется настройка MCP_TRANSPORT_TYPE=stdio.

• Потоковый HTTP: Этот режим позволяет серверу прослушивать MCP-запросы по HTTP, что подходит для удаленных клиентов или веб-интеграций.

bash npm run start:http

Используется настройка MCP_TRANSPORT_TYPE=http. Сервер будет слушать на хосте и порту, определенных в вашем файле .env (например, MCP_HTTP_HOST и MCP_HTTP_PORT, по умолчанию 127.0.0.1:3010). Убедитесь, что ваш межсетевой экран разрешает подключения при удаленном доступе.

Веб-интерфейс (экспериментальный)

Доступен базовый веб-интерфейс для просмотра деталей Проектов, Задач и Знаний.

• Открытие интерфейса:

• Чтобы открыть интерфейс прямо в вашем браузере, выполните следующую команду в вашем терминале: bash npm run webui

• Функциональность:

• Пример скриншота веб-интерфейса можно посмотреть здесь.

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

Переменные окружения

Переменные окружения должны быть установлены в конфигурации клиента в вашем MCP-клиенте или в файле .env в корне проекта для локальной разработки.

# Neo4j Configuration
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password2

# Application Configuration
MCP_LOG_LEVEL=debug # Minimum logging level. Options: emerg, alert, crit, error, warning, notice, info, debug. Default: "debug".
LOGS_DIR=./logs # Directory for log files. Default: "./logs" in project root.
NODE_ENV=development # 'development' or 'production'. Default: "development".

# MCP Transport Configuration
MCP_TRANSPORT_TYPE=stdio # 'stdio' or 'http'. Default: "stdio".
MCP_HTTP_HOST=127.0.0.1 # Host for HTTP transport. Default: "127.0.0.1".
MCP_HTTP_PORT=3010 # Port for HTTP transport. Default: 3010.
# MCP_ALLOWED_ORIGINS=http://localhost:someport,https://your-client.com # Optional: Comma-separated list of allowed origins for HTTP CORS.

# MCP Security Configuration
# MCP_AUTH_SECRET_KEY=your_very_long_and_secure_secret_key_min_32_chars # Optional: Secret key (min 32 chars) for JWT authentication if HTTP transport is used. CRITICAL for production. *Note: Production environment use has not been tested yet.*
MCP_RATE_LIMIT_WINDOW_MS=60000 # Rate limit window in milliseconds. Default: 60000 (1 minute).
MCP_RATE_LIMIT_MAX_REQUESTS=100 # Max requests per window per IP for HTTP transport. Default: 100.

# Database Backup Configuration
BACKUP_MAX_COUNT=10 # Maximum number of backup sets to keep. Default: 10.
BACKUP_FILE_DIR=./atlas-backups # Directory where backup files will be stored (relative to project root). Default: "./atlas-backups".

Ссылка на src/config/index.ts для получения информации обо всех доступных переменных окружения, их описаниях и значениях по умолчанию.

Настройки MCP-клиента

Способ настройки вашего MCP-клиента зависит от самого клиента и выбранного типа транспорта. Файл mcp.json в корне проекта может использоваться некоторыми клиентами (например, mcp-inspector) для определения конфигураций сервера; обновите его при необходимости.

Для Stdio-транспорта (пример конфигурации):

{
  "mcpServers": {
    "atlas-mcp-server-stdio": {
      "command": "node",
      "args": ["/full/path/to/atlas-mcp-server/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password2",
        "MCP_LOG_LEVEL": "info",
        "NODE_ENV": "development",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Для потокового HTTP (пример конфигурации): Если ваш клиент поддерживает подключение к MCP-серверу через потоковый HTTP, вы указываете конечную точку сервера (например, http://localhost:3010/mcp) в конфигурации вашего клиента.

{
  "mcpServers": {
    "atlas-mcp-server-http": {
      "command": "node",
      "args": ["/full/path/to/atlas-mcp-server/dist/index.js"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "password2",
        "MCP_LOG_LEVEL": "info",
        "NODE_ENV": "development",
        "MCP_TRANSPORT_TYPE": "http",
        "MCP_HTTP_PORT": "3010",
        "MCP_HTTP_HOST": "127.0.0.1"
        // "MCP_AUTH_SECRET_KEY": "your-secure-token" // If authentication is enabled on the server
      }
    }
  }
}

Примечание: Всегда используйте абсолютные пути для args при настройке команд клиента, если сервер не находится в непосредственной рабочей директории клиента. MCP_AUTH_SECRET_KEY в блоке env клиента является иллюстративным; фактическая обработка токенов для коммуникации от клиента к серверу будет зависеть от возможностей клиента и механизма аутентификации сервера (например, отправка JWT в заголовке Authorization).

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

Базовая структура кода следует модульному подходу:

src/
├── config/          # Configuration management (index.ts)
├── index.ts         # Main server entry point
├── mcp/             # MCP server implementation (server.ts)
│   ├── resources/   # MCP resource handlers (index.ts, types.ts, knowledge/, projects/, tasks/)
│   └── tools/       # MCP tool handlers (individual tool directories)
├── services/        # Core application services
│   └── neo4j/       # Neo4j database services (index.ts, driver.ts, backupRestoreService.ts, etc.)
├── types/           # Shared TypeScript type definitions (errors.ts, mcp.ts, tool.ts)
└── utils/           # Utility functions and internal services (e.g., logger, errorHandler, sanitization)

Инструменты

ATLAS предоставляет комплексный набор инструментов для управления проектами, задачами и знаниями, доступных для вызова через протокол Model Context Protocol.

Операции с проектами

Операции с задачами

Операции со знаниями

Операции поиска

Исследовательские операции

Операции с базой данных

Ресурсы

ATLAS предоставляет доступ к данным о проектах, задачах и знаниях через стандартные конечные точки ресурсов MCP.

Прямые ресурсы

Шаблоны ресурсов

Резервное копирование и восстановление базы данных

ATLAS предоставляет функциональность резервного копирования и восстановления содержимого базы данных Neo4j. Основная логика находится в src/services/neo4j/backupRestoreService.ts.

Процесс резервного копирования

• Механизм: Процесс резервного копирования экспортирует все узлы Project, Task и Knowledge вместе со связями в отдельные JSON-файлы. Также создаётся файл full-export.json, содержащий все данные.
• Выходные данные: Каждое резервное копирование создаёт каталог с временной меткой (например, atlas-backup-YYYYMMDDHHMMSS) в настроенном пути для резервных копий (по умолчанию: ./atlas-backups/). Этот каталог содержит файлы projects.json, tasks.json, knowledge.json, relationships.json и full-export.json.
• Ручное резервное копирование: Вы можете запустить ручное резервное копирование с помощью предоставленного скрипта: bash npm run db:backup Эта команда выполняет src/services/neo4j/backupRestoreService/scripts/db-backup.ts, который вызывает функцию exportDatabase.

Процесс восстановления

• Механизм: Процесс восстановления сначала полностью очищает существующую базу данных Neo4j. Затем он импортирует узлы и связи из JSON-файлов, расположенных в указанном каталоге резервной копии. Приоритет отдаётся файлу full-export.json, если он доступен.
• Предупреждение: Восстановление из резервной копии является деструктивной операцией. Оно перезапишет все текущие данные в вашей базе данных Neo4j.
• Ручное восстановление: Чтобы восстановить базу данных из каталога резервной копии, используйте скрипт импорта: bash npm run db:import <путь_к_каталогу_резервной_копии> Замените <путь_к_каталогу_резервной_копии> на фактический путь к папке резервной копии (например, ./atlas-backups/atlas-backup-20250326120000). Эта команда выполняет src/services/neo4j/backupRestoreService/scripts/db-import.ts, который вызывает функцию importDatabase.
• Обработка связей: Процесс импорта пытается воссоздать связи на основе свойств id, сохранённых в узлах при экспорте. Убедитесь, что ваши узлы имеют согласованные свойства id для корректного восстановления связей.

Примеры

Каталог examples/ содержит практические примеры, демонстрирующие различные функции ATLAS MCP Server.

• Пример резервного копирования: Расположен в examples/backup-example/, показывает структуру и формат JSON-файлов, генерируемых командой npm run db:backup. Подробности смотрите в README примеров.
• Пример глубокого исследования: Расположен в examples/deep-research-example/, демонстрирует вывод и структуру, генерируемые инструментом atlas_deep_research. Включает markdown-файл (covington_community_grant_research.md) с описанием плана исследования и JSON-файл (full-export.json) с сырыми данными, экспортированными из базы данных после создания плана исследования. Подробности смотрите в README примеров.

Лицензия

Лицензия Apache 2.0

Создано с использованием Model Context Protocol