1.7.0 ā€¢ Published 5 months ago

@pimzino/agentic-tools-mcp v1.7.0

Weekly downloads
-
License
MIT
Repository
github
Last release
5 months ago

Agentic Tools MCP Server

npm version npm downloads GitHub stars GitHub license Node.js Version

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

  • Projects: Organize work into distinct projects with descriptions
  • Enhanced Tasks: Rich task metadata with dependencies, priority, complexity, status, tags, and time tracking
  • Simple Subtasks: Focused implementation tracking with name, details, and completion
  • Hierarchical Organization: Projects ā†’ Tasks ā†’ Subtasks
  • Intelligent Dependencies: Task dependency management with validation
  • Priority & Complexity: 1-10 scale prioritization and complexity estimation
  • 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
  • Progress Tracking: Monitor completion status at all 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

  • list_tasks - View tasks (optionally filtered by project)
  • create_task - Create a new task with enhanced metadata (dependencies, priority, complexity, status, tags, time tracking)
  • get_task - Get detailed task information
  • update_task - Edit task details, metadata, or mark as completed
  • delete_task - Delete task and all associated subtasks

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

Subtask Management

  • list_subtasks - View subtasks (filtered by task or project)
  • create_subtask - Create a new subtask within a task
  • get_subtask - Get detailed subtask information
  • update_subtask - Edit subtask details or mark as completed
  • delete_subtask - Delete a specific subtask

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 (Enhanced v1.7.0)

{
  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

  // Enhanced metadata fields (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)
}

Subtask

{
  id: string;           // Unique identifier
  name: string;         // Subtask name
  details: string;      // Enhanced description
  taskId: string;       // Parent task reference
  projectId: string;    // Parent project reference
  completed: boolean;   // Completion status
  createdAt: string;    // ISO timestamp
  updatedAt: string;    // ISO timestamp
}

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

  • āœ… 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
  • āœ… Priority & Complexity System: 1-10 scale prioritization and complexity estimation
  • āœ… 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 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

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

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
mcpmodel-context-protocoltask-managementagent-memoriesjson-storagefile-storagetext-searchproductivityai-tools
@modelcontextprotocol/sdkzod
1.7.0

5 months ago

1.6.0

5 months ago

1.5.0

5 months ago

1.4.0

5 months ago

1.3.2

5 months ago

1.3.1

5 months ago

1.3.0

5 months ago

1.2.3

5 months ago

1.2.2

5 months ago

1.2.1

5 months ago

1.2.0

5 months ago

1.1.0

5 months ago

1.0.0

5 months ago