Code Assistant MCP

Gemini-powered MCP server for code analysis with structured outputs for findings, risk assessment, and focused patch suggestions.

Overview

Code Assistant is a Model Context Protocol server that connects AI assistants to the Google Gemini API for automated code review, refactoring suggestions, complexity analysis, breaking-change detection, and test plan generation. It operates over stdio transport and exposes 13 tools, 7 resources, and 2 prompts.

Key Features

• Diff-based code review — generate diffs from git, then analyze PR impact, produce review summaries, detect API breaking changes, and assess time/space complexity
• File-based analysis — load individual files for refactoring suggestions, question answering, and logic verification via Gemini's code execution sandbox
• Repository indexing — walk a local repository into a Gemini File Search Store for natural-language RAG queries
• Web search — Google Search with Grounding for up-to-date information
• Structured outputs — all Gemini-backed tools return validated JSON via Zod v4 schemas
• Task lifecycle — supports MCP Tasks API for async operation tracking with cancellation
• Configurable thinking — per-tool thinking levels (minimal/medium/high) balance speed vs depth
• Multi-platform Docker — published to GHCR for linux/amd64 and linux/arm64

Requirements

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

Quick Start

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

[!TIP] Use the one-click install badges above for automatic setup in VS Code, Cursor, Goose, or LM Studio.

Client Configuration

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

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

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

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

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

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

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

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

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

{
  "mcpServers": {
    "code-assistant": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GEMINI_API_KEY",
        "ghcr.io/j0hanz/code-assistant:latest"
      ],
      "env": {
        "GEMINI_API_KEY": "<your-api-key>"
      }
    }
  }
}

docker run -i -e GEMINI_API_KEY="<your-api-key>" ghcr.io/j0hanz/code-assistant:latest

MCP Surface

Tools

generate_diff

Generate a diff of current changes and cache it server-side. Must be called before diff-based analysis tools.

analyze_pr_impact

Assess severity, categories, breaking changes, and rollback complexity.

generate_review_summary

Produce PR summary, risk rating, and merge recommendation.

generate_test_plan

Generate prioritized test cases and coverage guidance.

analyze_time_space_complexity

Analyze Big-O complexity and detect degradations in changed code.

detect_api_breaking_changes

Detect breaking API/interface changes in a diff.

load_file

Read a single file from disk and cache it server-side. Must be called before file analysis tools.

refactor_code

Analyze cached file for naming, complexity, duplication, and grouping improvements.

ask_about_code

Answer natural-language questions about a cached file.

verify_logic

Verify algorithms and logic in cached file using Gemini code execution sandbox.

web_search

Perform a Google Search with Grounding to get up-to-date information.

index_repository

Walk a local repository, upload source files to a Gemini File Search Store for RAG queries.

query_repository

Query the indexed repository search store using natural language.

Resources

Prompts

Configuration

Environment Variables

CLI Arguments

Security

Development

Debugging with MCP Inspector

npx @modelcontextprotocol/inspector npx -y @j0hanz/code-assistant@latest

Build and Release

• Release workflow: manual dispatch via GitHub Actions (workflow_dispatch) with version bump type (patch/minor/major) or custom version.
• npm: published to @j0hanz/code-assistant with OIDC trusted publishing and provenance attestation.
• Docker: multi-platform image (linux/amd64, linux/arm64) pushed to ghcr.io/j0hanz/code-assistant.
• MCP Registry: published to registry.modelcontextprotocol.io as io.github.j0hanz/code-assistant.

Docker Build

docker build -t code-assistant .

Troubleshooting

• Missing API key: set GEMINI_API_KEY or GOOGLE_API_KEY in your environment or client config.
• Diff too large: increase MAX_DIFF_CHARS or use --max-diff-chars flag. Lock files and build artifacts are excluded automatically.
• Inspector not connecting: ensure the server builds cleanly with npm run build before running the inspector.
• E_NO_DIFF error: call generate_diff before any diff-based analysis tool.
• E_NO_FILE error: call load_file before refactor_code, ask_about_code, or verify_logic.

Contributing and License

• License: MIT
• Repository: github.com/j0hanz/code-assistant