Back to search
agentic-tools-mcp
MCP serverGitHub
A comprehensive Model Context Protocol (MCP) server providing AI assistants with powerful task management and agent memories capabilities with project-specific storage.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/pimzino--agentic-tools-mcp)HTML
<a href="/listings/pimzino--agentic-tools-mcp"><img src="/api/listings/pimzino--agentic-tools-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Quick Start
npx -y @pimzino/agentic-tools-mcp
Global Installation
npm install -g @pimzino/agentic-tools-mcp
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 533 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.