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