codeviewer-mcp

codeviewer-mcp is a TypeScript MCP server for stateful, AST-aware code review workflows.

It runs over STDIO and is designed for MCP clients and LLM harnesses that can launch local MCP servers.

What this server provides

• MCP tools for iterative plan registration and code-chunk review

• SQLite-backed review sessions and history

• AST indexing/context localization for JS/TS source trees

• Preflight checks (TypeScript diagnostics + security pattern detection)

• Structured review output with verdicts, categorized feedback, and optional patch hints

Related MCP server: code-analysis-mcp-server

MCP tools

1. register_plan

2. review_code_chunk

3. cleanup_expired_sessions

4. cleanup_session

5. list_sessions

6. list_indexing_errors

7. list_prompt_profiles

8. health_check

Prerequisites

These prerequisites are required for this MCP to install and run correctly.

Native build toolchain by OS:

• Windows: Visual Studio Build Tools 2022 (Desktop development with C++) + Python 3

• macOS: Xcode Command Line Tools (xcode-select --install)

• Linux (Debian/Ubuntu): build-essential python3 make g++

If native builds are missing, pnpm install can fail while compiling better-sqlite3.

Quick start

git clone https://github.com/Master0fFate/codeviewer-mcp.git
cd codeviewer-mcp
pnpm install
pnpm build
pnpm start

Development mode:

pnpm dev

Environment variables

Example:

MCP_PROJECT_PATH=/absolute/path/to/repo \
MCP_SESSION_TTL_HOURS=24 \
LOG_LEVEL=info \
node dist/index.js

For a database shared by multiple server principals, configure the secret only in the trusted process environment:

MCP_SHARED_DB=true \
MCP_PRINCIPAL_TOKEN='your-shared-secret' \
MCP_REVIEWER_DB_PATH=/absolute/path/to/shared/reviews.sqlite \
node dist/index.js

The STDIO process/connection is the authentication boundary. The principal token is a startup identity used only to derive a project-root-bound owner namespace; it is never part of an MCP tool schema and does not provide per-call authentication. Without shared mode, the server derives a stable local owner key from the canonical project root and database path.

Prompt profile workflow (compartmentalized prompts)

This MCP now supports session-level prompt compartmentalization from the prompts folder.

• Add prompt files as *.md in the prompts directory.

• Profile ID is the filename without extension.

  • Example: prompts/cybersec.md -> prompt_profile: "cybersec"

• Start a session with register_plan and optional prompt_profile.

• The selected profile is persisted on the session and reused for every review_code_chunk call in that session.

• review_code_chunk output includes:

  • active_prompt_profile

  • active_prompt_title

  • active_prompt_headings

Use list_prompt_profiles to see profile IDs, titles, filenames, and headings. Full prompt bodies remain server-side and are not exposed through the normal MCP tool surface.

Example register_plan payload with specialization profile:

{
  "project_path": "/absolute/path/to/repo",
  "prompt_profile": "cybersec",
  "steps": [
    "Review auth and secrets handling",
    "Check unsafe execution paths"
  ]
}

LLM auto-install guide

This section is written for autonomous LLM installers and MCP harnesses.

Canonical server launch

node /absolute/path/to/codeviewer-mcp/dist/index.js

Idempotent install/update (bash)

set -euo pipefail
INSTALL_ROOT="${HOME}/mcp-servers"
SERVER_DIR="${INSTALL_ROOT}/codeviewer-mcp"

mkdir -p "${INSTALL_ROOT}"
if [ ! -d "${SERVER_DIR}/.git" ]; then
  git clone https://github.com/Master0fFate/codeviewer-mcp.git "${SERVER_DIR}"
else
  git -C "${SERVER_DIR}" pull --ff-only
fi

cd "${SERVER_DIR}"
pnpm install
pnpm build

Idempotent install/update (PowerShell)

$InstallRoot = Join-Path $HOME "mcp-servers"
$ServerDir = Join-Path $InstallRoot "codeviewer-mcp"

New-Item -ItemType Directory -Path $InstallRoot -Force | Out-Null
if (-not (Test-Path (Join-Path $ServerDir ".git"))) {
  git clone https://github.com/Master0fFate/codeviewer-mcp.git $ServerDir
} else {
  git -C $ServerDir pull --ff-only
}

