mcp-memory-gateway

Instructions

Implementation Reference

• scripts/failure-diagnostics.js:431-503 (handler)

  The core implementation of the diagnoseFailure logic, which orchestrates various violation checks and categorizes failure root causes.

  function diagnoseFailure(options = {}) {
    const compiledConstraints = options.compiledConstraints || compileFailureConstraints({
      toolSchemas: options.toolSchemas,
      intentPlan: options.intentPlan,
      allowedToolNames: options.allowedToolNames,
      mcpProfile: options.mcpProfile,
      projectRoot: options.projectRoot,
    });
    const toolPolicyViolations = findToolPolicyViolations(
      options.toolName,
      compiledConstraints,
    );
    const toolSchemaViolations = findToolSchemaViolations(
      options.toolName,
      options.toolArgs,
      compiledConstraints.toolSchemas,
      {
        skipMissingSchema: toolPolicyViolations.length > 0,
      },
    );
    const verificationViolations = findVerificationViolations(options.verification);
    const approvalViolations = findApprovalViolations(options.intentPlan);
    const guardrailViolations = findGuardrailViolations(options);
    const workflowViolations = findWorkflowViolations(options.context, compiledConstraints, options.verification);
    const systemViolations = findSystemViolations(options);
    const category = pickCategory({
      systemViolations,
      approvalViolations,
      guardrailViolations,
      toolPolicyViolations,
      toolSchemaViolations,
      verificationViolations,
      workflowViolations,
      context: options.context,
    });
  
    const evidence = buildEvidence(options);
    const violations = [
      ...systemViolations,
      ...approvalViolations,
      ...guardrailViolations,
      ...toolPolicyViolations,
      ...toolSchemaViolations,
      ...workflowViolations,
      ...verificationViolations,
    ];
    const suspicious = options.suspect === true
      || violations.length > 0
      || (options.verification && options.verification.passed === false);
  
    if (!category) {
      return {
        diagnosed: false,
        suspicious,
        rootCauseCategory: null,
        criticalFailureStep: null,
        violations: [],
        evidence,
        constraintSummary: compiledConstraints.summary,
      };
    }
  
    return {
      diagnosed: true,
      suspicious,
      rootCauseCategory: category || 'tool_output_misread',
      criticalFailureStep: options.step || (options.healthCheck && options.healthCheck.name) || options.toolName || 'verification',
      violations,
      evidence,
      constraintSummary: compiledConstraints.summary,
      compiledConstraints: options.includeConstraints === true ? compiledConstraints : undefined,
    };
  }

• adapters/mcp/server-stdio.js:167-187 (handler)

  The MCP adapter handler that calls diagnoseFailure and maps tool arguments for the execution of the diagnose_failure tool.

    const result = diagnoseFailure({
      step: args.step,
      context: args.context || '',
      toolName: args.toolName,
      toolArgs: args.toolArgs,
      output: args.output,
      error: args.error,
      exitCode: args.exitCode,
      verification: args.verification,
      guardrails: args.guardrails,
      rubricScores: args.rubricScores,
      intentPlan,
      mcpProfile: requestedProfile,
      allowedToolNames,
      toolSchemas: TOOLS.filter((tool) => allowedToolNames.includes(tool.name)),
      includeConstraints: true,
      projectRoot: args.repoPath,
    });
  
    return toTextResult(result);
  }

• scripts/tool-registry.js:78-100 (registration)

  The definition and schema registration for the diagnose_failure tool.

  readOnlyTool({
    name: 'diagnose_failure',
    description: 'Diagnose a failed or suspect workflow step using MCP schema, workflow, gate, and approval constraints.',
    inputSchema: {
      type: 'object',
      properties: {
        step: { type: 'string' },
        context: { type: 'string' },
        toolName: { type: 'string' },
        toolArgs: { type: 'object' },
        output: { type: 'string' },
        error: { type: 'string' },
        exitCode: { type: 'number' },
        intentId: { type: 'string' },
        approved: { type: 'boolean' },
        mcpProfile: { type: 'string' },
        verification: { type: 'object' },
        rubricScores: {
          type: 'array',
          items: {
            type: 'object',
            properties: {
              criterion: { type: 'string' },