ATLAS: 任务管理系统

ATLAS（自适应任务和逻辑自动化系统）是一个面向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实现了Model Context Protocol (MCP)，通过以下方式使LLM与外部系统之间的通信标准化：

• 客户端：Claude Desktop、IDE和其他兼容MCP的客户端
• 服务器：用于项目、任务和知识管理的工具和资源
• LLM代理：利用服务器管理能力的人工智能模型

系统集成

Atlas平台将这些组件整合成一个统一的系统：

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

特性

项目管理

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

任务管理

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

知识管理

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

图数据库集成

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

统一搜索

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

安装

1. 克隆仓库：

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

1. 安装依赖项：

npm install

1. 配置Neo4j：

# Start Neo4j using Docker
docker-compose up -d

1. 构建项目：

npm run build

配置

环境变量

根据.env.example创建一个.env文件：

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

# Application Configuration
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/          # 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 (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', 可选)。

知识操作

请注意，翻译中保持了原始的 Markdown 格式，并且代码块和链接内容没有进行更改。

工具名称	描述	关键参数
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. 分叉仓库
2. 创建特性分支
3. 使用描述性信息提交您的更改
4. 推送到该分支
5. 创建拉取请求

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

许可证

Apache License 2.0

---