Skip to main content
Glama

TasksMultiServer

Version 0.1.0-alpha - Multi-interface task management system with MCP Server, REST API, and React UI.

⚠️ ALPHA RELEASE WARNING

This is an alpha release and is under active development. The API and functionality may change significantly before the stable 1.0.0 release. Use in production at your own risk.

  • Breaking changes may occur between alpha versions

  • API endpoints and response formats may change

  • Database schema migrations may not be backwards compatible

  • Documentation may be incomplete or outdated

For stable releases, please wait for version 1.0.0 or later.

Overview

TasksMultiServer provides hierarchical task management through multiple interfaces, designed for both human users and AI agents. Store tasks in PostgreSQL or filesystem, access via MCP protocol, REST API, or web UI.

TasksMultiServer dashboard

For developers: See CONTRIBUTING.md for development setup and contribution guidelines.

Related MCP server: pith

Features

  • Multi-interface access: MCP Server for AI agents, REST API for programmatic access, React UI for visual management

  • Pluggable storage: Choose between filesystem or PostgreSQL

  • Hierarchical organization: Projects → Task Lists → Tasks

  • Dependency management: DAG-based task dependencies with circular dependency detection

  • Template-based instructions: Generate agent-specific task instructions

  • Direct store access: No caching ensures consistency across multiple agents

  • Agent-friendly features: Automatic parameter preprocessing, enhanced error messages with visual indicators and examples

  • Tags and search: Organize tasks with tags, search and filter by multiple criteria (text, status, priority, tags, project)

  • Dependency analysis: Analyze critical paths, identify bottlenecks, visualize dependency graphs (ASCII, DOT, Mermaid)

  • Bulk operations: Efficiently create, update, delete, or tag multiple tasks in a single operation

  • Automatic blocking detection: Tasks automatically show why they're blocked with dependency information

  • Health monitoring: Built-in health check endpoint for monitoring system status

Three Ways to Access TasksMultiServer

TasksMultiServer provides three distinct interfaces for different use cases:

1. MCP Server (for AI Agents)

⚠️ NOT YET PUBLISHED: This project is not yet available on PyPI or uvx. To use it, you must clone the repository and build it locally.

Local build and installation:

# Clone the repository
git clone https://github.com/YOUR_USERNAME/tasks-multiserver.git
cd tasks-multiserver

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run the MCP server
python -m src.interfaces.mcp.server

Configure in your AI agent's MCP settings (e.g., .kiro/settings/mcp.json):

{
  "mcpServers": {
    "tasks-multiserver": {
      "command": "python",
      "args": ["-m", "src.interfaces.mcp.server"],
      "cwd": "/path/to/tasks-multiserver",
      "env": {
        "DATA_STORE_TYPE": "filesystem",
        "FILESYSTEM_PATH": "/path/to/tasks",
        "MULTI_AGENT_ENVIRONMENT_BEHAVIOR": "false"
      }
    }
  }
}

Once published, you'll be able to use:

uvx tasks-multiserver
# or
pip install tasks-multiserver

2. REST API + React UI (via Docker Compose)

Use Docker Compose to run both the REST API and web UI together.

docker-compose up

Access:

Configure via .env file (see Configuration section below).

Agent-Friendly Features

TasksMultiServer is designed to work seamlessly with AI agents, providing intelligent parameter handling and clear error feedback.

Automatic Parameter Preprocessing

The system automatically converts common input patterns to the correct types, reducing friction for AI agents:

  • String numbers → Numbers: "5" → 5, "3.14" → 3.14

  • JSON strings → Arrays: '["tag1", "tag2"]' → ["tag1", "tag2"]

  • Boolean strings → Booleans: "true", "yes", "1" → True

This means agents don't need to worry about exact type formatting - the system handles it intelligently.

Enhanced Error Messages

When validation errors occur, the system provides:

  • Visual indicators (❌, 💡, 📝, 🔧) for quick scanning

  • Field names and specific problem descriptions

  • Actionable guidance on how to fix the error

  • Working examples of correct usage

  • Valid options for enum fields

Example error message:

❌ priority: Invalid value "urgent"
💡 Priority must be one of: CRITICAL, HIGH, MEDIUM, LOW, TRIVIAL
📝 Example: "priority": "HIGH"

Organize and find tasks efficiently with tags and powerful search capabilities.

Task Tags

