Valkey AI Tasks

Un sistema de gestión de tareas para agentes de IA que utiliza Valkey como su capa de persistencia.

GitHub
25
Prueba este MCPPatrocinado

Documentación

Servidor de Gestión de Tareas Valkey MCP

Lint Publish Container Release Conventional Commits

Un sistema de gestión de tareas que implementa el Protocolo de Contexto de Modelo (MCP) para una integración perfecta con herramientas de IA agénticas. Este sistema permite a los agentes de IA crear, gestionar y realizar seguimiento de tareas dentro de planes utilizando Valkey como capa de persistencia.

Características

  • Gestión de planes (crear, leer, actualizar, eliminar)
  • Gestión de tareas (crear, leer, actualizar, eliminar)
  • Ordenación y priorización de tareas
  • Seguimiento de estado de tareas
  • Soporte de notas con formato Markdown tanto para planes como para tareas
  • Servidor MCP para integración con agentes de IA
  • Soporta protocolos de transporte STDIO, SSE y Streamable HTTP
  • Soporte de contenedores Docker para despliegue fácil

Arquitectura

El sistema está construido usando:

  • Go: Para la implementación del backend
  • Valkey: Para la persistencia de datos
  • Valkey-Glide v2: Cliente Go oficial para Valkey
  • Model Context Protocol: Para la integración con agentes de IA

Inicio Rápido

Despliegue con Docker

El servidor MCP está diseñado para ejecutar un protocolo a la vez por simplicidad. Por defecto, todos los protocolos están deshabilitados y necesitas habilitar explícitamente el que quieras usar.

Requisitos Previos

  1. Crea un volumen con nombre para la persistencia de datos de Valkey: 
    docker volume create valkey-data

Ejecución con SSE (Recomendado para la mayoría de los casos de uso)

docker run -d --name valkey-mcp \
  -p 8080:8080 \
  -p 6379:6379 \
  -v valkey-data:/data \
  -e ENABLE_SSE=true \
  ghcr.io/jbrinkman/valkey-ai-tasks:latest

Ejecución con Streamable HTTP

docker run -d --name valkey-mcp \
  -p 8080:8080 \
  -p 6379:6379 \
  -v valkey-data:/data \
  -e ENABLE_STREAMABLE_HTTP=true \
  ghcr.io/jbrinkman/valkey-ai-tasks:latest

Ejecución con STDIO (Para comunicación directa entre procesos)

docker run -i --rm --name valkey-mcp \
  -v valkey-data:/data \
  -e ENABLE_STDIO=true \
  ghcr.io/jbrinkman/valkey-ai-tasks:latest

Uso de las Imágenes de Contenedor

Las imágenes de contenedor se publican en GitHub Container Registry y se pueden descargar usando:

docker pull ghcr.io/jbrinkman/valkey-ai-tasks:latest
# or a specific version
docker pull ghcr.io/jbrinkman/valkey-ai-tasks:1.1.0

Referencia de la API MCP

El servidor MCP soporta dos protocolos de transporte: Server-Sent Events (SSE) y Streamable HTTP. Cada protocolo expone endpoints similares pero con diferentes patrones de interacción.

Endpoints de Server-Sent Events (SSE)

  • GET /sse/list_functions: Lista todas las funciones disponibles
  • POST /sse/invoke/{function_name}: Invoca una función con los parámetros dados

Endpoints de Streamable HTTP

  • POST /mcp: Maneja todas las solicitudes MCP usando formato JSON
    • Para listar funciones: {"method": "list_functions", "params": {}}
    • Para invocar funciones: {"method": "invoke", "params": {"function": "function_name", "params": {...}}}

Selección de Transporte

El servidor selecciona automáticamente el transporte apropiado basándose en:

  1. Ruta URL: Conéctate al endpoint específico para tu transporte preferido
  2. Tipo de Contenido: Al conectarse a la ruta raíz (/), el servidor redirige según el tipo de contenido:
    • application/json → Streamable HTTP
    • Otros tipos de contenido → SSE

Verificación de Salud

  • GET /health: Devuelve el estado de salud del servidor

Funciones Disponibles

Gestión de Planes

  • create_plan: Crear un nuevo plan
  • get_plan: Obtener un plan por ID
  • list_plans: Listar todos los planes
  • list_plans_by_application: Listar todos los planes para una aplicación específica
  • update_plan: Actualizar un plan existente
  • delete_plan: Eliminar un plan por ID
  • update_plan_notes: Actualizar notas de un plan
  • get_plan_notes: Obtener notas de un plan

