jbrinkman/valkey-ai-tasks

A task management system that implements the Model Context Protocol (MCP) for seamless integration with agentic AI tools. This system allows AI agents to create, manage, and track tasks within plans using Valkey as the persistence layer.
Features
- Plan management (create, read, update, delete)
- Task management (create, read, update, delete)
- Task ordering and prioritization
- Status tracking for tasks
- Notes support with Markdown formatting for both plans and tasks
- MCP server for AI agent integration
- Supports STDIO, SSE and Streamable HTTP transport protocols
- Docker container support for easy deployment
Architecture
The system is built using:
- **Go**: For the backend implementation
- **Valkey**: For data persistence
- **Valkey-Glide v2**: Official Go client for Valkey
- **Model Context Protocol**: For AI agent integration
Quick Start
Docker Deployment
The MCP server is designed to run one protocol at a time for simplicity. By default, all protocols are disabled and you need to explicitly enable the one you want to use.
Prerequisites
1. Create a named volume for Valkey data persistence:
Running with SSE (Recommended for most use cases)
Running with Streamable HTTP
Running with STDIO (For direct process communication)
Using the Container Images
The container images are published to GitHub Container Registry and can be pulled using:
MCP API Reference
The MCP server supports two transport protocols: Server-Sent Events (SSE) and Streamable HTTP. Each protocol exposes similar endpoints but with different interaction patterns.
Server-Sent Events (SSE) Endpoints
- GET /sse/list_functions: Lists all available functions
- POST /sse/invoke/{function_name}: Invokes a function with the given parameters
Streamable HTTP Endpoints
- POST /mcp: Handles all MCP requests using JSON format
- For function listing: {"method": "list_functions", "params": {}}
- For function invocation: {"method": "invoke", "params": {"function": "function_name", "params": {...}}}
Transport Selection
The server automatically selects the appropriate transport based on:
1. **URL Path**: Connect to the specific endpoint for your preferred transport
2. **Content Type**: When connecting to the root path (/), the server redirects based on content type:
- application/json → Streamable HTTP
- Other content types → SSE
Health Check
- GET /health: Returns server health status
Available Functions
Plan Management
- create_plan: Create a new plan
- get_plan: Get a plan by ID
- list_plans: List all plans
- list_plans_by_application: List all plans for a specific application
- update_plan: Update an existing plan
- delete_plan: Delete a plan by ID
- update_plan_notes: Update notes for a plan
- get_plan_notes: Get notes for a plan
Task Management
- create_task: Create a new task in a plan
- get_task: Get a task by ID
- list_tasks_by_plan: List all tasks in a plan
- list_tasks_by_status: List all tasks with a specific status
- update_task: Update an existing task
- delete_task: Delete a task by ID
- reorder_task: Change the order of a task within its plan
- update_task_notes: Update notes for a task
- get_task_notes: Get notes for a task
MCP Configuration
Local MCP Configuration
To configure an AI agent to use the local MCP server, add the following to your MCP configuration file (the exact file location depends on your AI Agent):
Using SSE Transport (Default)
> Note: The docker container should already be running.
Using Streamable HTTP Transport
> Note: The docker container should already be running.