Valkey AI Tasks

Um sistema de gerenciamento de tarefas para agentes de IA que utiliza Valkey como camada de persistência.

Documentação

Servidor de Gerenciamento de Tarefas MCP Valkey

Um sistema de gerenciamento de tarefas que implementa o Model Context Protocol (MCP) para integração perfeita com ferramentas de IA agênticas. Este sistema permite que agentes de IA criem, gerenciem e acompanhem tarefas dentro de planos usando Valkey como camada de persistência.

Recursos

Gerenciamento de planos (criar, ler, atualizar, excluir)
Gerenciamento de tarefas (criar, ler, atualizar, excluir)
Ordenação e priorização de tarefas
Acompanhamento de status das tarefas
Suporte a notas com formatação Markdown para planos e tarefas
Servidor MCP para integração com agentes de IA
Suporte aos protocolos de transporte STDIO, SSE e Streamable HTTP
Suporte a contêineres Docker para implantação facilitada

Arquitetura

O sistema é construído usando:

Go: Para a implementação do backend
Valkey: Para persistência de dados
Valkey-Glide v2: Cliente Go oficial para Valkey
Model Context Protocol: Para integração com agentes de IA

Início Rápido

Implantação com Docker

O servidor MCP foi projetado para executar um protocolo por vez para simplificar. Por padrão, todos os protocolos estão desabilitados e você precisa habilitar explicitamente o que deseja usar.

Pré-requisitos

Crie um volume nomeado para a persistência de dados do Valkey:
```
docker volume create valkey-data
```

Executando com SSE (Recomendado para a maioria dos 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

Executando com 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

Executando com STDIO (Para comunicação direta entre processos)

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

Usando as Imagens de Contêiner

As imagens de contêiner são publicadas no GitHub Container Registry e podem ser obtidas 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

Referência da API MCP

O servidor MCP suporta dois protocolos de transporte: Server-Sent Events (SSE) e Streamable HTTP. Cada protocolo expõe endpoints semelhantes, mas com padrões de interação diferentes.

Endpoints Server-Sent Events (SSE)

GET /sse/list_functions: Lista todas as funções disponíveis
POST /sse/invoke/{function_name}: Invoca uma função com os parâmetros fornecidos

Endpoints Streamable HTTP

POST /mcp: Gerencia todas as solicitações MCP usando formato JSON
- Para listagem de funções: {"method": "list_functions", "params": {}}
- Para invocação de funções: {"method": "invoke", "params": {"function": "function_name", "params": {...}}}

Seleção de Transporte

O servidor seleciona automaticamente o transporte apropriado com base em:

Caminho da URL: Conecte-se ao endpoint específico para o transporte de sua preferência
Tipo de Conteúdo: Ao conectar ao caminho raiz (/), o servidor redireciona com base no tipo de conteúdo:
- application/json → Streamable HTTP
- Outros tipos de conteúdo → SSE

Verificação de Saúde

GET /health: Retorna o status de saúde do servidor

Funções Disponíveis

Gerenciamento de Planos

create_plan: Criar um novo plano
get_plan: Obter um plano por ID
list_plans: Listar todos os planos
list_plans_by_application: Listar todos os planos de um aplicativo específico
update_plan: Atualizar um plano existente
delete_plan: Excluir um plano por ID
update_plan_notes: Atualizar notas de um plano
get_plan_notes: Obter notas de um plano

Gerenciamento de Tarefas

create_task: Criar uma nova tarefa em um plano
get_task: Obter uma tarefa por ID
list_tasks_by_plan: Listar todas as tarefas em um plano
list_tasks_by_status: Listar todas as tarefas com um status específico
update_task: Atualizar uma tarefa existente
delete_task: Excluir uma tarefa por ID
reorder_task: Alterar a ordem de uma tarefa dentro do seu plano
update_task_notes: Atualizar notas de uma tarefa
get_task_notes: Obter notas de uma tarefa

Configuração MCP

Configuração MCP Local

Para configurar um agente de IA para usar o servidor MCP local, adicione o seguinte ao seu arquivo de configuração MCP (a localização exata do arquivo depende do seu Agente de IA):

Usando Transporte SSE (Padrão)

Nota: O contêiner Docker já deve estar em execução.

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

Usando Transporte Streamable HTTP

Nota: O contêiner Docker já deve estar em execução.

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

Usando Transporte STDIO

O transporte STDIO permite que o servidor MCP se comunique via entrada/saída padrão, o que é útil para ferramentas de IA legadas que dependem de stdin/stdout para comunicação.

Para ferramentas agênticas que precisam iniciar e gerenciar o processo do servidor MCP, use uma configuração 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"
      ]    
    }
  }
}

