Agentic Tools MCP Server

Agentic Tools MCP 服务

一款功能全面的模型上下文协议（MCP）服务，为 AI 助手提供强大的高级任务管理和Agent 记忆能力，并支持项目专属存储。

🔗 生态系统

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

• 🖥️ VS Code 扩展 - 美观的图形界面，可直接在 VS Code 中管理任务和记忆
• ⚡ MCP 服务（本仓库）- 用于智能任务管理的高级 AI Agent 工具和 API

💡 专业提示：结合使用两者，获得极致的效率体验！VS Code 扩展提供可视化界面，而 MCP 服务则支持 AI 助手集成，并提供 PRD 解析、任务推荐和研究能力等高级功能。

功能

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

• 项目：将工作整理到不同项目中，并添加描述
• 统一任务模型：采用单一任务接口，支持无限嵌套深度
• 无限层级：任务 → 子任务 → 子子任务 → 无限深度嵌套
• 各层级均具备丰富功能：每项任务均包含优先级、复杂度、依赖项、标签和时间跟踪
• 父子关系：通过 parentId 字段灵活组织层级结构
• 层级跟踪：自动计算层级，并提供可视化指示
• 树形可视化：全面展示层级树，且深度不限
• 智能依赖项：管理任务依赖项，并对整个层级进行验证
• 优先级和复杂度：各层级均支持 1-10 级优先级评定和复杂度估算
• 增强的状态跟踪：待处理、进行中、已阻塞、已完成状态工作流
• 基于标签的整理：灵活分类和筛选
• 时间跟踪：记录预计和实际工时，助力项目规划
• 自动迁移：从旧的三级模型无缝升级到无限深度模型
• 进度跟踪：监控各层级的完成状态
• 项目专属存储：每个工作目录都有独立的任务数据
• 可纳入 Git 跟踪：任务数据可与代码一同提交

🧠 Agent 记忆系统

• 持久记忆：存储和检索带有标题及详细内容的 Agent 记忆
• 智能搜索：跨标题、内容和类别进行多字段文本搜索，并计算相关性评分
• 智能排序：高级评分算法优先考虑标题匹配（60%）、内容匹配（30%）和类别加分（20%）
• 丰富的元数据：灵活的元数据系统，提供更完善的上下文
• JSON 存储：按类别整理的独立 JSON 文件，以记忆标题命名
• 项目专属：每个工作目录均使用独立的记忆存储

🔧 可用的 MCP 工具

项目管理

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

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

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

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

• parse_prd - 解析产品需求文档并自动生成结构化任务
• get_next_task_recommendation - 根据依赖关系、优先级和复杂度获取智能任务建议
• analyze_task_complexity - 分析任务复杂度，并建议拆分过于复杂的任务
• infer_task_progress - 分析代码库，根据实现证据推断任务完成状态
• research_task - 指导 AI Agent 开展全面的网络研究，并集成记忆
• generate_research_queries - 为任务研究生成智能、针对性的网络搜索查询

旧版子任务管理（向后兼容）

• list_subtasks - 查看子任务（旧版兼容接口，现使用统一的 Task 模型）
• create_subtask - 创建子任务（旧版兼容接口，使用 parentId 创建任务）
• get_subtask - 获取任务信息（兼容现有子任务的旧版接口）
• update_subtask - 编辑子任务（旧版兼容接口，使用统一的 Task 操作）
• delete_subtask - 删除子任务（旧版兼容接口，递归删除任务）

Agent 记忆管理

• 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 Desktop 客户端配合使用（非项目专属用法）
• 需要为所有任务和记忆使用一个统一的全局工作区时
• 用于跨多个项目工作的 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"]
    }
  }
}

注意：该服务现在同时包含任务管理和 Agent 记忆功能。

与 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

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

使用 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;           // Unique identifier
  name: string;         // Project name
  description: string;  // Project overview
  createdAt: string;    // ISO timestamp
  updatedAt: string;    // ISO timestamp
}

任务（统一模型 v1.8.0——层级不限）

{
  id: string;                    // Unique identifier
  name: string;                  // Task name
  details: string;               // Enhanced description
  projectId: string;             // Parent project reference
  completed: boolean;            // Completion status
  createdAt: string;             // ISO timestamp
  updatedAt: string;             // ISO timestamp

  // Unlimited hierarchy fields (v1.8.0)
  parentId?: string;             // Parent task ID for unlimited nesting (NEW)
  level?: number;                // Computed hierarchy level (0, 1, 2, etc.) (NEW)

  // Enhanced metadata fields (from v1.7.0)
  dependsOn?: string[];          // Task dependencies (IDs of prerequisite tasks)
  priority?: number;             // Priority level (1-10, where 10 is highest)
  complexity?: number;           // Complexity estimate (1-10, where 10 is most complex)
  status?: string;               // Enhanced status: 'pending' | 'in-progress' | 'blocked' | 'done'
  tags?: string[];               // Tags for categorization and filtering
  estimatedHours?: number;       // Estimated time to complete (hours)
  actualHours?: number;          // Actual time spent (hours)
}

