Agentic Tools MCP Server

一个全面的模型上下文协议（MCP）服务器，提供强大的高级任务管理和代理记忆功能，并具有项目特定存储。

🔗 生态系统

此MCP服务器是完整的任务和记忆管理系统的一部分：

• 🖥️ VS Code 扩展 - 在VS Code中管理任务和记忆的漂亮GUI界面
• ⚡ MCP Server (此仓库) - 高级AI代理工具和API，用于智能任务管理

💡 提示: 同时使用两者以获得最佳生产力体验！VS Code扩展提供了视觉界面，而MCP服务器则使AI助手集成具备PRD解析、任务推荐和研究能力等高级功能。

功能

🎯 高级任务管理系统（无限层级 v1.8.0）

• 项目: 将工作组织成带有描述的不同项目
• 统一任务模型: 支持无限嵌套深度的单一任务接口
• 无限层级: 任务 → 子任务 → 子子任务 → 无限深度嵌套
• 所有层级丰富的功能: 每个任务都具有优先级、复杂性、依赖关系、标签和时间跟踪
• 父子关系: 使用parentId字段灵活组织层次结构
• 层级跟踪: 自动计算层级并显示视觉指示器
• 树形可视化: 全面的无限深度层次树显示
• 智能依赖关系: 跨层级的任务依赖关系管理
• 优先级与复杂性: 1-10比例的优先级和复杂性估计
• 增强状态跟踪: 待办、进行中、阻塞、完成的状态工作流
• 基于标签的组织: 灵活的分类和过滤
• 时间跟踪: 项目规划的预计和实际小时数
• 自动迁移: 无缝升级从旧的三层到无限深度模型
• 进度跟踪: 监控所有层级的完成状态
• 项目特定存储: 每个工作目录都有隔离的任务数据
• Git追踪: 任务数据可以与代码一起提交

🧠 代理记忆系统

• 持久记忆: 存储和检索带有标题和详细内容的代理记忆
• 智能搜索: 多字段文本搜索，根据标题、内容和类别进行相关性评分
• 智能排名: 高级评分算法优先考虑标题匹配（60%）、内容匹配（30%）和类别加分（20%）
• 丰富元数据: 增强上下文的灵活元数据系统
• JSON存储: 按类别组织的单独JSON文件，以记忆标题命名
• 项目特定: 每个工作目录都有隔离的记忆存储

🔧 可用的MCP工具

项目管理

• list_projects - 查看工作目录中的所有项目
• create_project - 在工作目录中创建新项目
• get_project - 获取详细的项目信息
• update_project - 编辑项目名称/描述
• delete_project - 删除项目及其所有关联数据

任务管理（无限层级 v1.8.0）

• list_tasks - 以无限深度的层次树格式查看任务
• create_task - 在任何层级创建任务（支持无限嵌套）
• get_task - 获取详细的任务信息，包括层级关系
• update_task - 编辑任务、元数据或在层级之间移动
• delete_task - 递归删除任务及其所有子任务
• move_task - 专门用于在层级结构内移动任务的工具
• migrate_subtasks - 将遗留子任务转换为统一模型的自动迁移工具

高级任务管理（AI代理工具）

• parse_prd - 解析产品需求文档并自动生成结构化任务
• get_next_task_recommendation - 根据依赖关系、优先级和复杂性获取智能任务推荐
• analyze_task_complexity - 分析任务复杂性并建议分解过于复杂的任务
• infer_task_progress - 分析代码库以推断任务完成状态
• research_task - 引导AI代理执行综合网络研究并整合记忆
• generate_research_queries - 生成智能、有针对性的网络搜索查询以进行任务研究

遗留子任务管理（向后兼容）

• list_subtasks - 查看子任务（遗留兼容，现在使用统一任务模型）
• create_subtask - 创建子任务（遗留兼容，创建带有parentId的任务）
• get_subtask - 获取任务信息（遗留兼容，针对现有子任务）
• update_subtask - 编辑子任务（遗留兼容，使用统一任务操作）
• delete_subtask - 删除子任务（遗留兼容，递归删除任务）

代理记忆管理

• create_memory - 存储带有标题和详细内容的新记忆
• search_memories - 使用智能多字段搜索查找记忆，并进行相关性评分
• get_memory - 获取详细的记忆信息
• list_memories - 列出记忆，可选过滤
• update_memory - 编辑记忆标题、内容、元数据或分类
• delete_memory - 删除记忆（需要确认）

重要: 所有工具都需要一个workingDirectory参数来指定数据应存储的位置。这使得每个项目的任务和记忆管理成为可能。

安装

快速开始

npx -y @pimzino/agentic-tools-mcp

全局安装

npm install -g @pimzino/agentic-tools-mcp

