Deep Code Reasoning MCP Server

Instructions

Implementation Reference

• src/index.ts:510-536 (handler)

  MCP CallToolRequest handler case for 'escalate_analysis': parses args using EscalateAnalysisSchema, validates context, constructs ClaudeCodeContext, calls deepReasoner.escalateFromClaudeCode and returns result as text content.

  case 'escalate_analysis': {
    const parsed = EscalateAnalysisSchema.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: parsed.time_budget_seconds,
    };
  
    const result = await deepReasoner.escalateFromClaudeCode(
      context,
      parsed.analysis_type,
      parsed.depth_level || 3,
    );
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/analyzers/DeepCodeReasonerV2.ts:32-67 (handler)

  Core logic execution for escalate_analysis: reads code files from context.focusArea, optionally enriches with related files based on depthLevel, performs analysis via GeminiService.analyzeWithGemini, handles timeout and errors.

  async escalateFromClaudeCode(
    context: ClaudeCodeContext,
    analysisType: string,
    depthLevel: number,
  ): Promise<DeepAnalysisResult> {
    const startTime = Date.now();
    const timeoutMs = context.analysisBudgetRemaining * 1000;
  
    try {
      // Read all relevant code files
      const codeFiles = await this.codeReader.readCodeFiles(context.focusArea);
  
      // Enrich with related files if depth > 3
      if (depthLevel > 3) {
        await this.enrichWithRelatedFiles(context, codeFiles);
      }
  
      // Send to Gemini for deep analysis
      const result = await this.geminiService.analyzeWithGemini(
        context,
        analysisType,
        codeFiles,
      );
  
      // Check timeout
      const elapsedTime = Date.now() - startTime;
      if (elapsedTime > timeoutMs) {
        result.status = 'partial';
      }
  
      return result;
    } catch (error) {
      console.error('Deep reasoning failed:', error);
      return this.createErrorResult(error as Error, context);
    }
  }

• src/index.ts:42-56 (schema)

  Zod schema for validating input parameters to the escalate_analysis tool.

  const EscalateAnalysisSchema = 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(),
      }),
    }),
    analysis_type: z.enum(['execution_trace', 'cross_system', 'performance', 'hypothesis_test']),
    depth_level: z.number().min(1).max(5),
    time_budget_seconds: z.number().default(60),
  });

• src/index.ts:150-212 (registration)

  Registration of escalate_analysis tool in the ListToolsRequestSchema response, defining name, description, and JSON inputSchema mirroring the Zod schema.

  name: 'escalate_analysis',
  description: 'Hand off complex analysis to Gemini when Claude Code hits reasoning limits. Gemini will perform deep semantic analysis beyond syntactic patterns.',
  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'],
      },
      analysis_type: {
        type: 'string',
        enum: ['execution_trace', 'cross_system', 'performance', 'hypothesis_test'],
        description: 'Type of deep analysis to perform',
      },
      depth_level: {
        type: 'number',
        minimum: 1,
        maximum: 5,
        description: 'How deep to analyze (1=shallow, 5=very deep)',
      },
      time_budget_seconds: {
        type: 'number',
        default: 60,
        description: 'Maximum time for analysis',
      },
    },
    required: ['claude_context', 'analysis_type'],
  },