Content
# Agentic Tools MCP Server
[](https://badge.fury.io/js/@pimzino%2Fagentic-tools-mcp)
[](https://www.npmjs.com/package/@pimzino/agentic-tools-mcp)
[](https://github.com/Pimzino/agentic-tools-mcp/stargazers)
[](https://github.com/Pimzino/agentic-tools-mcp/blob/main/LICENSE)
[](https://nodejs.org/)
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](https://github.com/Pimzino/agentic-tools-mcp-companion)** - 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 directory
- `create_project` - Create a new project in a working directory
- `get_project` - Get detailed project information
- `update_project` - Edit project name/description
- `delete_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 visualization
- `create_task` - Create tasks at any hierarchy level with `parentId` (supports unlimited nesting)
- `get_task` - Get detailed task information including hierarchy relationships
- `update_task` - Edit tasks, metadata, or move between hierarchy levels with `parentId`
- `delete_task` - Delete task and all child tasks recursively
- `move_task` - Dedicated tool for moving tasks within hierarchy structure
- `migrate_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 tasks
- `get_next_task_recommendation` - Get intelligent task recommendations based on dependencies, priorities, and complexity
- `analyze_task_complexity` - Analyze task complexity and suggest breaking down overly complex tasks
- `infer_task_progress` - Analyze codebase to infer task completion status from implementation evidence
- `research_task` - Guide AI agents to perform comprehensive web research with memory integration
- `generate_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 with `parentId`)
- `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 content
- `search_memories` - Find memories using intelligent multi-field search with relevance scoring
- `get_memory` - Get detailed memory information
- `list_memories` - List memories with optional filtering
- `update_memory` - Edit memory title, content, metadata, or categorization
- `delete_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
```bash
npx -y @pimzino/agentic-tools-mcp
```
### Global Installation
```bash
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.
```bash
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/`
```bash
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)
```json
{
"mcpServers": {
"agentic-tools": {
"command": "npx",
"args": ["-y", "@pimzino/agentic-tools-mcp"]
}
}
}
```
#### Global Directory Mode (Recommended for Claude Desktop)
```json
{
"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)
1. Open Augment Settings Panel (gear icon)
2. Add MCP server:
- **Name**: `agentic-tools`
- **Command**: `npx -y @pimzino/agentic-tools-mcp`
3. Restart VS Code
#### Global Directory Mode
1. Open Augment Settings Panel (gear icon)
2. Add MCP server:
- **Name**: `agentic-tools`
- **Command**: `npx -y @pimzino/agentic-tools-mcp --claude`
3. 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**](https://github.com/Pimzino/agentic-tools-mcp-companion) VS Code extension:
1. Clone the companion extension repository
2. Open it in VS Code and press `F5` to run in development mode
3. 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
```bash
npx -y @pimzino/agentic-tools-mcp
```
#### Global Directory Mode
```bash
npx -y @pimzino/agentic-tools-mcp --claude
```
## Data Models
### Project
```typescript
{
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)
```typescript
{
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
```typescript
{
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
1. **Create a Project**
```
Use create_project with:
- workingDirectory="/path/to/your/project"
- name="Website Redesign"
- description="Complete overhaul of company website"
```
2. **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
```
3. **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]"
```
4. **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
1. **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"
```
2. **Search Memories**
```
Use search_memories with:
- workingDirectory="/path/to/your/project"
- query="user preferences responses"
- limit=5
- threshold=0.3
- category="user_preferences"
```
3. **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](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
```bash
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](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](https://github.com/modelcontextprotocol/typescript-sdk)** - The foundation for MCP server implementation
- **[Node.js File System](https://nodejs.org/api/fs.html)** - Reliable file-based storage for memory persistence
- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript development
- **[Node.js](https://nodejs.org/)** - JavaScript runtime environment
### Development & Validation
- **[Zod](https://zod.dev/)** - TypeScript-first schema validation for robust input handling
- **[ESLint](https://eslint.org/)** - Code quality and consistency
- **[Prettier](https://prettier.io/)** - 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
```bash
git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start
```
## Related Projects
### 🖥️ VS Code Extension
**[Agentic Tools MCP Companion](https://github.com/Pimzino/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](docs/API_REFERENCE.md)** - Complete tool documentation
- 🧠 **[Agent Memories Guide](docs/AGENT_MEMORIES.md)** - Comprehensive memory system guide
- 🚀 **[Quick Start: Memories](docs/QUICK_START_MEMORIES.md)** - Get started with agent memories
- 📋 **[Changelog](CHANGELOG.md)** - 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](https://github.com/Pimzino/agentic-tools-mcp-companion/issues)
Connection Info
You Might Also Like
No recommendations available