codeviewer-mcp

codeviewer-mcp 是一个用于有状态、具备 AST 感知能力的代码审查工作流的 TypeScript MCP 服务器。

它通过 STDIO 运行，专为能够启动本地 MCP 服务器的 MCP 客户端和 LLM 工具链设计。

该服务器提供的功能

• 用于迭代计划注册和代码块审查的 MCP 工具

• 基于 SQLite 的审查会话和历史记录

• 针对 JS/TS 源码树的 AST 索引/上下文定位

• 预检检查（TypeScript 诊断 + 安全模式检测）

• 包含结论、分类反馈和可选补丁提示的结构化审查输出

Related MCP server: lsp-intelligence

MCP 工具

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. get_prompt_profile

9. health_check

先决条件

此 MCP 要正确安装和运行，需要满足以下先决条件。

各操作系统的原生构建工具链：

• Windows: Visual Studio Build Tools 2022 (使用 C++ 的桌面开发) + Python 3

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

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

如果缺少原生构建工具，pnpm install 在编译 better-sqlite3 时可能会失败。

快速开始

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

开发模式：

pnpm dev

环境变量

示例：

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

设置 MCP_AUTH_TOKEN 时的身份验证示例：

{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "plan_step": 1,
  "target_file": "src/example.ts",
  "code_chunk": "export const ok = true;",
  "modification_type": "MODIFY",
  "auth_token": "your-shared-secret"
}

提示词配置文件工作流（分区提示词）

此 MCP 现在支持从 prompts 文件夹进行会话级的提示词分区。

• 将提示词文件以 *.md 格式添加到 prompts 目录中。

• 配置文件 ID 为不带扩展名的文件名。

  • 示例：prompts/cybersec.md -> prompt_profile: "cybersec"

• 使用 register_plan 和可选的 prompt_profile 启动会话。

• 所选配置文件将持久化在会话中，并用于该会话中的每次 review_code_chunk 调用。

• review_code_chunk 输出包含：

  • active_prompt_profile

  • active_prompt_title

  • active_prompt_headings

使用辅助工具：

• list_prompt_profiles 查看可用配置文件。

• get_prompt_profile 读取配置文件的完整提示词内容。

带有专业化配置文件的 register_plan 有效载荷示例：

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

LLM 自动安装指南

本节专为自主 LLM 安装程序和 MCP 工具链编写。

规范服务器启动

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

幂等安装/更新 (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

幂等安装/更新 (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

工具链安装 (Claude Code, VS Code Copilot, OpenCode, 通用 MCP)

在每个工具链中使用相同的 STDIO 启动值。

规范服务器块：

{
  "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. 打开 Claude MCP 配置。

2. 在 mcpServers 下添加 codeviewer-mcp，并填入规范的 command/args/env 值。

3. 重启 Claude。

4. 验证工具是否可被发现。

示例：

{
  "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. 打开 VS Code MCP 服务器管理（根据版本不同，可能是 UI 或 JSON 设置）。

2. 注册一个名为 codeviewer-mcp 的本地 STDIO MCP 服务器。

3. 设置命令 node，将参数指向构建好的 dist/index.js，并设置 MCP_PROJECT_PATH。

4. 如果扩展版本要求，请重新加载 VS Code 窗口。

5. 在 Copilot Chat MCP 工具列表中确认工具发现情况。

如果您的版本支持 JSON 设置，请将规范服务器块映射到您的 MCP 设置架构中。

OpenCode

1. 打开 OpenCode MCP 配置。

2. 添加一个名为 codeviewer-mcp 的本地 STDIO 服务器。

3. 使用 node + 构建好的 dist/index.js。

4. 设置 MCP_PROJECT_PATH 以及可选的数据库/日志环境变量。

5. 重启 OpenCode 并验证工具是否出现。

通用 MCP 客户端

任何支持本地 STDIO MCP 服务器的客户端都可以使用上面的规范块。 如果字段名称不同，请将相同的值映射到您的客户端架构中。

验证清单

• [ ] 服务器启动且无进程错误

• [ ] 客户端报告 MCP 连接已建立

• [ ] 工具可见：register_plan, review_code_chunk, cleanup_expired_sessions, cleanup_session, list_sessions, list_indexing_errors, list_prompt_profiles, get_prompt_profile, health_check

• [ ] register_plan 返回有效的 session_id

• [ ] review_code_chunk 返回结构化的结论输出

• [ ] health_check 报告健康的数据库/会话状态

开发与验证

pnpm test
pnpm build

安全说明

• 路径包含检查可防止逃逸出配置的项目根目录，包括基于符号链接的逃逸。

• 身份验证是可选的 (MCP_AUTH_TOKEN)，建议在共享环境中启用。

• 会话根据 MCP_SESSION_TTL_HOURS 自动过期。

• SQLite 配置为 WAL 模式并启用了外键。

仓库布局

• /src/index.ts - 进程入口点和 STDIO 传输

• /src/server.ts - MCP 服务器和工具注册

• /src/schemas.ts - Zod 工具契约架构

• /src/state.ts - SQLite 状态存储和会话生命周期

• /src/ast.ts - AST 索引和上下文定位

• /src/preflight.ts - 静态预检检查

• /src/reviewer.ts - 审查决策和输出塑造

• /src/logger.ts - 结构化日志记录

• /tests - Vitest 测试套件

许可证

GNU v3