ATLAS: Task Management System

ATLAS：任务管理系统

ATLAS（Adaptive Task & Logic Automation System，自适应任务与逻辑自动化系统）是面向大模型 Agent 的项目、知识和任务管理系统。

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

ATLAS 以 Model Context Protocol（MCP）服务的形式实现，允许大模型 Agent 与项目管理数据库交互，从而管理项目、任务和知识条目。

重要版本说明：Version 1.5.4 是最后一个使用 SQLite 作为数据库的版本。Version 2.0 及之后的版本已完全重写为使用 Neo4j，因此需要：

• 使用 Docker 自托管（仓库中包含 docker-compose）
• 使用 Neo4j AuraDB 云服务：https://neo4j.com/product/auradb/

Version 2.5.0 引入了新的 3 节点系统（项目、任务、知识），取代了先前的结构。

目录

• 概述
• 功能
• 安装
• 运行服务
• Web UI（实验性）
• 配置
• 项目结构
• 工具
• 资源
• 数据库备份与恢复
• 示例
• 许可证

概述

ATLAS 实现了 Model Context Protocol（MCP），通过以下组件实现大模型与外部系统之间的标准化通信：

• 客户端：Claude Desktop、IDE 及其他兼容 MCP 的客户端
• 服务：用于项目、任务和知识管理的工具与资源
• 大模型 Agent：利用服务管理功能的 AI 模型

系统集成

Atlas Platform 将这些组件整合为一个协调一致的系统：

• 项目-任务关系：项目包含代表实现项目目标所需行动步骤的任务。任务继承其所属项目的上下文，同时提供对各项工作的精细跟踪。
• 知识集成：项目和任务均可通过知识条目补充信息，为团队成员提供所需的信息和上下文。
• 依赖管理：项目和任务均支持依赖关系，支持包含前置条件和顺序执行要求的复杂工作流。
• 统一搜索：平台提供跨实体搜索功能，允许用户根据各种条件查找相关项目、任务或知识。

功能特性

功能领域	主要能力
项目管理	- 全面跟踪：管理项目元数据、状态和丰富内容（笔记、链接等），并内置批量操作支持。 - 依赖项与关系处理：自动验证并跟踪项目间依赖关系。
任务管理	- 任务生命周期管理：在任务的整个生命周期中创建、跟踪和更新任务。 - 优先级与分类：为任务分配优先级，并使用标签对任务分类，以便更好地组织。 - 依赖项跟踪：建立任务依赖关系，创建结构化工作流。
知识管理	- 结构化知识库：维护可搜索的项目相关信息知识库。 - 领域分类：按领域和标签组织知识，便于检索。 - 引用支持：跟踪知识条目的来源和参考资料。
图数据库集成	- 原生关系管理：利用 Neo4j 符合 ACID 标准的事务和优化查询，确保可靠的数据完整性。 - 高级搜索与可扩展性：执行基于属性的搜索，支持模糊匹配和通配符，同时保持高性能。
统一搜索	- 跨实体搜索：根据内容、元数据或关系查找相关项目、任务或知识。 - 灵活的查询选项：支持不区分大小写、模糊搜索和高级筛选选项。

安装

1. 克隆仓库：

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

2. 安装依赖项：

   npm install
   

3. 配置 Neo4j： 确保 Neo4j 实例正在运行且可以访问。你可以使用提供的 Docker 配置启动实例：

   docker-compose up -d
   

   使用 Neo4j 连接详情更新你的 .env 文件（参见配置）。

4. 构建项目：

   npm run build
   

运行服务

大多数 MCP 客户端会自动运行服务，但你也可以使用以下命令手动运行，以进行测试或开发。

ATLAS MCP Server 支持多种通信传输机制：

• **标准输入/输出（stdio）：**这是默认模式，通常用于与本地 MCP 客户端（如 IDE 扩展）直接集成。

  npm run start:stdio
  

  此模式使用 MCP_TRANSPORT_TYPE=stdio 设置。

• **可流式传输的 HTTP：**此模式允许服务通过 HTTP 监听 MCP 请求，适用于远程客户端或基于 Web 的集成。

  npm run start:http
  

  此模式使用 MCP_TRANSPORT_TYPE=http 设置。服务将在 .env 文件中定义的主机和端口上监听（例如 MCP_HTTP_HOST 和 MCP_HTTP_PORT，默认为 127.0.0.1:3010）。如果要从远程访问，请确保防火墙允许连接。

Web UI（实验性）

提供了一个基础的 Web UI，用于查看项目、任务和知识详情。

• 打开 UI：

  • 要直接在浏览器中打开 UI，请在终端中运行以下命令：

    npm run webui
    

• 功能：

  • 此处可以查看 Web UI 的示例截图。

配置

环境变量

在 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-inspector）可以使用项目根目录下的 mcp.json 文件来定义服务配置；请按需更新。

使用 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"
      }
    }
  }
}

使用 Streamable HTTP（配置示例）： 如果客户端支持通过 Streamable HTTP 连接到 MCP 服务，请在客户端配置中提供服务端点（例如 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 请始终使用绝对路径。客户端 env 块中的 MCP_AUTH_SECRET_KEY 仅为示例；客户端与服务之间的实际令牌处理方式取决于客户端的功能和服务的身份验证机制（例如，在 Authorization 标头中发送 JWT）。

项目结构

代码库采用模块化结构：

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_project_create	创建新项目（单个/批量）。	mode（'single'/'bulk'）、id（单个模式下可选的客户端生成 ID）、项目详情（name、description、status、urls、completionRequirements、dependencies、outputFormat、taskType）。批量模式下，使用 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（单个模式下使用）、updates 对象。批量模式下，使用 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（可选，由客户端生成的 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（单个模式下使用）、updates 对象。批量模式下，使用 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、assignedToUserId）、选项（caseInsensitive（默认值：true，用于正则表达式）、fuzzy（默认值：false，用于正则表达式的“contains”或全文 Lucene 模糊搜索））、分页（page、limit）、responseFormat（'formatted'/'json'，可选，默认值：'formatted'）。

研究运营

工具名称	描述	关键参数
atlas_deep_research	通过在 Atlas 知识库中创建分层计划，启动结构化的深度研究流程。	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 文件中。还会创建一个包含所有数据的 full-export.json。
• 输出：每次备份都会在配置的备份路径（默认值：./atlas-backups/）下创建一个带时间戳的目录（例如 atlas-backup-YYYYMMDDHHMMSS）。该目录包含 projects.json、tasks.json、knowledge.json、relationships.json 和 full-export.json。
• 手动备份：可以使用提供的脚本触发手动备份：

  npm run db:backup
  

  此命令会执行 src/services/neo4j/backupRestoreService/scripts/db-backup.ts，该脚本会调用 exportDatabase 函数。

恢复流程

• 机制：恢复流程会先彻底清空现有的 Neo4j 数据库，然后从指定备份目录中的 JSON 文件导入节点和关系。如果存在 full-export.json，则优先使用该文件。
• 警告：从备份恢复属于破坏性操作。这会覆盖 Neo4j 数据库中的所有当前数据。
• 手动恢复：如需从备份目录恢复数据库，请使用导入脚本：

  npm run db:import <path_to_backup_directory>
  

  将 <path_to_backup_directory> 替换为备份文件夹的实际路径（例如 ./atlas-backups/atlas-backup-20250326120000）。此命令会执行 src/services/neo4j/backupRestoreService/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。

许可证

Apache License 2.0

---