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 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

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)

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 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

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

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 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_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

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