ADR-020: MCP Tasks Integration Strategy

Status

Accepted (Phase 1 Complete)

Date

2025-12-17

Context

The Model Context Protocol (MCP) 2025-11-25 specification introduced Tasks as a new primitive for tracking durable, long-running operations. Tasks are state machines that allow servers to manage expensive computations, batch processing, and operations that may take significant time to complete.

MCP Tasks Overview

From the MCP Specification 2025-11-25:

• Tasks are durable state machines for tracking long-running operations
• Lifecycle states: working, input_required, completed, failed, cancelled
• Task Creation: Tasks are created implicitly by tools returning CreateTaskResult (not via explicit tasks/create endpoint)
• Key methods (SDK request schemas):
  • GetTaskRequestSchema (tasks/get) - Get task status and progress
  • ListTasksRequestSchema (tasks/list) - List all tasks
  • GetTaskPayloadRequestSchema (tasks/result) - Get final task result payload
  • CancelTaskRequestSchema (tasks/cancel) - Cancel an in-progress task
• Use cases: Expensive computations, batch processing, operations requiring progress tracking

Important SDK Behavior: Unlike a REST-style API, MCP Tasks do not have a tasks/create endpoint. Tasks are created as a side effect when a tool returns a CreateTaskResult containing task metadata. This design ties task creation directly to tool execution.

Current Server Architecture

The mcp-adr-analysis-server currently has several tools that implement custom long-running operation tracking:

1. Bootstrap Validation Loop Tool (src/tools/bootstrap-validation-loop-tool.ts)

   • Self-learning deployment validation system
   • Executes multiple phases: generate scripts, execute, capture learnings, update ADRs
   • Custom BootstrapExecutionResult with executionId, timestamp, progress tracking
   • DAG-based parallel execution via DAGExecutor

2. Deployment Readiness Tool (src/tools/deployment-readiness-tool.ts)

   • Multi-phase deployment validation with test failure tracking
   • Custom result interfaces: TestValidationResult, TestSuiteResult
   • History analysis and pattern recognition
   • Memory integration for deployment assessment tracking

3. Tool Chain Orchestrator (src/tools/tool-chain-orchestrator.ts)

   • Already deprecated for CE-MCP migration
   • Step dependencies, retry logic, conditional execution
   • Custom step tracking with dependsOn, retryable, conditional

4. DAG Executor (src/utils/dag-executor.ts)

   • Directed Acyclic Graph execution engine
   • Parallel task execution with dependency resolution
   • Custom TaskNode interface with retryCount, retryDelay, canFailSafely

5. Research Tools (perform-research-tool.ts, research-integration-tool.ts)

   • Multi-step research workflows
   • Custom progress tracking

6. Interactive ADR Planning Tool (src/tools/interactive-adr-planning-tool.ts)

   • 7-phase guided ADR creation workflow
   • Phases: problem_definition → research_analysis → option_exploration → decision_making → impact_assessment → implementation_planning → adr_generation
   • Session-based with persistent state across tool calls
   • Uses ResearchOrchestrator for context gathering
   • Generates TODOs from architectural decisions

7. Troubleshoot Guided Workflow Tool (src/tools/troubleshoot-guided-workflow-tool.ts)

   • Systematic troubleshooting with multiple operations: analyze_failure, generate_test_plan, full_workflow
   • Memory integration via TroubleshootingMemoryManager for session persistence
   • Stores troubleshooting sessions with effectiveness tracking
   • Related ADR lookup, follow-up action determination
   • Already deprecated for CE-MCP (returns state machine directives)

SDK Version Consideration

• Previous SDK: @modelcontextprotocol/sdk@^1.19.1
• Updated SDK: @modelcontextprotocol/sdk@^1.25.1 (completed)
• Tasks support enabled via SDK upgrade

Decision

We will integrate MCP Tasks into the mcp-adr-analysis-server to provide standardized, protocol-compliant long-running operation tracking. This integration will:

Phase 1: SDK Upgrade and Infrastructure

1. Upgrade @modelcontextprotocol/sdk from ^1.19.1 to ^1.25.1
2. Implement TaskManager utility class to abstract MCP Tasks operations
3. Add task lifecycle handlers in src/index.ts

Phase 2: Tool Migration (Priority Order)

High Priority - Replace Custom Implementations

Tool	Current Implementation	MCP Tasks Benefit
bootstrap_validation_loop	Custom executionId, phases	Standardized progress, cancellation support
deployment_readiness	Custom history tracking	Protocol-compliant state persistence
tool_chain_orchestrator	Already deprecated	Direct replacement with Tasks
troubleshoot_guided_workflow	Custom memory session tracking	Track full_workflow with session effectiveness
interactive_adr_planning	Custom 7-phase session state	Track ADR planning workflow with phase progress (14% per phase)

Medium Priority - Enhance with Tasks

Tool	Enhancement
perform_research	Track multi-step research workflows
adr_bootstrap_validation	Track script generation progress
adr_validation	Track bulk ADR validation with AI analysis progress

Phase 3: DAG Executor Integration

Integrate DAGExecutor with MCP Tasks:

• Each DAG node becomes a sub-task
• Parent task tracks overall DAG execution
• Preserve parallel execution benefits

Task Schema Design

