Taskeristl

You have reached the home page of the Taskeristl service. It tracks tasks across people and tools in one shared MySQL database, behind a small HTTP API and a Model Context Protocol (MCP) endpoint for LLM clients. Two front doors, one task list.

Where would you like to go?

• What is a task? — the data model
• Plain HTTP API — curl, scripts, services
• MCP endpoint — Claude Desktop, Claude Code, agents
• Claude Skill — teach Claude to use taskeristl (downloadable)
• Errors

Quick links: openapi.yaml · openapi.json · SKILL.md · healthz

What is a task?

Every task carries the following fields:

Status meanings

Workflows

Canonical filter combinations callers compose from primitives. Replace ME with the user's identifier (e.g. juan.perez).

The server has no concept of workdays or holidays. For recently_closed, the caller computes the ISO cutoff and passes it as closed_after.

The plain HTTP API

Authentication is one header on every request:

X-API-Key: your-key-here

Endpoints:

Subtasks

Large tasks can hold a checklist of subtasks: lightweight children with just a title, a simple lifecycle (open / in_progress / done), and tracking timestamps (created_at, last_updated_at, closed_at). closed_at is stamped when a subtask becomes done and cleared if reopened.

Subtasks are numbered per parent — seq starts at 1 for each task and each subtask gets a display name like #43-2 (#<task-id>-<seq>). Seqs are stable: deleting one leaves a gap and never renumbers the rest. Deleting a task deletes its subtasks.

Examples

Create a task:

curl -X POST http://localhost:3000/v1/tasks \
  -H "X-API-Key: your-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Wire up the MCP client",
    "owner": "juan.perez",
    "labels": ["mcp","setup"]
  }'

List tasks you own:

curl -H "X-API-Key: your-key-here" \
  "http://localhost:3000/v1/tasks?owner=juan.perez"

Filter by label:

curl -H "X-API-Key: your-key-here" \
  "http://localhost:3000/v1/tasks?label=mcp"

Move a task forward:

curl -X PATCH http://localhost:3000/v1/tasks/42 \
  -H "X-API-Key: your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"status":"in_progress","notes":"started today"}'

Transfer ownership:

curl -X PATCH http://localhost:3000/v1/tasks/42 \
  -H "X-API-Key: your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"owner":"new.owner"}'

Delete:

curl -X DELETE http://localhost:3000/v1/tasks/42 \
  -H "X-API-Key: your-key-here"

The full machine-readable contract lives at /openapi.yaml (and /openapi.json). Feed it to your favorite client generator and you are off.

The MCP endpoint

Have an LLM driving the work? Point any MCP-aware client (Claude Code, Claude Desktop, custom agents) at POST /mcp. The transport is Streamable HTTP (JSON-RPC over HTTP); authentication is the same X-API-Key header used by the plain API.

The MCP server exposes seven tools:

Wire it up — Claude Code

Add this to ~/.claude/settings.json (global) or your project's .mcp.json:

{
  "mcpServers": {
    "taskeristl": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-API-Key": "your-key-here"
      }
    }
  }
}

Or via the Claude Code CLI:

claude mcp add task-database \
  --transport http \
  --url http://localhost:3000/mcp \
  --header "X-API-Key: your-key-here"

Wire it up — Claude Desktop

Same JSON, dropped into the mcpServers section of:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Restart the client and the six tools above will appear in the tool catalog. Speak to them by name (or just describe what you want — the model will pick the right tool).

Tip: when the server is deployed remotely, swap http://localhost:3000 for the real address and use https:// in any non-local environment.

The Claude Skill

Want Claude to know how to drive taskeristl — the data model, the workflow filters, subtasks, backdating — without you explaining it each time? Download the Skill and drop it into your Claude skills directory. Claude loads it automatically when a task-management request comes up.

↓ Download SKILL.md

Install it as a personal skill (available across all your projects):

mkdir -p ~/.claude/skills/taskeristl
curl -s https://gkeakzm5hy.us-east-1.awsapprunner.com/SKILL.md \
  -o ~/.claude/skills/taskeristl/SKILL.md

Or commit it to a project at .claude/skills/taskeristl/SKILL.md to share it with your repo. Either way, pair it with the MCP endpoint (preferred) or the HTTP API and an X-API-Key.

Errors

All errors return JSON with this shape:

{
  "error": {
    "code": "validation_error",
    "message": "Request body failed validation",
    "details": [ ... ]
  }
}

The HTTP status code is the source of truth.