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:
3. Name: agentic-tools
4. Command: npx -y @pimzino/agentic-tools-mcp
5. Restart VS Code

Global Directory Mode

1. Open Augment Settings Panel (gear icon)
2. Add MCP server:
3. Name: agentic-tools
4. Command: npx -y @pimzino/agentic-tools-mcp --claude
5. 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:
2. workingDirectory="/path/to/your/project"
3. name="Website Redesign"

4. description="Complete overhaul of company website" ```

5. Add Enhanced Tasks ``` Use create_task with:

6. workingDirectory="/path/to/your/project"
7. name="Design mockups"
8. details="Create wireframes and high-fidelity designs"
9. projectId="[project-id-from-step-1]"
10. priority=8 (high priority)
11. complexity=6 (above average complexity)
12. status="pending"
13. tags=["design", "ui", "mockups"]

14. estimatedHours=16 ```

15. Break Down Tasks ``` Use create_subtask with:

16. workingDirectory="/path/to/your/project"
17. name="Create wireframes"
18. details="Sketch basic layout structure"

19. taskId="[task-id-from-step-2]" ```

20. 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:
2. workingDirectory="/path/to/your/project"
3. title="User prefers concise technical responses"
4. content="The user has explicitly stated they prefer concise responses with technical explanations. They value brevity but want detailed technical information when relevant."
5. metadata={"source": "conversation", "confidence": 0.9}

6. category="user_preferences" ```

7. Search Memories ``` Use search_memories with:

8. workingDirectory="/path/to/your/project"
9. query="user preferences responses"
10. limit=5
11. threshold=0.3

12. category="user_preferences" ```

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