使用

存储模式

MCP服务器支持两种存储模式：

📁 项目特定模式（默认）

数据存储在每个项目的工作目录内的.agentic-tools-mcp/子目录中。

npx -y @pimzino/agentic-tools-mcp

🌐 全局目录模式

使用--claude标志将所有数据存储在一个标准化的全局目录中：

• Windows: C:\Users\{username}\.agentic-tools-mcp\
• macOS/Linux: ~/.agentic-tools-mcp/

npx -y @pimzino/agentic-tools-mcp --claude

何时使用--claude标志:

• 使用Claude桌面客户端（非项目特定使用）
• 当您希望所有任务和记忆有一个单一的全局工作区
• 对于跨多个项目的AI代理

注意: 使用--claude标志时，所有工具中的workingDirectory参数将被忽略，而是使用全局目录。

与Claude Desktop

项目特定模式（默认）

{
  "mcpServers": {
    "agentic-tools": {
      "command": "npx",
      "args": ["-y", "@pimzino/agentic-tools-mcp"]
    }
  }
}

全局目录模式（推荐用于Claude Desktop）

{
  "mcpServers": {
    "agentic-tools": {
      "command": "npx",
      "args": ["-y", "@pimzino/agentic-tools-mcp", "--claude"]
    }
  }
}

注意: 该服务器现在包括任务管理和代理记忆功能。

与AugmentCode

项目特定模式（默认）

1. 打开Augment设置面板（齿轮图标）
2. 添加MCP服务器：
   • 名称: agentic-tools
   • 命令: npx -y @pimzino/agentic-tools-mcp
3. 重启VS Code

全局目录模式

1. 打开Augment设置面板（齿轮图标）
2. 添加MCP服务器：
   • 名称: agentic-tools
   • 命令: npx -y @pimzino/agentic-tools-mcp --claude
3. 重启VS Code

可用功能: 任务管理、代理记忆和基于文本的搜索能力。

与VS Code扩展（推荐）

为了获得最佳用户体验，请安装Agentic Tools MCP Companion VS Code扩展：

1. 克隆伴生扩展仓库
2. 在VS Code中打开它并按F5以开发模式运行
3. 享受所有任务和记忆管理的漂亮GUI界面

同时使用的好处:

• 🎯 视觉任务管理: 包含优先级、复杂性、状态、标签和时间跟踪的丰富表单
• 🎨 增强UI: 状态表情符号、优先级徽章和视觉指示器
• 🔄 实时同步: VS Code中的更改即时对AI助手可用
• 📁 项目集成: 无缝集成到您的工作空间
• 🤖 AI协作: 人类规划与AI执行相结合，实现最优生产力

与其他MCP客户端

服务器使用STDIO传输，可以与任何兼容MCP的客户端集成：

项目特定模式

npx -y @pimzino/agentic-tools-mcp

全局目录模式

npx -y @pimzino/agentic-tools-mcp --claude

数据模型

项目

{
  id: string;           // 唯一标识符
  name: string;         // 项目名称
  description: string;  // 项目概述
  createdAt: string;    // ISO时间戳
  updatedAt: string;    // ISO时间戳
}

任务（统一模型 v1.8.0 - 无限层级）

{
  id: string;                    // 唯一标识符
  name: string;                  // 任务名称
  details: string;               // 增强描述
  projectId: string;             // 父项目引用
  completed: boolean;            // 完成状态
  createdAt: string;             // ISO时间戳
  updatedAt: string;             // ISO时间戳

  // 无限层级字段（v1.8.0）
  parentId?: string;             // 无限嵌套的父任务ID（新增）
  level?: number;                // 计算的层级（0, 1, 2等）（新增）

  // 增强的元数据字段（从v1.7.0起）
  dependsOn?: string[];          // 任务依赖项（先决条件任务的ID）
  priority?: number;             // 优先级（1-10，其中10最高）
  complexity?: number;           // 复杂性估计（1-10，其中10最复杂）
  status?: string;               // 增强状态：'待办' | '进行中' | '阻塞' | '完成'
  tags?: string[];               // 分类和过滤的标签
  estimatedHours?: number;       // 预计完成时间（小时）
  actualHours?: number;          // 实际花费时间（小时）
}

遗留子任务（在v1.8.0中已弃用）

独立的子任务接口已被统一的任务模型取代。遗留子任务会自动迁移到带有parentId字段的任务。这确保了无限层级深度的同时，在每一层都保留了所有丰富的功能。

记忆

{
  id: string;                    // 唯一标识符
  title: string;                 // 文件命名的短标题（最多50个字符）
  content: string;               // 详细记忆内容/文本（无限制）
  metadata: Record<string, any>; // 灵活的元数据对象
  createdAt: string;            // ISO时间戳
  updatedAt: string;            // ISO时间戳
  category?: string;            // 可选分类
}

