# Code Lens MCP Server
[](https://www.npmjs.com/package/%40j0hanz%2Fcode-lens) [](#contributing-and-license)
[](https://insiders.vscode.dev/redirect/mcp/install?name=code-lens&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-lens%40latest%22%5D%7D) [](https://insiders.vscode.dev/redirect/mcp/install?name=code-lens&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-lens%40latest%22%5D%7D&quality=insiders) [](https://vs-open.link/mcp-install?%7B%22code-lens%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-lens%40latest%22%5D%7D%7D)
[](https://lmstudio.ai/install-mcp?name=code-lens&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1sZW5zQGxhdGVzdCJdfQ==) [](https://cursor.com/en/install-mcp?name=code-lens&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1sZW5zQGxhdGVzdCJdfQ==) [](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Fcode-lens%40latest&id=%40j0hanz%2Fcode-lens&name=code-lens&description=Gemini-powered%20MCP%20server%20for%20code%20analysis.)
Gemini-powered MCP server for automated code review, analysis, and documentation.
## Overview
Code Lens is a [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://aistudio.google.com/apikey) (`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
Install in VS Code
[](https://insiders.vscode.dev/redirect/mcp/install?name=code-lens&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-lens%40latest%22%5D%7D)
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:
```sh
code --add-mcp '{"name":"code-lens","command":"npx","args":["-y","@j0hanz/code-lens-mcp@latest"]}'
```
For more info, see [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
Install in VS Code Insiders
[](https://insiders.vscode.dev/redirect/mcp/install?name=code-lens&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-lens%40latest%22%5D%7D&quality=insiders)
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:
```sh
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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
Install in Cursor
[](https://cursor.com/en/install-mcp?name=code-lens&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1sZW5zQGxhdGVzdCJdfQ==)
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](https://docs.cursor.com/context/model-context-protocol).
Install in Visual Studio
[](https://vs-open.link/mcp-install?%7B%22code-lens%22%3A%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40j0hanz%2Fcode-lens%40latest%22%5D%7D%7D)
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](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers).
Install in Goose
[](https://block.github.io/goose/extension?cmd=npx&arg=-y&arg=%40j0hanz%2Fcode-lens%40latest&id=%40j0hanz%2Fcode-lens&name=code-lens&description=Gemini-powered%20MCP%20server%20for%20code%20analysis.)
```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](https://block.github.io/goose/docs/getting-started/using-extensions).
Install in LM Studio
[](https://lmstudio.ai/install-mcp?name=code-lens&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqMGhhbnovY29kZS1sZW5zQGxhdGVzdCJdfQ==)
```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](https://lmstudio.ai/docs/basics/mcp).
Install in Claude Desktop
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](https://modelcontextprotocol.io/quickstart/user).
Install in Claude Code
```sh
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](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp).
Install in Windsurf
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](https://docs.windsurf.com/windsurf/mcp).
Install in Amp
```sh
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](https://docs.amp.dev).
Install in Cline
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](https://docs.cline.bot/mcp-servers/configuring-mcp-servers).
Install in Codex CLI
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](https://github.com/openai/codex).
Install in GitHub Copilot
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](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
Install in Warp
```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](https://docs.warp.dev/features/mcp-model-context-protocol).
Install in Kiro
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](https://kiro.dev/docs/mcp/overview/).
Install in Gemini CLI
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](https://github.com/google-gemini/gemini-cli).
Install in Zed
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](https://zed.dev/docs/assistant/model-context-protocol).
Install in Augment
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](https://docs.augmentcode.com/setup-mcp-servers).
Install in Roo Code
```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](https://docs.roocode.com/features/mcp/using-mcp-in-roo).
Install in Kilo Code
```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](https://kilocode.ai/docs/features/mcp/using-mcp-servers).
## Use Cases
### PR Review Pipeline
1. Call `generate_diff` to capture unstaged or staged changes
2. Run `analyze_pr_impact` to assess severity and breaking changes
3. Run `generate_review_summary` for a risk rating and merge recommendation
4. Run `detect_api_breaking_changes` to check for public API breakage
5. Run `generate_test_plan` to produce prioritized test cases
### Single-File Analysis
1. Call `load_file` to cache a source file
2. Run `refactor_code` for structural improvement suggestions
3. Run `detect_code_smells` for Fowler-taxonomy anti-patterns
4. Run `generate_documentation` to generate JSDoc/TSDoc stubs
5. Use `ask_about_code` for natural-language Q&A about the file
6. Use `verify_logic` to verify algorithms with code execution
### Performance Audit
1. Call `generate_diff` on a performance-sensitive change
2. 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`](https://www.npmjs.com/package/@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](https://ai.google.dev/) — LLM backend (`@google/genai`)
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk) — MCP framework (`@modelcontextprotocol/sdk`)
- [Zod](https://zod.dev/) — Schema validation (`zod` v4)
- [parse-diff](https://www.npmjs.com/package/parse-diff) — Diff parsing
## Contributing and License
MIT License. See [LICENSE](LICENSE) for details.
Contributions welcome via [pull requests](https://github.com/j0hanz/code-lens/pulls).