Agentic Tools

Proporciona a los asistentes de IA capacidades avanzadas de gestión de tareas y memoria utilizando almacenamiento local de archivos JSON.

GitHub
88
Prueba este MCPPatrocinado

Documentación

Servidor MCP de Agentic Tools

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

Un servidor integral de Protocolo de Contexto de Modelo (MCP) que proporciona a los asistentes de IA potentes capacidades de gestión avanzada de tareas y memorias de agente con almacenamiento específico del proyecto.

🔗 Ecosistema

Este servidor MCP es parte de un ecosistema completo de gestión de tareas y memorias:

  • 🖥️ Extensión de VS Code - Interfaz gráfica hermosa para gestionar tareas y memorias directamente en VS Code
  • ⚡ Servidor MCP (este repositorio) - Herramientas avanzadas de agente de IA y API para gestión inteligente de tareas

💡 Consejo Profesional: ¡Usa ambos juntos para la máxima experiencia de productividad! La extensión de VS Code proporciona una interfaz visual mientras que el servidor MCP permite la integración con asistentes de IA con características avanzadas como análisis de PRD, recomendaciones de tareas y capacidades de investigación.

Características

🎯 Sistema Avanzado de Gestión de Tareas con Jerarquía Ilimitada (v1.8.0)

  • Proyectos: Organiza el trabajo en proyectos distintos con descripciones
  • Modelo de Tarea Unificado: Interfaz de tarea única que soporta profundidad de anidamiento ilimitada
  • Jerarquía Ilimitada: Tareas → Subtareas → Sub-subtareas → anidamiento de profundidad infinita
  • Características Ricas en Todos los Niveles: Cada tarea obtiene prioridad, complejidad, dependencias, etiquetas y seguimiento de tiempo
  • Relaciones Padre-Hijo: Organización flexible de jerarquía con el campo parentId
  • Seguimiento de Nivel: Cálculo automático del nivel de jerarquía e indicadores visuales
  • Visualización de Árbol: Visualización completa de árbol jerárquico con profundidad ilimitada
  • Dependencias Inteligentes: Gestión de dependencias de tareas con validación en toda la jerarquía
  • Prioridad y Complejidad: Priorización en escala 1-10 y estimación de complejidad en cada nivel
  • Seguimiento de Estado Mejorado: flujo de trabajo de estados pendiente, en progreso, bloqueado, hecho
  • Organización Basada en Etiquetas: Categorización y filtrado flexibles
  • Seguimiento de Tiempo: Horas estimadas y reales para la planificación de proyectos
  • Migración Automática: Actualización sin problemas del antiguo modelo de 3 niveles al modelo de profundidad ilimitada
  • Seguimiento de Progreso: Monitorear el estado de finalización en todos los niveles de jerarquía
  • Almacenamiento Específico del Proyecto: Cada directorio de trabajo tiene datos de tareas aislados
  • Rastreable con Git: Los datos de tareas se pueden confirmar junto con tu código

🧠 Sistema de Memorias de Agente

  • Memoria Persistente: Almacena y recupera memorias de agente con títulos y contenido detallado
  • Búsqueda Inteligente: Búsqueda de texto en múltiples campos con puntuación de relevancia en títulos, contenido y categorías
  • Clasificación Inteligente: Algoritmo de puntuación avanzado prioriza coincidencias de título (60%), coincidencias de contenido (30%) y bonificaciones de categoría (20%)
  • Metadatos Ricos: Sistema de metadatos flexible para contexto mejorado
  • Almacenamiento JSON: Archivos JSON individuales organizados por categoría, nombrados según los títulos de memoria
  • Específico del Proyecto: Almacenamiento de memoria aislado por directorio de trabajo

🔧 Herramientas MCP Disponibles

Gestión de Proyectos

  • list_projects - Ver todos los proyectos en un directorio de trabajo
  • create_project - Crear un nuevo proyecto en un directorio de trabajo
  • get_project - Obtener información detallada del proyecto
  • update_project - Editar nombre/descripción del proyecto
  • delete_project - Eliminar el proyecto y todos los datos asociados

