atlas-mcp-服务器

Name: atlas-mcp-服务器
Author: cyanheads

作者：cyanheads272 星标更新：2025-07-22

安装使用来源：spider==github.com

项目介绍

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

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

重要版本说明: 版本 1.5.4 是最后一个使用 SQLite 作为数据库的版本。从版本 2.0 开始，已完全重写以使用 Neo4j，需要以下之一：

使用 Docker 自托管（仓库中包含 docker-compose）

使用 Neo4j AuraDB 云服务: https://neo4j.com/product/auradb/

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

概述

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

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

系统集成

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

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

特性

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

安装

克隆仓库:

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

安装依赖:
```
npm install
```
配置 Neo4j: 确保您有一个正在运行且可访问的 Neo4j 实例。您可以使用提供的 Docker 配置启动一个实例：
```
docker-compose up -d
```
更新您的 .env 文件，填写 Neo4j 连接详情（参见配置）。
构建项目:
```
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 # 可选：JWT 认证的密钥（至少 32 个字符）。生产环境必须使用。*注意：生产环境使用尚未经过测试。*
MCP_RATE_LIMIT_WINDOW_MS=60000 # 速率限制窗口，单位毫秒。默认值：60000（1 分钟）。
MCP_RATE_LIMIT_MAX_REQUESTS=100 # 每个 IP 每个窗口的最大请求次数。默认值：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": "development",
        "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": "development",
        "MCP_TRANSPORT_TYPE": "http",
        "MCP_HTTP_PORT": "3010",
        "MCP_HTTP_HOST": "127.0.0.1"
        // "MCP_AUTH_SECRET_KEY": "your-secure-token" // 如果启用了认证
      }
    }
  }
}

注意: 配置客户端命令时，如果服务器不在客户端的当前工作目录中，始终使用绝对路径。客户端中的 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_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`