ADR-018: MCP Tasks Integration Strategy

Status

Proposed

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: running, completed, failed, cancelled
• Key methods:
  • tasks/create - Create a new task
  • tasks/get - Get task status and progress
  • tasks/list - List all tasks
  • tasks/result - Get final task result
• Use cases: Expensive computations, batch processing, operations requiring progress tracking

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

• Current SDK: @modelcontextprotocol/sdk@^1.19.1
• Latest SDK: @modelcontextprotocol/sdk@1.25.1
• Tasks support requires 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

interface McpTask {
  taskId: string; // Unique task identifier
  type: TaskType; // 'bootstrap' | 'deployment' | 'research' | 'orchestration' | 'troubleshooting' | 'validation' | 'planning'
  state: TaskState; // 'running' | 'completed' | 'failed' | 'cancelled'
  progress: number; // 0-100 percentage
  metadata: {
    tool: string; // Originating tool name
    startTime: string; // ISO timestamp
    endTime?: string; // ISO timestamp when complete
    phases?: PhaseInfo[]; // For multi-phase operations
    dependencies?: string[]; // For DAG-based execution
  };
  result?: unknown; // Final result when completed
  error?: {
    // Error info when failed
    code: string;
    message: string;
    recoverable: boolean;
  };
}

API Integration

// Server capability declaration
server.setRequestHandler(InitializeRequestSchema, async () => ({
  capabilities: {
    tasks: {
      // Enable Tasks capability
      supported: true,
      // Support task cancellation
      cancellable: true,
      // Support progress updates
      progressUpdates: true,
    },
  },
}));

// Task handlers
server.setRequestHandler('tasks/create', async request => {
  const { type, parameters } = request.params;
  return taskManager.create(type, parameters);
});

server.setRequestHandler('tasks/get', async request => {
  const { taskId } = request.params;
  return taskManager.get(taskId);
});

server.setRequestHandler('tasks/list', async request => {
  return taskManager.list(request.params.filter);
});

server.setRequestHandler('tasks/result', async request => {
  const { taskId } = request.params;
  return taskManager.getResult(taskId);
});

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)

• Upgrade MCP SDK to 1.25.1
• Create TaskManager class in src/utils/task-manager.ts
• Add task handlers in src/index.ts
• Add task persistence (file-based or memory entities)

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