Gestión de Tareas (Jerarquía Ilimitada v1.8.0)

  • list_tasks - Ver tareas en formato de árbol jerárquico con visualización de profundidad ilimitada
  • create_task - Crear tareas en cualquier nivel de jerarquía con parentId (soporta anidamiento ilimitado)
  • get_task - Obtener información detallada de la tarea incluyendo relaciones de jerarquía
  • update_task - Editar tareas, metadatos o mover entre niveles de jerarquía con parentId
  • delete_task - Eliminar tarea y todas las subtareas recursivamente
  • move_task - Herramienta dedicada para mover tareas dentro de la estructura jerárquica
  • migrate_subtasks - Herramienta de migración automática para convertir subtareas heredadas al modelo unificado

Gestión Avanzada de Tareas (Herramientas de Agente de IA)

  • parse_prd - Analizar documentos de requisitos de producto y generar automáticamente tareas estructuradas
  • get_next_task_recommendation - Obtener recomendaciones inteligentes de tareas basadas en dependencias, prioridades y complejidad
  • analyze_task_complexity - Analizar la complejidad de las tareas y sugerir desglosar tareas demasiado complejas
  • infer_task_progress - Analizar el código base para inferir el estado de finalización de tareas a partir de evidencia de implementación
  • research_task - Guiar a los agentes de IA para realizar investigación web exhaustiva con integración de memoria
  • generate_research_queries - Generar consultas de búsqueda web inteligentes y específicas para la investigación de tareas

Gestión de Subtareas Heredadas (Compatibilidad hacia atrás)

  • list_subtasks - Ver subtareas (compatibilidad heredada, ahora usa el modelo de Tarea unificado)
  • create_subtask - Crear subtareas (compatibilidad heredada, crea tareas con parentId)
  • get_subtask - Obtener información de tarea (compatibilidad heredada para subtareas existentes)
  • update_subtask - Editar subtareas (compatibilidad heredada, usa operaciones de Tarea unificadas)
  • delete_subtask - Eliminar subtareas (compatibilidad heredada, elimina tareas recursivamente)

Gestión de Memorias de Agente

  • create_memory - Almacenar nuevas memorias con título y contenido detallado
  • search_memories - Encontrar memorias usando búsqueda inteligente de múltiples campos con puntuación de relevancia
  • get_memory - Obtener información detallada de la memoria
  • list_memories - Listar memorias con filtrado opcional
  • update_memory - Editar título, contenido, metadatos o categorización de la memoria
  • delete_memory - Eliminar una memoria (requiere confirmación)

Importante: Todas las herramientas requieren un parámetro workingDirectory para especificar dónde se deben almacenar los datos. Esto permite la gestión de tareas y memorias específica del proyecto.

Instalación

Inicio Rápido

npx -y @pimzino/agentic-tools-mcp

Instalación Global

npm install -g @pimzino/agentic-tools-mcp

Uso

Modos de Almacenamiento

El servidor MCP soporta dos modos de almacenamiento:

📁 Modo Específico del Proyecto (Predeterminado)

Los datos se almacenan en subdirectorios .agentic-tools-mcp/ dentro del directorio de trabajo de cada proyecto.

npx -y @pimzino/agentic-tools-mcp

🌐 Modo de Directorio Global

Usa la bandera --claude para almacenar todos los datos en un directorio global estandarizado:

  • Windows: C:\Users\{username}\.agentic-tools-mcp\
  • macOS/Linux: ~/.agentic-tools-mcp/
npx -y @pimzino/agentic-tools-mcp --claude

Cuándo usar la bandera --claude:

  • Con el cliente Claude Desktop (uso no específico del proyecto)
  • Cuando quieras un único espacio de trabajo global para todas las tareas y memorias
  • Para asistentes de IA que trabajan en múltiples proyectos

Nota: Al usar la bandera --claude, el parámetro workingDirectory en todas las herramientas se ignora y se usa el directorio global en su lugar.

Con Claude Desktop

Modo Específico del Proyecto (Predeterminado)

{
  "mcpServers": {
    "agentic-tools": {
      "command": "npx",
      "args": ["-y", "@pimzino/agentic-tools-mcp"]
    }
  }
}

Modo de Directorio Global (Recomendado para Claude Desktop)

