Allows task data to be tracked alongside code in Git repositories, with project-specific storage that supports committing task management data in version control for team collaboration.
Provides structured data models defined in TypeScript for projects, tasks, and subtasks, enabling type-safe interactions with the task management system.
Agentic Tools MCP Server
A comprehensive Model Context Protocol (MCP) server providing AI assistants with powerful advanced task management and agent memories capabilities with project-specific storage.
🔗 Ecosystem
This MCP server is part of a complete task and memory management ecosystem:
- 🖥️ VS Code Extension - Beautiful GUI interface for managing tasks and memories directly in VS Code
- ⚡ MCP Server (this repository) - Advanced AI agent tools and API for intelligent task management
💡 Pro Tip: Use both together for the ultimate productivity experience! The VS Code extension provides a visual interface while the MCP server enables AI assistant integration with advanced features like PRD parsing, task recommendations, and research capabilities.
Features
🎯 Advanced Task Management System with Unlimited Hierarchy (v1.8.0)
- Projects: Organize work into distinct projects with descriptions
- Unified Task Model: Single task interface supporting unlimited nesting depth
- Unlimited Hierarchy: Tasks → Subtasks → Sub-subtasks → infinite depth nesting
- Rich Features at All Levels: Every task gets priority, complexity, dependencies, tags, and time tracking
- Parent-Child Relationships: Flexible hierarchy organization with
parentId
field - Level Tracking: Automatic hierarchy level calculation and visual indicators
- Tree Visualization: Comprehensive hierarchical tree display with unlimited depth
- Intelligent Dependencies: Task dependency management with validation across hierarchy
- Priority & Complexity: 1-10 scale prioritization and complexity estimation at every level
- Enhanced Status Tracking: pending, in-progress, blocked, done status workflow
- Tag-Based Organization: Flexible categorization and filtering
- Time Tracking: Estimated and actual hours for project planning
- Automatic Migration: Seamless upgrade from old 3-level to unlimited depth model
- Progress Tracking: Monitor completion status at all hierarchy levels
- Project-Specific Storage: Each working directory has isolated task data
- Git-Trackable: Task data can be committed alongside your code
🧠 Agent Memories System
- Persistent Memory: Store and retrieve agent memories with titles and detailed content
- Intelligent Search: Multi-field text search with relevance scoring across titles, content, and categories
- Smart Ranking: Advanced scoring algorithm prioritizes title matches (60%), content matches (30%), and category bonuses (20%)
- Rich Metadata: Flexible metadata system for enhanced context
- JSON Storage: Individual JSON files organized by category, named after memory titles
- Project-Specific: Isolated memory storage per working directory
🔧 MCP Tools Available
Project Management
list_projects
- View all projects in a working directorycreate_project
- Create a new project in a working directoryget_project
- Get detailed project informationupdate_project
- Edit project name/descriptiondelete_project
- Delete project and all associated data
Task Management (Unlimited Hierarchy v1.8.0)
list_tasks
- View tasks in hierarchical tree format with unlimited depth visualizationcreate_task
- Create tasks at any hierarchy level withparentId
(supports unlimited nesting)get_task
- Get detailed task information including hierarchy relationshipsupdate_task
- Edit tasks, metadata, or move between hierarchy levels withparentId
delete_task
- Delete task and all child tasks recursivelymove_task
- Dedicated tool for moving tasks within hierarchy structuremigrate_subtasks
- Automatic migration tool for converting legacy subtasks to unified model
Advanced Task Management (AI Agent Tools)
parse_prd
- Parse Product Requirements Documents and automatically generate structured tasksget_next_task_recommendation
- Get intelligent task recommendations based on dependencies, priorities, and complexityanalyze_task_complexity
- Analyze task complexity and suggest breaking down overly complex tasksinfer_task_progress
- Analyze codebase to infer task completion status from implementation evidenceresearch_task
- Guide AI agents to perform comprehensive web research with memory integrationgenerate_research_queries
- Generate intelligent, targeted web search queries for task research
Legacy Subtask Management (Backward Compatibility)
list_subtasks
- View child tasks (legacy compatibility, now uses unified Task model)create_subtask
- Create child tasks (legacy compatibility, creates tasks withparentId
)get_subtask
- Get task information (legacy compatibility for existing subtasks)update_subtask
- Edit child tasks (legacy compatibility, uses unified Task operations)delete_subtask
- Delete child tasks (legacy compatibility, deletes tasks recursively)
Agent Memory Management
create_memory
- Store new memories with title and detailed contentsearch_memories
- Find memories using intelligent multi-field search with relevance scoringget_memory
- Get detailed memory informationlist_memories
- List memories with optional filteringupdate_memory
- Edit memory title, content, metadata, or categorizationdelete_memory
- Delete a memory (requires confirmation)
Important: All tools require a workingDirectory
parameter to specify where the data should be stored. This enables project-specific task and memory management.
Installation
Quick Start
Global Installation
Usage
Storage Modes
The MCP server supports two storage modes:
📁 Project-Specific Mode (Default)
Data is stored in .agentic-tools-mcp/
subdirectories within each project's working directory.
🌐 Global Directory Mode
Use the --claude
flag to store all data in a standardized global directory:
- Windows:
C:\Users\{username}\.agentic-tools-mcp\
- macOS/Linux:
~/.agentic-tools-mcp/
When to use --claude
flag:
- With Claude Desktop client (non-project-specific usage)
- When you want a single global workspace for all tasks and memories
- For AI assistants that work across multiple projects
Note: When using --claude
flag, the workingDirectory
parameter in all tools is ignored and the global directory is used instead.
With Claude Desktop
Project-Specific Mode (Default)
Global Directory Mode (Recommended for Claude Desktop)
Note: The server now includes both task management and agent memories features.
With AugmentCode
Project-Specific Mode (Default)
- Open Augment Settings Panel (gear icon)
- Add MCP server:
- Name:
agentic-tools
- Command:
npx -y @pimzino/agentic-tools-mcp
- Name:
- Restart VS Code
Global Directory Mode
- Open Augment Settings Panel (gear icon)
- Add MCP server:
- Name:
agentic-tools
- Command:
npx -y @pimzino/agentic-tools-mcp --claude
- Name:
- Restart VS Code
Features Available: Task management, agent memories, and text-based search capabilities.
With VS Code Extension (Recommended)
For the best user experience, install the Agentic Tools MCP Companion VS Code extension:
- Clone the companion extension repository
- Open it in VS Code and press
F5
to run in development mode - Enjoy a beautiful GUI interface for all task and memory management
Benefits of using both together:
- 🎯 Visual Task Management: Rich forms with priority, complexity, status, tags, and time tracking
- 🎨 Enhanced UI: Status emojis, priority badges, and visual indicators
- 🔄 Real-time Sync: Changes in VS Code instantly available to AI assistants
- 📁 Project Integration: Seamlessly integrated with your workspace
- 🤖 AI Collaboration: Human planning with AI execution for optimal productivity
With Other MCP Clients
The server uses STDIO transport and can be integrated with any MCP-compatible client:
Project-Specific Mode
Global Directory Mode
Data Models
Project
Task (Unified Model v1.8.0 - Unlimited Hierarchy)
Legacy Subtask (Deprecated in v1.8.0)
The separate Subtask interface has been replaced by the unified Task model. Legacy subtasks are automatically migrated to tasks with parentId
field. This ensures unlimited hierarchy depth while maintaining all rich features at every level.
Memory
Example Workflow
- Create a Project
- Add Enhanced Tasks
- Break Down Tasks
- Track Progress
Agent Memories Workflow
- Create a Memory
- Search Memories
- List and Manage
📖 Quick Start: See docs/QUICK_START_MEMORIES.md for a step-by-step guide to agent memories.
Data Storage
- Project-specific: Each working directory has its own isolated task and memory data
- File-based: Task data stored in
.agentic-tools-mcp/tasks/
, memory data in.agentic-tools-mcp/memories/
- Git-trackable: All data can be committed alongside your project code
- Persistent: All data persists between server restarts
- Atomic: All operations are atomic to prevent data corruption
- JSON Storage: Simple file-based storage for efficient memory organization
- Backup-friendly: Simple file-based storage for easy backup and migration
Storage Structure
Working Directory Parameter
All MCP tools require a workingDirectory
parameter that specifies:
- Where to store the
.agentic-tools-mcp/
folder (in project-specific mode) - Which project's task and memory data to access
- Enables multiple projects to have separate task lists and memory stores
Note: When the server is started with the --claude
flag, the workingDirectory
parameter is ignored and a global user directory is used instead (~/.agentic-tools-mcp/
on macOS/Linux or C:\Users\{username}\.agentic-tools-mcp\
on Windows).
Benefits of Project-Specific Storage
- Git Integration: Task and memory data can be committed with your code
- Team Collaboration: Share task lists and agent memories via version control
- Project Isolation: Each project has its own task management and memory system
- Multi-Project Workflow: Work on multiple projects simultaneously with isolated memories
- Backup & Migration: File-based storage travels with your code
- Text Search: Simple content-based memory search for intelligent context retrieval
- Agent Continuity: Persistent agent memories across sessions and deployments
Error Handling
- Validation: All inputs are validated with comprehensive error messages
- Directory Validation: Ensures working directory exists and is accessible
- Referential Integrity: Prevents orphaned tasks/subtasks with cascade deletes
- Unique Names: Enforces unique names within scope (project/task)
- Confirmation: Destructive operations require explicit confirmation
- Graceful Degradation: Detailed error messages for troubleshooting
- Storage Errors: Clear messages when storage initialization fails
Development
Building from Source
Project Structure
Troubleshooting
Common Issues
"Working directory does not exist"
- Ensure the path exists and is accessible
- Use absolute paths for reliability
- Check directory permissions
"Text search returns no results" (Agent Memories)
- Try using different keywords or phrases
- Check that memories contain the search terms
- Verify that the query content matches memory content
"Memory files not found" (Agent Memories)
- Ensure the working directory exists and is writable
- Check that the .agentic-tools-mcp/memories directory was created
Version History
See CHANGELOG.md for detailed version history and release notes.
Current Version: 1.8.0
- 🚀 NEW: Unified Task Model: Single task interface supporting unlimited nesting depth
- 🚀 NEW: Unlimited Hierarchy: Tasks → Subtasks → Sub-subtasks → infinite depth nesting
- 🚀 NEW: Automatic Migration: Seamless upgrade from 3-level to unlimited depth model
- 🚀 NEW: Enhanced Tree Display: Hierarchical visualization with level indicators and unlimited depth
- 🚀 NEW: Hierarchy Tools:
move_task
,migrate_subtasks
for unlimited depth management - ✅ Rich Features at All Levels: Every task gets priority, complexity, dependencies, tags, and time tracking
- ✅ Enhanced Task Management: Rich metadata with dependencies, priority, complexity, status, tags, and time tracking
- ✅ Advanced AI Agent Tools: PRD parsing, task recommendations, complexity analysis, progress inference, and research guidance
- ✅ Intelligent Task Dependencies: Dependency validation and workflow management across hierarchy
- ✅ Priority & Complexity System: 1-10 scale prioritization and complexity estimation at every level
- ✅ Enhanced Status Workflow: pending → in-progress → blocked → done status tracking
- ✅ Tag-Based Organization: Flexible categorization and filtering system
- ✅ Time Tracking: Estimated and actual hours for project planning
- ✅ Hybrid Research Integration: Web research with memory caching for AI agents
- ✅ Complete task management system with unlimited hierarchical organization
- ✅ Agent memories with title/content architecture and JSON file storage
- ✅ Intelligent multi-field search with relevance scoring
- ✅ Project-specific storage with comprehensive MCP tools
- ✅ Global directory mode with --claude flag for Claude Desktop
- ✅ VS Code extension ecosystem integration
Acknowledgments
We're grateful to the open-source community and the following projects that make this MCP server possible:
Core Technologies
- @modelcontextprotocol/sdk - The foundation for MCP server implementation
- Node.js File System - Reliable file-based storage for memory persistence
- TypeScript - Type-safe JavaScript development
- Node.js - JavaScript runtime environment
Development & Validation
- Zod - TypeScript-first schema validation for robust input handling
- ESLint - Code quality and consistency
- Prettier - Code formatting
File Storage & Search
- JSON - Simple, human-readable data format for memory storage
- Text Search - Efficient content-based search across memory files
Special Thanks
- Open Source Community - For creating the tools and libraries that make this project possible
License
MIT License - see LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit issues and pull requests.
Development Setup
Related Projects
🖥️ VS Code Extension
Agentic Tools MCP Companion - A beautiful VS Code extension that provides a GUI interface for this MCP server.
Key Features:
- 🎯 Visual Task Management: Rich GUI with enhanced task metadata forms
- 📝 Enhanced Forms: Priority, complexity, status, tags, and time tracking
- 🎨 Visual Indicators: Status emojis, priority badges, and complexity indicators
- 📊 Rich Tooltips: Complete task information on hover
- 🔄 Real-time Sync: Instant synchronization with MCP server data
- � Responsive Design: Adaptive forms that work on different screen sizes
Perfect for:
- Visual task management and planning
- Teams who prefer GUI interfaces
- Project managers who need rich task metadata
- Anyone who wants beautiful task organization in VS Code
Support
For issues and questions, please use the GitHub issue tracker.
Documentation
- 📖 API Reference - Complete tool documentation
- 🧠 Agent Memories Guide - Comprehensive memory system guide
- 🚀 Quick Start: Memories - Get started with agent memories
- 📋 Changelog - Version history and release notes
Getting Help
- 🐛 Report bugs via GitHub issues
- 💡 Request features via GitHub discussions
- 🖥️ VS Code Extension Issues: Report extension-specific issues at agentic-tools-mcp-companion
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A Model Context Protocol server providing AI assistants with comprehensive project, task, and subtask management capabilities with project-specific storage.
Related MCP Servers
- -securityFlicense-qualityA versatile Model Context Protocol server that enables AI assistants to manage calendars, track tasks, handle emails, search the web, and control smart home devices.Last updated -2Python
- -security-license-qualityA Model Context Protocol server implementation that enables AI assistants to interact with Linear project management systems, allowing them to create, retrieve, and modify data related to issues, projects, teams, and users.Last updated -202TypeScript
- -securityFlicense-qualityA Model Context Protocol server that provides persistent task management capabilities for AI assistants, allowing them to create, update, and track tasks beyond their usual context limitations.Last updated -1TypeScript
- -securityFlicense-qualityA comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.Last updated -16TypeScript