atlas-mcp-сервер

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

ATLAS (Adaptive Task & Logic Automation System) — это система управления проектами, знаниями и задачами для агентов LLM.

Построен на основе трехуровневой архитектуры:

                  +------------------------------------------+
                  |                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                | |                                  |
+----------------------------------+ +----------------------------------+

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

Важное примечание к версии : версия 1.5.4 — последняя версия, которая использует SQLite в качестве базы данных. Версия 2.0 и последующие полностью переписаны для использования Neo4j, что требует либо:
Самостоятельное размещение с использованием Docker (docker-compose включен в репозиторий)
Использование облачного сервиса Neo4j AuraDB: https://neo4j.com/product/auradb/
В версии 2.5.0 представлена новая система из трех узлов (Проекты, Задачи, Знания), которая заменяет предыдущую структуру.

Обзор

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

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

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

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

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

Функции

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

Комплексное отслеживание: управляйте метаданными проекта, статусами и расширенным контентом (заметками, ссылками и т. д.) с помощью встроенной поддержки массовых операций.
Обработка зависимостей и отношений: автоматическая проверка и отслеживание межпроектных зависимостей.

Управление задачами

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

Управление знаниями

Структурированное хранилище знаний: поддерживайте доступное для поиска хранилище информации, связанной с проектом.
Категоризация доменов: организация знаний по доменам и тегам для удобства поиска.
Поддержка цитирования: отслеживайте источники и ссылки на элементы знаний.

Интеграция графической базы данных

Встроенное управление отношениями: используйте ACID-совместимые транзакции Neo4j и оптимизированные запросы для надежной целостности данных.
Расширенный поиск и масштабируемость: выполняйте поиск по свойствам с использованием нечеткого соответствия и подстановочных знаков, сохраняя при этом высокую производительность.

Единый поиск

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

Установка

Клонируйте репозиторий:
git clone https://github.com/cyanheads/atlas-mcp-server.git cd atlas-mcp-server
Установить зависимости:
npm install
Настройте Neo4j: Убедитесь, что у вас есть запущенный и доступный экземпляр Neo4j. Вы можете запустить его, используя предоставленную конфигурацию Docker:
docker-compose up -d
Обновите файл .env , указав сведения о подключении Neo4j (см. Конфигурация ).
Создайте проект:
npm run build

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

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

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

Стандартный ввод-вывод (stdio): это режим по умолчанию, который обычно используется для прямой интеграции с локальными клиентами MCP (например, расширениями IDE).
npm run start:stdio
Здесь используется настройка MCP_TRANSPORT_TYPE=stdio .
Потоковый HTTP: этот режим позволяет серверу прослушивать запросы MCP по протоколу HTTP, подходит для удаленных клиентов или веб-интеграций.
npm run start:http
Это использует настройку MCP_TRANSPORT_TYPE=http . Сервер будет прослушивать хост и порт, указанные в вашем файле .env (например, MCP_HTTP_HOST и MCP_HTTP_PORT , по умолчанию 127.0.0.1:3010 ). Убедитесь, что ваш брандмауэр разрешает подключения при удаленном доступе.

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

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

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

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

# Application Configuration
LOG_LEVEL=info # Log level for the server (corresponds to MCP_LOG_LEVEL). Options: emerg, alert, crit, error, warning, notice, info, debug.
NODE_ENV=development # 'development' or 'production'.

# 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 for JWT authentication if HTTP transport is used.
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: ./backups.

Все доступные переменные среды и их значения по умолчанию см. в src/config/index.ts

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

Способ настройки клиента MCP зависит от самого клиента и выбранного типа транспорта.

Для Stdio Transport: как правило, вы настраиваете клиент для выполнения стартового скрипта сервера.