{
  "mcpServers": {
    "agentic-tools": {
      "command": "npx",
      "args": ["-y", "@pimzino/agentic-tools-mcp", "--claude"]
    }
  }
}

Nota: El servidor ahora incluye tanto la gestión de tareas como las características de memorias de agente.

Con AugmentCode

Modo Específico del Proyecto (Predeterminado)

  1. Abre el Panel de Configuración de Augment (icono de engranaje)
  2. Agrega el servidor MCP:
    • Nombre: agentic-tools
    • Comando: npx -y @pimzino/agentic-tools-mcp
  3. Reinicia VS Code

Modo de Directorio Global

  1. Abre el Panel de Configuración de Augment (icono de engranaje)
  2. Agrega el servidor MCP:
    • Nombre: agentic-tools
    • Comando: npx -y @pimzino/agentic-tools-mcp --claude
  3. Reinicia VS Code

Características Disponibles: Gestión de tareas, memorias de agente y capacidades de búsqueda basada en texto.

Con la Extensión de VS Code (Recomendado)

Para la mejor experiencia de usuario, instala la extensión de VS Code Agentic Tools MCP Companion:

  1. Clona el repositorio de la extensión complementaria
  2. Ábrelo en VS Code y presiona F5 para ejecutarlo en modo de desarrollo
  3. Disfruta de una interfaz gráfica hermosa para toda la gestión de tareas y memorias

Beneficios de usar ambos juntos:

  • 🎯 Gestión Visual de Tareas: Formularios ricos con prioridad, complejidad, estado, etiquetas y seguimiento de tiempo
  • 🎨 UI Mejorada: Emojis de estado, insignias de prioridad e indicadores visuales
  • 🔄 Sincronización en Tiempo Real: Cambios en VS Code disponibles al instante para asistentes de IA
  • 📁 Integración con Proyectos: Integrado sin problemas con tu espacio de trabajo
  • 🤖 Colaboración con IA: Planificación humana con ejecución de IA para una productividad óptima

Con Otros Clientes MCP

El servidor usa transporte STDIO y se puede integrar con cualquier cliente compatible con MCP:

Modo Específico del Proyecto

npx -y @pimzino/agentic-tools-mcp

Modo de Directorio Global

npx -y @pimzino/agentic-tools-mcp --claude

Modelos de Datos

Proyecto

{
  id: string;           // Unique identifier
  name: string;         // Project name
  description: string;  // Project overview
  createdAt: string;    // ISO timestamp
  updatedAt: string;    // ISO timestamp
}

Tarea (Modelo Unificado v1.8.0 - Jerarquía Ilimitada)

{
  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)
}

Subtarea Heredada (Obsoleta en v1.8.0)

La interfaz separada de Subtarea ha sido reemplazada por el modelo de Tarea unificado. Las subtareas heredadas se migran automáticamente a tareas con el campo parentId. Esto asegura profundidad de jerarquía ilimitada mientras se mantienen todas las características ricas en cada nivel.

Memoria

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

Ejemplo de Flujo de Trabajo

  1. Crear un Proyecto

    Use create_project with:
- workingDirectory="/path/to/your/project"
- name="Website Redesign"
- description="Complete overhaul of company website"

  2. Agregar Tareas Mejoradas

    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. Desglosar Tareas

    Use create_subtask with:
- workingDirectory="/path/to/your/project"
- name="Create wireframes"
- details="Sketch basic layout structure"
- taskId="[task-id-from-step-2]"

  4. Seguimiento del Progreso

    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)

Flujo de Trabajo de Memorias de Agente

  1. Crear una Memoria

    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. Buscar Memorias

    Use search_memories with:
- workingDirectory="/path/to/your/project"
- query="user preferences responses"
- limit=5
- threshold=0.3
- category="user_preferences"

  3. Listar y Gestionar

    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)

📖 Inicio Rápido: Consulta docs/QUICK_START_MEMORIES.md para una guía paso a paso sobre memorias de agente.