Gestión de Tareas

  • create_task: Crear una nueva tarea en un plan
  • get_task: Obtener una tarea por ID
  • list_tasks_by_plan: Listar todas las tareas en un plan
  • list_tasks_by_status: Listar todas las tareas con un estado específico
  • update_task: Actualizar una tarea existente
  • delete_task: Eliminar una tarea por ID
  • reorder_task: Cambiar el orden de una tarea dentro de su plan
  • update_task_notes: Actualizar notas de una tarea
  • get_task_notes: Obtener notas de una tarea

Configuración de MCP

Configuración Local de MCP

Para configurar un agente de IA para usar el servidor MCP local, añade lo siguiente a tu archivo de configuración de MCP (la ubicación exacta del archivo depende de tu Agente de IA):

Uso del Transporte SSE (Predeterminado)

Nota: El contenedor docker ya debería estar en ejecución.

{
  "mcpServers": {
    "valkey-tasks": {
      "serverUrl": "http://localhost:8080/sse"
    }
  }
}

Uso del Transporte Streamable HTTP

Nota: El contenedor docker ya debería estar en ejecución.

{
  "mcpServers": {
    "valkey-tasks": {
      "serverUrl": "http://localhost:8080/mcp"
    }
  }
}

Uso del Transporte STDIO

El transporte STDIO permite que el servidor MCP se comunique a través de la entrada/salida estándar, lo cual es útil para herramientas de IA heredadas que dependen de stdin/stdout para la comunicación.

Para herramientas agénticas que necesitan iniciar y gestionar el proceso del servidor MCP, usa una configuración como esta:

{
  "mcpServers": {
    "valkey-tasks": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "valkey-data:/data"
        "-e", "ENABLE_STDIO=true",
        "ghcr.io/jbrinkman/valkey-ai-tasks:latest"
      ]    
    }
  }
}

Configuración de MCP en Docker

Cuando se ejecuta en Docker, usa el nombre del contenedor como nombre de host:

Uso del Transporte SSE (Predeterminado)

{
  "mcpServers": {
    "valkey-tasks": {
      "serverUrl": "http://valkey-mcp-server:8080/sse"
    }
  }
}

Funcionalidad de Notas

El sistema soporta notas enriquecidas con formato Markdown tanto para planes como para tareas. Esta funcionalidad es particularmente útil para que los agentes de IA mantengan contexto entre sesiones y documenten información importante.

Características de las Notas

  • Soporte completo de Markdown incluyendo:
    • Encabezados, listas y tablas
    • Bloques de código con resaltado de sintaxis
    • Enlaces e imágenes
    • Énfasis y formato
  • Notas separadas para planes y tareas
  • Herramientas MCP dedicadas para gestionar notas
  • Las notas se incluyen en todas las respuestas relevantes de la API

Mejores Prácticas para Notas

  1. Mantener Contexto: Usa notas para documentar contexto importante que deba persistir entre sesiones
  2. Documentar Decisiones: Registra decisiones clave y su justificación
  3. Seguimiento del Progreso: Usa notas para hacer seguimiento del progreso y los siguientes pasos
  4. Organizar Información: Usa formato Markdown para estructurar la información claramente
  5. Ejemplos de Código: Incluye fragmentos de código con resaltado de sintaxis adecuado

Seguridad de las Notas

El contenido de las notas se sanitiza para prevenir XSS y otros problemas de seguridad mientras se preserva el formato Markdown.

Recursos MCP

Además de las herramientas MCP, el sistema proporciona recursos MCP que permiten a los agentes de IA acceder directamente a datos estructurados. Estos recursos proporcionan una vista completa de planes y tareas en una sola solicitud, lo cual es más eficiente que realizar múltiples llamadas a herramientas.

Recursos Disponibles

Recurso de Plan

El Recurso de Plan proporciona una vista completa de un plan, incluyendo sus tareas y notas. Soporta los siguientes patrones de URI:

  • Plan Individual: ai-tasks://plans/{id}/full - Devuelve un plan específico con sus tareas
  • Todos los Planes: ai-tasks://plans/full - Devuelve todos los planes con sus tareas
  • Planes de Aplicación: ai-tasks://applications/{app_id}/plans/full - Devuelve todos los planes para una aplicación específica

Cada recurso devuelve un objeto o array JSON con la siguiente estructura:

