Deep Code Reasoning MCP Server

Instructions

Implementation Reference

• src/index.ts:730-762 (handler)

  MCP tool dispatch handler for 'run_hypothesis_tournament': parses input using schema, validates context, constructs config, calls DeepCodeReasonerV2.runHypothesisTournament, and formats result as MCP response.

  case 'run_hypothesis_tournament': {
    const parsed = RunHypothesisTournamentSchema.parse(args);
  
    // Validate and sanitize the Claude context
    const validatedContext = InputValidator.validateClaudeContext(parsed.claude_context);
  
    // Override with specific values from the parsed input
    const context: ClaudeCodeContext = {
      ...validatedContext,
      analysisBudgetRemaining: 300, // 5 minutes for tournament
    };
  
    const tournamentConfig = {
      maxHypotheses: parsed.tournament_config?.max_hypotheses ?? 6,
      maxRounds: parsed.tournament_config?.max_rounds ?? 3,
      parallelSessions: parsed.tournament_config?.parallel_sessions ?? 4,
    };
  
    const result = await deepReasoner.runHypothesisTournament(
      context,
      InputValidator.validateString(parsed.issue, 1000),
      tournamentConfig,
    );
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/analyzers/DeepCodeReasonerV2.ts:541-573 (handler)

  DeepCodeReasonerV2 handler method: creates or uses HypothesisTournamentService instance and delegates to its runTournament method, with error handling.

  async runHypothesisTournament(
    context: ClaudeCodeContext,
    issue: string,
    tournamentConfig?: {
      maxHypotheses?: number;
      maxRounds?: number;
      parallelSessions?: number;
    },
  ): Promise<TournamentResult> {
    try {
      // Override tournament config if provided
      const tournament = tournamentConfig
        ? new HypothesisTournamentService(
            this.geminiApiKey,
            tournamentConfig,
          )
        : this.tournamentService;
  
      // Run the tournament
      const result = await tournament.runTournament(context, issue);
  
      return result;
    } catch (error) {
      console.error('Hypothesis tournament failed:', {
        error,
        issue,
        tournamentConfig,
        contextFiles: context.focusArea.files,
        entryPoints: context.focusArea.entryPoints,
      });
      throw error;
    }
  }

• src/services/HypothesisTournamentService.ts:50-112 (handler)

  Core tournament execution logic: generates hypotheses, runs elimination rounds in parallel, computes winner, extracts findings and recommendations.

  async runTournament(
    context: ClaudeCodeContext,
    issue: string,
  ): Promise<TournamentResult> {
    const startTime = Date.now();
    
    // Generate initial hypotheses
    const hypotheses = await this.generateHypotheses(context, issue);
    
    const rounds: TournamentRound[] = [];
    let remainingHypotheses = [...hypotheses];
    let allFindings: Finding[] = [];
  
    // Run tournament rounds
    for (let roundNum = 1; roundNum <= this.config.maxRounds && remainingHypotheses.length > 1; roundNum++) {
      const round = await this.runRound(
        roundNum,
        remainingHypotheses,
        context,
        issue,
        rounds,
      );
      
      rounds.push(round);
      allFindings.push(...this.extractFindingsFromRound(round));
      
      // Eliminate low-confidence hypotheses
      remainingHypotheses = round.results
        .filter(r => r.overallConfidence >= this.config.eliminationThreshold)
        .sort((a, b) => b.overallConfidence - a.overallConfidence)
        .slice(0, Math.ceil(remainingHypotheses.length / 2))
        .map(r => r.hypothesis);
      
      // Share insights across sessions if enabled
      if (this.config.crossPollinationEnabled && remainingHypotheses.length > 1) {
        await this.crossPollinateInsights(round.results);
      }
    }
  
    // Determine winner and runner-up
    const finalResults = rounds[rounds.length - 1]?.results || [];
    const sortedResults = finalResults.sort((a, b) => b.overallConfidence - a.overallConfidence);
    
    const winner = sortedResults[0];
    const runnerUp = sortedResults[1];
  
    // Calculate metrics
    const duration = Date.now() - startTime;
    const sequentialTime = hypotheses.length * (duration / rounds.length);
    const parallelEfficiency = sequentialTime / duration;
  
    return {
      issue,
      totalHypotheses: hypotheses.length,
      rounds,
      winner,
      runnerUp,
      allFindings,
      recommendations: this.generateRecommendations(winner, runnerUp, allFindings),
      duration,
      parallelEfficiency,
    };
  }

• src/index.ts:127-144 (schema)

  Zod schema for validating run_hypothesis_tournament tool input parameters.

  const RunHypothesisTournamentSchema = z.object({
    claude_context: z.object({
      attempted_approaches: z.array(z.string()),
      partial_findings: z.array(z.any()),
      stuck_description: z.string(),
      code_scope: z.object({
        files: z.array(z.string()),
        entry_points: z.array(z.any()).optional(),
        service_names: z.array(z.string()).optional(),
      }),
    }),
    issue: z.string(),
    tournament_config: z.object({
      max_hypotheses: z.number().min(2).max(20).optional(),
      max_rounds: z.number().min(1).max(5).optional(),
      parallel_sessions: z.number().min(1).max(10).optional(),
    }).optional(),
  });

• src/index.ts:418-492 (registration)

  Tool registration in ListTools response: defines name, description, and inputSchema for MCP tool discovery.

    name: 'run_hypothesis_tournament',
    description: 'Run a competitive hypothesis tournament to find root causes. Multiple AI conversations test different theories in parallel, with evidence-based scoring and elimination rounds.',
    inputSchema: {
      type: 'object',
      properties: {
        claude_context: {
          type: 'object',
          properties: {
            attempted_approaches: {
              type: 'array',
              items: { type: 'string' },
              description: 'What Claude Code already tried',
            },
            partial_findings: {
              type: 'array',
              description: 'Any findings Claude Code discovered',
            },
            stuck_description: {
              type: 'string',
              description: 'Description of where Claude Code got stuck',
            },
            code_scope: {
              type: 'object',
              properties: {
                files: {
                  type: 'array',
                  items: { type: 'string' },
                  description: 'Files to analyze',
                },
                entry_points: {
                  type: 'array',
                  description: 'Specific functions/methods to start from',
                },
                service_names: {
                  type: 'array',
                  items: { type: 'string' },
                  description: 'Services involved in cross-system analysis',
                },
              },
              required: ['files'],
            },
          },
          required: ['attempted_approaches', 'partial_findings', 'stuck_description', 'code_scope'],
        },
        issue: {
          type: 'string',
          description: 'Description of the issue to investigate',
        },
        tournament_config: {
          type: 'object',
          properties: {
            max_hypotheses: {
              type: 'number',
              minimum: 2,
              maximum: 20,
              description: 'Number of initial hypotheses to generate (default: 6)',
            },
            max_rounds: {
              type: 'number',
              minimum: 1,
              maximum: 5,
              description: 'Maximum tournament rounds (default: 3)',
            },
            parallel_sessions: {
              type: 'number',
              minimum: 1,
              maximum: 10,
              description: 'Max concurrent conversations (default: 4)',
            },
          },
        },
      },
      required: ['claude_context', 'issue'],
    },
  },