Add tags to tasks for categorization and filtering:

  • Up to 10 tags per task

  • Support for unicode, emoji, numbers, hyphens, and underscores

  • Maximum 50 characters per tag

  • Automatic deduplication

MCP Example:

# Add tags to a task
add_task_tags(task_id="...", tags=["frontend", "urgent", "🚀"])

# Remove tags
remove_task_tags(task_id="...", tags=["urgent"])

REST API Example:

# Add tags
POST /tasks/{id}/tags
{"tags": ["frontend", "urgent", "🚀"]}

# Remove tags
DELETE /tasks/{id}/tags
{"tags": ["urgent"]}

Search and filter tasks by multiple criteria in a single query:

  • Text search: Match against task titles and descriptions

  • Status filter: Filter by task status (NOT_STARTED, IN_PROGRESS, BLOCKED, COMPLETED)

  • Priority filter: Filter by priority level (CRITICAL, HIGH, MEDIUM, LOW, TRIVIAL)

  • Tag filter: Find tasks with specific tags

  • Project filter: Filter by project name

  • Pagination: Control result size with limit and offset

  • Sorting: Order by relevance, created_at, updated_at, or priority

MCP Example:

search_tasks(
    query="authentication",
    status=["IN_PROGRESS"],
    priority=["HIGH", "CRITICAL"],
    tags=["backend"],
    project_name="API Development",
    limit=20,
    sort_by="priority"
)

REST API Example:

POST /search/tasks
{
  "query": "authentication",
  "status": ["IN_PROGRESS"],
  "priority": ["HIGH", "CRITICAL"],
  "tags": ["backend"],
  "project_name": "API Development",
  "limit": 20,
  "sort_by": "priority"
}

Dependency Analysis and Visualization

Understand project structure and identify critical paths with powerful dependency analysis tools.

Dependency Analysis

Analyze task dependencies to gain insights:

  • Critical path: Identify the longest chain of dependent tasks

  • Bottlenecks: Find tasks that block multiple other tasks

  • Leaf tasks: Identify tasks with no dependencies (ready to start)

  • Progress tracking: Calculate completion percentage across the dependency graph

  • Circular dependency detection: Automatically detect and report cycles

MCP Example:

analyze_dependencies(scope_type="project", scope_id="...")

REST API Example:

GET /projects/{id}/dependencies/analysis
GET /task-lists/{id}/dependencies/analysis

Response:

{
  "critical_path": ["task-id-1", "task-id-2", "task-id-3"],
  "critical_path_length": 3,
  "bottleneck_tasks": [["task-id-2", 5]],
  "leaf_tasks": ["task-id-1", "task-id-4"],
  "completion_progress": 45.5,
  "total_tasks": 10,
  "completed_tasks": 4,
  "circular_dependencies": []
}

Dependency Visualization

Visualize dependency graphs in multiple formats:

  • ASCII: Tree-like structure with box-drawing characters (for terminal display)

  • DOT: Graphviz format (for rendering with Graphviz tools)

  • Mermaid: Mermaid diagram syntax (for documentation and web display)

MCP Example:

# ASCII visualization
visualize_dependencies(scope_type="project", scope_id="...", format="ascii")

# DOT format for Graphviz
visualize_dependencies(scope_type="project", scope_id="...", format="dot")

# Mermaid diagram
visualize_dependencies(scope_type="project", scope_id="...", format="mermaid")

REST API Example:

GET /projects/{id}/dependencies/visualize?format=ascii
GET /projects/{id}/dependencies/visualize?format=dot
GET /projects/{id}/dependencies/visualize?format=mermaid

Automatic Blocking Detection

Tasks automatically include blocking information when they have incomplete dependencies:

{
  "id": "task-123",
  "title": "Deploy to production",
  "status": "BLOCKED",
  "block_reason": {
    "is_blocked": true,
    "blocking_task_ids": ["task-100", "task-101"],
    "blocking_task_titles": ["Run integration tests", "Security audit"],
    "message": "Blocked by 2 incomplete dependencies: Run integration tests, Security audit"
  }
}

This eliminates the need for additional queries to understand why a task can't proceed.

Bulk Operations

Efficiently manage multiple tasks at once with bulk operations (REST API only).

Supported Operations

  • Bulk create: Create multiple tasks in one request

  • Bulk update: Update multiple tasks in one request

  • Bulk delete: Delete multiple tasks in one request

  • Bulk tag operations: Add or remove tags from multiple tasks

