Code Sentinel

🚀 CodeSentinel MCP 服务器

CodeSentinel MCP 服务器是一个全面的代码质量分析服务器，专为 模型上下文协议 (MCP) 设计。它能与 Claude Code 及其他支持 MCP 的客户端集成，检测代码中的安全漏洞、欺骗性模式、不完整代码，并突出良好实践。

🚀 快速开始

CodeSentinel 作为代码质量的把关者，在问题进入生产环境之前，对代码进行分析，检测其中可能存在的问题。它能检测 5 个类别下的 93 种不同模式，确保代码的安全性和质量。

✨ 主要特性

• 安全分析（16 种模式）：检测硬编码密钥、SQL 注入、XSS、命令注入、不安全的加密、禁用的 SSL 等。
• 欺骗性模式检测（17 种模式）：检测空的 catch 块、静默失败、隐藏错误的回退机制、禁用代码检查等。
• 占位符检测（19 种模式）：检测 TODO/FIXME/HACK 注释、占位文本、测试数据、不完整的实现等。
• 错误与代码异味检测（18 种模式）：检测类型强制转换问题、空引用、异步反模式、浮点比较等。
• 优点识别（23 种模式）：突出良好实践，如正确的类型定义、错误处理、测试模式、文档编写等。
• HTML 报告：生成带有质量评分和可操作建议的可视化报告。

📦 安装指南

从 npm 安装

npm install -g code-sentinel-mcp

从源代码安装

git clone https://github.com/salrad22/code-sentinel.git
cd code-sentinel
npm install
npm run build

💻 使用示例

与 Claude Code 配合使用

快速设置

claude mcp add code-sentinel -- npx code-sentinel-mcp

若已全局安装

claude mcp add code-sentinel -- code-sentinel

手动配置

将以下内容添加到你的 Claude Code MCP 配置文件（~/.claude/claude_desktop_config.json）中：

{
  "mcpServers": {
    "code-sentinel": {
      "command": "npx",
      "args": ["code-sentinel-mcp"]
    }
  }
}

远程服务器（Cloudflare Workers）

CodeSentinel 也可作为 Cloudflare Workers 上的远程 MCP 服务器使用，无需本地安装！

快速连接（Claude Code）

claude mcp add-remote code-sentinel https://code-sentinel-mcp.sharara.dev/sse

或者使用可流式传输的 HTTP 端点（推荐用于较新的客户端）：

claude mcp add --transport http code-sentinel https://code-sentinel-mcp.sharara.dev/mcp

端点信息

在 Cloudflare 上自行托管

部署你自己的实例：

cd cloudflare
npm install
npm run dev      # 在 localhost:8787 进行本地开发
npm run deploy   # 部署到你的 Cloudflare 账户

要求：

• Cloudflare 账户（免费套餐即可）
• Wrangler CLI（npm install -g wrangler）
• 执行 wrangler login 进行身份验证

该服务器使用 Durable Objects 进行持久的 MCP 连接，无需数据库。

📚 详细文档

可用工具

analyze_code

进行全面分析，返回包含所有问题和优点的结构化 JSON。最适合编程式处理。 参数：

• code（字符串，必需）：要分析的源代码
• filename（字符串，必需）：用于语言检测的文件名（例如，"app.ts"）

返回：包含问题、优点和汇总统计信息的 JSON 对象。

generate_report

进行全面分析并生成可视化的 HTML 报告。最适合人工审查。 参数：

• code（字符串，必需）：要分析的源代码
• filename（字符串，必需）：用于语言检测的文件名

返回：Markdown 摘要和完整的 HTML 报告。

check_security

仅进行安全相关的分析。当你需要专门审核漏洞时使用。 参数：

• code（字符串，必需）：要检查的源代码
• filename（字符串，必需）：文件名

返回：安全问题列表或确认未发现问题。

check_deceptive_patterns

检查隐藏错误或产生虚假信心的代码模式。 参数：

• code（字符串，必需）：要检查的源代码
• filename（字符串，必需）：文件名

返回：发现的欺骗性模式列表。

check_placeholders

查找 TODO、虚拟数据和不完整的实现。 参数：

• code（字符串，必需）：要检查的源代码
• filename（字符串，必需）：文件名

返回：发现的占位符代码列表。

analyze_patterns

分析代码中的架构、设计和实现模式。检测模式使用情况、不一致性，并提供可操作的建议。 参数：

• code（字符串，必需）：要分析的源代码
• filename（字符串，必需）：用于语言检测的文件名
• level（字符串，可选）：要分析的模式级别：
  • architectural：系统结构模式（分层、模块）
  • design：四人组设计模式（单例、工厂、观察者）
  • code：实现习惯用法（错误处理、异步模式）
  • all：所有级别（默认）