Set-Location $ServerDir
pnpm install
pnpm build

Harness installation (Claude Code, VS Code Copilot, OpenCode, generic MCP)

Use the same STDIO launch values in every harness.

Canonical server block:

{
  "name": "codeviewer-mcp",
  "transport": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/codeviewer-mcp/dist/index.js"],
  "env": {
    "MCP_PROJECT_PATH": "/absolute/path/to/target/repo",
    "MCP_REVIEWER_DB_PATH": "/absolute/path/to/target/repo/.codeviewer-mcp.sqlite",
    "LOG_LEVEL": "info"
  }
}

Claude Code / Claude Desktop

1. Open Claude MCP config.

2. Add codeviewer-mcp under mcpServers with the canonical command/args/env values.

3. Restart Claude.

4. Verify tools are discoverable.

Example:

{
  "mcpServers": {
    "codeviewer-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/codeviewer-mcp/dist/index.js"],
      "env": {
        "MCP_PROJECT_PATH": "/absolute/path/to/repo"
      }
    }
  }
}

VS Code Copilot (MCP)

1. Open VS Code MCP server management (UI or JSON settings, depending on version).

2. Register a local STDIO MCP server named codeviewer-mcp.

3. Set command node, point args to built dist/index.js, and set MCP_PROJECT_PATH.

4. Reload VS Code window if required by your extension version.

5. Confirm tool discovery in Copilot Chat MCP tools list.

If your version supports JSON settings, map the canonical server block into your MCP settings schema.

OpenCode

1. Open OpenCode MCP configuration.

2. Add a local STDIO server named codeviewer-mcp.

3. Use node + built dist/index.js.

4. Set MCP_PROJECT_PATH and optional DB/log env vars.

5. Restart OpenCode and verify tools appear.

Generic MCP clients

Any client that supports local STDIO MCP servers can use the canonical block above. If field names differ, map the same values into your client schema.

Verification checklist

• Server starts without process errors

• Client reports MCP connection established

• Tools visible: register_plan, review_code_chunk, cleanup_expired_sessions, cleanup_session, list_sessions, list_indexing_errors, list_prompt_profiles, health_check

• register_plan returns a valid session_id

• review_code_chunk returns structured verdict output

• health_check reports healthy database/session status

Development and validation

pnpm test
pnpm build
pnpm smoke

Security notes

• Path containment checks prevent escaping the configured project root, including symlink-based escapes.

• Shared database mode requires a trusted startup principal (MCP_PRINCIPAL_TOKEN); secrets are never model-visible tool inputs.

• Sessions are owner-scoped and expire automatically based on MCP_SESSION_TTL_HOURS; foreign, expired, and nonexistent IDs are indistinguishable to callers.

• Legacy sessions with no owner are quarantined by default. Use MCP_LEGACY_OWNER_POLICY=claim or purge only as an explicit migration decision.

• SQLite uses transactional PRAGMA user_version migrations, WAL mode, foreign keys, and a busy timeout.

• Request cancellation is checked at asynchronous boundaries and immediately before commit. Once synchronous parsing or the SQLite transaction begins, cancellation is best-effort and the atomic operation may finish.

• AST indexing swaps temporary state only after a complete successful reindex and uses a bounded lease-aware LRU cache.

• Structured logs use stderr only, carry JSON-RPC request correlation, and redact tokens, raw code, database paths, and session identifiers.

• Shutdown stops admission, aborts active work, and reports when MCP_SHUTDOWN_GRACE_MS elapses, but shared resources remain open until admitted handlers settle. The process watchdog is derived from the configured grace plus a five-second finalization allowance.

Repository layout

• /src/index.ts - Process entrypoint and STDIO transport

• /src/server.ts - MCP server and tool registration

• /src/schemas.ts - Zod tool contract schemas

• /src/state.ts - SQLite state store and session lifecycle

• /src/ast.ts - AST indexing and context localization

• /src/preflight.ts - Static preflight checks

• /src/reviewer.ts - Review decision and output shaping

• /src/logger.ts - Structured logging

• /tests - Vitest test suite

License

GNU v3