session-mcp/README.md

# 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`:

```json
{
  "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 |

## CLI Wrapper

A command-line wrapper is available at `~/Development/Infrastructure/AgilitonScripts/bin/task`:

```bash
# Create task
task add "Task title" --project CF --priority P1 --type bug

# List tasks
task list                          # All open tasks
task list --project CF             # CF project tasks
task list --status in_progress     # Tasks in progress
task list --type bug               # All bugs

# Show task details
task show CF-123

# Update task
task update CF-123 --status in_progress
task update CF-123 --priority P0

# Close task
task close CF-123

# Add checklist item
task checklist add CF-123 "Complete integration tests"

# Search similar tasks
task similar "performance optimization"

# Investigation workflow
task investigate "Debug memory leak" --project CF
```

The CLI wrapper provides terminal access to all MCP tools without requiring Claude Code.

## Investigation Workflow (CF-166)

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

### Starting an Investigation

```typescript
// 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

```typescript
// 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

```bash
npm install
npm run build
```

## Development

```bash
npm run dev  # Run with tsx (no build)
```