Almacenamiento de Datos

  • Específico del proyecto: Cada directorio de trabajo tiene sus propios datos de tareas y memorias aislados
  • Basado en archivos: Datos de tareas almacenados en .agentic-tools-mcp/tasks/, datos de memoria en .agentic-tools-mcp/memories/
  • Rastreable con Git: Todos los datos se pueden confirmar junto con el código de tu proyecto
  • Persistente: Todos los datos persisten entre reinicios del servidor
  • Atómico: Todas las operaciones son atómicas para prevenir la corrupción de datos
  • Almacenamiento JSON: Almacenamiento simple basado en archivos para una organización eficiente de la memoria
  • Amigable con copias de seguridad: Almacenamiento simple basado en archivos para fácil respaldo y migración

Estructura de Almacenamiento

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

Parámetro de Directorio de Trabajo

Todas las herramientas MCP requieren un parámetro workingDirectory que especifica:

  • Dónde almacenar la carpeta .agentic-tools-mcp/ (en modo específico del proyecto)
  • A qué proyecto acceder para datos de tareas y memorias
  • Permite que múltiples proyectos tengan listas de tareas y almacenes de memoria separados

Nota: Cuando el servidor se inicia con la bandera --claude, el parámetro workingDirectory se ignora y se usa un directorio de usuario global en su lugar (~/.agentic-tools-mcp/ en macOS/Linux o C:\Users\{username}\.agentic-tools-mcp\ en Windows).

Beneficios del Almacenamiento Específico del Proyecto

  • Integración con Git: Los datos de tareas y memorias se pueden confirmar con tu código
  • Colaboración en Equipo: Comparte listas de tareas y memorias de agente mediante control de versiones
  • Aislamiento de Proyectos: Cada proyecto tiene su propio sistema de gestión de tareas y memoria
  • Flujo de Trabajo Multi-Proyecto: Trabaja en múltiples proyectos simultáneamente con memorias aisladas
  • Respaldo y Migración: El almacenamiento basado en archivos viaja con tu código
  • Búsqueda de Texto: Búsqueda simple de memoria basada en contenido para recuperación inteligente de contexto
  • Continuidad del Agente: Memorias de agente persistentes entre sesiones y despliegues

Manejo de Errores

  • Validación: Todas las entradas se validan con mensajes de error completos
  • Validación de Directorio: Asegura que el directorio de trabajo exista y sea accesible
  • Integridad Referencial: Previene tareas/subtareas huérfanas con eliminaciones en cascada
  • Nombres Únicos: Aplica nombres únicos dentro del alcance (proyecto/tarea)
  • Confirmación: Las operaciones destructivas requieren confirmación explícita
  • Degradación Elegante: Mensajes de error detallados para solución de problemas
  • Errores de Almacenamiento: Mensajes claros cuando falla la inicialización del almacenamiento

Desarrollo

Compilación desde el Código Fuente

git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start

Estructura del Proyecto

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

Solución de Problemas

Problemas Comunes

"El directorio de trabajo no existe"

  • Asegúrate de que la ruta exista y sea accesible
  • Usa rutas absolutas para mayor confiabilidad
  • Verifica los permisos del directorio "La búsqueda de texto no devuelve resultados" (Memorias del agente)
  • Pruebe con diferentes palabras clave o frases
  • Verifique que las memorias contengan los términos de búsqueda
  • Confirme que el contenido de la consulta coincida con el contenido de la memoria

"Archivos de memoria no encontrados" (Memorias del agente)

  • Asegúrese de que el directorio de trabajo exista y sea escribible
  • Verifique que se haya creado el directorio .agentic-tools-mcp/memories

Historial de versiones

Consulte CHANGELOG.md para obtener un historial de versiones detallado y notas de la versión.