旧版子任务（在 v1.8.0 中弃用）

单独的 Subtask 接口已被统一的 Task 模型取代。旧版子任务会自动迁移为带有 parentId 字段的任务。这样既能确保层级深度不限，也能在每个层级保留所有丰富功能。

记忆

{
  id: string;                    // Unique identifier
  title: string;                 // Short title for file naming (max 50 characters)
  content: string;               // Detailed memory content/text (no limit)
  metadata: Record<string, any>; // Flexible metadata object
  createdAt: string;            // ISO timestamp
  updatedAt: string;            // ISO timestamp
  category?: string;            // Optional categorization
}

示例工作流

1. 创建项目

   Use create_project with:
   - workingDirectory="/path/to/your/project"
   - name="Website Redesign"
   - description="Complete overhaul of company website"
   

2. 添加增强型任务

   Use create_task with:
   - workingDirectory="/path/to/your/project"
   - name="Design mockups"
   - details="Create wireframes and high-fidelity designs"
   - projectId="[project-id-from-step-1]"
   - priority=8 (high priority)
   - complexity=6 (above average complexity)
   - status="pending"
   - tags=["design", "ui", "mockups"]
   - estimatedHours=16
   

3. 拆分任务

   Use create_subtask with:
   - workingDirectory="/path/to/your/project"
   - name="Create wireframes"
   - details="Sketch basic layout structure"
   - taskId="[task-id-from-step-2]"
   

4. 跟踪进度

   Use update_task and update_subtask to mark items as completed
   Use list_projects, list_tasks, and list_subtasks to view progress
   (All with workingDirectory parameter)
   

Agent 记忆工作流

1. 创建记忆

   Use create_memory with:
   - workingDirectory="/path/to/your/project"
   - title="User prefers concise technical responses"
   - content="The user has explicitly stated they prefer concise responses with technical explanations. They value brevity but want detailed technical information when relevant."
   - metadata={"source": "conversation", "confidence": 0.9}
   - category="user_preferences"
   

2. 搜索记忆

   Use search_memories with:
   - workingDirectory="/path/to/your/project"
   - query="user preferences responses"
   - limit=5
   - threshold=0.3
   - category="user_preferences"
   

3. 列出并管理

   Use list_memories to view all memories
   Use update_memory to modify existing memories (title, content, metadata, category)
   Use delete_memory to remove outdated memories
   (All with workingDirectory parameter)
   

📖 快速入门：请参阅 docs/QUICK_START_MEMORIES.md，了解 Agent 记忆的分步指南。

数据存储

• 项目专属：每个工作目录都有各自独立的任务和记忆数据
• 基于文件：任务数据存储在 .agentic-tools-mcp/tasks/ 中，记忆数据存储在 .agentic-tools-mcp/memories/ 中
• 可纳入 Git 跟踪：所有数据都可以与项目代码一同提交
• 持久化：所有数据都会在服务重启后保留
• 原子性：所有操作都是原子的，可防止数据损坏
• JSON 存储：简单的基于文件的存储，便于高效组织记忆
• 便于备份：简单的基于文件的存储，便于备份和迁移

存储结构

your-project/
├── .agentic-tools-mcp/
│   ├── tasks/              # Task management data for this project
│   │   └── tasks.json      # Projects, tasks, and subtasks data
│   └── memories/           # JSON file storage for memories
│       ├── preferences/    # User preferences category
│       │   └── User_prefers_concise_technical_responses.json
│       ├── technical/      # Technical information category
│       │   └── React_TypeScript_project_with_strict_ESLint.json
│       └── context/        # Context information category
│           └── 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 集成：任务和记忆数据可以与代码一同提交
• 团队协作：通过版本控制共享任务列表和 Agent 记忆
• 项目隔离：每个项目都有自己的任务管理和记忆系统
• 多项目工作流：可同时处理多个项目，并使用相互隔离的记忆
• 备份与迁移：基于文件的存储可随代码一起迁移
• 文本搜索：简单的基于内容的记忆搜索，便于智能检索上下文
• Agent 连续性：在不同会话和部署中保留 Agent 记忆

错误处理

• 验证：验证所有输入，并提供全面的错误消息
• 目录验证：确保工作目录存在且可访问
• 引用完整性：通过级联删除防止任务／子任务成为孤项
• 名称唯一性：确保同一范围（项目／任务）内的名称唯一
• 确认：执行破坏性操作前必须明确确认
• 优雅降级：提供详细的错误消息以便排查问题
• 存储错误：存储初始化失败时提供清晰的消息

开发

从源代码构建

git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start

项目结构

src/
├── features/
│   ├── task-management/
│   │   ├── tools/           # MCP tool implementations
│   │   │   ├── projects/    # Project CRUD operations
│   │   │   ├── tasks/       # Task CRUD operations
│   │   │   └── subtasks/    # Subtask CRUD operations
│   │   ├── models/          # TypeScript interfaces
│   │   └── storage/         # Data persistence layer
│   └── agent-memories/
│       ├── tools/           # Memory MCP tool implementations
│       │   └── memories/    # Memory CRUD operations
│       ├── models/          # Memory TypeScript interfaces
│       └── storage/         # JSON file storage implementation
├── server.ts            # MCP server configuration
└── index.ts             # Entry point

