Deep Code Reasoning MCP Server

Instructions

Implementation Reference

• src/index.ts:235-254 (registration)

  Registers the 'hypothesis_test' MCP tool with name, description, and JSON input schema defining hypothesis, code_scope (files), and test_approach.

  {
    name: 'hypothesis_test',
    description: 'Use Gemini to test specific theories about code behavior',
    inputSchema: {
      type: 'object',
      properties: {
        hypothesis: { type: 'string' },
        code_scope: {
          type: 'object',
          properties: {
            files: { type: 'array', items: { type: 'string' } },
            entry_points: { type: 'array' },
          },
          required: ['files'],
        },
        test_approach: { type: 'string' },
      },
      required: ['hypothesis', 'code_scope', 'test_approach'],
    },
  },

• src/index.ts:68-75 (schema)

  Zod schema for validating 'hypothesis_test' tool inputs: hypothesis (string), code_scope with files array, optional entry_points, and test_approach (string). Used in handler parsing.

  const HypothesisTestSchema = z.object({
    hypothesis: z.string(),
    code_scope: z.object({
      files: z.array(z.string()),
      entry_points: z.array(z.any()).optional(),
    }),
    test_approach: z.string(),
  });

• src/index.ts:566-592 (handler)

  MCP CallToolRequest handler for 'hypothesis_test': parses args with HypothesisTestSchema, validates/sanitizes inputs and file paths, delegates execution to deepReasoner.testHypothesis, returns JSON-formatted result as text content.

  case 'hypothesis_test': {
    const parsed = HypothesisTestSchema.parse(args);
  
    // Validate file paths
    const validatedFiles = InputValidator.validateFilePaths(parsed.code_scope.files);
    if (validatedFiles.length === 0) {
      throw new McpError(
        ErrorCode.InvalidParams,
        'No valid file paths provided',
      );
    }
  
    const result = await deepReasoner.testHypothesis(
      InputValidator.validateString(parsed.hypothesis, 2000),
      validatedFiles,
      InputValidator.validateString(parsed.test_approach, 1000),
    );
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/analyzers/DeepCodeReasonerV2.ts:205-240 (handler)

  DeepCodeReasonerV2.testHypothesis method: reads code files from codeScope using SecureCodeReader, passes sanitized codeFiles/hypothesis/testApproach to GeminiService.testHypothesis for analysis, returns structured result.

  async testHypothesis(
    hypothesis: string,
    codeScope: string[],
    testApproach: string,
  ): Promise<{
    hypothesis: string;
    testApproach: string;
    analysis: string;
    filesAnalyzed: string[];
  }> {
    const codeFiles = new Map<string, string>();
  
    // Read all files in scope
    for (const file of codeScope) {
      try {
        const content = await this.codeReader.readFile(file);
        codeFiles.set(file, content);
      } catch (error) {
        console.error(`Failed to read ${file}:`, error);
      }
    }
  
    // Use Gemini to test hypothesis
    const analysis = await this.geminiService.testHypothesis(
      hypothesis,
      codeFiles,
      testApproach,
    );
  
    return {
      hypothesis,
      testApproach,
      analysis,
      filesAnalyzed: Array.from(codeFiles.keys()),
    };
  }

• src/services/GeminiService.ts:438-470 (helper)

  GeminiService.testHypothesis: builds secure, sanitized prompt with hypothesis, testApproach, and formatted code files; sends to Gemini-2.5-pro model; returns raw analysis text response.

    async testHypothesis(
      hypothesis: string,
      codeFiles: Map<string, string>,
      testApproach: string,
    ): Promise<string> {
      const systemInstructions = `Test the provided hypothesis about the code behavior.
  
  Systematically:
  1. Find evidence supporting the hypothesis
  2. Find evidence contradicting the hypothesis
  3. Consider edge cases and boundary conditions
  4. Evaluate the likelihood of the hypothesis being correct
  5. Suggest specific tests or checks to validate
  
  Be rigorous and evidence-based in your analysis.`;
  
      // Prepare sanitized data
      const codeFileData: string[] = [];
      for (const [file, content] of codeFiles) {
        codeFileData.push(PromptSanitizer.formatFileContent(file, content));
      }
  
      const userData = {
        'Hypothesis': PromptSanitizer.sanitizeString(hypothesis),
        'Test Approach': PromptSanitizer.sanitizeString(testApproach),
        'Code Files for Analysis': codeFileData.join('\n\n'),
      };
  
      const prompt = PromptSanitizer.createSafePrompt(systemInstructions, userData);
  
      const result = await this.model.generateContent(prompt);
      return result.response.text();
    }