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

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

Docker

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

Or with Docker Compose:

GEMINI_API_KEY=your-api-key docker compose up

Client Configuration

Add to .vscode/mcp.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.

Add to .vscode/mcp.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.

Add to ~/.cursor/mcp.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.

Add to mcp.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.

{
  "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.

{
  "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.

Add to claude_desktop_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 Desktop MCP docs.

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

Or add to config:

{
  "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.

Add to ~/.codeium/windsurf/mcp_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 Windsurf MCP docs.

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

Or add to config:

{
  "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.

Add to cline_mcp_settings.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.

Add to ~/.codex/config.yaml:

{
  "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.

Add to .vscode/mcp.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.

{
  "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.

Add to .kiro/settings/mcp.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.

Add to ~/.gemini/settings.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.

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

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

For more info, see Zed MCP docs.

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

{
  "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.

{
  "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.

{
  "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.

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

[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

[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

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

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.