ATLAS MCP 服务器

ATLAS (自适应任务与逻辑自动化系统) 是一个模型上下文协议服务器，为大型语言模型提供分层任务管理能力。该工具为 LLM 提供管理复杂任务和依赖关系所需的结构和上下文。

目录

• 概述
• 特性
• 安装
• 配置
• 任务结构
• 工具
• 最佳实践
• 已知问题
• 开发
• 贡献
• 许可证

概述

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

• 维护服务器连接的客户端（Claude Desktop、IDE）
• 提供工具和资源的服务器
• 通过客户端应用程序与服务器交互的 LLM

开发说明：

• 此项目正在积极开发中，可能会有重大更改。
• 这是我第一次使用 TypeScript，我正在边做边学。

核心组件

• TaskManager: 集中式任务协调，具有验证和事件处理功能
• TaskOperations: 符合 ACID 的任务操作，支持事务
• TaskValidator: 使用 Zod 模式和路径验证进行全面验证
• PathValidator: 强大的路径验证和清理
• TransactionScope: 改进的事务管理，具有隔离级别
• StorageManager: 基于 SQLite 的持久化，采用 WAL 模式
• EventManager: 系统范围的事件跟踪和通知
• BatchProcessors: 优化的批量操作，用于状态和依赖关系更新

特性

任务组织

• 具有父子关系的分层任务结构
• 强类型验证 (TASK, GROUP, MILESTONE)
• 状态管理 (PENDING, IN_PROGRESS, COMPLETED, FAILED, BLOCKED)
• 具有循环检测的依赖关系跟踪
• 具有模式验证的丰富元数据支持

路径验证与安全

• 防止目录遍历
• 特殊字符验证
• 父子路径验证
• 路径深度限制
• 项目名称验证
• 路径清理
• 一致的路径格式

事务管理

• 隔离级别支持
• 嵌套事务处理
• 保存点管理
• 自动回滚
• 事务安全操作
• Vacuum 操作支持

存储与性能

• 具有预写日志 (WAL) 的 SQLite 后端
• 具有内存压力监控的 LRU 缓存
• 基于事务的操作，支持回滚
• 用于批量更新的批量处理
• 基于索引的快速检索
• 自动缓存管理

验证与安全

• 所有输入的 Zod 模式验证
• 循环依赖预防
• 状态转换验证
• 元数据模式强制执行
• 父子关系验证
• 并发版本跟踪

监控与维护

• 全面的事件系统
• 内存使用情况监控
• 数据库优化工具
• 关系修复实用程序
• 缓存统计跟踪
• 健康状况监控

错误处理

• 详细的错误代码和消息
• 具有回滚的事务安全性
• 可重试操作支持
• 丰富的错误上下文
• 基于事件的错误跟踪

安装

1. 克隆存储库：

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

配置

添加到您的 MCP 客户端设置：

{
  "mcpServers": {
    "atlas": {
      "command": "node",
      "args": ["/path/to/atlas-mcp-server/build/index.js"],
      "env": {
        "ATLAS_STORAGE_DIR": "/path/to/storage/directory",
        "ATLAS_STORAGE_NAME": "atlas-tasks",
        "NODE_ENV": "production"
      }
    }
  }
}

高级配置选项：

{
  "storage": {
    "connection": {
      "maxRetries": 3,
      "retryDelay": 500,
      "busyTimeout": 2000
    },
    "performance": {
      "checkpointInterval": 60000,
      "cacheSize": 1000,
      "mmapSize": 1073741824,
      "pageSize": 4096
    }
  },
  "logging": {
    "console": true,
    "file": true,
    "level": "debug"
  }
}

任务结构

任务支持分层结构中的丰富内容和元数据：

