Code Lens MCP Server

Gemini-powered MCP server for automated code review, analysis, and documentation.

Overview

Code Lens is a Model Context Protocol server that uses Google Gemini to analyze diffs, review pull requests, detect code smells, generate documentation, and verify logic. It exposes 13 tools, 7 resources, and 5 prompts over stdio transport.

Key Features

PR review pipeline — generate diffs, assess impact, detect breaking API changes, and produce review summaries with merge recommendations
File analysis — load any source file for refactoring suggestions, code smell detection, documentation generation, and natural-language Q&A
Logic verification — verify algorithms using Gemini's code execution sandbox
Structured outputs — all tools return validated JSON via Zod v4 output schemas
Web search — Google Search with Grounding for up-to-date information retrieval
Task lifecycle support — every tool except load_file can run via MCP tasks with polling, cancellation, and progress updates

Requirements

Node.js >= 24
A Gemini API key (GEMINI_API_KEY or GOOGLE_API_KEY)

Quick Start

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Docker

bash

docker run -i --rm -e GEMINI_API_KEY="your-api-key" ghcr.io/j0hanz/code-lens

Or with Docker Compose:

bash

GEMINI_API_KEY=your-api-key docker compose up

Client Configuration

<details> <summary>Install in VS Code</summary>

Add to .vscode/mcp.json:

json

