Codesentinel

CodeSentinel MCP 服务

一款全面的代码质量分析服务，适用于 Model Context Protocol (MCP)。CodeSentinel 可与 Claude Code 和其他兼容 MCP 的客户端集成，用于检测安全漏洞、欺骗性模式和不完整代码，并突出良好实践。

为什么选择 CodeSentinel？

AI 编码助手可能会无意中引入一些不易察觉的问题：硬编码密钥、空的 catch 块、遗留的 TODO 占位内容，或隐藏错误的模式。CodeSentinel 充当质量关卡，在问题进入生产环境之前，分析代码中的 5 类共 93 种不同模式。

主要差异：

• 考虑验证的检测：许多模式包含验证步骤，可减少误报
• 针对 LLM 优化的输出：结构化 JSON 输出，专为 AI 使用和采取行动而设计
• 平衡的分析：既能检测问题，也能识别优点，从而公平地评估代码
• 多语言支持：支持 TypeScript、JavaScript、Python、Go、Rust、Java 等

为什么不用 Tree-sitter 或基于 AST 的工具？

CodeSentinel 有意采用基于模式的方法，而非 AST 解析。原因如下：

我们要解决的问题不同

传统代码检查工具（ESLint、tree-sitter）检测语法错误和风格违规。CodeSentinel 检测的是语义上具有欺骗性的模式——这类代码：

• 语法有效（通过所有代码检查工具）
• 结构正确（AST 有效）
• 但隐藏了 AI Agent 常会引入的严重问题

AST 工具会遗漏的示例

// AST sees: valid try-catch block
// CodeSentinel sees: error swallowing that masks failures
try { riskyOperation(); } catch(e) { }

// AST sees: valid function returning boolean
// CodeSentinel sees: fake implementation that always succeeds
function validateUser() { return true; } // TODO: implement

// AST sees: valid fallback expression
// CodeSentinel sees: failure masking - "no data" vs "fetch failed" indistinguishable
const users = response.data || [];

// AST sees: valid return statement
// CodeSentinel sees: silent failure hiding
if (error) { return null; } // error case

各种方法检测的问题

问题类型	AST/Tree-sitter	CodeSentinel
语法错误	是	否（不在我们的目标范围内）
缺少分号	是	否
未使用的变量	是	否
空的 catch 块	部分支持	是
静默返回错误	否	是
虚假的成功响应	否	是
TODO/占位代码	否	是
掩盖错误的回退方案	否	是
硬编码密钥	有限支持	是
欺骗性注释	否	是

真正的问题：Agent 行为

AI 编码 Agent 生成的代码看起来正确，却包含不易察觉的欺骗性做法：

1. “让错误消失”——空的 catch 块、静默返回、吞掉异常
2. 占位实现——return true、return []、TODO 注释
3. 制造虚假信心的模式——会掩盖获取失败的 || [] 回退方案
4. 滥用抑制指令——使用 @ts-ignore、eslint-disable 隐藏类型错误

这些模式能通过所有代码检查并成功编译。AST 工具看到的是有效结构。只有基于模式的检测才能捕捉代码背后的语义意图。

何时使用哪种工具

工具	适用场景
ESLint/TSLint	风格一致性、语法规则、未使用的代码
Tree-sitter	语法高亮、代码导航、重构
TypeScript	类型安全、编译时错误
CodeSentinel	Agent 生成的欺骗性代码、隐藏错误、不完整实现

CodeSentinel 可与这些工具互补——它能捕捉它们在结构层面无法检测的问题。

功能

• 安全分析（16 种模式）：硬编码密钥、SQL 注入、XSS、命令注入、不安全的加密、禁用 SSL 等
• 欺骗性模式检测（17 种模式）：空的 catch 块、静默失败、隐藏错误的回退方案、抑制代码检查
• 占位内容检测（19 种模式）：TODO/FIXME/HACK 注释、lorem ipsum、测试数据、不完整实现
• 错误和代码异味检测（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

或者使用 Streamable HTTP 端点（推荐用于较新的客户端）：

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

端点

端点	协议	描述
https://code-sentinel-mcp.sharara.dev/mcp	Streamable HTTP	推荐
https://code-sentinel-mcp.sharara.dev/sse	Server-Sent Events	旧版支持
https://code-sentinel-mcp.sharara.dev/	HTTP GET	健康检查 / 服务信息

在 Cloudflare 上自托管

部署你自己的实例：

cd cloudflare
npm install
npm run dev      # Local development at localhost:8787
npm run deploy   # Deploy to your Cloudflare account

要求：

• 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：四人帮设计模式（Singleton、Factory、Observer）
  • code：实现惯用法（错误处理、异步模式）
  • all：所有层级（默认）
• query（字符串，可选）：用于聚焦分析的自然语言查询（例如，“如何进行错误处理？”）

**返回：**经过 LLM 优化的 JSON，包含检测到的模式、不一致之处、建议和可直接执行的行动项。

analyze_design_patterns

专门分析四人帮（GoF）设计模式。最适合了解 OOP 结构。

参数：

• 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）

ID	模式
SEC001	硬编码的机密（API 密钥、令牌、密码）
SEC002	GitHub 令牌
SEC003	OpenAI API 密钥
SEC004	AWS 访问密钥
SEC005-010	SQL 注入模式
SEC011-015	XSS 漏洞
SEC016	命令注入（eval、exec）

欺骗性模式（CS-DEC）

ID	模式
DEC001-003	空的／仅含注释的 catch 块
DEC010-012	静默拒绝的 Promise
DEC020-025	隐藏错误的回退（
DEC030+	Linter 抑制、伪造成功响应

占位内容（CS-PH）

