Moo Tasks

mootasks.dev

A kanban-style task management dashboard with an integrated MCP server.
Human users manage tasks via a drag-and-drop web UI, while AI agents connect via the MCP server to discover, accept, update, and create tasks programmatically.

✨ Features

💾 Board Management

• Import Board: Available on the Dashboard page.
• Export Board: Available in the Board Settings panel.

🚀 Quick Start

The fastest way to get started with Moo Tasks is using Docker.

🐳 Running with Docker (Recommended)

If you have Docker installed, you can start the entire stack (including the database, Adminer, and Mailpit) with one command:

docker-compose up -d

The application will be available at http://localhost:3000.

🛠️ Manual Development Setup

If you prefer to run locally without Docker:

1. Prerequisites: Ensure you have Node.js (v22+) and npm installed.
2. Install dependencies: npm install
3. Environment Variables: Create a .env file from .env.example and set NUXT_SESSION_PASSWORD (at least 32 characters long).
4. Start development server: npm run dev

📖 Usage Guide

Get up and running in just a few minutes:

1. Launch: Once the server is running, navigate to http://localhost:3000 (or the live site at mootasks.dev).
2. Account: Register your account at /register or login.
3. Create Board: Head to the Dashboard to create your first project board.
4. Manage Tasks: Add, move, and update tasks on your new board using the drag-and-drop Kanban view or the list view.
5. Connect AI: Go to Board Settings to view your MCP configuration and connect your favorite AI agent (e.g., Claude Code, Cursor, VS Code).
6. Seed Data: Need test data? Run npx tsx server/db/seed.ts to populate the database with sample tasks.

⚙️ Environment Variables

Copy .env.example to .env and adjust as needed:

🤖 MCP Server

Moo Tasks is primarily an MCP server and Agent API. While it provides a web interface for humans, its core purpose is to enable AI agents to manage tasks programmatically.

🎯 Board-Scoped Architecture

Everything in Moo Tasks is scoped to a board. There are no global queries for tasks. This ensures that agents only work within the context they are assigned to, improving focus and security.

• Each board has its own unique MCP endpoint.
• AI agents connect to a specific board to work on its tasks.
• Resources, prompts, and tools are all scoped to the active board.

📋 Working with Tasks via MCP

The board acts as the primary task list for this application. To programmatically work on tasks:

1. Get the MCP Token: In the Board Settings, generate an MCP token if the board is private.
2. Configure Your Agent: Add the MCP server configuration for your specific board.
3. Use Tools: Use the available tools (list-tasks, accept-task, update-task-status, etc.) to interact with the tasks.

🔐 Security & Privacy

Tokens can be generated, rotated, or revoked at any time from Board Settings.

🛠️ Tools

📚 Resources

💬 Prompts

🔄 Task Hierarchy & Corrections

Moo Tasks supports a refined workflow for task completion:

• Review Status — Move tasks to "Review" when ready for human verification
• Request Corrections — From "Review" or "Done", create linked "Correction Tasks"
• Linked Navigation — Correction tasks link to their parent for easy navigation

Configurable Instructions

Both support reset to default to restore the original built-in instructions.

🔌 MCP Client Configuration

{
  "mcpServers": {
    "moo-tasks": {
      "type": "streamable-http",
      "url": "http://localhost:3000/api/boards/<boardId>/mcp",
      "headers": {
        "Authorization": "Bearer <your-bearer-token>"
      }
    }
  }
}

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "moo-tasks": {
      "type": "streamable-http",
      "url": "http://localhost:3000/api/boards/<boardId>/mcp",
      "headers": {
        "Authorization": "Bearer <your-bearer-token>"
      }
    }
  }
}

Add to your client's MCP config (e.g. .vscode/mcp.json or JetBrains MCP settings):

{
  "mcpServers": {
    "moo-tasks": {
      "type": "streamable-http",
      "url": "http://localhost:3000/api/boards/<boardId>/mcp",
      "headers": {
        "Authorization": "Bearer <your-bearer-token>"
      }
    }
  }
}

💡 The board page has a 📋 Copy JSON button that emits this exact snippet pre-filled with your board ID and token.

🔐 Security & Scoping

• Each MCP endpoint is scoped to a single board (/api/boards/<boardId>/mcp). The server only ever sees tasks, comments, and instructions belonging to that one board.
• Tokens are sent via the standard Authorization: Bearer <token> HTTP header per the MCP authorization spec. Query-string tokens are no longer accepted.
• Generate or revoke a board's token from the board settings drawer at any time. Revoking immediately invalidates all existing agent connections.
• Boards may also be marked mcpPublic in settings for read-friendly demos; in that mode no token is required, but it is not recommended for real work.

📡 API Routes

🐳 Docker

Build & Run

# Build
docker build -t moo-tasks .

# Run
docker run -p 3000:3000 \
  -e NUXT_SESSION_PASSWORD="your-secret" \
  -e DATABASE_URL="mysql://user:pass@host:3306/db" \
  moo-tasks

☁️ Deploy to DigitalOcean App Platform

• A DigitalOcean account
• Your repo pushed to GitHub
• A DigitalOcean API token

1. Fork/push this repo to GitHub
2. Go to DigitalOcean App Platform → Create App
3. Connect your GitHub repo and select the main branch
4. DigitalOcean will auto-detect the Dockerfile — confirm the settings
5. Under Environment Variables, add these secrets:
   • NUXT_SESSION_PASSWORD — 32+ character secret for session encryption
   • DATABASE_URL — Your MySQL connection string
6. Deploy!

Note: MySQL is recommended for production as it allows you to increase instance_count to handle more traffic.

# Install doctl and authenticate
doctl auth init

# Create the app from the spec (update repo in .do/app.yaml first)
doctl apps create --spec .do/app.yaml

# Set secrets
doctl apps update <app-id> --spec .do/app.yaml

The included workflow at .github/workflows/deploy.yml automatically:

• On pull requests — builds and validates the project
• On push to main — builds, then deploys to DigitalOcean App Platform

Setup:

1. Create the app on DigitalOcean first (Option 1 or 2)
2. Generate a DigitalOcean API token
3. Add it as a GitHub repository secret:
   • Go to Settings → Secrets and variables → Actions
   • Add DIGITALOCEAN_ACCESS_TOKEN with your DO API token
4. Push to main — the workflow will deploy automatically

The .do/app.yaml file defines the full app configuration:

name: moo-tasks

services:
  - name: web
    dockerfile_path: Dockerfile
    github:
      branch: main
      deploy_on_push: true
    http_port: 3000
    instance_count: 1
    instance_size_slug: apps-s-1vcpu-1gb
    envs:
      - key: NUXT_SESSION_PASSWORD
        type: SECRET
      - key: DATABASE_URL
        type: SECRET

• "Only board owners can invite users" or missing boards after creation: Ensure DATABASE_URL is correctly configured and the MySQL server is accessible from the app.
• Scalability: Unlike SQLite, you can increase instance_count to handle more traffic, as all instances share the same MySQL database.
• Session Reset: If the database is reset but your browser still has a session cookie, the app will automatically log you out. Simply register again to start fresh.

🧱 Tech Stack

_{Built with 🐄 by the Moo Tasks team}