// Internal AdrTask structure (maps to MCP Task types)
interface AdrTask {
  taskId: string; // Unique task identifier (UUID)
  type: TaskType; // 'bootstrap' | 'deployment' | 'research' | 'orchestration' | 'troubleshooting' | 'validation' | 'planning'
  status: TaskStatus; // 'working' | 'input_required' | 'completed' | 'failed' | 'cancelled' (MCP SDK values)
  progress: number; // 0-100 percentage
  tool: string; // Originating tool name
  createdAt: string; // ISO timestamp
  lastUpdatedAt: string; // ISO timestamp
  phases?: AdrTaskPhase[]; // For multi-phase operations
  result?: TaskResult; // Final result when completed
  error?: string; // Error message when failed
}

// Phase tracking for multi-step operations
interface AdrTaskPhase {
  name: string;
  description: string;
  status: 'pending' | 'working' | 'completed' | 'failed';
  startedAt?: string;
  completedAt?: string;
  result?: unknown;
}

API Integration

// Import SDK task schemas (experimental)
import {
  ListTasksRequestSchema,
  GetTaskRequestSchema,
  CancelTaskRequestSchema,
  GetTaskPayloadRequestSchema,
} from '@modelcontextprotocol/sdk/types.js';

// Server capability declaration
server.setRequestHandler(InitializeRequestSchema, async () => ({
  capabilities: {
    experimental: {
      tasks: {}, // Enable experimental Tasks capability
    },
  },
}));

// Task handlers using SDK schemas
// NOTE: No tasks/create handler - tasks are created implicitly by tools returning CreateTaskResult

server.setRequestHandler(ListTasksRequestSchema, async () => {
  const taskManager = getTaskManager();
  const tasks = await taskManager.listTasks();
  return { tasks };
});

server.setRequestHandler(GetTaskRequestSchema, async request => {
  const { taskId } = request.params;
  const taskManager = getTaskManager();
  const task = await taskManager.getTask(taskId);
  if (!task) throw new McpAdrError(`Task not found: ${taskId}`, 'TASK_NOT_FOUND');
  return { task };
});

server.setRequestHandler(CancelTaskRequestSchema, async request => {
  const { taskId } = request.params;
  const taskManager = getTaskManager();
  const cancelled = await taskManager.cancelTask(taskId);
  if (!cancelled) throw new McpAdrError(`Task not found: ${taskId}`, 'TASK_NOT_FOUND');
  return { success: true };
});

server.setRequestHandler(GetTaskPayloadRequestSchema, async request => {
  const { taskId } = request.params;
  const taskManager = getTaskManager();
  const result = await taskManager.getTaskResult(taskId);
  return result ?? {};
});

Consequences

Positive

1. Protocol Compliance: Aligns with MCP 2025-11-25 specification
2. Standardized Progress Tracking: Clients can uniformly track all long-running operations
3. Cancellation Support: Native support for cancelling in-progress operations
4. Reduced Custom Code: Replace bespoke tracking implementations
5. Better Client Integration: AI assistants can better manage and monitor operations
6. Memory Integration: Tasks can persist to memory entities for historical analysis
7. Interoperability: Other MCP clients can interact with our tasks

Negative

1. SDK Upgrade Required: May introduce breaking changes
2. Migration Effort: Existing tools need refactoring
3. Learning Curve: Team needs to understand Tasks API
4. Potential Overhead: Tasks add protocol overhead for simple operations

Neutral

1. Experimental Feature: Tasks marked as experimental in MCP spec
2. Backward Compatibility: Need to maintain support for clients without Tasks

Implementation Plan

Step 1: Infrastructure (Week 1) ✅ COMPLETE

• Upgrade MCP SDK to 1.25.1
• Create TaskManager class in src/utils/task-manager.ts
• Add task handlers in src/index.ts (ListTasks, GetTask, CancelTask, GetTaskPayload)
• Add task persistence (file-based in src/utils/task-persistence.ts)

Step 2: Bootstrap Validation Migration (Week 2)

• Wrap BootstrapValidationLoop.run() as a Task
• Emit progress updates for each phase
• Support cancellation between phases
• Migrate executionId to taskId

Step 3: Deployment Readiness Migration (Week 3)

• Wrap validation operations as Tasks
• Track test execution progress
• Integrate with memory entities

Step 4: Tool Chain Orchestrator Replacement (Week 4)

• Create tasks/orchestrate task type
• Map step execution to sub-tasks
• Preserve dependency resolution
• Remove deprecated orchestrator code

Step 5: Interactive ADR Planning Migration (Week 5)

• Wrap 7-phase planning workflow as a Task
• Map phases to progress (0-14-28-42-57-71-85-100%)
• Support session persistence across tool calls
• Enable cancellation between phases
• Track research sub-operations as nested progress

Step 6: DAG Executor Enhancement (Week 6)

• Create tasks/dag task type
• Map DAG nodes to sub-tasks
• Maintain parallel execution
• Add progress aggregation

Alternatives Considered

1. Keep Custom Implementations

• Pro: No migration effort
• Con: Not protocol-compliant, harder for clients to integrate

2. Partial Migration (High-Value Tools Only)

• Pro: Reduced effort
• Con: Inconsistent API experience

3. Wait for Tasks to Exit Experimental

• Pro: More stable API
• Con: Delays benefits, experimental doesn't mean unstable

References

• MCP Tasks Specification
• One Year of MCP Blog Post
• MCP SDK Changelog
• ADR-014: CE-MCP Architecture

Notes

This ADR is related to the ongoing CE-MCP migration (ADR-014). The tool-chain-orchestrator is already deprecated for CE-MCP, and MCP Tasks provides a natural replacement path.

---

Last Updated: 2025-12-17 (Phase 1 Complete - SDK integration and handlers implemented)