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
parentIdfield - 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 withparentIddelete_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
npx -y @pimzino/agentic-tools-mcp
Global Installation
npm install -g @pimzino/agentic-tools-mcp
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.
npx -y @pimzino/agentic-tools-mcp
🌐 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/
npx -y @pimzino/agentic-tools-mcp --claude
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)
{
"mcpServers": {
"agentic-tools": {
"command": "npx",
"args": ["-y", "@pimzino/agentic-tools-mcp"]
}
}
}
Global Directory Mode (Recommended for Claude Desktop)
{
"mcpServers": {
"agentic-tools": {
"command": "npx",
"args": ["-y", "@pimzino/agentic-tools-mcp", "--claude"]
}
}
}
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
F5to 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
npx -y @pimzino/agentic-tools-mcp
Global Directory Mode
npx -y @pimzino/agentic-tools-mcp --claude
Data Models
Project
{
id: string; // Unique identifier
name: string; // Project name
description: string; // Project overview
createdAt: string; // ISO timestamp
updatedAt: string; // ISO timestamp
}
Task (Unified Model v1.8.0 - Unlimited Hierarchy)
{
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)
}
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
{
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
}
Example Workflow
-
Create a Project
Use create_project with: - workingDirectory="/path/to/your/project" - name="Website Redesign" - description="Complete overhaul of company website" -
Add Enhanced Tasks
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 -
Break Down Tasks
Use create_subtask with: - workingDirectory="/path/to/your/project" - name="Create wireframes" - details="Sketch basic layout structure" - taskId="[task-id-from-step-2]" -
Track Progress
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 Memories Workflow
-
Create a Memory
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" -
Search Memories
Use search_memories with: - workingDirectory="/path/to/your/project" - query="user preferences responses" - limit=5 - threshold=0.3 - category="user_preferences" -
List and Manage
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)
📖 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
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
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
git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start
Project Structure
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
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_subtasksfor 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
git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start
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