ATLAS：任务管理系统

ATLAS (自适应任务与逻辑自动化系统) 是一个用于 LLM Agent 的任务管理系统。

构建于三层架构之上：

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

ATLAS 作为模型上下文协议 (MCP) 服务器实现，允许 LLM Agent 与项目管理数据库交互，从而能够管理项目、任务和知识条目。

重要版本说明：Version 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 Agent：利用服务器管理能力的人工智能模型

系统集成

Atlas 平台将这些组件集成到一个有凝聚力的系统中：

• 项目-任务关系：项目包含代表实现项目目标所需的可操作步骤的任务。任务继承其父项目的上下文，同时提供对单个工作项的精细跟踪。
• 知识集成：项目和任务都可以通过知识条目来丰富，从而为团队成员提供必要的信息和上下文。
• 依赖管理：项目和任务都支持依赖关系，从而可以实现具有先决条件和顺序执行要求的复杂工作流程。
• 统一搜索：该平台提供跨实体搜索功能，允许用户根据各种条件查找相关的项目、任务或知识。

特性

项目管理

• 全面跟踪： 管理项目元数据、状态和富内容（注释、链接等），并内置对批量操作的支持。
• 依赖关系处理： 自动验证和跟踪项目间的依赖关系。

任务管理

• 任务生命周期管理： 创建、跟踪和更新任务的整个生命周期。
• 优先级和分类： 分配优先级并使用标签对任务进行分类，以实现更好的组织。
• 依赖关系跟踪： 建立任务依赖关系以创建结构化的工作流程。

知识管理

• 结构化知识库： 维护项目相关信息的可搜索存储库。
• 领域分类： 按领域和标签组织知识，以便于检索。
• 引用支持： 跟踪知识条目的来源和参考。

图数据库集成

• 原生关系管理： 利用 Neo4j 的 ACID 兼容事务和优化的查询来确保强大的数据完整性。
• 高级搜索和可扩展性： 执行基于属性的搜索，具有模糊匹配和通配符，同时保持高性能。

统一搜索

• 跨实体搜索： 根据内容、元数据或关系查找相关的项目、任务或知识。
• 灵活的查询选项： 支持不区分大小写、模糊和高级过滤选项。

安装

1. 克隆存储库：

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

2. 安装依赖项：

npm install

3. 配置 Neo4j：

# 使用 Docker 启动 Neo4j
docker-compose up -d

4. 构建项目：

npm run build

配置

环境变量

基于 .env.example 创建一个 .env 文件：

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

# 应用程序配置
LOG_LEVEL=info # debug, info, warn, error
NODE_ENV=development # development, production

MCP 客户端设置

添加到您的 MCP 客户端设置：

{
  "mcpServers": {
    "atlas": {
      "command": "node",
      "args": ["/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"
      }
    }
  }
}

项目结构

代码库遵循模块化结构：

src/
├── config/          # 配置管理 (index.ts)
├── index.ts         # 主服务器入口点
├── mcp/             # MCP 服务器实现 (server.ts)
│   ├── resources/   # MCP 资源处理程序 (index.ts, types.ts, knowledge/, projects/, tasks/)
│   └── tools/       # MCP 工具处理程序 (各个工具目录)
├── services/        # 核心应用程序服务
│   └── neo4j/       # Neo4j 数据库服务 (index.ts, driver.ts, backupRestoreService.ts, etc.)
├── types/           # 共享 TypeScript 类型定义 (errors.ts, mcp.ts, tool.ts)
└── utils/           # 实用程序函数 (logger.ts, errorHandler.ts, etc.)

注意：ID 生成逻辑主要位于 src/services/neo4j/helpers.ts 中。

工具

ATLAS 提供了一套全面的工具，用于项目、任务和知识管理，可通过模型上下文协议调用。

项目操作