Versión actual: 1.8.0

  • 🚀 NUEVO: Modelo de tareas unificado: Interfaz de tarea única que admite profundidad de anidamiento ilimitada
  • 🚀 NUEVO: Jerarquía ilimitada: Tareas → Subtareas → Sub-subtareas → anidamiento de profundidad infinita
  • 🚀 NUEVO: Migración automática: Actualización sin problemas del modelo de 3 niveles al de profundidad ilimitada
  • 🚀 NUEVO: Visualización de árbol mejorada: Visualización jerárquica con indicadores de nivel y profundidad ilimitada
  • 🚀 NUEVO: Herramientas de jerarquía: move_task, migrate_subtasks para gestión de profundidad ilimitada
  • ✅ Funciones enriquecidas en todos los niveles: Cada tarea obtiene prioridad, complejidad, dependencias, etiquetas y seguimiento de tiempo
  • ✅ Gestión de tareas mejorada: Metadatos enriquecidos con dependencias, prioridad, complejidad, estado, etiquetas y seguimiento de tiempo
  • ✅ Herramientas avanzadas de agente de IA: Análisis de PRD, recomendaciones de tareas, análisis de complejidad, inferencia de progreso y guía de investigación
  • ✅ Dependencias de tareas inteligentes: Validación de dependencias y gestión de flujo de trabajo en toda la jerarquía
  • ✅ Sistema de prioridad y complejidad: Priorización en escala de 1 a 10 y estimación de complejidad en cada nivel
  • ✅ Flujo de trabajo de estado mejorado: Seguimiento de estado pendiente → en curso → bloqueado → completado
  • ✅ Organización basada en etiquetas: Sistema flexible de categorización y filtrado
  • ✅ Seguimiento de tiempo: Horas estimadas y reales para la planificación de proyectos
  • ✅ Integración de investigación híbrida: Investigación web con caché de memoria para agentes de IA
  • ✅ Sistema completo de gestión de tareas con organización jerárquica ilimitada
  • ✅ Memorias del agente con arquitectura de título/contenido y almacenamiento en archivos JSON
  • ✅ Búsqueda inteligente de múltiples campos con puntuación de relevancia
  • ✅ Almacenamiento específico del proyecto con herramientas MCP integrales
  • ✅ Modo de directorio global con la bandera --claude para Claude Desktop
  • ✅ Integración del ecosistema de extensiones de VS Code

Agradecimientos

Agradecemos a la comunidad de código abierto y a los siguientes proyectos que hacen posible este servidor MCP:

Tecnologías principales

Desarrollo y validación

  • Zod - Validación de esquemas centrada en TypeScript para un manejo robusto de entradas
  • ESLint - Calidad y consistencia del código
  • Prettier - Formato de código

Almacenamiento de archivos y búsqueda

  • JSON - Formato de datos simple y legible para el almacenamiento de memoria
  • Búsqueda de texto - Búsqueda eficiente basada en contenido en archivos de memoria

Agradecimientos especiales

  • Comunidad de código abierto - Por crear las herramientas y bibliotecas que hacen posible este proyecto

Licencia

Licencia MIT: consulte el archivo LICENSE para obtener más detalles.

Contribuciones

¡Las contribuciones son bienvenidas! No dude en enviar problemas y solicitudes de extracción.

Configuración de desarrollo

git clone <repository>
cd agentic-tools-mcp
npm install
npm run build
npm start

Proyectos relacionados

🖥️ Extensión de VS Code

Agentic Tools MCP Companion - Una hermosa extensión de VS Code que proporciona una interfaz gráfica para este servidor MCP.

Características principales:

  • 🎯 Gestión visual de tareas: Interfaz gráfica enriquecida con formularios de metadatos de tareas mejorados
  • 📝 Formularios mejorados: Prioridad, complejidad, estado, etiquetas y seguimiento de tiempo
  • 🎨 Indicadores visuales: Emojis de estado, insignias de prioridad e indicadores de complejidad
  • 📊 Información sobre herramientas enriquecida: Información completa de la tarea al pasar el cursor
  • 🔄 Sincronización en tiempo real: Sincronización instantánea con los datos del servidor MCP
  • Diseño adaptable: Formularios adaptativos que funcionan en diferentes tamaños de pantalla

Perfecto para:

  • Gestión y planificación visual de tareas
  • Equipos que prefieren interfaces gráficas
  • Gerentes de proyectos que necesitan metadatos de tareas enriquecidos
  • Cualquier persona que quiera una organización hermosa de tareas en VS Code

Soporte

Para problemas y preguntas, utilice el rastreador de problemas de GitHub.

Documentación

Obtener ayuda

  • 🐛 Informe errores a través de problemas de GitHub
  • 💡 Solicite funciones a través de debates de GitHub
  • 🖥️ Problemas de la extensión de VS Code: Informe problemas específicos de la extensión en agentic-tools-mcp-companion