{
  "id": "plan-123",
  "application_id": "my-app",
  "name": "New Feature Development",
  "description": "Implement new features for the application",
  "status": "new",
  "notes": "# Project Notes\n\nThis project aims to implement the following features...",
  "created_at": "2025-06-27T14:00:21Z",
  "updated_at": "2025-07-01T13:04:01Z",
  "tasks": [
    {
      "id": "task-456",
      "plan_id": "plan-123",
      "title": "Task 1",
      "description": "Description for task 1",
      "status": "pending",
      "priority": "high",
      "order": 0,
      "notes": "# Task Notes\n\nThis task requires the following steps...",
      "created_at": "2025-06-27T14:00:50Z",
      "updated_at": "2025-07-01T12:04:27Z"
    },
    // Additional tasks...
  ]
}

Uso de los Recursos MCP

Los agentes de IA pueden acceder a estos recursos usando la API de recursos MCP. Aquí hay un ejemplo de cómo leer un recurso:

{
  "action": "read_resource",
  "params": {
    "uri": "ai-tasks://plans/123/full"
  }
}

Esto devolverá el recurso de plan completo incluyendo todas las tareas, lo cual es más eficiente que hacer llamadas separadas para obtener el plan y luego sus tareas.

Uso con Agentes de IA

Los agentes de IA pueden interactuar con este sistema de gestión de tareas a través de la API MCP usando transporte SSE o Streamable HTTP. Aquí hay ejemplos para ambos protocolos de transporte:

Uso del Transporte SSE

  1. El agente llama a /sse/list_functions para descubrir las funciones disponibles
  2. El agente llama a /sse/invoke/create_plan con parámetros: 
    {
  "application_id": "my-app",
  "name": "New Feature Development",
  "description": "Implement new features for the application",
  "notes": "# Project Notes\n\nThis project aims to implement the following features:\n\n- Feature A\n- Feature B\n- Feature C"
}
  3. El agente puede añadir tareas al plan usando:
    • Creación individual de tareas con /sse/invoke/create_task
    • Creación masiva de tareas con /sse/invoke/bulk_create_tasks para múltiples tareas a la vez: 
      {
  "plan_id": "plan-123",
  "tasks_json": "[
    {
      \"title\": \"Task 1\",
      \"description\": \"Description for task 1\",
      \"priority\": \"high\",
      \"status\": \"pending\",
      \"notes\": \"# Task Notes\\n\\nThis task requires the following steps:\\n\\n1. Step one\\n2. Step two\\n3. Step three\"
    },
    {
      \"title\": \"Task 2\",
      \"description\": \"Description for task 2\",
      \"priority\": \"medium\",
      \"status\": \"pending\"
    }
  ]"
}
  4. El agente llama a /sse/invoke/update_task para actualizar el estado de las tareas a medida que avanza el trabajo

Ejemplo de Prompt de Agente

Aquí hay un ejemplo de prompt que haría que un agente de IA use el sistema de gestión de tareas MCP:

I need to organize work for my new application called "inventory-manager". 
Create a plan for this application with the following plan notes:
"# Inventory Manager Project

This project aims to create a comprehensive inventory management system with the following goals:
- Track inventory levels in real-time
- Generate reports on inventory movement
- Provide alerts for low stock items"

Add the following tasks:
1. Set up database schema
2. Implement REST API endpoints
3. Create user authentication system
4. Design frontend dashboard
5. Implement inventory tracking features

For the database schema task, add these notes:
"# Database Schema Notes

The schema should include the following tables:
- Products
- Categories
- Inventory Transactions
- Users
- Roles"

Prioritize the tasks appropriately and set the first two tasks as "in_progress".

Con este prompt, un agente de IA con acceso al Servidor de Gestión de Tareas Valkey MCP:

  1. Creará un nuevo plan con application_id "inventory-manager" y las notas con formato Markdown especificadas
  2. Añadirá las cinco tareas especificadas al plan
  3. Añadirá notas detalladas con formato Markdown a la tarea de esquema de base de datos
  4. Establecerá prioridades apropiadas para cada tarea
  5. Actualizará el estado de las dos primeras tareas a "in_progress"
  6. Devolverá un resumen del plan y las tareas creadas

Documentación para Desarrolladores

Para obtener información sobre cómo configurar un entorno de desarrollo, contribuir al proyecto y comprender la estructura del código, consulta la Guía para Desarrolladores.

Para las pautas de contribución, incluido el formato de mensajes de commit y el proceso de pull requests, consulta Pautas de Contribución.

Licencia

Este proyecto está licenciado bajo la Licencia BSD-3-Clause.