Features

  • Validation before apply: All inputs are validated before any changes are made

  • Partial failure reporting: Detailed results show which operations succeeded and which failed

  • Transaction support: PostgreSQL operations use transactions; filesystem operations support rollback

Examples:

# Bulk create tasks
POST /tasks/bulk/create
{
  "tasks": [
    {"task_list_id": "...", "title": "Task 1", "description": "...", ...},
    {"task_list_id": "...", "title": "Task 2", "description": "...", ...}
  ]
}

# Bulk update tasks
PUT /tasks/bulk/update
{
  "updates": [
    {"id": "task-1", "status": "COMPLETED"},
    {"id": "task-2", "priority": "HIGH"}
  ]
}

# Bulk delete tasks
DELETE /tasks/bulk/delete
{
  "task_ids": ["task-1", "task-2", "task-3"]
}

# Bulk add tags
POST /tasks/bulk/tags/add
{
  "task_ids": ["task-1", "task-2"],
  "tags": ["urgent", "frontend"]
}

# Bulk remove tags
POST /tasks/bulk/tags/remove
{
  "task_ids": ["task-1", "task-2"],
  "tags": ["urgent"]
}

Response format:

{
  "total": 3,
  "succeeded": 2,
  "failed": 1,
  "results": [
    { "index": 0, "success": true, "task_id": "task-1" },
    { "index": 1, "success": true, "task_id": "task-2" },
    { "index": 2, "success": false, "error": "Task not found" }
  ],
  "errors": [{ "index": 2, "error": "Task not found" }]
}

Test Data Generator

TasksMultiServer includes a test data generator that creates realistic, comprehensive test data for development, testing, and demonstration purposes.

Features

  • Database reset: Automatically resets Docker database to clean state

  • Realistic data: Creates 15 projects, 35 task lists, and hundreds of tasks with varied metadata

  • Dependency graphs: Generates task dependencies ensuring no circular references

  • Status distribution: Creates tasks in different states (NOT_STARTED, IN_PROGRESS, COMPLETED)

  • Rich metadata: Adds tags, priorities, notes, action plans, and exit criteria

  • Reproducible: Uses configurable random seed for consistent results

  • Validated: Automatically validates generated data against 22 correctness properties

Usage

Prerequisites:

Basic usage:

# Generate with default settings (seed=42)
python scripts/generate_test_data.py

# Generate with custom seed for different data
python scripts/generate_test_data.py --seed 123

# Generate with custom API URL
python scripts/generate_test_data.py --api-url http://localhost:9000

What it generates:

  • 15 projects with varying numbers of task lists (0-10 per project)

  • 35 task lists with 0-25 tasks each

  • Tasks with realistic titles, descriptions, and exit criteria

  • Task dependencies forming valid DAGs (no circular dependencies)

  • Mixed task statuses respecting dependency constraints

  • Tags (1-5 per task) from a realistic pool

  • All 5 priority levels (CRITICAL, HIGH, MEDIUM, LOW, TRIVIAL)

  • Notes (research, execution, general) based on task status

  • Action plans (70% of tasks) with 3-8 sequential items

Example output:

Test Data Generator for TasksMultiServer
==================================================
Random seed: 42
API URL: http://localhost:8000

Phase 1: Resetting database...
✓ Database reset complete

Phase 2: Creating entities...
✓ Created 15 projects, 35 task lists, 247 tasks

Phase 3: Assigning dependencies...
✓ Dependencies assigned

Phase 4: Assigning statuses...
✓ Statuses assigned

Phase 5: Enriching metadata...
✓ Metadata enriched

Phase 6: Validating data...
======================================================================
Data Validation Report
======================================================================
Status: PASSED
Properties Passed: 22/22
Properties Failed: 0/22

Summary:
  Total Projects: 15
  Total Task Lists: 35
  Total Tasks: 247

No violations found!
======================================================================

✓ Data generation completed successfully!

When to use

  • Development: Populate your local database with realistic test data

  • Testing: Create consistent test scenarios with reproducible seeds

  • Demos: Generate impressive sample data for demonstrations

  • CI/CD: Validate system behavior with comprehensive test data

Notes

  • The generator requires Docker Compose to be running

  • It will completely reset the database, deleting all existing data

  • Use different seeds to generate varied data sets

  • All generated data is validated against the specification

Configuration

