@j0hanz/code-assistant

v1.1.1

Published

10 hours ago

Gemini-powered MCP server for code analysis.

0High
0Medium
0Low

j0hanz

mcp mcp-server code-assistant code-review code-suggestions code-explanations code-refactorings google-genai typescript

Code Assistant MCP Server

Gemini-powered MCP server for automated code review, analysis, and documentation.

Overview

Code Assistant 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

Requirements

Node.js >= 24
A 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"
      }
    }
  }
}

Docker

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

Or with Docker Compose:

GEMINI_API_KEY=your-api-key docker compose up

Client Configuration

Add to .vscode/mcp.json:

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

Or install via CLI:

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

For more info, see VS Code MCP docs.

Add to .vscode/mcp.json:

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

Or install via CLI:

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

For more info, see VS Code Insiders MCP docs.

Add to ~/.cursor/mcp.json:

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

For more info, see Cursor MCP docs.

Add to mcp.json:

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

For more info, see Visual Studio MCP docs.

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

For more info, see Goose MCP docs.

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

For more info, see LM Studio MCP docs.

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 mcp add code-assistant -- npx -y @j0hanz/code-assistant@latest

Or add to config:

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

For more info, see Windsurf MCP docs.

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

Or add to config:

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

For more info, see Amp MCP docs.

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.

Add to ~/.codex/config.yaml:

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

For more info, see Codex CLI MCP docs.

Add to .vscode/mcp.json:

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

For more info, see GitHub Copilot MCP docs.

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

For more info, see Warp MCP docs.

Add to .kiro/settings/mcp.json:

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

For more info, see Kiro MCP docs.

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "code-assistant": {
      "command": "npx",
      "args": ["-y", "@j0hanz/code-assistant@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-assistant": {
      "settings": {
        "command": "npx",
        "args": ["-y", "@j0hanz/code-assistant@latest"]
      }
    }
  }
}

For more info, see Zed MCP docs.

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

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

For more info, see Augment MCP docs.

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

For more info, see Roo Code MCP docs.

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

For more info, see Kilo Code MCP docs.

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

[MCP Client]
    │
    │ Transport: stdio
    ▼
[MCP Server: code-assistant]
    │ 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]

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. | | 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-assistant@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-assistant

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Code Assistant MCP Server

Overview

Key Features

Requirements

Quick Start

Docker

Client Configuration

Use Cases

PR Review Pipeline

Single-File Analysis

Performance Audit

Research

Architecture

Request Lifecycle

MCP Surface

Tools

Resources

Prompts

MCP Capabilities

Tool Annotations

Structured Output

Configuration

CLI Flags

Security

Development

Build and Release

Troubleshooting

Credits

Contributing and License