io.github.j0hanz/code-assistant

Official

by j0hanz · TypeScript

Code Assistant

Gemini-powered MCP server for code analysis.

Analyzes code using Gemini AI to provide insights and optimization suggestions.

Topics

code-explanationcode-lenscode-refactoringcode-reviewcode-suggestionsgenaigoogle-genaigoogle-genai-sdkmcpmcp-servermcp-toolsgeminigemini-3gemini-api

README.md27 KBView on GitHub

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.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "code-assistant": {
      "command": "npx",
      "args": [
        "-y",
        "@j0hanz/code-assistant@2.0.0"
      ]
    }
  }
}