示例工作流程

1. 创建项目

   使用create_project:
   - workingDirectory="/path/to/your/project"
   - name="网站重新设计"
   - description="公司网站的全面翻新"
   

2. 添加增强任务

   使用create_task:
   - workingDirectory="/path/to/your/project"
   - name="设计草图"
   - details="创建线框图和高保真设计"
   - projectId="[步骤1中的项目ID]"
   - priority=8 （高优先级）
   - complexity=6 （高于平均复杂度）
   - status="待办"
   - tags=["设计", "UI", "草图"]
   - estimatedHours=16
   

3. 分解任务

   使用create_subtask:
   - workingDirectory="/path/to/your/project"
   - name="创建线框图"
   - details="绘制基本布局结构"
   - taskId="[步骤2中的任务ID]"
   

4. 跟踪进度

   使用update_task和update_subtask标记已完成的项目
   使用list_projects、list_tasks和list_subtasks查看进度
   （所有操作均需指定workingDirectory参数）
   

代理记忆工作流程

1. 创建记忆

   使用create_memory:
   - workingDirectory="/path/to/your/project"
   - title="用户偏好简洁的技术响应"
   - content="用户明确表示他们偏好简洁且包含技术解释的响应。他们重视简洁但需要相关的详细技术信息。"
   - metadata={"来源": "对话", "信心": 0.9}
   - category="用户偏好"
   

2. 搜索记忆

   使用search_memories:
   - workingDirectory="/path/to/your/project"
   - query="用户偏好响应"
   - limit=5
   - threshold=0.3
   - category="用户偏好"
   

3. 列出和管理

   使用list_memories查看所有记忆
   使用update_memory修改现有记忆（标题、内容、元数据、分类）
   使用delete_memory移除过时的记忆
   （所有操作均需指定workingDirectory参数）
   

📖 快速开始: 请参阅docs/QUICK_START_MEMORIES.md以获取代理记忆的逐步指南。

数据存储

• 项目特定: 每个工作目录都有自己的隔离任务和记忆数据
• 基于文件: 任务数据存储在.agentic-tools-mcp/tasks/，记忆数据存储在.agentic-tools-mcp/memories/
• Git追踪: 所有数据都可以与项目代码一起提交
• 持久性: 所有数据在服务器重启之间持续存在
• 原子性: 所有操作都是原子性的，以防止数据损坏
• JSON存储: 简单的基于文件的存储，用于高效的记忆组织
• 备份友好: 简单的基于文件的存储，便于备份和迁移

存储结构

your-project/
├── .agentic-tools-mcp/
│   ├── tasks/              # 此项目的任务管理数据
│   │   └── tasks.json      # 项目、任务和子任务的数据
│   └── memories/           # 记忆的JSON文件存储
│       ├── preferences/    # 用户偏好类别
│       │   └── User_prefers_concise_technical_responses.json
│       ├── technical/      # 技术信息类别
│       │   └── React_TypeScript_project_with_strict_ESLint.json
│       └── context/        # 上下文信息类别
│           └── User_works_in_healthcare_needs_HIPAA_compliance.json
├── src/
├── package.json
└── README.md

工作目录参数

所有MCP工具都需要一个workingDirectory参数，指定：

• 存储.agentic-tools-mcp/文件夹的位置（在项目特定模式下）
• 访问哪个项目的任务和记忆数据
• 使多个项目能够拥有独立的任务列表和记忆存储

注意: 当服务器使用--claude标志启动时，workingDirectory参数将被忽略，而是使用全局用户目录（macOS/Linux上的~/.agentic-tools-mcp/或Windows上的C:\Users\{username}\.agentic-tools-mcp\）。

项目特定存储的好处

• Git集成: 任务和记忆数据可以与代码一起提交
• 团队协作: 通过版本控制共享任务列表和代理记忆
• 项目隔离: 每个项目都有自己独立的任务管理和记忆系统
• 多项目工作流: 同时处理多个项目，每个项目都有独立的记忆
• 备份与迁移: 基于文件的存储随代码一起迁移
• 文本搜索: 简单的内容基础记忆搜索以智能地检索上下文
• 代理连续性: 跨会话和部署的持久代理记忆

错误处理

• 验证: 所有输入都经过全面错误消息的验证
• 目录验证: 确保工作目录存在且可访问
• 参照完整性: 防止由于级联删除而导致孤立的任务/子任务
• 唯一名称: 在作用域内强制唯一名称（项目/任务）
• 确认: 破坏性操作需要显式确认
• 优雅降级: 详细的错误消息用于故障排除