{
  "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",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

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

Если ваш клиент запускает сервер для режима HTTP:

{
  "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",
        "LOG_LEVEL": "info",
        "NODE_ENV": "production",
        "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 предоставляет комплексный набор инструментов для управления проектами, задачами и знаниями, вызываемых через протокол контекста модели.

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

Название инструмента	Описание	Ключевые аргументы
`atlas_project_create`	Создает новые проекты (отдельные/групповые).	`mode` ('single'/'bulk'), `id` (необязательный идентификатор, сгенерированный клиентом для single mode), сведения о проекте ( `name` , `description` , `status` , `urls` , `completionRequirements` , `dependencies` , `outputFormat` , `taskType` ). Для bulk mode используйте `projects` (массив объектов проекта). `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').
`atlas_project_list`	Список проектов (все/подробно).	`mode` ('all'/'details', по умолчанию: 'all'), `id` (для подробного режима), фильтры ( `status` , `taskType` ), пагинация ( `page` , `limit` ), включает ( `includeKnowledge` , `includeTasks` ), `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').
`atlas_project_update`	Обновляет существующие проекты (отдельные/массовые).	`mode` ('single'/'bulk'), `id` (для single mode), `updates` объект. Для bulk mode используйте `projects` (массив объектов, каждый с `id` и `updates` ). `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').
`atlas_project_delete`	Удаляет проекты (отдельные/массово).	`mode` («single»/«bulk»), `id` (для одиночного режима) или `projectIds` (массив для массового режима). `responseFormat` («formatted»/«json», необязательно, по умолчанию: «formatted»).

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

Название инструмента	Описание	Ключевые аргументы
`atlas_task_create`	Создает новые задачи (одиночные/групповые).	`mode` ('single'/'bulk'), `id` (необязательно, сгенерированный клиентом идентификатор), `projectId` , сведения о задаче ( `title` , `description` , `priority` , `status` , `assignedTo` , `urls` , `tags` , `completionRequirements` , `dependencies` , `outputFormat` , `taskType` ). Для массового режима используйте `tasks` (массив объектов задач). `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').
`atlas_task_update`	Обновляет существующие задачи (отдельные/массовые).	`mode` ('single'/'bulk'), `id` (для single mode), `updates` object. Для bulk mode используйте `tasks` (массив объектов, каждый с `id` и `updates` ). `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').
`atlas_task_delete`	Удаляет задачи (отдельные/групповые).	`mode` («single»/«bulk»), `id` (для одиночного режима) или `taskIds` (массив для массового режима). `responseFormat` («formatted»/«json», необязательно, по умолчанию: «formatted»).
`atlas_task_list`	Перечисляет задачи для конкретного проекта.	`projectId` (обязательно), фильтры ( `status` , `assignedTo` , `priority` , `tags` , `taskType` ), сортировка ( `sortBy` , `sortDirection` ), разбиение на страницы ( `page` , `limit` ), `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').

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

Название инструмента	Описание	Ключевые аргументы
`atlas_knowledge_add`	Добавляет новые элементы знаний (отдельные/групповые).	`mode` ('single'/'bulk'), `id` (необязательно, сгенерированный клиентом ID), `projectId` , сведения о знаниях ( `text` , `tags` , `domain` , `citations` ). Для массового режима используйте `knowledge` (массив объектов знаний). `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').
`atlas_knowledge_delete`	Удаляет элементы знаний (отдельные/групповые).	`mode` («single»/«bulk»), `id` (для одиночного режима) или `knowledgeIds` (массив для массового режима). `responseFormat` («formatted»/«json», необязательно, по умолчанию: «formatted»).
`atlas_knowledge_list`	Перечисляет элементы знаний для конкретного проекта.	`projectId` (обязательно), фильтры ( `tags` , `domain` , `search` ), пагинация ( `page` , `limit` ), `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').

Поисковые операции

Название инструмента	Описание	Ключевые аргументы
`atlas_unified_search`	Выполняет унифицированный поиск по всем сущностям.	`value` (поисковый запрос, обязательно), `property` (необязательно), фильтры ( `entityTypes` , `taskType` ), параметры ( `caseInsensitive` (по умолчанию: true), `fuzzy` (по умолчанию: false)), пагинация ( `page` , `limit` ), `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').

Научно-исследовательские работы

Название инструмента	Описание	Ключевые аргументы
`atlas_deep_research`	Инициирует структурированный глубокий процесс исследования путем создания иерархического плана в базе знаний Атласа.	`projectId` (обязательно), `researchTopic` (обязательно), `researchGoal` (обязательно), `scopeDefinition` (необязательно), `subTopics` (обязательный массив объектов, каждый с `question` (обязательно), `initialSearchQueries` (необязательный массив), `nodeId` (необязательно), `priority` (необязательно), `assignedTo` (необязательно), `initialStatus` (необязательно, по умолчанию: 'todo')), `researchDomain` (необязательно), `initialTags` (необязательно), `planNodeId` (необязательно), `createTasks` (необязательно, по умолчанию: true), `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').

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

Название инструмента	Описание	Ключевые аргументы
`atlas_database_clean`	Разрушительный: полностью сбрасывает базу данных, удаляя все проекты, задачи и знания.	`acknowledgement` (должно быть установлено значение `true` для подтверждения, обязательно), `responseFormat` ('formatted'/'json', необязательно, по умолчанию: 'formatted').

Ресурсы

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

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

Имя ресурса	Описание
`atlas://projects`	Список всех проектов на платформе Atlas с поддержкой пагинации.
`atlas://tasks`	Список всех задач на платформе Atlas с поддержкой пагинации и фильтрации.
`atlas://knowledge`	Список всех элементов знаний на платформе Atlas с поддержкой пагинации и фильтрации.

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

Имя ресурса	Описание
`atlas://projects/{projectId}`	Извлекает один проект по его уникальному идентификатору ( `projectId` ).
`atlas://tasks/{taskId}`	Извлекает одну задачу по ее уникальному идентификатору ( `taskId` ).
`atlas://projects/{projectId}/tasks`	Извлекает все задачи, относящиеся к определенному проекту ( `projectId` ).
`atlas://knowledge/{knowledgeId}`	Извлекает отдельный элемент знаний по его уникальному идентификатору ( `knowledgeId` ).
`atlas://projects/{projectId}/knowledge`	Извлекает все элементы знаний, относящиеся к определенному проекту ( `projectId` ).

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

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

Автоматическое резервное копирование (Примечание)

Важно: Автоматическая функция резервного копирования была удалена из-за неэффективности. Пожалуйста, используйте ручной процесс резервного копирования, описанный ниже, чтобы защитить ваши данные.

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

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

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

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

Примеры

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

Пример резервного копирования : Расположенный в 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

Integrations