Atlas MCP Server

ATLAS：任务管理系统

  ](https://github.com/cyanheads/atlas-mcp-server/releases)   ](https://github.com/cyanheads/atlas-mcp-server)

ATLAS（自适应任务和逻辑自动化系统）是一个面向LLM代理的项目、知识和任务管理系统。

基于3节点架构构建：

                  +-------------------------------------------+
                  |                PROJECT                    |
                  |-------------------------------------------|
                  | id: string                                |
                  | name: string                              |
                  | description: string                       |
                  | status: string                            |
                  | urls?: Array|
                  | 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                  | | updatedAt: string                |
| tags?: string[]                  | |                                  |
| completionRequirements: string   | |                                  |
| outputFormat: string             | |                                  |
| taskType: string                 | |                                  |
| createdAt: string                | |                                  |
| updatedAt: string                | |                                  |
+----------------------------------+ +----------------------------------+

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

重要版本说明: 版本1.5.4 是最后一个使用SQLite作为数据库的版本。2.0及更高版本已完全重写为使用Neo4j，这需要： - 使用Docker的自托管（Docker compose包含在存储库中） - 使用Neo4j AuraDB云服务：https://neo4j.com/product/auradb/ 2.5.0版本引入了一个新的3节点系统（项目、任务、知识），取代了之前的结构。

目录

• 概述
• 特性
• 安装
• 运行服务器
• Web UI（实验）
• 配置
• 项目结构
• 工具
• 资源
• 数据库备份和还原
• 例子
• 许可证

概述

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

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

系统集成

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

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

特性

-优先级和分类：分配优先级并用标签对任务进行分类，以便更好地组织。 -依赖关系跟踪：建立任务依赖关系以创建结构化工作流。 | | 知识管理 |结构化知识库：维护一个可搜索的项目相关信息库。 -领域分类：按领域和标签组织知识，以便于检索。 -引文支持：跟踪知识项的来源和参考文献。 | | 图形数据库集成 |-原生关系管理：利用Neo4j的ACID兼容事务和优化的查询，实现强大的数据完整性。 -高级搜索和可扩展性：使用模糊匹配和通配符执行基于属性的搜索，同时保持高性能。 | | 统一搜索 |-跨实体搜索：根据内容、元数据或关系查找相关项目、任务或知识。 -灵活的查询选项：支持不区分大小写、模糊和高级过滤选项。 |

安装

1. 克隆存储库：

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

1. 安装依赖项：

   npm install

1. 配置Neo4j：

确保您有一个运行且可访问的Neo4j实例。您可以使用提供的Docker配置启动一个：

   docker-compose up -d

更新您的 .env 包含Neo4j连接详细信息的文件（请参见 配置).

1. 构建项目：

   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的示例屏幕截图 这里.

配置

环境变量

环境变量应在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.json 某些客户端可以使用项目根目录中的文件（如 mcp-inspector)定义服务器配置；根据需要进行更新。

对于标准运输（示例配置）：

{
  "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"
      }
    }
  }
}

对于流式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 在配置客户端命令时，如果服务器不在客户端的直接工作目录中。这 MCP_AUTH_SECRET_KEY 在客户的 env 块是说明性的；客户端到服务器通信的实际令牌处理将取决于客户端的能力和服务器的身份验证机制（例如，在 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通过标准MCP资源端点公开项目、任务和知识数据。

直接资源

资源模板

数据库备份和还原

ATLAS提供了备份和恢复Neo4j数据库内容的功能。核心逻辑在于 src/services/neo4j/backupRestoreService.ts.

备份过程

• 机制：备份过程导出所有 Project, Task，以及 Knowledge 节点及其关系被合并到单独的JSON文件中。A. full-export.json 还创建了包含所有数据的数据库。
• 输出：每个备份创建一个带时间戳的目录（例如。， atlas-backup-YYYYMMDDHHMMSS)在配置的备份路径内（默认值： ./atlas-backups/).此目录包含 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 

替换 使用备份文件夹的实际路径（例如。， ./atlas-backups/atlas-backup-20250326120000).此命令执行 src/services/neo4j/backupRestoreService/scripts/db-import.ts，这叫 importDatabase 功能。

• 关系处理：导入过程尝试基于以下内容重新创建关系 id 导出期间存储在节点内的属性。确保您的节点具有一致性 id 正确恢复关系的属性。

例子

这 examples/ 该目录包含演示ATLASMCP服务器各种功能的实际示例。

• 备份示例：位于 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

______________________________________________________________________

Built with the Model Context Protocol