TypeScript MCP Server for Task Dispatch (replaces bash plugin)

[Olbrasoft]

Summary

Create a TypeScript MCP server that provides task dispatch functionality for Claude Code, replacing the bash-based plugin approach.

User Story

As a Claude Code user, I want task dispatch functionality via MCP tools, so that Claude can fetch pending tasks and report completion without bash scripts.

Context

Current State (to be removed)

Claude Code → bash hooks → psql → PostgreSQL  ❌

Target Architecture

┌─────────────┐     ┌──────────────────┐     ┌─────────────────────┐     ┌────────────┐
│ Claude Code │ ←→  │ TypeScript       │ ←→  │ VirtualAssistant    │ ←→  │ PostgreSQL │
│             │     │ MCP Server       │     │ (C# .NET API)       │     │            │
└─────────────┘     └──────────────────┘     └─────────────────────┘     └────────────┘
                    HTTP calls              Entity Framework

Technology Stack (simplified)

• C# .NET - VirtualAssistant API + database access (existing)
• TypeScript - MCP server for Claude Code (new)
• No bash scripts

Why MCP Server instead of Hooks?

1. Cleaner architecture - MCP is the standard way for Claude to interact with external services
2. No bash - Pure TypeScript, type-safe, testable
3. Flexible - Claude can call tools anytime, not just on SessionStart/Stop
4. Reusable - Same MCP server can be used by multiple Claude instances

Requirements

Must Have

• Create TypeScript MCP server project
• Implement get_pending_task tool
• Implement complete_task tool
• Configure server in Claude Code settings
• Remove old bash plugin (plugins/task-dispatch/scripts/)

Should Have

• Error handling for API failures
• Timeout configuration
• Logging for debugging

Technical Specification

MCP Server Location

~/mcp-servers/task-dispatch/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── tools/
│   │   ├── get-pending-task.ts
│   │   └── complete-task.ts
│   ├── api-client.ts      # HTTP client for VirtualAssistant
│   └── types.ts           # TypeScript interfaces
├── package.json
├── tsconfig.json
└── README.md

MCP Tools

get_pending_task

Fetches the oldest pending task for Claude agent.

Input: None

Output:

interface PendingTaskResult {
  found: boolean;
  task?: {
    id: number;
    githubIssueUrl: string;
    githubIssueNumber: number;
    summary: string;
    createdAt: string;
  };
  message: string;
}

Implementation:

// Calls GET http://localhost:5055/api/claude/tasks/pending
// Returns task data or "No pending tasks" message

complete_task

Marks a task as completed with result summary.

Input:

interface CompleteTaskInput {
  taskId: number;
  result: string;
  sessionId?: string;
}

Output:

interface CompleteTaskResult {
  success: boolean;
  taskId: number;
  status: string;
  completedAt: string;
  message: string;
}

Implementation:

// Calls POST http://localhost:5055/api/claude/tasks/{id}/complete
// Body: { sessionId, result }

Claude Code Configuration

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "task-dispatch": {
      "command": "node",
      "args": ["~/mcp-servers/task-dispatch/dist/index.js"],
      "env": {
        "API_URL": "http://localhost:5055"
      }
    }
  }
}

VirtualAssistant API (already implemented)

