Python Code Review MCP Agent

Instructions

Implementation Reference

• src/index.ts:81-105 (registration)

  MCP tool registration for 'review_python_code' including name, description, and input schema.

  {
    name: 'review_python_code',
    description: 'Comprehensive Python code analysis focusing on quality and security. Provides detailed reports with actionable recommendations.',
    inputSchema: {
      type: 'object',
      properties: {
        code: {
          type: 'string',
          description: 'Python code to analyze'
        },
        filename: {
          type: 'string',
          description: 'Name of the file (optional, defaults to unknown.py)',
          default: 'unknown.py'
        },
        reportType: {
          type: 'string',
          enum: ['detailed', 'summary', 'security'],
          description: 'Type of report to generate',
          default: 'detailed'
        }
      },
      required: ['code']
    }
  },

• src/index.ts:26-30 (schema)

  Zod input validation schema for review_python_code tool.

  const ReviewCodeSchema = z.object({
    code: z.string().min(1, "Code cannot be empty"),
    filename: z.string().optional().default("unknown.py"),
    reportType: z.enum(["detailed", "summary", "security"]).optional().default("detailed")
  });

• src/index.ts:243-268 (handler)

  Core handler function for 'review_python_code' tool: validates input, performs analysis, generates and returns formatted report.

  private async handleReviewCode(args: unknown) {
    const { code, filename, reportType } = ReviewCodeSchema.parse(args);
    
    const result = this.analyzer.analyzePythonCode(code, filename);
    let report: string;
    
    switch (reportType) {
      case 'summary':
        report = this.formatter.generateSummaryReport(result);
        break;
      case 'security':
        report = this.formatter.generateSecurityReport(result);
        break;
      default:
        report = this.formatter.generateDetailedReport(result);
    }
  
    return {
      content: [
        {
          type: 'text',
          text: report
        }
      ]
    };
  }

• src/python-analyzer.ts:112-195 (helper)

  PythonAnalyzer.analyzePythonCode: Performs the core static analysis detecting issues via regex patterns for security, quality, maintainability; calculates scores and generates issues list.

  public analyzePythonCode(code: string, fileName: string = 'unknown.py'): AnalysisResult {
    const lines = code.split('\n');
    const issues: CodeIssue[] = [];
    
    // Analyze each line
    lines.forEach((line, index) => {
      const lineNumber = index + 1;
      
      // Check security patterns
      this.securityPatterns.forEach(pattern => {
        if (pattern.pattern.test(line)) {
          issues.push({
            type: 'security',
            severity: pattern.severity,
            line: lineNumber,
            message: pattern.message,
            rule: pattern.rule,
            codeSnippet: line.trim(),
            suggestion: this.getSuggestion(pattern.rule, line)
          });
        }
      });
      
      // Check quality patterns
      this.qualityPatterns.forEach(pattern => {
        if (pattern.pattern.test(line)) {
          issues.push({
            type: 'quality',
            severity: pattern.severity,
            line: lineNumber,
            message: pattern.message,
            rule: pattern.rule,
            codeSnippet: line.trim(),
            suggestion: this.getSuggestion(pattern.rule, line)
          });
        }
      });
      
      // Check maintainability patterns
      this.maintainabilityPatterns.forEach(pattern => {
        if (pattern.pattern.test(line)) {
          issues.push({
            type: 'maintainability',
            severity: pattern.severity,
            line: lineNumber,
            message: pattern.message,
            rule: pattern.rule,
            codeSnippet: line.trim(),
            suggestion: this.getSuggestion(pattern.rule, line)
          });
        }
      });
    });
  
    // Multi-line analysis
    this.analyzeMultilinePatterns(code, issues);
    
    // Calculate metrics
    const criticalIssues = issues.filter(i => i.severity === 'critical').length;
    const highIssues = issues.filter(i => i.severity === 'high').length;
    const mediumIssues = issues.filter(i => i.severity === 'medium').length;
    const lowIssues = issues.filter(i => i.severity === 'low').length;
    
    const codeQualityScore = this.calculateCodeQualityScore(issues, lines.length);
    const securityScore = this.calculateSecurityScore(issues);
    
    return {
      fileName,
      totalLines: lines.length,
      totalIssues: issues.length,
      criticalIssues,
      highIssues,
      mediumIssues,
      lowIssues,
      issues: issues.sort((a, b) => {
        const severityOrder = { critical: 4, high: 3, medium: 2, low: 1 };
        return severityOrder[b.severity] - severityOrder[a.severity] || a.line - b.line;
      }),
      summary: this.generateSummary(issues, lines.length),
      recommendations: this.generateRecommendations(issues),
      codeQualityScore,
      securityScore
    };
  }

• src/report-formatter.ts:9-21 (helper)

  ReportFormatter.generateDetailedReport: Formats analysis results into comprehensive Markdown report used by the tool.

  public generateDetailedReport(result: AnalysisResult): string {
    const sections = [
      this.generateHeader(result),
      this.generateExecutiveSummary(result),
      this.generateScorecard(result),
      this.generateIssuesBreakdown(result),
      this.generateDetailedIssues(result),
      this.generateRecommendations(result),
      this.generateFooter()
    ];
    
    return sections.join('\n\n');
  }