• query（字符串，可选）：自然语言查询，用于聚焦分析（例如，"错误处理是如何实现的？"）

返回：针对大语言模型优化的 JSON，包含检测到的模式、不一致性、建议和可立即执行的操作项。

analyze_design_patterns

专注于四人组（GoF）设计模式的分析。最适合理解面向对象编程结构。 参数：

• code（字符串，必需）：要分析的源代码
• filename（字符串，必需）：用于语言检测的文件名

返回：检测到的设计模式，包含置信度级别、位置和实现细节。

示例用法

让 Claude 分析代码：

Analyze this code for quality issues:

const API_KEY = "sk-abc123456789";

async function fetchData() {
  try {
    const response = await fetch(url);
    return response.json();
  } catch (e) {
    // TODO: handle error
  }
}

CodeSentinel 将检测到：

• 严重（CS-SEC003）：OpenAI API 密钥硬编码在源代码中
• 高（CS-DEC001）：空的 catch 块静默吞掉错误
• 低（CS-PH001）：TODO 注释表明实现不完整

检测类别

安全问题（CS-SEC）

欺骗性模式（CS-DEC）

占位符（CS-PH）

错误与代码异味（CS-ERR）

优点（CS-STR）

评分算法

质量得分（0 - 100）的计算方式如下：

Score = 100 - (critical × 25) - (high × 15) - (medium × 5) - (low × 1) + (strengths × 2)

支持的语言

CodeSentinel 根据文件扩展名检测语言：

🔧 技术细节

扩展 CodeSentinel

CodeSentinel 使用数据驱动的模式系统，将模式定义与正则表达式生成分离。这使得添加新的模式更加容易和可维护。

项目结构

src/
├── patterns/
│   ├── types.ts           # 模式配置的类型定义
│   ├── builders.ts        # 从配置生成正则表达式的函数
│   ├── compiler.ts        # 将定义编译为可执行模式
│   └── definitions/
│       ├── security.ts    # 安全漏洞模式
│       ├── deceptive.ts   # 隐藏错误的模式
│       ├── placeholders.ts # 不完整代码模式
│       ├── errors.ts      # 代码异味模式
│       └── index.ts       # 导出所有定义
├── analyzers/
│   ├── core.ts            # 使用编译后的模式进行统一分析
│   ├── security.ts        # 安全分析器（委托给核心）
│   ├── deceptive.ts       # 欺骗性分析器（委托给核心）
│   ├── placeholders.ts    # 占位符分析器（委托给核心）
│   ├── errors.ts          # 错误分析器（委托给核心）
│   └── strengths.ts       # 优点分析器
└── index.ts               # MCP 服务器入口点

添加新的模式

无需手动编写正则表达式，只需定义要检测的内容，系统会自动生成正则表达式：

// 旧方法（手动正则表达式）
{
  id: 'CS-DEC001',
  pattern: /catch\s*\([^)]*\)\s*\{\s*\}/g,  // 容易出错
  title: 'Empty Catch Block',
  // ...
}

// 新方法（数据驱动）
{
  id: 'CS-DEC001',
  title: 'Empty Catch Block',
  description: 'Silently swallowing errors makes debugging impossible.',
  severity: 'high',
  category: 'deceptive',
  suggestion: 'At minimum, log the error. Better: handle it appropriately.',
  match: {
    type: 'catch_handler',
    behavior: 'empty'
  }
}

可用的匹配类型

逐步添加模式

1. 选择类别 - 安全、欺骗性、占位符或错误
2. 打开定义文件 - src/patterns/definitions/<category>.ts
3. 使用适当的匹配类型添加新的模式定义
4. 构建 - npm run build
5. 测试 - 使用 MCP 检查器验证检测结果

模式定义结构

{
  id: string;              // 唯一 ID: CS-<CAT><NUM>（例如，CS-SEC001）
  title: string;           // 简短描述（显示在结果中）
  description: string;     // 问题的详细解释
  severity: Severity;      // 'critical' | 'high' | 'medium' | 'low' | 'info'
  category: Category;      // 'security' | 'deceptive' | 'placeholder' | 'error'
  suggestion?: string;     // 如何修复问题
  match: MatchConfig;      // 要检测的内容（见上面的匹配类型）
  verification?: {         // 可选：减少误报
    status: 'needs_verification' | 'confirmed';
    assumption?: string;
    confirmIf?: string;
    falsePositiveIf?: string;
  }
}

开发

# 安装依赖
npm install

# 构建
npm run build

# 监听模式
npm run watch

# 使用 MCP 检查器进行测试
npm run inspector

贡献

欢迎贡献代码！请按照以下步骤进行：

1. 分叉仓库
2. 创建功能分支
3. 按照现有格式添加模式
4. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证。

🔗 链接

• GitHub 仓库
• npm 包
• 远程服务器
• 模型上下文协议
• Claude Code