Endpoints in VirtualAssistant repo (issue #214):

• ✅ GET /api/claude/tasks/pending
• ✅ POST /api/claude/tasks/{id}/complete

Acceptance Criteria

• Given MCP server is running, when Claude uses get_pending_task tool, then it returns pending task or "no tasks" message
• Given a pending task exists, when get_pending_task is called, then task is marked as sent in database
• Given valid task ID and result, when complete_task is called, then task is marked as completed
• Given API is unreachable, when tools are called, then appropriate error is returned
• Given old bash plugin exists, when this is implemented, then bash scripts are removed

Out of Scope

• Auto-dispatch on session start (Claude will call tools manually or via prompts)
• WebSocket real-time notifications
• Authentication/authorization

Related

• Supersedes Refactor: Task-dispatch plugin to use VirtualAssistant API instead of direct DB access #6 (bash-based refactor)
• Supersedes Task Dispatch: Plugin skeleton with hooks.json and plugin manifest #2, Task Dispatch: SessionStart hook - Load pending task from database #3, Task Dispatch: Stop hook - Save result to database #4, Deploy task-dispatch plugin to Claude Code #5 (bash plugin issues)
• Depends on VirtualAssistant#214 (API endpoints) ✅ Done

References

• MCP TypeScript SDK
• Claude Code MCP Configuration

[Olbrasoft]

Algorithm Details (preserved from #3 and #4)

Task Selection Algorithm (from #3)

FIFO with atomic locking:

-- Select oldest pending task with row-level lock
UPDATE agent_tasks
SET status = 'sent', sent_at = NOW()
WHERE id = (
    SELECT id FROM agent_tasks
    WHERE status IN ('pending', 'approved', 'notified')
    ORDER BY created_at ASC
    LIMIT 1
    FOR UPDATE SKIP LOCKED
)
RETURNING id, github_issue_number, github_issue_url, summary, created_at;

Key points:

• ORDER BY created_at ASC - FIFO ordering
• FOR UPDATE SKIP LOCKED - Atomic update, prevents race conditions
• LIMIT 1 - Only one task at a time

Context Output Format (from #3)

When Claude receives a task, format should be:

================================================================================
ASSIGNED TASK FROM VIRTUAL ASSISTANT
================================================================================

Task ID: {id}
GitHub Issue: {githubIssueUrl}
Issue Number: #{githubIssueNumber}
Created: {createdAt}

TASK DESCRIPTION:
{summary}

--------------------------------------------------------------------------------
INSTRUCTIONS:
1. Work on this task as your primary objective
2. When complete, your session result will be automatically saved
3. Include clear summary of what was done in your final response
================================================================================

Result Capture (from #4)

Primary method: Claude Code hook receives session info via stdin:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/dir"
}

Extract last assistant message from transcript:

// Read transcript file
const transcript = fs.readFileSync(transcriptPath, 'utf-8');
const lines = transcript.trim().split('\n');

// Find last assistant message
const lastAssistant = lines
  .map(line => JSON.parse(line))
  .filter(msg => msg.role === 'assistant')
  .pop();

const result = lastAssistant?.content || 'Task completed';

Fallback: prompt-based result capture:
If transcript is unavailable, use prompt hook:

Before ending, please provide a 1-2 sentence summary of what you accomplished.
Output it in the format: TASK_RESULT: <your summary>

Status Transitions

pending → sent (when task is fetched)
sent → completed (success)
sent → failed (error)

Error Handling

If task fails:

await apiClient.completeTask(taskId, {
  result: `[FAILED] ${errorMessage}`,
  sessionId: sessionId
});

---

These details should be implemented in the TypeScript MCP server tools.

[Olbrasoft]

Analysis: Weak Points & Solutions

🔴 Weak Point 1: No Auto-Dispatch on Session Start

Problem: MCP tools don't auto-run. Claude has to manually call get_pending_task. Unlike bash hooks, there's no automatic trigger on SessionStart.

Impact: Claude might start working without checking for pending tasks.

Solutions:

• A) Hybrid approach: Keep minimal SessionStart hook that just outputs reminder text:

  💡 Check for pending tasks: Use mcp__task-dispatch__get_pending_task tool
  

• B) CLAUDE.md instruction: Add to Claude's context to always check for tasks at session start
• C) Accept manual workflow: Claude (or user) explicitly calls the tool when needed

Recommendation: Option A (hybrid) - best UX with minimal bash

---

🔴 Weak Point 2: Result Capture on Session End

Problem: MCP server can't intercept session end. How does Claude know when to call complete_task?

Impact: Task might stay in "sent" status forever if Claude forgets to complete it.

Solutions:

• A) Stop hook reminder: Minimal bash Stop hook that reminds/prompts Claude
• B) Instruction-based: Task context includes clear instruction "When done, call complete_task"
• C) Timeout mechanism: Tasks in "sent" >2h automatically reset to "pending" (server-side)