工具名称	描述	主要参数
atlas_project_create	创建新项目（单个/批量）。	mode ('single'/'bulk')，项目详细信息（name、description、status、urls、completionRequirements、dependencies、outputFormat、taskType），responseFormat ('formatted'/'json', 可选）。
atlas_project_list	列出项目（全部/详细信息）。	mode ('all'/'details')，id（用于详细信息），过滤器（status、taskType），分页（page、limit），包含（includeKnowledge、includeTasks），responseFormat ('formatted'/'json', 可选）。
atlas_project_update	更新现有项目（单个/批量）。	mode ('single'/'bulk')，id，updates 对象，responseFormat ('formatted'/'json', 可选）。批量模式使用 projects 数组。
atlas_project_delete	删除项目（单个/批量）。	mode ('single'/'bulk')，id（单个）或 projectIds 数组（批量），responseFormat ('formatted'/'json', 可选）。

任务操作

工具名称	描述	主要参数
atlas_task_create	创建新任务（单个/批量）。	mode ('single'/'bulk')，projectId，任务详细信息（title、description、priority、status、assignedTo、tags、completionRequirements、dependencies、outputFormat、taskType），responseFormat ('formatted'/'json', 可选）。
atlas_task_update	更新现有任务（单个/批量）。	mode ('single'/'bulk')，id，updates 对象，responseFormat ('formatted'/'json', 可选）。批量模式使用 tasks 数组。
atlas_task_delete	删除任务（单个/批量）。	mode ('single'/'bulk')，id（单个）或 taskIds 数组（批量），responseFormat ('formatted'/'json', 可选）。
atlas_task_list	列出特定项目的任务。	projectId（必需），过滤器（status、assignedTo、priority、tags、taskType），排序（sortBy、sortDirection），分页（page、limit），responseFormat ('formatted'/'json', 可选）。

知识操作

工具名称	描述	主要参数
atlas_knowledge_add	添加新知识条目（单个/批量）。	mode ('single'/'bulk')，projectId，知识详细信息（text、tags、domain、citations），responseFormat ('formatted'/'json', 可选）。批量模式使用 knowledge 数组。
atlas_knowledge_delete	删除知识条目（单个/批量）。	mode ('single'/'bulk')，id（单个）或 knowledgeIds 数组（批量），responseFormat ('formatted'/'json', 可选）。
atlas_knowledge_list	列出特定项目的知识条目。	projectId（必需），过滤器（tags、domain、search），分页（page、limit），responseFormat ('formatted'/'json', 可选）。

搜索操作

工具名称	描述	主要参数
atlas_unified_search	执行跨实体的统一搜索。	value（搜索词），property（可选），过滤器（entityTypes、taskType），选项（caseInsensitive、fuzzy），分页（page、limit），responseFormat ('formatted'/'json', 可选）。

研究操作

工具名称	描述	主要参数
atlas_deep_research	通过在 Atlas 知识库中创建一个分层计划来启动结构化的深度研究过程。	projectId（必需），researchTopic（必需），researchGoal（必需），scopeDefinition（可选），subTopics（包含问题和搜索查询的必需数组），researchDomain（可选），initialTags（可选），planNodeId（可选），responseFormat（可选）。

数据库操作

工具名称	描述	主要参数
atlas_database_clean	破坏性： 完全重置数据库，删除所有项目、任务和知识。	acknowledgement（必须设置为 true 才能确认），responseFormat ('formatted'/'json', 可选）。

资源

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 中。

自动备份（注意）

重要提示： 由于效率低下，自动备份功能已被删除。src/services/neo4j/driver.ts 中对 triggerBackgroundBackup 的调用已注释掉，并附有说明已删除的注释。请使用下面描述的手动备份过程来保护您的数据。

备份过程

• 机制： 备份过程将所有 Project、Task 和 Knowledge 节点及其关系导出到单独的 JSON 文件中。
• 输出： 每次备份都会在配置的备份路径（默认：./atlas-backups/）中创建一个带时间戳的目录（例如，atlas-backup-YYYYMMDDHHMMSS）。此目录包含 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> 替换为备份文件夹的实际路径（例如，./atlas-backups/atlas-backup-20250326120000）。此命令执行 scripts/db-import.ts，该脚本调用 importDatabase 函数。
• 关系处理： 导入过程尝试根据导出期间存储在节点中的 id 属性重新创建关系。确保您的节点具有一致的 id 属性，以便正确恢复关系。

示例

examples/ 目录包含演示 ATLAS MCP 服务器各种功能的实用示例。

• 备份示例： 位于 examples/backup-example/ 中，这显示了 npm run db:backup 命令生成的 JSON 文件的结构和格式。有关更多详细信息，请参见 示例 README。
• 深度研究示例： 位于 examples/deep-research-example/ 中，这演示了 atlas_deep_research 工具生成的输出和结构。它包括一个 markdown 文件 (covington_community_grant_research.md)，总结了研究计划，以及一个 JSON 文件 (full-export.json)，其中包含从创建研究计划后从数据库导出的原始数据。有关更多详细信息，请参见 示例 README。

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 使用描述性消息提交您的更改
4. 推送到分支
5. 创建一个 Pull Request

对于错误和功能请求，请创建一个 issue。

许可证

Apache License 2.0

---

<div align="center"> 使用模型上下文协议构建 </div>