TasksMultiServer supports two backing stores and multi-agent coordination settings.

Environment Variables

Create a .env file or set these environment variables:

# Storage Backend (required)
DATA_STORE_TYPE=filesystem  # Options: "filesystem" or "postgresql"

# Filesystem Configuration (when DATA_STORE_TYPE=filesystem)
FILESYSTEM_PATH=/path/to/tasks  # Default: /tmp/tasks

# PostgreSQL Configuration (when DATA_STORE_TYPE=postgresql)
POSTGRES_URL=postgresql://user:password@localhost:5432/dbname

# Multi-Agent Coordination (optional)
MULTI_AGENT_ENVIRONMENT_BEHAVIOR=false  # Options: "true" or "false"

Storage Backend Options

Filesystem (Default)

  • Simple file-based storage

  • No database setup required

  • Good for single-user or development use

  • Configure with FILESYSTEM_PATH

export DATA_STORE_TYPE=filesystem
export FILESYSTEM_PATH=/home/user/tasks

PostgreSQL

  • Robust database storage

  • Better for multi-user or production use

  • Requires PostgreSQL 14+

  • Configure with POSTGRES_URL

export DATA_STORE_TYPE=postgresql
export POSTGRES_URL=postgresql://user:pass@localhost:5432/tasks

Multi-Agent Environment Behavior

Controls how tasks appear in "ready tasks" queries when multiple agents work concurrently:

  • false (default): Both NOT_STARTED and IN_PROGRESS tasks are ready

    • Allows agents to resume interrupted work

    • Good for single-agent or sequential workflows

  • true: Only NOT_STARTED tasks are ready

    • Prevents multiple agents from working on the same task

    • Good for concurrent multi-agent environments

export MULTI_AGENT_ENVIRONMENT_BEHAVIOR=true

Docker Compose Configuration

For Docker deployments, create a .env file in the project root:

# .env file for docker-compose
DATA_STORE_TYPE=postgresql
POSTGRES_URL=postgresql://postgres:postgres@db:5432/tasks
MULTI_AGENT_ENVIRONMENT_BEHAVIOR=false

The docker-compose.yml automatically includes a PostgreSQL container when needed.

Usage Examples

MCP Server with Filesystem

{
  "mcpServers": {
    "tasks-multiserver": {
      "command": "python",
      "args": ["-m", "src.interfaces.mcp.server"],
      "cwd": "/path/to/tasks-multiserver",
      "env": {
        "DATA_STORE_TYPE": "filesystem",
        "FILESYSTEM_PATH": "/home/user/.tasks"
      }
    }
  }
}

MCP Server with PostgreSQL

{
  "mcpServers": {
    "tasks-multiserver": {
      "command": "python",
      "args": ["-m", "src.interfaces.mcp.server"],
      "cwd": "/path/to/tasks-multiserver",
      "env": {
        "DATA_STORE_TYPE": "postgresql",
        "POSTGRES_URL": "postgresql://user:pass@localhost:5432/tasks",
        "MULTI_AGENT_ENVIRONMENT_BEHAVIOR": "true"
      }
    }
  }
}

Docker Compose with PostgreSQL

Create .env:

DATA_STORE_TYPE=postgresql
POSTGRES_URL=postgresql://postgres:postgres@db:5432/tasks

Run:

docker-compose up

Contributing

We welcome contributions! Please see CONTRIBUTING.md for:

  • Development environment setup

  • Coding standards and guidelines

  • Testing requirements

  • Pull request process

  • Quality standards

Documentation

Getting Started

Guides

API Reference

Examples

Architecture

For a complete documentation index, see docs/README.md.

Architecture

Layered architecture following data flow:

Interfaces (MCP/REST/UI)
    ↓
Orchestration (Business Logic)
    ↓
Data Delegation (Abstract Interface)
    ↓
Data Access (PostgreSQL/Filesystem)
    ↓
Storage (Database/Files)

License

MIT

Note: PyPI package will be available after the first stable release.

Available Tools

23 tools
add_execution_noteC

Add an execution note to a task

Inputs: task_id (required), content (required).

add_research_noteC

Add a research note to a task

Inputs: task_id (required), content (required).

add_task_noteC

Add a general note to a task

Inputs: task_id (required), content (required).

add_task_tagsC

Add tags to a task with validation and deduplication. Tags are labels for categorization and filtering.

Inputs: task_id (required), tags (required).