故障排除

常见问题

“工作目录不存在”

• 确保路径存在且可访问
• 使用绝对路径以提高可靠性
• 检查目录权限

“文本搜索未返回结果”（Agent Memories）

• 尝试使用不同的关键词或短语
• 检查记忆中是否包含搜索词
• 确认查询内容与记忆内容匹配

“未找到记忆文件”（Agent Memories）

• 确保工作目录存在且可写
• 检查是否已创建 .agentic-tools-mcp/memories 目录

版本历史

详细的版本历史和发行说明请参阅 CHANGELOG.md。

当前版本：1.8.0

• 🚀 新增：统一任务模型：单一任务接口，支持无限嵌套深度
• 🚀 新增：无限层级结构：任务 → 子任务 → 子子任务 → 无限深度嵌套
• 🚀 新增：自动迁移：从 3 层模型无缝升级到无限深度模型
• 🚀 新增：增强的树形显示：通过层级指示器可视化层级结构，并支持无限深度
• 🚀 新增：层级工具：move_task、migrate_subtasks，用于管理无限深度层级
• ✅ 各层级均具备丰富功能：每个任务都支持优先级、复杂度、依赖项、标签和时间跟踪
• ✅ 增强的任务管理：提供丰富的元数据，包括依赖项、优先级、复杂度、状态、标签和时间跟踪
• ✅ 高级 AI Agent 工具：PRD 解析、任务推荐、复杂度分析、进度推断和研究指导
• ✅ 智能任务依赖项：跨层级进行依赖项验证和工作流管理
• ✅ 优先级与复杂度系统：各层级均支持 1–10 分优先级和复杂度估算
• ✅ 增强的状态工作流：跟踪 pending → in-progress → blocked → done 状态
• ✅ 基于标签的组织方式：灵活的分类和筛选系统
• ✅ 时间跟踪：记录预估和实际工时，用于项目规划
• ✅ 混合研究集成：为 AI Agent 提供带记忆缓存的网络研究
• ✅ 完整的任务管理系统，支持无限层级组织
• ✅ Agent 记忆，采用标题／内容架构并以 JSON 文件存储
• ✅ 智能多字段搜索，支持相关性评分
• ✅ 项目专属存储，配备全面的 MCP 工具
• ✅ 全局目录模式：通过 --claude 标志用于 Claude Desktop
• ✅ 与 VS Code 扩展生态系统集成

致谢

我们感谢开源社区，以及让这个 MCP 服务成为可能的以下项目：

核心技术

• @modelcontextprotocol/sdk - MCP 服务实现的基础
• Node.js File System - 可靠的基于文件的记忆持久化存储
• TypeScript - 类型安全的 JavaScript 开发
• Node.js - JavaScript 运行时环境

开发与验证

• Zod - 面向 TypeScript 的优先级架构验证，支持可靠的输入处理
• ESLint - 代码质量与一致性
• Prettier - 代码格式化

文件存储与搜索

• JSON - 用于存储记忆的简单易读数据格式
• 文本搜索 - 对记忆文件进行高效的基于内容的搜索

特别感谢

• 开源社区 - 感谢社区创建了让本项目得以实现的工具和库

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件。

参与贡献

欢迎贡献！欢迎提交问题和拉取请求。

开发环境设置

git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start

相关项目

🖥️ VS Code 扩展

Agentic Tools MCP Companion - 一款出色的 VS Code 扩展，为此 MCP 服务提供图形界面。

主要功能：

• 🎯 可视化任务管理：功能丰富的图形界面，提供增强型任务元数据表单
• 📝 增强型表单：优先级、复杂度、状态、标签和时间跟踪
• 🎨 可视化指示器：状态表情符号、优先级徽章和复杂度指示器
• 📊 丰富的工具提示：悬停即可查看完整任务信息
• 🔄 实时同步：与 MCP 服务数据即时同步
• � 响应式设计：自适应表单，可在不同屏幕尺寸下使用

适用于：

• 可视化任务管理和规划
• 偏好图形界面的团队
• 需要丰富任务元数据的项目经理
• 任何想在 VS Code 中优雅地组织任务的人

支持

如有问题或疑问，请使用 GitHub 问题跟踪器。

文档

• 📖 API 参考 - 完整的工具文档
• 🧠 Agent 记忆指南 - 全面的记忆系统指南
• 🚀 快速入门：记忆 - 开始使用 Agent 记忆
• 📋 更新日志 - 版本历史和发布说明

获取帮助

• 🐛 通过 GitHub 问题报告错误
• 💡 通过 GitHub 讨论提出功能请求
• 🖥️ VS Code 扩展问题：在 agentic-tools-mcp-companion 报告扩展相关问题