Configuração MCP Docker

Ao executar no Docker, use o nome do contêiner como nome do host:

Usando Transporte SSE (Padrão)

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

Funcionalidade de Notas

O sistema suporta notas ricas formatadas em Markdown para planos e tarefas. Este recurso é particularmente útil para agentes de IA manterem contexto entre sessões e documentarem informações importantes.

Recursos de Notas

Suporte completo a Markdown, incluindo:
- Títulos, listas e tabelas
- Blocos de código com realce de sintaxe
- Links e imagens
- Ênfase e formatação
Notas separadas para planos e tarefas
Ferramentas MCP dedicadas para gerenciamento de notas
Notas incluídas em todas as respostas relevantes da API

Boas Práticas para Notas

Manter Contexto: Use notas para documentar contexto importante que deve persistir entre sessões
Documentar Decisões: Registre decisões importantes e sua justificativa
Acompanhar Progresso: Use notas para acompanhar o progresso e os próximos passos
Organizar Informações: Use formatação Markdown para estruturar informações claramente
Exemplos de Código: Inclua trechos de código com realce de sintaxe adequado

Segurança das Notas

O conteúdo das notas é sanitizado para prevenir XSS e outros problemas de segurança, preservando a formatação Markdown.

Recursos MCP

Além das ferramentas MCP, o sistema fornece recursos MCP que permitem que agentes de IA acessem dados estruturados diretamente. Esses recursos fornecem uma visão completa de planos e tarefas em uma única solicitação, o que é mais eficiente do que fazer múltiplas chamadas de ferramentas.

Recursos Disponíveis

Recurso de Plano

O Recurso de Plano fornece uma visão completa de um plano, incluindo suas tarefas e notas. Ele suporta os seguintes padrões de URI:

Plano Único: ai-tasks://plans/{id}/full - Retorna um plano específico com suas tarefas
Todos os Planos: ai-tasks://plans/full - Retorna todos os planos com suas tarefas
Planos do Aplicativo: ai-tasks://applications/{app_id}/plans/full - Retorna todos os planos de um aplicativo específico

Cada recurso retorna um objeto ou array JSON com a seguinte estrutura:

{
  "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...
  ]
}

Usando Recursos MCP

Agentes de IA podem acessar esses recursos usando a API de recursos MCP. Aqui está um exemplo de como ler um recurso:

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

Isso retornará o recurso completo do plano, incluindo todas as tarefas, o que é mais eficiente do que fazer chamadas separadas para obter o plano e depois suas tarefas.

Usando com Agentes de IA

Agentes de IA podem interagir com este sistema de gerenciamento de tarefas através da API MCP usando transporte SSE ou Streamable HTTP. Aqui estão exemplos para ambos os protocolos de transporte:

Usando Transporte SSE

O agente chama /sse/list_functions para descobrir funções disponíveis

O agente chama /sse/invoke/create_plan com 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"
}

O agente pode adicionar tarefas ao plano usando:

Criação individual de tarefas com /sse/invoke/create_task

Criação em lote de tarefas com /sse/invoke/bulk_create_tasks para múltiplas tarefas de uma 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\"
    }
  ]"
}

O agente chama /sse/invoke/update_task para atualizar o status das tarefas conforme o trabalho avança

Exemplo de Prompt para Agente

Aqui está um exemplo de prompt que acionaria um agente de IA para usar o sistema de gerenciamento de tarefas 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".

Com este prompt, um agente de IA com acesso ao Servidor de Gerenciamento de Tarefas MCP Valkey iria:

Criar um novo plano com application_id "inventory-manager" e as notas formatadas em Markdown especificadas
Adicionar as cinco tarefas especificadas ao plano
Adicionar notas detalhadas formatadas em Markdown à tarefa de esquema do banco de dados
Definir prioridades apropriadas para cada tarefa
Atualizar o status das duas primeiras tarefas para "in_progress"
Retornar um resumo do plano e das tarefas criadas

Documentação para Desenvolvedores

Para informações sobre como configurar um ambiente de desenvolvimento, contribuir com o projeto e entender a estrutura do código, consulte o Guia do Desenvolvedor.

Para diretrizes de contribuição, incluindo formato de mensagens de commit e processo de pull request, veja Diretrizes de Contribuição.

Licença

Este projeto é licenciado sob a Licença BSD-3-Clause.