analyze_dependenciesB

Analyze task dependencies within a scope (project or task list). Returns critical path, bottlenecks, leaf tasks, progress, and circular dependencies.

Inputs: scope_type (required), scope_id (required).

create_projectC

Create a new project with a name and optional agent instructions template

Inputs: name (required), agent_instructions_template.

create_taskC

Create a new task with all required fields (title, description, status, dependencies, exit_criteria, priority, notes) and optional fields (research_notes, action_plan, execution_notes, agent_instructions_template, tags)

Inputs: task_list_id (required), title (required), description (required), status (required), +9 more.

create_task_listA

Create a new task list with project assignment logic. If repeatable=true, assigns to 'Repeatable' project. If no project specified, assigns to 'Chore' project. Otherwise assigns to specified project (creating it if needed).

Inputs: name (required), project_name, repeatable, agent_instructions_template.

delete_projectA

Delete a project and all its task lists and tasks. Default projects (Chore, Repeatable) cannot be deleted.

Inputs: project_id, project_name.

delete_task_listC

Delete a task list and all its tasks

Inputs: task_list_id (required).

get_agent_instructionsB

Generate agent instructions for a task using template resolution hierarchy (task → task list → project → fallback)

Inputs: task_id (required).

get_projectC

Retrieve a project by its ID or name

Inputs: project_id, project_name.

get_ready_tasksB

Retrieve tasks that are ready for execution (tasks with no pending dependencies or all dependencies completed) within a specified scope (project or task list)

Inputs: scope_type (required), scope_id (required).

get_task_listB

Retrieve a task list by its ID, including all its tasks

Inputs: task_list_id (required).

list_projectsB

List all projects in the task management system, including default projects (Chore and Repeatable)

Inputs: no named parameters.

remove_task_tagsA

Remove tags from a task. Tags that don't exist on the task are silently ignored.

Inputs: task_id (required), tags (required).

search_tasksB

Search and filter tasks by multiple criteria including text query, status, priority, tags, and project. Supports pagination and sorting.

Inputs: query, status, priority, tags, +4 more.

update_action_planC

Update the action plan for a task (replaces existing action plan)

Inputs: task_id (required), action_plan (required).

update_exit_criteriaC

Update exit criteria for a task, marking individual criteria as COMPLETE or INCOMPLETE

Inputs: task_id (required), exit_criteria (required).

update_projectB

Update an existing project's name and/or agent instructions template

Inputs: project_id, project_name, name, agent_instructions_template.

update_task_dependenciesC

Update task dependencies with circular dependency validation

Inputs: task_id (required), dependencies (required).

update_task_statusA

Update task status with exit criteria validation (cannot mark COMPLETED unless all exit criteria are COMPLETE)

Inputs: task_id (required), status (required).

visualize_dependenciesB

Generate a visualization of task dependencies within a scope (project or task list). Supports ASCII art, Graphviz DOT format, and Mermaid diagram formats.

Inputs: scope_type (required), scope_id (required), format (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 23 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific resources and actions, such as create_task vs. update_task_status. However, there is some overlap among the note-adding tools (add_execution_note, add_research_note, add_task_note), which could cause confusion as their differences are subtle and not clearly differentiated in descriptions.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, such as create_project, delete_task_list, and update_action_plan. All tools use snake_case with clear, descriptive verbs, making the naming predictable and easy to understand.

    Tool Count3/5

    With 23 tools, the count is borderline high for a task management server, potentially feeling heavy and overwhelming. While it covers many operations, it may include tools that could be consolidated or simplified, such as multiple note-adding functions, leading to some redundancy.

    Completeness5/5

    The tool set provides comprehensive CRUD and lifecycle coverage for tasks, projects, and task lists, including creation, retrieval, updating, deletion, dependency analysis, visualization, and search. There are no obvious gaps; all core operations for task management are well-covered, ensuring agents can handle full workflows without dead ends.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A file-backed MCP server for hierarchical project management that enables AI assistants to create, claim, and complete tasks within a project→epic→feature→task structure, with dependency management and Markdown-based storage.
      22 PyPI
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for task management that enables AI agents to read, create, update tasks, and track work sessions, allowing agents and humans to collaborate on the same task board.
      14
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A task manager MCP server that demonstrates all three MCP primitives (tools, resources, prompts). Enables users to manage tasks, read task summaries and details, and run structured planning/review prompts through natural language.
      -