LLM Code Reviewer Service

An intelligent, automated code review system that integrates with GitLab repositories to analyze merge requests and provide actionable feedback using AI-powered criteria evaluation.

🎯 Overview

The LLM Code Reviewer Service transforms the traditional code review process by:

• Automated Analysis: Processes GitLab merge requests automatically via webhooks
• AI-Powered Insights: Uses PocketFlow-orchestrated LLM agents for semantic code analysis
• Configurable Criteria: Manages review criteria through natural language via MCP tools
• Contextual Feedback: Provides line-specific comments directly in GitLab merge requests
• Multi-Category Reviews: Supports style, security, performance, and bug detection criteria

🔥 Product Features (from PRD)

Core Capabilities

• GitLab Integration: Webhook-driven merge request processing
• PocketFlow Orchestration: Two-phase review workflow (Context Gathering → Code Review)
• MongoDB Storage: Persistent review criteria and history
• MCP Tools: Natural language criteria management via Cursor IDE
• Multi-Language Support: Configurable criteria per programming language
• Real-Time Processing: Asynchronous review pipeline with immediate webhook response

Review Categories

• Style: Code formatting, naming conventions, documentation
• Security: Vulnerability detection, data exposure, injection risks
• Performance: Algorithm efficiency, memory usage, resource management
• Bugs: Logic errors, edge cases, error handling

🚀 PocketFlow Implementation

The service leverages PocketFlow - a 100-line minimalist LLM framework for orchestrating the review process through two connected flows:

Context Gathering Flow

FetchMergeRequestNode → AnalyzeFilesNode → CombineInsightsNode

Code Review Flow

GenerateCommentsNode → PostReviewNode

Flow Connection: Flows are chained using PocketFlow's operator overloading pattern, maintaining state through a SimplifiedSharedStore.

🔄 Complete Code Review Workflow

1. GitLab Webhook Reception

GitLab MR Event → Express Server (/api/webhook/gitlab) → Payload Validation

2. Flow Orchestration

graph TD
    A[GitLab Webhook] --> B[Express Server]
    B --> C[Context Gathering Flow]
    C --> D[Code Review Flow]
    D --> E[GitLab API]
    E --> F[MR Comments Posted]
    
    G[MongoDB] --> C
    G --> D
    H[Review Criteria] --> D

3. Processing Pipeline

Phase 1: Context Gathering

• FetchMergeRequestNode: Retrieves MR details, file changes, and diffs
• AnalyzeFilesNode: Semantic analysis of changed files with LLM
• CombineInsightsNode: Consolidates findings and prepares context

Phase 2: Code Review

• GenerateCommentsNode: LLM-powered review against stored criteria
• PostReviewNode: Posts structured comments to GitLab MR

4. End-to-End Flow

[GitLab MR] → [Webhook] → [Validation] → [PocketFlow] → [LLM Analysis] → [Criteria Check] → [Comments] → [GitLab API]

🛠️ Setup & Installation

Prerequisites

• Node.js 16+
• MongoDB instance
• GitLab instance with webhook access
• Anthropic API key

Installation

1. Clone and Install

git clone <repository-url>
cd mcp-server-template
npm install

1. Environment Configuration

cp .env.example .env
# Edit .env with your configuration

1. Required Environment Variables

# Server
PORT=8001

# Database
MONGODB_URI=mongodb://localhost:27017/code-reviewer

# GitLab Integration
GITLAB_API_URL=https://your-gitlab-instance.com/api/v4
GITLAB_API_TOKEN=your-gitlab-token
GITLAB_WEBHOOK_SECRET=your-webhook-secret

# AI Services
ANTHROPIC_API_KEY=your-anthropic-key

# Observability (Optional)
LANGFUSE_BASE_URL=your-langfuse-url
LANGFUSE_PUBLIC_KEY=your-langfuse-public-key
LANGFUSE_SECRET_KEY=your-langfuse-secret-key

1. Database Setup

npm run db:init

1. Build and Run

# Development
npm run dev

# Production
npm run build
npm start

🔧 MCP Tool Interfaces

The service exposes powerful MCP tools for criteria management via Cursor IDE:

Available Tools

| Tool | Purpose | Usage | |------|---------|-------| | createCriteria | Create structured review criteria | Manual criteria definition | | nlpCreateCriteria | Create criteria from natural language | "Check for SQL injection vulnerabilities" | | listCriteria | List all criteria with filters | Browse by category/language | | getCriteria | Get specific criteria details | Inspect individual criteria | | updateCriteria | Modify existing criteria | Edit rules and examples | | enableDisableCriteria | Toggle criteria active status | Control which criteria are applied | | deleteCriteria | Remove criteria | Cleanup unused criteria |

MCP Configuration

Add to your Cursor settings.json:

{
  "mcpServers": {
    "code-reviewer": {
      "url": "http://localhost:8001/sse",
      "type": "url"
    }
  }
}

Example MCP Usage

// Create criteria via natural language
await nlpCreateCriteria({
  description: "Check for hardcoded API keys and secrets in JavaScript files"
});

// List security criteria
await listCriteria({
  category: "security",
  language: ["javascript", "typescript"]
});

📋 GitLab Webhook Setup

1. In GitLab Project Settings:

   • Go to Settings → Webhooks
   • URL: http://your-server:8001/api/webhook/gitlab
   • Secret Token: (your GITLAB_WEBHOOK_SECRET)
   • Trigger: Merge request events

2. Supported Events:

   • Merge request opened
   • Merge request updated
   • Merge request reopened

🧪 Testing

# Unit tests
npm run test:unit

# Integration tests
npm run test:integration

# Coverage report
npm run test:coverage

# Test webhook processing
npm run test:client

📊 Monitoring & Observability

• Langfuse Integration: Traces all LLM calls and flow execution
• Structured Logging: Winston-based logging with module-specific loggers
• Health Endpoints: /health and /health/detailed for monitoring
• Metrics: Flow execution times, success rates, and error tracking

🔍 Architecture

src/
├── api/webhook/          # GitLab webhook handlers
├── flows/               # PocketFlow implementations
├── nodes/               # Individual workflow nodes
├── tools/               # MCP tools for criteria management
├── services/            # External service integrations
├── models/              # MongoDB schemas
└── config/              # Application configuration

📖 Documentation

• Product PRD: Complete product requirements
• PocketFlow Docs: Framework documentation
• API Documentation: Generated API docs via TypeDoc

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

MIT License - see LICENSE file for details