ATLAS: 任务管理系统

ATLAS（自适应任务与逻辑自动化系统）是一个为LLM（大型语言模型）代理设计的项目、知识和任务管理系统。

基于三节点架构构建：

                  +-------------------------------------------+
                  |                项目                      |
                  |-------------------------------------------|
                  | id: 字符串                               |
                  | name: 字符串                             |
                  | description: 字符串                      |
                  | status: 字符串                           |
                  | urls?: 数组<{title: 字符串, url: 字符串}>|
                  | completionRequirements: 字符串           |
                  | outputFormat: 字符串                      |
                  | taskType: 字符串                         |
                  | createdAt: 字符串                        |
                  | updatedAt: 字符串                        |
                  +----------------+--------------------------+
                            |                    |
                            |                    |
                            v                    v
+----------------------------------+ +----------------------------------+
|               任务               | |             知识                  |
|----------------------------------| |----------------------------------|
| id: 字符串                       | | id: 字符串                       |
| projectId: 字符串                | | projectId: 字符串                |
| title: 字符串                    | | text: 字符串                     |
| description: 字符串              | | tags?: 字符串数组                |
| priority: 字符串                 | | domain: 字符串                   |
| status: 字符串                   | | citations?: 字符串数组           |
| assignedTo?: 字符串              | | createdAt: 字符串                |
| urls?: 数组<{title: 字符串,     | |                                  |
|   url: 字符串}>                  | | updatedAt: 字符串                |
| tags?: 字符串数组                | |                                  |
| completionRequirements: 字符串   | |                                  |
| outputFormat: 字符串             | |                                  |
| taskType: 字符串                 | |                                  |
| createdAt: 字符串                | |                                  |
| updatedAt: 字符串                | |                                  |
+----------------------------------+ +----------------------------------+

ATLAS作为模型上下文协议（MCP）服务器实现，允许LLM代理与项目管理数据库进行交互，从而管理项目、任务和知识项。

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

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

2.5.0版本引入了一个新的三节点系统（项目、任务、知识），取代了之前的结构。

目录

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

概述

ATLAS实现了模型上下文协议（MCP），通过以下方式实现LLM与外部系统之间的标准化通信：

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

系统集成

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

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

功能

安装

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
   

   在.env文件中更新Neo4j连接信息（参见配置）。

4. 构建项目：

   npm run build
   

运行服务器

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

ATLAS MCP服务器支持多种通信传输机制：

• 标准I/O（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的示例截图here。

配置

环境变量

环境变量应在MCP客户端的配置中设置，或在项目根目录的.env文件中进行本地开发。

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

# 应用配置
MCP_LOG_LEVEL=debug # 最小日志级别。选项：emerg, alert, crit, error, warning, notice, info, debug。默认："debug"。
LOGS_DIR=./logs # 日志文件目录。默认：项目根目录下的"./logs"。
NODE_ENV=development # 'development' 或 'production'。默认："development"。

# MCP传输配置
MCP_TRANSPORT_TYPE=stdio # 'stdio' 或 'http'。默认："stdio"。
MCP_HTTP_HOST=127.0.0.1 # HTTP传输的主机。默认："127.0.0.1"。
MCP_HTTP_PORT=3010 # HTTP传输的端口。默认：3010。
# MCP_ALLOWED_ORIGINS=http://localhost:someport,https://your-client.com # 可选：HTTP CORS允许的来源列表，逗号分隔。

# MCP安全配置
# MCP_AUTH_SECRET_KEY=your_very_long_and_secure_secret_key_min_32_chars # 可选：如果使用HTTP传输，用于JWT认证的密钥（最少32字符）。生产环境中至关重要。*注意：生产环境使用尚未测试。*
MCP_RATE_LIMIT_WINDOW_MS=60000 # 速率限制窗口（毫秒）。默认：60000（1分钟）。
MCP_RATE_LIMIT_MAX_REQUESTS=100 # 每个窗口每个IP的最大请求数（HTTP传输）。默认：100。

# 数据库备份配置
BACKUP_MAX_COUNT=10 # 保留的最大备份集数量。默认：10。
BACKUP_FILE_DIR=./atlas-backups # 备份文件存储目录（相对于项目根目录）。默认："./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": "production",
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

对于可流式HTTP（示例配置）： 如果你的客户端支持通过可流式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": "production",
        "MCP_TRANSPORT_TYPE": "http",
        "MCP_HTTP_PORT": "3010",
        "MCP_HTTP_HOST": "127.0.0.1"
        // "MCP_AUTH_SECRET_KEY": "your-secure-token" // 如果服务器启用了认证
      }
    }
  }
}

注意： 如果服务器不在客户端的当前工作目录中，配置客户端命令时始终使用绝对路径。客户端env块中的MCP_AUTH_SECRET_KEY是示例；实际的客户端到服务器通信的令牌处理将取决于客户端的能力和服务器的认证机制（例如，在Authorization头中发送JWT）。

项目结构

代码库遵循模块化结构：

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, 等)
├── types/           # 共享的TypeScript类型定义 (errors.ts, mcp.ts, tool.ts)
└── utils/           # 实用函数和内部服务 (例如，logger, errorHandler, sanitization)

工具

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

项目操作

任务操作

知识运营

搜索操作

研究运营

数据库操作

资源

ATLAS 通过标准的 MCP 资源端点公开项目、任务和知识数据。

直接资源

资源模板

数据库备份和恢复

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 文件的结构和格式。更多详情请参见 示例自述文件。
• 深度研究示例: 位于 examples/deep-research-example/ 中，此示例演示了 atlas_deep_research 工具生成的输出和结构。它包含一个 markdown 文件 (covington_community_grant_research.md)，总结了研究计划，以及一个 JSON 文件 (full-export.json)，其中包含创建研究计划后从数据库导出的原始数据。更多详情请参见 示例自述文件。

许可证

Apache 许可证 2.0