@j0hanz/code-assistant

Code Assistant MCP Server

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

Overview

This server accepts unified diffs and returns structured JSON results — findings with severity, impact categories, merge risk, test plans, and verbatim search/replace fixes. It uses Gemini Thinking models (Flash for fast tools, Flash for deep analysis) and runs over stdio transport.

Key Features

• Impact Analysis — Objective severity scoring, breaking change detection, and rollback complexity assessment.
• Review Summary — Concise PR digest with merge recommendation and change statistics.
• Deep Code Inspection — Flash model with high thinking level for context-aware analysis using full file contents.
• Search & Replace Fixes — Verbatim, copy-paste-ready code fixes tied to specific findings.
• Test Plan Generation — Systematic test case generation with priority ranking and pseudocode.
• Async Task Support — All tools support MCP task lifecycle with progress notifications.

Requirements

• Node.js >=24
• One API key: GEMINI_API_KEY or GOOGLE_API_KEY
• MCP client that supports stdio servers and tool calls

Quick Start

{
  "mcpServers": {
    "code-assistant": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-assistant@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Client Configuration

VS Code / VS Code Insiders

Add to .vscode/mcp.json:

{
  "servers": {
    "code-assistant": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-assistant@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Or via CLI:

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

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "code-assistant": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-assistant@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Visual Studio

For more info, see Visual Studio MCP docs.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "code-assistant": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-assistant@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

For more info, see Claude Desktop MCP docs.

Claude Code

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

For more info, see Claude Code MCP docs.

Windsurf

Add to MCP config:

{
  "mcpServers": {
    "code-assistant": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-assistant@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

For more info, see Windsurf MCP docs.

Amp

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

For more info, see Amp MCP docs.

Cline

Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "code-assistant": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-assistant@latest"],
      "env": {
        "GEMINI_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

For more info, see Cline MCP docs.

Zed

Add to Zed settings.json:

{
  "context_servers": {
    "code-assistant": {
      "command": {
        "path": "npx",
        "args": ["-y", "@j0hanz/code-assistant@latest"],
        "env": {
          "GEMINI_API_KEY": "YOUR_API_KEY"
        }
      }
    }
  }
}

For more info, see Zed MCP docs.

Augment

Add to settings.json:

{
  "augment.advanced": {
    "mcpServers": [
      {
        "name": "code-assistant",
        "command": "npx",
        "args": ["-y", "@j0hanz/code-assistant@latest"],
        "env": {
          "GEMINI_API_KEY": "YOUR_API_KEY"
        }
      }
    ]
  }
}

Docker

{
  "mcpServers": {
    "code-assistant": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GEMINI_API_KEY=YOUR_API_KEY",
        "ghcr.io/j0hanz/code-assistant:latest"
      ]
    }
  }
}

Or build locally:

docker build -t code-assistant .

Tools

[!IMPORTANT] Call generate_diff first (mode: "unstaged" or "staged"). All review tools read the cached server-side diff (diff://current) and do not accept a direct diff parameter.

generate_diff

Generate and cache the current branch diff for downstream review tools.

Parameter	Type	Required	Description
mode	string	Yes	unstaged (working tree) or staged (git index).

Returns: diffRef, stats (files, added, deleted), generatedAt, mode, message.

analyze_pr_impact

Assess the impact and risk of cached pull request changes using the Flash model.

Parameter	Type	Required	Description
repository	string	Yes	Repository identifier (e.g. org/repo).
language	string	No	Primary language hint.

Returns: severity (low/medium/high/critical), categories[], breakingChanges[], affectedAreas[], rollbackComplexity, summary.

generate_review_summary

Summarize a pull request diff and assess high-level risk using the Flash model.

Parameter	Type	Required	Description
repository	string	Yes	Repository identifier (e.g. org/repo).
language	string	No	Primary language hint.

Returns: summary, overallRisk (low/medium/high), keyChanges[], recommendation, stats (filesChanged, linesAdded, linesRemoved).

generate_test_plan

Create a test plan covering the changes in the diff using the Flash model with thinking (8K token budget).

Parameter	Type	Required	Description
repository	string	Yes	Repository identifier (e.g. org/repo).
language	string	No	Primary language hint.
testFramework	string	No	Test framework (e.g. jest, vitest, pytest).
maxTestCases	number	No	Maximum test cases to return (1-30).

Returns: summary, testCases[] (name, type, file, description, pseudoCode, priority), coverageSummary.

Resources

URI	Type	Description
internal://instructions	text/markdown	Server usage instructions.

Prompts

Name	Arguments	Description
get-help	—	Return the server usage instructions.
review-guide	tool, focusArea	Guided workflow for a specific tool and focus area.

Configuration

CLI Arguments

Option	Description	Env Var Equivalent
--model, -m	Override default model	GEMINI_MODEL
--max-diff-chars	Override max diff size	MAX_DIFF_CHARS

Environment Variables

Variable	Description	Default	Required
GEMINI_API_KEY	Gemini API key	—	Yes
GOOGLE_API_KEY	Alternative API key (if GEMINI_API_KEY not set)	—	No
GEMINI_MODEL	Override default model selection	—	No
GEMINI_HARM_BLOCK_THRESHOLD	Safety threshold (BLOCK_NONE, BLOCK_ONLY_HIGH, etc.)	BLOCK_NONE	No
MAX_DIFF_CHARS	Max chars for diff input	120000	No
MAX_CONCURRENT_CALLS	Max concurrent Gemini requests	10	No
MAX_CONCURRENT_BATCH_CALLS	Max concurrent inline batch requests	2	No
MAX_CONCURRENT_CALLS_WAIT_MS	Max wait time for a free Gemini slot	2000	No
MAX_SCHEMA_RETRY_ERROR_CHARS	Max chars from schema error injected into retry text	1500	No
GEMINI_BATCH_MODE	Request mode for Gemini calls (off, inline)	off	No
GEMINI_BATCH_POLL_INTERVAL_MS	Poll interval for batch job status	2000	No
GEMINI_BATCH_TIMEOUT_MS	Max wait for batch completion	120000	No

Models

Tool	Model	Thinking Level
analyze_pr_impact	gemini-3-flash-preview	minimal
generate_review_summary	gemini-3-flash-preview	minimal
generate_test_plan	gemini-3-flash-preview	medium

Workflows

Quick PR Triage

• Call analyze_pr_impact to get severity and category breakdown.
• If low/medium — call generate_review_summary for a quick digest.
• If high/critical — proceed to deep inspection.

Testing

• Call generate_test_plan to create a verification strategy.
• Implement tests based on returned test cases and coverage summary.

Development

npm ci            # Install dependencies
npm run dev       # TypeScript watch mode
npm run dev:run   # Run built server with .env and --watch

Script	Command	Purpose
npm run build	node scripts/tasks.mjs build	Clean, compile, validate, copy
npm test	node scripts/tasks.mjs test	Build + run all tests
npm run test:fast	node --test --import tsx/esm ...	Run tests without build
npm run lint	eslint .	Lint all files
npm run lint:fix	eslint . --fix	Lint and auto-fix
npm run format	prettier --write .	Format all files
npm run type-check	node scripts/tasks.mjs type-check	Type-check without emitting
npm run inspector	Build + launch MCP Inspector	Debug with MCP Inspector

Debugging with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Build & Release

Releases are triggered via GitHub Actions workflow_dispatch with version bump selection (patch/minor/major/custom).

The pipeline runs lint, type-check, test, and build, then publishes to three targets in parallel:

• npm — @j0hanz/code-assistant with OIDC trusted publishing and provenance
• Docker — ghcr.io/j0hanz/code-assistant (linux/amd64, linux/arm64)
• MCP Registry — io.github.j0hanz/code-assistant

Troubleshooting

Issue	Solution
Missing GEMINI_API_KEY or GOOGLE_API_KEY	Set one of the API key env vars in your MCP client config.
E_INPUT_TOO_LARGE	Diff exceeds budget. Split into smaller diffs.
Gemini request timed out	Deep analysis tasks may take 60-120s. Increase your client timeout.
Too many concurrent Gemini calls	Reduce parallel tool calls or increase MAX_CONCURRENT_CALLS.
No tool output visible	Ensure your MCP client is not swallowing stderr — the server uses stdio transport.

License

MIT