ID	模式
PH001-005	TODO/FIXME/HACK/XXX/NOTE 注释
PH010-015	Lorem ipsum、占位文本
PH020-025	测试／虚拟数据（[email protected]、password123）
PH030+	console.log 调试、debugger 语句

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

ID	模式
ERR001-005	宽松相等（==）、类型强制转换问题
ERR010-015	空引用风险
ERR020-025	异步反模式
ERR030+	不指定基数的 parseInt、循环中的数组变更

优势（CS-STR）

ID	模式
STR001-005	TypeScript 严格类型检查
STR010-015	恰当的错误处理模式
STR020-025	测试覆盖率指标
STR030+	文档、输入验证

评分算法

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

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

严重性	扣分
严重	-25 分
高	-15 分
中	-5 分
低	-1 分
优势	+2 分（奖励）

支持的语言

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

扩展名	语言
.ts、.tsx	TypeScript
.js、.jsx	JavaScript
.py	Python
.go	Go
.rs	Rust
.java	Java
.kt	Kotlin
.swift	Swift
.cs	C#
.cpp、.c	C/C++
.php	PHP
.vue	Vue
.svelte	Svelte

扩展 CodeSentinel

CodeSentinel 使用数据驱动的模式系统，将模式定义与正则表达式生成分离。这让添加新模式更简单，也更易于维护。

项目结构

src/
├── patterns/
│   ├── types.ts           # Type definitions for pattern configs
│   ├── builders.ts        # Functions that generate regex from configs
│   ├── compiler.ts        # Compiles definitions to executable patterns
│   └── definitions/
│       ├── security.ts    # Security vulnerability patterns
│       ├── deceptive.ts   # Error-hiding patterns
│       ├── placeholders.ts # Incomplete code patterns
│       ├── errors.ts      # Code smell patterns
│       └── index.ts       # Exports all definitions
├── analyzers/
│   ├── core.ts            # Unified analyzer using compiled patterns
│   ├── security.ts        # Security analyzer (delegates to core)
│   ├── deceptive.ts       # Deceptive analyzer (delegates to core)
│   ├── placeholders.ts    # Placeholder analyzer (delegates to core)
│   ├── errors.ts          # Error analyzer (delegates to core)
│   └── strengths.ts       # Strength analyzer
└── index.ts               # MCP server entry point

添加新模式

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

// Old approach (manual regex)
{
  id: 'CS-DEC001',
  pattern: /catch\s*\([^)]*\)\s*\{\s*\}/g,  // Error-prone
  title: 'Empty Catch Block',
  // ...
}

// New approach (data-driven)
{
  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'
  }
}

可用的匹配类型

匹配类型	描述	配置示例
empty_block	空的 catch/finally/promise 代码块	{ type: 'empty_block', constructs: ['catch', '.catch'] }
function_call	函数/方法调用	{ type: 'function_call', names: ['eval', 'exec'] }
returns_only	返回特定值的 return 语句	{ type: 'returns_only', values: ['null', '[]', '{}'] }
contains_text	注释/字符串中的文本	{ type: 'contains_text', terms: ['TODO', 'FIXME'], context: 'comment' }
fallback_value	回退模式	{ type: 'fallback_value', operators: ['||'], values: ['[]'] }
catch_handler	Catch 代码块的行为	{ type: 'catch_handler', behavior: 'empty' }
promise_catch	Promise .catch() 的行为	{ type: 'promise_catch', behavior: 'returns_silent' }
comment_marker	TODO/FIXME/HACK 标记	{ type: 'comment_marker', markers: ['TODO', 'FIXME'] }
string_literal	字符串中的模式	{ type: 'string_literal', patterns: ['password', 'secret'] }
secret_pattern	API 密钥和令牌	{ type: 'secret_pattern', kind: 'github' }
url_pattern	URL 模式	{ type: 'url_pattern', protocol: 'http', excludeLocalhost: true }
suppression_comment	Linter 抑制注释	{ type: 'suppression_comment', tools: ['ts-ignore', 'eslint-disable'] }
type_cast	类型转换	{ type: 'type_cast', targets: ['any'] }
comparison	比较运算符	{ type: 'comparison', operators: ['==', '!='] }
loop_pattern	循环模式	{ type: 'loop_pattern', kind: 'while_true' }
raw_regex	复杂模式的逃生通道	{ type: 'raw_regex', pattern: 'your-regex', flags: 'gi' }

分步指南：添加模式

1. 选择类别 - security、deceptive、placeholder 或 error
2. 打开定义文件 - src/patterns/definitions/<category>.ts
3. 使用相应的匹配类型添加新的模式定义
4. 构建 - npm run build
5. 测试 - 使用 MCP 检查器验证检测结果

模式定义结构

{
  id: string;              // Unique ID: CS-<CAT><NUM> (e.g., CS-SEC001)
  title: string;           // Short description (displayed in results)
  description: string;     // Detailed explanation of the issue
  severity: Severity;      // 'critical' | 'high' | 'medium' | 'low' | 'info'
  category: Category;      // 'security' | 'deceptive' | 'placeholder' | 'error'
  suggestion?: string;     // How to fix the issue
  match: MatchConfig;      // What to detect (see match types above)
  verification?: {         // Optional: reduce false positives
    status: 'needs_verification' | 'confirmed';
    assumption?: string;
    confirmIf?: string;
    falsePositiveIf?: string;
  }
}

开发

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Test with MCP inspector
npm run inspector

贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 按照现有格式添加模式
4. 提交 pull request

许可证

MIT

链接

• GitHub 仓库
• npm 软件包
• 远程服务
• Model Context Protocol
• Claude Code