Task MCP Server

Exposes task management tools via Model Context Protocol. Uses PostgreSQL with pgvector for semantic search.

Requirements

• SSH tunnel to services: ssh -L 5432:localhost:5432 services -N &
• PostgreSQL with pgvector on services (CI stack postgres container)
• CI postgres must be running: ssh services "cd /opt/docker/ci && docker compose up -d postgres"

Configuration

Add to ~/.claude/settings.json under mcpServers:

{
  "task-mcp": {
    "command": "node",
    "args": ["/path/to/task-mcp/dist/index.js"],
    "env": {
      "DB_HOST": "localhost",
      "DB_PORT": "5432",
      "DB_NAME": "agiliton",
      "DB_USER": "agiliton",
      "DB_PASSWORD": "<from /opt/docker/ci/.env>",
      "LLM_API_URL": "https://llm.agiliton.cloud",
      "LLM_API_KEY": "sk-master-..."
    }
  }
}

Tools

Tool	Description
task_add	Create task with auto-generated ID and embedding
task_list	List tasks with filters (project, status, type, priority)
task_show	Show task details including checklist and dependencies
task_close	Mark task as completed
task_update	Update task fields
task_investigate	Start investigation workflow (auto-links subsequent tasks)
task_similar	Find semantically similar tasks using pgvector
task_context	Get related tasks for current work context
task_link	Create dependency between tasks
task_checklist_add	Add checklist item to task
task_checklist_toggle	Toggle checklist item

Investigation Workflow (CF-166)

The investigation workflow helps organize multi-step problem analysis by automatically linking related tasks.

Starting an Investigation

// Start investigation
task_investigate({
  title: "Investigate $4,746 Brave API cost overrun",
  project: "CF",
  priority: "P1",
  description: "Determine why Brave API costs are 10x expected"
});

This creates an investigation task and sets it as the session's investigation parent. All subsequent tasks created in this session will automatically link to the investigation.

Auto-Linking Behavior

When you create tasks during an active investigation:

1. Investigation Parent Linking: New tasks automatically link to the investigation task
2. Current Task Linking: Tasks also link to the current working task (if different from investigation)
3. Time-Based Linking: If no investigation is active, tasks created within 1 hour auto-link to recent tasks in the same session

Task Types

• task: General work item (default)
• bug: Bug fix
• feature: New feature
• debt: Technical debt
• investigation: Multi-step problem analysis (use with task_investigate)

Example Investigation Flow

// 1. Start investigation
task_investigate({
  title: "Investigate database performance degradation",
  project: "CF"
});
// Creates CF-100 (investigation task)

// 2. Create subtasks - these auto-link to CF-100
task_add({
  title: "Check slow query log",
  project: "CF"
});
// Creates CF-101, auto-links to CF-100

task_add({
  title: "Analyze connection pool metrics",
  project: "CF"
});
// Creates CF-102, auto-links to CF-100

// 3. View investigation with all linked tasks
task_show({ id: "CF-100" });
// Shows investigation with all related subtasks

Session Context

The MCP server tracks session context to enable smart auto-linking:

• Current Task: The task you're actively working on (set when status changes to in_progress)
• Investigation Parent: The investigation task all new tasks should link to
• Auto-link Enabled: Whether to automatically create task links (default: true)

Session context is stored per session and cleared when tasks are completed or sessions end.

Build

npm install
npm run build

Development

npm run dev  # Run with tsx (no build)