jayyeungchan/mcp-code-review

MCP Code Review Server

一个基于 Model Context Protocol (MCP) 的代码审查服务器，根据 DDD (Domain-Driven Design) 和 Clean Architecture 原则对代码进行审查，生成结构化的 Markdown 报告。

特性

• ✅ MCP 协议标准化接口 - 完全兼容 MCP 协议
• ✅ DDD 原则检查 - 检测领域模型违规、值对象可变性、聚合边界等问题
• ✅ Clean Architecture 检查 - 验证依赖方向、层次边界、接口隔离
• ✅ Markdown 报告生成 - 生成详细的、易读的审查报告
• ✅ 可扩展架构 - 遵循 Clean Architecture，易于添加新的分析规则
• ⚠️ 语言支持 - 当前版本优化支持 TypeScript/JavaScript，其他语言检测有限

架构设计

本项目严格遵循 Clean Architecture 分层：

src/
├── domain/              # 领域层 (核心业务逻辑)
│   ├── entities/        # 实体 (CodeReview)
│   ├── value-objects/   # 值对象 (ReviewResult, ReviewCriteria)
│   ├── services/        # 领域服务接口 (ICodeAnalyzer)
│   └── types.ts         # 领域类型定义
├── infrastructure/      # 基础设施层 (技术实现)
│   ├── analyzers/       # 分析器实现 (DDDAnalyzer, CleanArchAnalyzer)
│   └── formatters/      # 报告格式化器 (MarkdownFormatter)
└── interface/          # 接口层 (外部交互)
    └── handlers/        # MCP Tool 处理器

依赖方向：interface → infrastructure → domain (外层依赖内层)

安装

前置要求

• Node.js >= 18
• npm or yarn

本地安装

# 克隆仓库
git clone <repository-url>
cd mcp-code-review

# 安装依赖
npm install

# 构建项目
npm run build

全局安装 (可选)

npm install -g .

使用方法

作为 MCP Server 使用

配置 Claude Desktop (或其他 MCP 客户端):

在 ~/.config/claude/config.json 中添加:

{
  "mcpServers": {
    "code-review": {
      "command": "node",
      "args": ["/path/to/mcp-code-review/dist/index.js"]
    }
  }
}

或者如果已全局安装:

{
  "mcpServers": {
    "code-review": {
      "command": "mcp-code-review-server"
    }
  }
}

在 Claude Code 中使用

User: 请帮我 review 这段代码,检查是否符合 DDD 和 Clean Architecture 原则

[粘贴代码]

Claude: 我将使用 code-review MCP server 来进行分析...

[调用 review_code tool]

根据分析报告，发现以下问题：
1. [Critical] Line 45: 实体直接暴露内部集合...
2. [High] Line 78: 领域服务依赖了基础设施层...

Tool 参数

review_code

输入参数:

输出:

返回 Markdown 格式的审查报告，包含:

• 📊 总结 (文件信息、评分、问题统计)
• 🔍 发现的问题 (按严重程度分类)
• ✅ 建议 (立即行动、短期改进)
• 📈 指标 (详细评分表)

语言支持

当前支持

✅ 完全支持: TypeScript/JavaScript (.ts, .tsx, .js, .jsx, .mjs, .cjs)

• 准确的语法模式匹配
• DDD 和 Clean Architecture 特定检测
• 完整的问题报告

⚠️ 有限支持: 其他语言 (Go, Python, Java, C#, 等)

• 可能无法检测到语言特定的模式
• 评分 10/10 可能表示检测受限，而非代码完美
• 建议结合语言专用工具使用

语言支持路线图

• Go - 结构体字段可见性、接口定义、错误处理
• Python - 类属性、类型注解、导入检查
• Java - 访问修饰符、包结构、接口隔离
• C# - 属性、命名空间、依赖注入

欢迎贡献语言支持！参见 贡献指南。

检测规则

DDD 原则

1. 聚合根封装 (Critical)

   • 检测直接暴露内部集合的方法
   • 检测公开的数组字段

2. 值对象不可变性 (Critical)

   • 检测值对象中的 setter 方法
   • 检测非 readonly 属性

3. 领域服务纯净性 (High)

   • 检测领域层导入基础设施层代码
   • 检测直接使用外部依赖（数据库、HTTP 客户端等）

Clean Architecture 原则

1. 依赖方向 (Critical)

   • 验证导入语句的依赖方向
   • 检测内层依赖外层的违规

2. Use Case 独立性 (High)

   • 检测 Use Case 导入框架库
   • 检测直接使用基础设施库

3. 接口隔离 (Medium)

   • 检测在外层定义接口的情况

开发

目录结构

mcp-code-review/
├── src/                  # 源代码
│   ├── domain/          # 领域层
│   ├── infrastructure/  # 基础设施层
│   ├── interface/       # 接口层
│   └── index.ts         # 入口文件
├── dist/                # 编译输出
├── claudedocs/          # 设计文档
├── package.json
├── tsconfig.json
└── README.md

脚本命令

# 开发模式 (使用 tsx)
npm run dev

# 构建
npm run build

# 监听模式构建
npm run watch

添加新的分析规则

1. 实现 ICodeAnalyzer 接口:

// src/infrastructure/analyzers/MyAnalyzer.ts
export class MyAnalyzer implements ICodeAnalyzer {
  supports(reviewType: ReviewType): boolean {
    return reviewType === ReviewType.QUALITY || reviewType === ReviewType.ALL;
  }

  analyze(code: string, filePath: string): ReviewResult[] {
    // 实现分析逻辑
    return [];
  }
}

2. 在 src/index.ts 中注册:

const analyzers = [
  new DDDAnalyzer(),
  new CleanArchitectureAnalyzer(),
  new MyAnalyzer(), // 添加新的分析器
];

示例输出

# Code Review Report

## 📊 Summary

- **File**: `src/domain/user.ts`
- **Review Type**: all
- **Date**: 2025-09-30T10:30:00.000Z
- **Overall Score**: 7.5/10
- **Total Issues**: 12 (3 Critical, 5 High, 4 Medium)

---

## 🔍 Issues Found

### ❌ Critical Issues (3)

1. **Line 45**: Entity exposes internal collection directly
   - **Category**: ddd-encapsulation
   - **Impact**: Breaks encapsulation, allows external mutation
   - **Suggestion**: Return ReadonlyArray<T> or a copy of the array

...

技术栈

• TypeScript - 类型安全
• @modelcontextprotocol/sdk - MCP 协议支持
• Zod - 输入验证
• Node.js - 运行时环境

贡献

欢迎贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 创建 Pull Request

许可证

MIT License

相关文档

• MCP 协议文档
• Clean Architecture
• Domain-Driven Design