# Agentic Tools Mcp

> A comprehensive Model Context Protocol (MCP) server providing AI assistants with powerful task management and agent memories capabilities with project-specific storage.

- **Type:** MCP server
- **Install:** `agentstack add mcp-pimzino-agentic-tools-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Pimzino](https://agentstack.voostack.com/s/pimzino)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Pimzino](https://github.com/Pimzino)
- **Source:** https://github.com/Pimzino/agentic-tools-mcp

## Install

```sh
agentstack add mcp-pimzino-agentic-tools-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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; // 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 dir

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Pimzino](https://github.com/Pimzino)
- **Source:** [Pimzino/agentic-tools-mcp](https://github.com/Pimzino/agentic-tools-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pimzino-agentic-tools-mcp
- Seller: https://agentstack.voostack.com/s/pimzino
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.