ATLAS：任务管理系统

TypeScript 模型上下文协议 GitHub

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

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

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

概述

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

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

系统集成

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

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

特征

项目管理

**全面跟踪：**管理项目元数据、状态和丰富内容（注释、链接等），内置批量操作支持。
**依赖和关系处理：**自动验证和跟踪项目间依赖关系。

任务管理

**任务生命周期管理：**在整个生命周期内创建、跟踪和更新任务。
**优先级和分类：**分配优先级并使用标签对任务进行分类，以便更好地组织。
**依赖关系跟踪：**建立任务依赖关系以创建结构化工作流程。

知识管理

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

图数据库集成

**原生关系管理：**利用 Neo4j 的 ACID 兼容事务和优化查询来实现强大的数据完整性。
**高级搜索和可扩展性：**使用模糊匹配和通配符执行基于属性的搜索，同时保持高性能。

统一搜索

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

安装

克隆存储库：
git clone https://github.com/cyanheads/atlas-mcp-server.git cd atlas-mcp-server
安装依赖项：
npm install
**配置 Neo4j：**确保 Neo4j 实例已运行且可访问。您可以使用提供的 Docker 配置启动一个 Neo4j 实例：
docker-compose up -d
使用 Neo4j 连接详细信息更新您的.env文件（请参阅配置）。
构建项目：
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，请在终端中运行以下命令：
  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". # OpenRouter LLM Configuration (Optional - additional parameters present in `src/config/index.ts`) # OPENROUTER_API_KEY=your_openrouter_api_key # API key for OpenRouter services. LLM_DEFAULT_MODEL="google/gemini-2.5-flash-preview:thinking" # Default LLM model.

请参阅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": "production", "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": "production", "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 │ ├── llm-providers/ # LLM provider integrations (e.g., OpenRouter) │ └── 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_project_create`	创建新项目（单个/批量）。	`mode` ('single'/'bulk')、 `id` （单例模式下可选，客户端生成的 ID）、项目详情（ `name` 、 `description` 、 `status` 、 `urls` 、 `completionRequirements` 、 `dependencies` 、 `outputFormat` 、 `taskType` ）。批量模式下，使用`projects` （项目对象数组`responseFormat` 。responseFormat ('formatted'/'json'，可选，默认值：'formatted')。
`atlas_project_list`	列出项目（全部/详细信息）。	`mode` （'全部'/'详细信息'，默认值：'全部'）， `id` （用于详细信息模式），过滤器（ `status` ， `taskType` ），分页（ `page` ， `limit` ），包括（ `includeKnowledge` ， `includeTasks` ）， `responseFormat` （'格式化'/'json'，可选，默认值：'格式化'）。
`atlas_project_update`	更新现有项目（单个/批量）。	`mode` ('single'/'bulk')、 `id` （用于单次模式`responseFormat` 、 `updates`对象。对于批量模式，请使用`projects` （对象数组，每个对象包含`id`和`updates` ）。responseFormat ('formatted'/'json'，可选，默认值：'formatted')。
`atlas_project_delete`	删除项目（单个/批量）。	`mode` （'单一'/'批量'）， `id` （单一模式）或`projectIds` （批量模式`responseFormat`数组）。responseFormat（'formatted'/'json'，可选，默认值：'formatted'）。

任务操作

工具名称	描述	关键论点
`atlas_task_create`	创建新任务（单个/批量）。	`mode` ('single'/'bulk')、 `id` （可选，客户端生成的 ID）、 `projectId` 、任务详情（ `title` 、 `description` 、 `priority` 、 `status` 、 `assignedTo` 、 `urls` 、 `tags` 、 `completionRequirements` 、 `dependencies` 、 `outputFormat` 、 `taskType` ）。 `responseFormat`模式使用`tasks` （任务对象数组）。responseFormat（'formatted'/'json'，可选，默认值：'formatted'）。
`atlas_task_update`	更新现有任务（单个/批量）。	`mode` ('single'/'bulk')、 `id` （用于单次模式`responseFormat` 、 `updates`对象。对于批量模式，请使用`tasks` （对象数组，每个对象包含`id`和`updates` ）。responseFormat ('formatted'/'json'，可选，默认值：'formatted')。
`atlas_task_delete`	删除任务（单个/批量）。	`mode` （'single'/'bulk'）、 `id` （单一模式）或`taskIds` （批量模式的数组`responseFormat` 。responseFormat（'formatted'/'json'，可选，默认值：'formatted'）。
`atlas_task_list`	列出特定项目的任务。	`projectId` （必需）、过滤器（ `status` 、 `assignedTo` 、 `priority` 、 `tags` 、 `taskType` ）、排序（ `sortBy` 、 `sortDirection` ）、分页（ `page` 、 `limit` ）、 `responseFormat` （'格式化'/'json'，可选，默认值：'格式化'）。

知识运营

工具名称	描述	关键论点
`atlas_knowledge_add`	添加新的知识项目（单个/批量）。	`mode` ('single'/'bulk')、 `id` （可选，客户端生成的 ID）、 `projectId` 、知识详情（ `text` 、 `tags` 、 `domain` 、 `citations` ）。批量模式使用`knowledge` （知识对象数组`responseFormat` 。responseFormat ('formatted'/'json'，可选，默认值：'formatted')。
`atlas_knowledge_delete`	删除知识项（单个/批量）。	`mode` （'单一'/'批量'）， `id` （单一模式）或`knowledgeIds` （批量模式`responseFormat`数组）。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，用于正则表达式“包含”或全文 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
此命令执行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 ）。此命令执行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 许可证 2.0

atlas-mcp-server