debug-pipeline.ts

import * as z from "zod/v4";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const promptConfig = {
  description: "Analyze a failed pipeline execution and suggest fixes. Accepts an execution ID, pipeline ID, or Harness URL.",
  argsSchema: {
    executionId: z.string().describe("The failed execution ID, pipeline ID, or a Harness URL").optional(),
    projectId: z.string().describe("Project identifier").optional(),
  },
};

function handleDebugPipeline({ executionId, projectId }: { executionId?: string; projectId?: string }) {
  const isUrl = executionId?.startsWith("http");
  const idParam = isUrl
    ? `url="${executionId}"`
    : `execution_id="${executionId}"`;

  return {
    messages: [{
      role: "user" as const,
      content: {
        type: "text" as const,
        text: `Analyze this failed Harness pipeline execution and provide:

1. **Root cause** of the failure
2. **Which step failed** and why
3. **Suggested fix** with specific actions
4. **Similar patterns** — have we seen this failure type before?

Start by calling harness_diagnose with ${idParam}${projectId ? `, project_id="${projectId}"` : ""}, include_logs=true to get the execution report with stage/step breakdown, timing, failure details, and failed step logs.

Then analyze the diagnostic payload:
- **failure section**: failed stage, step, error message, and delegate
- **child_pipeline section**: if present, the failure is in a chained pipeline — focus on the child's failure details
- **failed_step_logs**: actual log output from the failed steps — look for error patterns, stack traces, and exit codes
- **runtime input issues**: if the error mentions unresolved \`<+input>\` expressions or missing variables, check:
  - For **post-run forensics** (what values *actually* ran?): call harness_get with resource_type="execution_inputs" and resource_id=<execution_id> to see the merged input set YAML used at runtime — this is the source of truth for what the failed run received
  - For **pre-run expectations** (what does the pipeline expect?): call harness_get with resource_type="runtime_input_template" and resource_id=<pipeline_id> to see which inputs the pipeline declares
  - Call harness_list with resource_type="input_set" and filters={ pipeline_id: <pipeline_id> } to see available input sets that could provide the missing values
  - Suggest the user either pass the missing values as \`inputs\` or use \`input_set_ids\` referencing a saved input set

Provide actionable recommendations based on the combined evidence.`,
      },
    }],
  };
}

export function registerDebugPipelinePrompt(server: McpServer): void {
  server.registerPrompt(
    "debug-pipeline-failure",
    promptConfig,
    async (args) => handleDebugPipeline(args),
  );

  // Alias: ml-infra requests this name via get_prompt("pipeline_error_analysis")
  server.registerPrompt(
    "pipeline_error_analysis",
    {
      ...promptConfig,
      description:
        "Alias of debug-pipeline-failure — analyze a failed pipeline execution and suggest fixes. Accepts an execution ID, pipeline ID, or Harness URL.",
    },
    async (args) => handleDebugPipeline(args),
  );
}