Recommendation: Option B + C (instructions + server-side timeout as safety net)

---

🟡 Weak Point 3: Stale Task Recovery

Problem: If Claude session crashes after fetching task, it stays "sent" forever.

Impact: Task queue gets stuck.

Solutions:

• Add reset_stale_tasks tool or scheduled job in VirtualAssistant
• API endpoint: POST /api/claude/tasks/reset-stale?olderThanHours=2

Recommendation: Add to VirtualAssistant API (separate issue)

---

🟡 Weak Point 4: No Real-Time Notifications

Problem: Claude has to poll for tasks, can't be notified when new task arrives.

Impact: Latency between task creation and pickup.

Solutions:

• For now: Accept polling (Claude checks at session start)
• Future: WebSocket/SSE for real-time push

Recommendation: Out of scope for v1, accept polling

---

🟢 Weak Point 5: Error Handling

Problem: What if VirtualAssistant API is down?

Solutions:

• Retry logic with exponential backoff
• Clear error messages returned to Claude
• Local queue for failed completions (future)

Recommendation: Basic retry + clear errors for v1

---

Revised Architecture

┌─────────────────────────────────────────────────────────────────────┐
│ Claude Code                                                          │
├──────────────────────┬──────────────────────────────────────────────┤
│ SessionStart Hook    │ MCP Server (TypeScript)                      │
│ (minimal bash)       │                                              │
│ - Output reminder    │ - get_pending_task tool                      │
│   to check tasks     │ - complete_task tool                         │
│                      │ - API client with retry                      │
└──────────────────────┴──────────────────────────────────────────────┘
                              │
                              ▼ HTTP
┌─────────────────────────────────────────────────────────────────────┐
│ VirtualAssistant API (C# .NET)                                       │
│ - GET /api/claude/tasks/pending                                      │
│ - POST /api/claude/tasks/{id}/complete                               │
│ - POST /api/claude/tasks/reset-stale (new)                          │
└─────────────────────────────────────────────────────────────────────┘

[Olbrasoft]

Sub-tasks Created

This issue has been broken down into the following implementable sub-tasks:

Implementation Order

#	Issue	Description	Dependencies
1	#8	Project Setup - TypeScript MCP Server scaffold	None
2	#9	API Client - VirtualAssistant API client with retry logic	#8
3	#10	get_pending_task tool - MCP tool implementation	#8, #9
4	#11	complete_task tool - MCP tool implementation	#8, #9
5	#12	MCP Server integration - Main entry point (index.ts)	#8, #9, #10, #11
6	#13	Configuration & Testing - Claude Code config + docs	#12

Progress Tracking

• Sub-task 1: Project Setup - TypeScript MCP Server scaffold #8 Project Setup
• Sub-task 2: API Client with retry logic #9 API Client
• Sub-task 3: Implement get_pending_task MCP tool #10 get_pending_task tool
• Sub-task 4: Implement complete_task MCP tool #11 complete_task tool
• Sub-task 5: MCP Server integration (index.ts) #12 MCP Server integration
• Sub-task 6: Claude Code configuration and testing #13 Configuration & Testing

Recommended Approach

1. Start with Sub-task 1: Project Setup - TypeScript MCP Server scaffold #8 (Project Setup) - creates the foundation
2. Then Sub-task 2: API Client with retry logic #9 (API Client) - standalone module, can be unit tested
3. Sub-task 3: Implement get_pending_task MCP tool #10 and Sub-task 4: Implement complete_task MCP tool #11 can be done in parallel - both depend on API client
4. Sub-task 5: MCP Server integration (index.ts) #12 ties everything together
5. Sub-task 6: Claude Code configuration and testing #13 is final integration and documentation