{
  // 路径必须遵循验证规则：
  // - 没有父目录遍历 (..)
  // - 仅限字母数字、破折号、下划线
  // - 最大深度为 5 级
  // - 有效的项目名称作为第一个段
  "path": "project/feature/task",
  
  "name": "Implementation Task",
  "description": "Implement core functionality",
  "type": "TASK", // TASK, GROUP, or MILESTONE
  "status": "PENDING",
  
  // 父路径必须存在并遵循相同的规则
  "parentPath": "project/feature",
  
  // 依赖项经过验证：
  // - 存在
  // - 没有循环引用
  // - 状态转换
  "dependencies": ["project/feature/design"],
  
  "notes": [
    "# Requirements\n- Feature A\n- Feature B",
    "interface Feature {\n  name: string;\n  enabled: boolean;\n}"
  ],
  
  "metadata": {
    "priority": "high",
    "tags": ["core", "implementation"],
    "estimatedHours": 8,
    "assignee": "john.doe",
    "customField": {
      "nested": {
        "value": 123
      }
    }
  },

  // 系统字段
  "created": 1703094689310,
  "updated": 1703094734316,
  "projectPath": "project",
  "version": 1
}

工具

任务管理

create_task

创建具有验证和依赖项检查的任务：

{
  "path": "project/backend", // 必须遵循路径规则
  "name": "Backend Development",
  "type": "GROUP",
  "description": "Implement core backend services",
  "metadata": {
    "priority": "high",
    "tags": ["backend", "api"]
  }
}

update_task

更新具有状态和依赖项验证的任务：

{
  "path": "project/backend/api",
  "updates": {
    "status": "IN_PROGRESS", // 验证依赖项
    "dependencies": ["project/backend/database"],
    "metadata": {
      "progress": 50,
      "assignee": "team-member"
    }
  }
}

bulk_task_operations

原子地执行多个操作：

{
  "operations": [
    {
      "type": "create",
      "path": "project/frontend",
      "data": {
        "name": "Frontend Development",
        "type": "GROUP"
      }
    },
    {
      "type": "update",
      "path": "project/backend",
      "data": {
        "status": "COMPLETED"
      }
    }
  ]
}

任务查询

get_tasks_by_status

按执行状态检索任务：

{
  "status": "IN_PROGRESS"
}

get_tasks_by_path

使用 glob 模式搜索：

{
  "pattern": "project/backend/**"
}

get_subtasks

列出直接子任务：

{
  "parentPath": "project/backend"
}

维护工具

vacuum_database

优化数据库存储和性能：

{
  "analyze": true // 还会更新统计信息
}

repair_relationships

修复任务关系不一致：

{
  "dryRun": true, // 预览更改
  "pathPattern": "project/**"
}

clear_all_tasks

使用确认重置数据库：

{
  "confirm": true
}

最佳实践

任务管理

• 使用反映层次结构的描述性路径名
• 设置适当的任务类型（TASK、GROUP、MILESTONE）
• 包含详细的上下文描述
• 使用元数据进行自定义字段
• 仔细考虑依赖关系
• 维护干净的父子关系

路径命名

• 使用字母数字字符、破折号、下划线
• 保持路径简短且有意义
• 以有效的项目名称开头
• 避免特殊字符
• 使用正斜杠
• 保持深度在 5 级以下

性能

• 使用批量操作进行多次更新
• 保持任务层次结构较浅
• 定期清理已完成的任务
• 监控内存使用情况
• 使用适当的批量大小
• 维护适当的索引

数据完整性

• 在操作前验证输入
• 正确处理状态转换
• 检查循环依赖
• 维护元数据一致性
• 对相关更改使用事务
• 定期数据库维护

已知问题

1. 路径深度验证

   • 可能会接受深层路径（>5 级）
   • 需要更严格的执行

2. 级联删除

   • 一些深层路径任务可能会在父级删除后仍然存在
   • 需要改进的递归删除

3. 事务管理

   • 批量操作可能会因嵌套事务而失败
   • clear_all_tasks 存在事务问题
   • 需要适当的嵌套事务支持

开发

npm run build    # 构建项目
npm run watch    # 监听更改
npm test        # 运行测试

贡献

1. Fork 存储库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到分支
5. 创建一个 Pull Request

对于错误和功能请求，请创建一个 issue。

许可证

Apache License 2.0

---

<div align="center"> 使用模型上下文协议构建 </div>