{
  "servers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Or install via CLI:

code --add-mcp '{"name":"code-lens","command":"npx","args":["-y","@j0hanz/code-lens-mcp@latest"]}'

For more info, see VS Code MCP docs.

</details> <details> <summary>Install in VS Code Insiders</summary>

Add to .vscode/mcp.json:

json

{
  "servers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

Or install via CLI:

code-insiders --add-mcp '{"name":"code-lens","command":"npx","args":["-y","@j0hanz/code-lens-mcp@latest"]}'

For more info, see VS Code Insiders MCP docs.

</details> <details> <summary>Install in Cursor</summary>

Add to ~/.cursor/mcp.json:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Cursor MCP docs.

</details> <details> <summary>Install in Visual Studio</summary>

Add to mcp.json:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Visual Studio MCP docs.

</details> <details> <summary>Install in Goose</summary>

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Goose MCP docs.

</details> <details> <summary>Install in LM Studio</summary>

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see LM Studio MCP docs.

</details> <details> <summary>Install in Claude Desktop</summary>

Add to claude_desktop_config.json:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Claude Desktop MCP docs.

</details> <details> <summary>Install in Claude Code</summary>

claude mcp add code-lens -- npx -y @j0hanz/code-lens-mcp@latest

Or add to config:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Claude Code MCP docs.

</details> <details> <summary>Install in Windsurf</summary>

Add to ~/.codeium/windsurf/mcp_config.json:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Windsurf MCP docs.

</details> <details> <summary>Install in Amp</summary>

amp mcp add code-lens -- npx -y @j0hanz/code-lens-mcp@latest

Or add to config:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Amp MCP docs.

</details> <details> <summary>Install in Cline</summary>

Add to cline_mcp_settings.json:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Cline MCP docs.

</details> <details> <summary>Install in Codex CLI</summary>

Add to ~/.codex/config.yaml:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Codex CLI MCP docs.

</details> <details> <summary>Install in GitHub Copilot</summary>

Add to .vscode/mcp.json:

json

{
  "servers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see GitHub Copilot MCP docs.

</details> <details> <summary>Install in Warp</summary>

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Warp MCP docs.

</details> <details> <summary>Install in Kiro</summary>

Add to .kiro/settings/mcp.json:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Kiro MCP docs.

</details> <details> <summary>Install in Gemini CLI</summary>

Add to ~/.gemini/settings.json:

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Gemini CLI MCP docs.

</details> <details> <summary>Install in Zed</summary>

Add to ~/.config/zed/settings.json:

json

{
  "context_servers": {
    "code-lens": {
      "settings": {
        "command": "npx",
        "args": ["-y", "@j0hanz/code-lens-mcp@latest"]
      }
    }
  }
}

For more info, see Zed MCP docs.

</details> <details> <summary>Install in Augment</summary>

Add to your VS Code settings.json under augment.advanced:

json

{
  "augment.advanced": {
    "mcpServers": [
      {
        "id": "code-lens",
        "command": "npx",
        "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
        "env": {
          "GEMINI_API_KEY": "your-api-key"
        }
      }
    ]
  }
}

For more info, see Augment MCP docs.

</details> <details> <summary>Install in Roo Code</summary>

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Roo Code MCP docs.

</details> <details> <summary>Install in Kilo Code</summary>

json

{
  "mcpServers": {
    "code-lens": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-lens-mcp@latest"],
      "env": {
        "GEMINI_API_KEY": "your-api-key"
      }
    }
  }
}

For more info, see Kilo Code MCP docs.

</details>

Use Cases

PR Review Pipeline

Call generate_diff to capture unstaged or staged changes
Run analyze_pr_impact to assess severity and breaking changes
Run generate_review_summary for a risk rating and merge recommendation
Run detect_api_breaking_changes to check for public API breakage
Run generate_test_plan to produce prioritized test cases

Single-File Analysis

Call load_file to cache a source file
Run refactor_code for structural improvement suggestions
Run detect_code_smells for Fowler-taxonomy anti-patterns
Run generate_documentation to generate JSDoc/TSDoc stubs
Use ask_about_code for natural-language Q&A about the file
Use verify_logic to verify algorithms with code execution

Performance Audit

Call generate_diff on a performance-sensitive change
Run analyze_time_space_complexity to detect Big-O degradation

Research

Use web_search for up-to-date documentation or API references via Google Search with Grounding

Architecture

text

[MCP Client]
    │
    │ Transport: stdio
    ▼
[MCP Server: code-lens]
    │ Entry: src/index.ts → src/server.ts
    │
    ├── initialize / initialized (lifecycle handshake)
    │
    ├── tools/call ──────────────────────────────────────────────
    │   │
    │   │ Diff-based tools (require generate_diff first):
    │   ├── [generate_diff]              Sync — capture git diff
    │   ├── [analyze_pr_impact]          Flash — severity & impact
    │   ├── [generate_review_summary]    Flash — risk & merge rec
    │   ├── [generate_test_plan]         Flash — test cases
    │   ├── [analyze_time_space_complexity] Flash — Big-O analysis
    │   ├── [detect_api_breaking_changes]  Flash — API breakage
    │   │
    │   │ File-based tools (require load_file first):
    │   ├── [load_file]                  Sync — cache source file
    │   ├── [refactor_code]              Flash — refactoring
    │   ├── [detect_code_smells]         Flash — smell detection
    │   ├── [generate_documentation]     Flash — doc stubs
    │   ├── [ask_about_code]             Flash — Q&A
    │   ├── [verify_logic]               Flash — code execution
    │   │
    │   │ Standalone:
    │   └── [web_search]                 Flash — Google Search
    │
    ├── resources/read ──────────────────────────────────────────
    │   ├── [internal://instructions]        Server usage guide
    │   ├── [internal://tool-catalog]        Tool reference
    │   ├── [internal://workflows]           Workflow sequences
    │   ├── [internal://server-config]       Runtime config
    │   ├── [internal://tool-info/{name}]    Per-tool details
    │   ├── [internal://diff/current]        Cached diff (text/x-patch)
    │   └── [internal://file/current]        Cached source file
    │
    ├── prompts/get ─────────────────────────────────────────────
    │   ├── [get-help]           Full server instructions
    │   ├── [review-guide]       Tool + focus area workflow
    │   ├── [select-workflow]    Pipeline by change type
    │   ├── [analyze-file]       File analysis pipeline
    │   └── [tool-chain]         Tool prerequisite chain
    │
    └── Capabilities: structured output, tool annotations, notifications

Request Lifecycle

text

[Client] -- initialize {protocolVersion, capabilities} --> [Server]
[Server] -- {protocolVersion, capabilities, serverInfo} --> [Client]
[Client] -- notifications/initialized --> [Server]
[Client] -- tools/call {name, arguments} --> [Server]
[Server] -- notifications/progress {token, progress, total} --> [Client]
[Server] -- {content, structuredContent, isError?} --> [Client]

Task Lifecycle

generate_diff and load_file are sync-only. All other tools advertise taskSupport: optional.
Requestors may supply a task TTL. The server uses that value up to MAX_TASK_TTL_MS, or falls back to TASK_TTL_MS when omitted.
Cancelled tasks remain terminal as cancelled, and tasks/result returns a cancellation-shaped tool result.

MCP Surface

Tools

Tool	Description	Prerequisite	Model
`generate_diff`	Capture git diff (unstaged/staged) and cache server-side	—	Sync
`analyze_pr_impact`	Assess severity, categories, breaking changes, rollback complexity	`generate_diff`	Flash
`generate_review_summary`	PR summary, risk rating, merge recommendation	`generate_diff`	Flash
`generate_test_plan`	Prioritized test cases and coverage guidance	`generate_diff`	Flash
`analyze_time_space_complexity`	Big-O complexity analysis and degradation detection	`generate_diff`	Flash
`detect_api_breaking_changes`	Detect breaking API/interface changes	`generate_diff`	Flash
`load_file`	Cache a source file for analysis tools	—	Sync
`refactor_code`	Complexity, duplication, naming, grouping suggestions	`load_file`	Flash
`detect_code_smells`	Structural code smells (Fowler taxonomy)	`load_file`	Flash
`generate_documentation`	JSDoc/TSDoc/docstring stubs for public exports	`load_file`	Flash
`ask_about_code`	Natural-language Q&A about a cached file	`load_file`	Flash
`verify_logic`	Verify algorithms via Gemini code execution sandbox	`load_file`	Flash
`web_search`	Google Search with Grounding	—	Flash

Resources

URI	Description	MIME
`internal://instructions`	Complete server usage instructions	`text/markdown`
`internal://tool-catalog`	Tool reference: models, params, outputs, data flow	`text/markdown`
`internal://workflows`	Recommended workflows and tool sequences	`text/markdown`
`internal://server-config`	Runtime configuration and limits	`text/markdown`
`internal://tool-info/{toolName}`	Per-tool details (parameterized)	`text/markdown`
`internal://diff/current`	Most recently generated diff	`text/x-patch`
`internal://file/current`	Most recently loaded source file	`text/plain`

Prompts

Prompt	Description
`get-help`	Full server instructions: capabilities, tools, resources, constraints
`review-guide`	Workflow guide for a specific tool and focus area
`select-workflow`	Recommended tool pipeline based on change type
`analyze-file`	Goal-based tool pipeline for single-file analysis
`tool-chain`	Full prerequisite chain for a given tool

MCP Capabilities

Tool Annotations

All tools expose MCP tool annotations:

Annotation	Used
`readOnlyHint`	Yes
`destructiveHint`	Yes
`idempotentHint`	Yes
`openWorldHint`	Yes

Structured Output

All Gemini-powered tools return validated structuredContent alongside text content, using Zod v4 output schemas.

Configuration

Variable	Default	Description
`GEMINI_API_KEY`	—	Required. Gemini API key. Falls back to `GOOGLE_API_KEY`.
`GEMINI_MODEL`	`gemini-3-flash-preview`	Override the default Gemini model for all tools.
`MAX_DIFF_CHARS`	`120000`	Maximum diff size in characters.
`MAX_CONCURRENT_CALLS`	`10`	Maximum concurrent Gemini API calls.
`MAX_CONCURRENT_BATCH_CALLS`	`2`	Maximum concurrent batch Gemini calls.
`MAX_CONCURRENT_CALLS_WAIT_MS`	`2000`	Wait timeout for concurrency semaphore.
`TASK_TTL_MS`	`300000`	Default task result retention in milliseconds when the request does not specify `task.ttl`.
`MAX_TASK_TTL_MS`	`3600000`	Upper bound for request-provided task TTL. Set to `0` to remove the cap.
`GEMINI_BATCH_MODE`	`off`	Enable Gemini batch mode.
`GEMINI_HARM_BLOCK_THRESHOLD`	`BLOCK_NONE`	Safety filter threshold (`BLOCK_NONE`, `BLOCK_ONLY_HIGH`, `BLOCK_MEDIUM_AND_ABOVE`, `BLOCK_LOW_AND_ABOVE`).
`GEMINI_DIFF_CACHE_ENABLED`	`false`	Enable Gemini context caching for large diffs.
`GEMINI_DIFF_CACHE_TTL_S`	`3600`	Cache TTL in seconds (when caching is enabled).

CLI Flags

bash

npx @j0hanz/code-lens-mcp@latest --model gemini-2.5-flash --max-diff-chars 200000

Flag	Env Equivalent
`--model`, `-m`	`GEMINI_MODEL`
`--max-diff-chars`	`MAX_DIFF_CHARS`

Security

Control	Status
Input validation	Zod v4 schema validation on all tool inputs
Path safety	`load_file` restricts paths to workspace root
Stdout safety	Logs to stderr; stdout reserved for MCP protocol
Non-root container	Docker runs as dedicated `mcp` user

Development

bash

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm run dev          # Watch mode
npm run dev:run      # Run with --watch and .env
npm run start        # Run compiled server
npm run type-check   # Type-check src + tests
npm run lint         # ESLint
npm run test         # Run test suite
npm run format       # Prettier
npm run inspector    # MCP Inspector
npm run knip         # Dead code detection

Build and Release

CI: .github/workflows/release.yml
Docker: Multi-stage build (Dockerfile) with node:24-alpine
Docker Compose: docker-compose.yml
npm: Published as @j0hanz/code-lens-mcp

Troubleshooting

Missing API key: Set GEMINI_API_KEY or GOOGLE_API_KEY in your environment or client config env block.
"E_NO_DIFF" errors: Call generate_diff before running any diff-based review tool.
"E_NO_FILE" errors: Call load_file before running any file analysis tool.
Large diffs truncated: Increase MAX_DIFF_CHARS (default: 120,000 characters).
Stdout noise: Ensure no other processes write to stdout; the server uses stdio transport.

Credits

Google Gemini — LLM backend (@google/genai)
Model Context Protocol SDK — MCP framework (@modelcontextprotocol/sdk)
Zod — Schema validation (zod v4)
parse-diff — Diff parsing

Contributing and License

MIT License. See LICENSE for details.

Contributions welcome via pull requests.

Code Review Analyst

Code Lens MCP Server

Overview

Key Features

Requirements

Quick Start

Docker

Client Configuration

Use Cases

PR Review Pipeline

Single-File Analysis

Performance Audit

Research

Architecture

Request Lifecycle

Task Lifecycle

MCP Surface

Tools

Resources

Prompts

MCP Capabilities

Tool Annotations

Structured Output

Configuration

CLI Flags

Security

Development

Build and Release

Troubleshooting

Credits

Contributing and License

Learn More