Code Audit MCP

🚀 MCP代碼審計服務器

本項目是一個全面的TypeScript MCP服務器，藉助本地AI模型（通過Ollama）對代碼進行智能審計，涵蓋安全性、完整性、性能、質量、架構、測試和文檔等多個維度。

🚀 快速開始

MCP代碼審計服務器是一款強大的工具，可利用本地AI模型對代碼進行多維度的審計。以下是快速上手的步驟：

1. 確保滿足項目的依賴要求，如Node.js和Ollama的安裝。
2. 選擇合適的安裝方式，如全局安裝或開發安裝。
3. 按照使用說明，通過CLI命令進行交互式設置、啟動服務器等操作。

✨ 主要特性

多維度代碼分析

• 安全性：檢測OWASP十大漏洞、認證缺陷、注入攻擊等。
• 完整性：檢查TODO項、空函數、缺失的錯誤處理和未完成的實現。
• 性能：分析算法複雜度、內存洩漏和優化機會。
• 質量：識別代碼異味、SOLID原則違背情況和可維護性問題。
• 架構：評估設計模式、關注點分離和依賴管理。
• 測試：發現可測試性問題、缺失的覆蓋率和競態條件。
• 文檔：檢查API文檔、代碼註釋和合規標準。

智能模型選擇

• 多模型支持：支持CodeLlama、DeepSeek - Coder、StarCoder2、Granite - Code、Qwen2.5 - Coder等模型。
• 基於專業化的路由：針對不同的審計類型選擇不同的模型。
• 後備策略：在模型失敗時自動切換到備用模型。
• 性能優化：提供快速模式和全面模式。

高級特性

• 上下文感知分析：支持特定框架的檢查（如React、Express、Django等）。
• 基於優先級的審計：快速模式（安全性 + 完整性）可提供快速反饋。
• 語言支持：支持10多種編程語言，並具備特定語言規則。
• 可配置的嚴重性：可自定義問題的嚴重程度閾值。
• 自動修復建議：提供帶有置信度評分的修復建議。
• 複雜度分析：分析圈複雜度、認知複雜度和可維護性指標。

📦 安裝指南

全局安裝（推薦）

# 從npm全局安裝
npm install -g @moikas/code-audit-mcp

# 運行交互式設置（包括MCP配置）
code-audit setup

# 或者使用自動MCP配置進行設置
code-audit setup --auto

# 啟動MCP服務器
code-audit start

開發安裝

# 克隆倉庫
git clone <repository-url>
cd code-audit-mcp

# 安裝依賴
npm install

# 構建項目
npm run build

# 本地測試
npm run test-local

開發環境設置

前提條件

• Node.js：版本18.0.0或更高
• npm：版本8.0.0或更高
• Git：用於版本控制和預提交鉤子
• VS Code：推薦的IDE（可參考.vscode/extensions.json安裝擴展）

初始設置

# 克隆並進入目錄
git clone https://github.com/warrengates/code-audit-mcp.git
cd code-audit-mcp

# 安裝依賴（包括husky設置）
npm install

# 構建項目
npm run build

# 運行質量檢查
npm run quality-check

# 測試設置
npm run test-local

預提交鉤子

本項目使用Husky和lint - staged進行自動代碼質量檢查：

• ESLint：檢查代碼錯誤和風格問題
• Prettier：統一代碼格式
• TypeScript：對所有TypeScript文件進行類型檢查

預提交鉤子會在git commit時自動運行。若要手動運行質量檢查：

# 運行所有質量檢查
npm run quality-check

# 修復可自動修復的問題
npm run quality-fix

# 單獨檢查
npm run lint          # ESLint檢查
npm run format:check  # Prettier檢查
npm run type-check    # TypeScript檢查

設置腳本將執行以下操作：

1. ✅ 檢查前提條件（Node.js、npm、tsx）
2. 🩺 驗證Ollama安裝和運行狀況
3. 📦 安裝推薦的AI模型
4. 🧪 測試MCP服務器功能
5. 📝 生成示例配置

手動設置

若您傾向於手動安裝：

# 安裝依賴
npm install

# 安裝必要的模型
ollama pull codellama:7b
ollama pull granite-code:8b

# 構建項目
npm run build

# 測試服務器
npm run dev

💻 使用示例

CLI命令

# 交互式設置嚮導
code-audit setup

# 啟動MCP服務器（前臺運行）
code-audit start

# 作為後臺守護進程啟動
code-audit start --daemon

# 停止正在運行的服務器
code-audit stop

# 檢查系統健康狀況
code-audit health

# 管理AI模型
code-audit models --list
code-audit models --pull codellama:7b

# 配置管理
code-audit config --show
code-audit config --set ollama.host=http://remote:11434

# MCP服務器管理
code-audit mcp status
code-audit mcp configure
code-audit mcp remove

# 檢查更新
code-audit update

開發模式

# 開啟熱重載的開發模式
npm run dev

# 構建TypeScript代碼
npm run build

# 本地測試包
npm run test-local

MCP集成

自動配置（推薦）

設置嚮導現在會自動將code - audit配置為MCP服務器：

# 在設置期間配置
code-audit setup

# 或者在安裝後配置
code-audit mcp configure

這將自動將code - audit添加到以下位置：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Code（全局）：~/.config/claude/mcp-settings.json
• Claude Code（項目）：.claude/mcp-settings.json

手動配置

若您傾向於手動配置，請將以下內容添加到MCP配置中：

{
  "mcpServers": {
    "code-audit": {
      "command": "code-audit",
      "args": ["start", "--stdio"],
      "env": {}
    }
  }
}

更多詳細信息，請參考：

• MCP配置指南
• Claude Code集成

可用工具

audit_code - 主要審計工具

{
  "name": "audit_code",
  "arguments": {
    "code": "function processPayment(amount) {\n  const query = `SELECT * FROM users WHERE id = ${userId}`;\n  // TODO: implement payment logic\n}",
    "language": "javascript",
    "auditType": "all",
    "priority": "thorough",
    "context": {
      "framework": "express",
      "environment": "production",
      "performanceCritical": true,
      "projectType": "api"
    }
  }
}

參數說明：

• code（必需）：要審計的代碼
• language（必需）：編程語言
• auditType：可選值為security、completeness、performance、quality、architecture、testing、documentation、all
• priority：可選值為fast（僅安全性 + 完整性）、thorough（所有審計類型）
• context：用於特定框架分析的額外上下文
• maxIssues：限制返回的問題數量（默認值：50）

health_check - 服務器健康狀態檢查

{
  "name": "health_check",
  "arguments": {}
}

list_models - 列出可用的AI模型

{
  "name": "list_models",
  "arguments": {}
}

📚 詳細文檔

配置

服務器配置

可創建配置文件或使用環境變量進行配置：

const config = {
  name: 'code-audit-mcp',
  version: '1.0.0',
  ollama: {
    host: 'http://localhost:11434',
    timeout: 30000,
    retryAttempts: 3,
    retryDelay: 1000,
  },
  auditors: {
    security: {
      enabled: true,
      severity: ['critical', 'high', 'medium'],
      rules: {
        sql_injection: true,
        xss_vulnerability: true,
        hardcoded_secret: true,
      },
    },
    performance: {
      enabled: true,
      severity: ['high', 'medium', 'low'],
      thresholds: {
        cyclomaticComplexity: 10,
        nestingDepth: 4,
      },
    },
  },
  logging: {
    level: 'info',
    enableMetrics: true,
    enableTracing: false,
  },
};

審計器配置

每個審計器都可以單獨配置：

{
  enabled: boolean;              // 啟用/禁用審計器
  severity: Severity[];          // 包含的嚴重程度級別
  rules: Record<string, boolean>; // 啟用/禁用的特定規則
  thresholds: Record<string, number>; // 數值閾值
}

模型選擇

可針對不同場景配置模型偏好：

// 對性能要求較高的代碼
const performanceConfig = {
  strategy: 'PerformanceModelSelectionStrategy', // 始終優先選擇快速模型
  fallbackModels: ['codellama:7b', 'granite-code:8b'],
};

// 注重質量的分析
const qualityConfig = {
  strategy: 'QualityModelSelectionStrategy', // 始終優先選擇準確的模型
  fallbackModels: ['deepseek-coder:33b', 'codellama:13b'],
};

支持的模型

必備模型（推薦）

• CodeLlama 7B：適用於快速、通用的代碼分析
• Granite Code 8B：在安全分析方面表現出色

全面配置

• CodeLlama 13B：在複雜分析中具有更高的準確性
• DeepSeek - Coder 6.7B：在性能分析方面表現優越
• StarCoder2 7B：專門用於測試分析
• Qwen2.5 - Coder 7B：適合文檔分析

完整配置（高級）

• DeepSeek - Coder 33B：具有最高的準確性（需要16GB以上的RAM）
• StarCoder2 15B：用於高級測試和架構分析
• Llama 3.1 8B：在文檔方面表現出色

模型安裝

# 必備模型（約7GB）
ollama pull codellama:7b
ollama pull granite-code:8b

# 全面配置（約30GB）
ollama pull codellama:13b
ollama pull deepseek-coder:6.7b
ollama pull starcoder2:7b
ollama pull qwen2.5-coder:7b

# 完整配置（約80GB）
ollama pull deepseek-coder:33b
ollama pull starcoder2:15b
ollama pull llama3.1:8b

語言支持

完全支持

• JavaScript/TypeScript：支持React、Node.js、Express特定的檢查
• Python：支持Django、Flask、FastAPI特定的分析
• Java：支持Spring Boot，側重於安全分析
• Go：檢查Goroutine安全性和性能模式
• Rust：關注內存安全和性能優化

良好支持

• C#：支持.NET模式和安全分析
• PHP：支持Laravel、WordPress安全檢查
• Ruby：支持Rails特定的模式
• Swift：支持iOS特定的模式
• Kotlin：支持Android特定的分析

基本支持

• C/C++：檢查內存安全和性能
• SQL：檢測注入攻擊和優化查詢
• HTML/CSS：防止XSS攻擊和優化性能
• Docker：檢查安全配置
• YAML/JSON：驗證配置

示例輸出

{
  "requestId": "audit_12345",
  "issues": [
    {
      "id": "sql_injection_2",
      "location": { "line": 2, "column": 15 },
      "severity": "critical",
      "type": "sql_injection",
      "category": "security",
      "title": "SQL injection vulnerability in query construction",
      "description": "Direct string interpolation in SQL query allows SQL injection attacks",
      "suggestion": "Use parameterized queries or prepared statements",
      "confidence": 0.95,
      "fixable": true,
      "ruleId": "SEC001",
      "documentation": "OWASP Top 10: A03:2021 – Injection"
    },
    {
      "id": "todo_3",
      "location": { "line": 3 },
      "severity": "medium",
      "type": "todo_comment",
      "category": "completeness",
      "title": "TODO comment indicates incomplete implementation",
      "description": "Found TODO comment: // TODO: implement payment logic",
      "suggestion": "Implement the missing functionality or remove the TODO comment",
      "confidence": 1.0,
      "fixable": false,
      "ruleId": "COMP001"
    }
  ],
  "summary": {
    "total": 2,
    "critical": 1,
    "high": 0,
    "medium": 1,
    "low": 0,
    "info": 0,
    "byCategory": {
      "security": 1,
      "completeness": 1
    }
  },
  "suggestions": {
    "autoFixable": [
      /* fixable issues */
    ],
    "priorityFixes": [
      /* critical/high severity */
    ],
    "quickWins": [
      /* low effort, high impact */
    ],
    "technicalDebt": [
      /* long-term improvements */
    ]
  },
  "metrics": {
    "duration": 1250,
    "modelResponseTime": 800,
    "coverage": {
      "linesAnalyzed": 15,
      "functionsAnalyzed": 1,
      "complexity": 3
    }
  }
}

性能優化

快速開發模式

{
  "auditType": "all",
  "priority": "fast" // 僅安全性 + 完整性
}

上下文感知分析

{
  "context": {
    "framework": "react",
    "environment": "production",
    "performanceCritical": true,
    "projectType": "web"
  }
}

緩存配置

{
  performance: {
    maxConcurrentAudits: 3,
    cacheEnabled: true,
    cacheTtl: 300  // 5分鐘
  }
}

審計類型深入解析

安全審計

• 覆蓋OWASP十大漏洞：檢測SQL注入、XSS、認證缺陷等。
• 特定語言漏洞：如JS的原型汙染、Python的pickle使用問題。
• 特定框架漏洞：如Express的CSRF保護、Django的SQL注入。

性能審計

• 算法分析：檢測O(n²)複雜度和優化嵌套循環。
• 內存管理：檢測內存洩漏和對象池優化機會。
• 數據庫優化：避免N + 1查詢和添加缺失的索引。
• 異步模式：檢查阻塞操作和Promise處理。

質量審計

• 代碼異味：識別長方法、大型類和重複代碼。
• SOLID原則：檢查SRP、OCP、LSP、ISP、DIP原則的違背情況。
• 可維護性：分析圈複雜度和認知負載。
• 命名規範：確保一致性、清晰度和領域對齊。

🔧 技術細節

開發

VS Code設置

本項目包含全面的VS Code配置，以提供最佳的開發體驗：

推薦擴展

安裝推薦的擴展以獲得最佳體驗：

# 安裝所有推薦的擴展
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension ms-vscode.vscode-typescript-next
code --install-extension usernamehw.errorlens
code --install-extension yoavbls.pretty-ts-errors

或者打開VS Code並接受工作區推薦彈出窗口。

工作區設置

.vscode/settings.json包含以下設置：

• 自動格式化：保存時使用Prettier格式化代碼
• 代碼檢查：即時提供ESLint反饋
• TypeScript：增強智能感知和錯誤檢查
• 導入管理：自動導入和路徑智能感知
• Git集成：為工作流程預先配置

調試

使用包含的調試配置：

1. 調試服務器：啟動並調試MCP服務器
2. 調試CLI：調試CLI命令
3. 調試測試：逐步執行測試

按F5或使用調試面板開始調試。

項目結構

code-audit-mcp/
├── src/
│   ├── server.ts              # 主MCP服務器
│   ├── types.ts               # TypeScript接口
│   ├── auditors/              # 審計實現
│   │   ├── base.ts           # 基礎審計器類
│   │   ├── security.ts       # 安全審計器
│   │   ├── completeness.ts   # 完整性審計器
│   │   ├── performance.ts    # 性能審計器
│   │   └── ...
│   ├── ollama/               # Ollama集成
│   │   ├── client.ts         # HTTP客戶端包裝器
│   │   ├── models.ts         # 模型配置
│   │   └── prompts.ts        # 審計提示
│   └── utils/                # 實用工具
│       ├── codeParser.ts     # 代碼解析
│       ├── complexity.ts     # 複雜度分析
│       └── logger.ts         # 日誌記錄工具
├── cli/
│   └── setup.ts              # 設置腳本
├── .vscode/                  # VS Code配置
│   ├── settings.json        # 工作區設置
│   ├── extensions.json      # 推薦擴展
│   └── launch.json          # 調試配置
├── .husky/                   # Git鉤子
│   └── pre-commit           # 預提交檢查
└── tests/                    # 測試套件

構建和測試

# 開發
npm run dev                   # 開啟熱重載啟動
npm run build                 # 編譯TypeScript代碼
npm run lint                  # 運行ESLint檢查
npm run format                # 使用Prettier格式化代碼

# 測試
npm test                      # 運行測試套件
npm run test:watch            # 監聽模式
npm run test:coverage         # 生成覆蓋率報告

# 生產
npm run start                 # 啟動生產服務器

添加自定義審計器

1. 創建一個新的審計器類，繼承自BaseAuditor：

import { BaseAuditor } from './base.js';

export class CustomAuditor extends BaseAuditor {
  constructor(config, ollamaClient, modelManager) {
    super('custom', config, ollamaClient, modelManager);
  }

  // 重寫方法以實現自定義邏輯
  protected async postProcessIssues(rawIssues, request, language) {
    // 自定義後處理
    return super.postProcessIssues(rawIssues, request, language);
  }
}

2. 在auditors/index.ts中註冊：

import { CustomAuditor } from './custom.js';

export const auditorClasses = {
  // ... 現有審計器
  custom: CustomAuditor,
};

3. 添加配置：

const config = {
  auditors: {
    custom: {
      enabled: true,
      severity: ['high', 'medium'],
      rules: {},
    },
  },
};

故障排除

常見問題

Ollama連接失敗

# 檢查Ollama是否正在運行
ollama list

# 啟動Ollama服務
ollama serve

# 檢查端口可用性
curl http://localhost:11434/api/tags

模型未找到

# 列出已安裝的模型
ollama list

# 安裝缺失的模型
ollama pull codellama:7b

# 檢查服務器中模型的可用性
curl -X POST http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{"model": "codellama:7b", "prompt": "test"}'

TypeScript編譯錯誤

# 清除構建緩存
rm -rf dist/
rm -rf node_modules/
npm install

# 檢查TypeScript配置
npx tsc --noEmit

# 更新依賴
npm update

內存問題

# 檢查可用內存
free -h

# 使用較小的模型
ollama pull codellama:7b  # 代替codellama:34b

# 減少併發審計
{
  "performance": {
    "maxConcurrentAudits": 1
  }
}

性能調優

模型選擇優化

// 對於CI/CD環境 - 優先考慮速度
const ciConfig = {
  strategy: 'PerformanceModelSelectionStrategy',
  priority: 'fast',
};

// 對於代碼審查 - 優先考慮準確性
const reviewConfig = {
  strategy: 'QualityModelSelectionStrategy',
  priority: 'thorough',
};

資源管理

{
  ollama: {
    timeout: 60000,        // 對於大文件增加超時時間
    retryAttempts: 5,      // 增加重試次數以提高可靠性
    healthCheckInterval: 30000  // 更頻繁地進行健康檢查
  },
  performance: {
    maxConcurrentAudits: 2,    // 對於有限的RAM減少併發審計數
    cacheEnabled: true,        // 對於重複分析啟用緩存
    cacheTtl: 600             // 10分鐘的緩存時間
  }
}

API參考

工具架構

audit_code

interface AuditRequest {
  code: string; // 必需：要審計的代碼
  language: string; // 必需：編程語言
  auditType: AuditType; // 可選：默認 'all'
  file?: string; // 可選：用於上下文的文件路徑
  context?: AuditContext; // 可選：額外的上下文
  priority?: 'fast' | 'thorough'; // 可選：默認 'thorough'
  maxIssues?: number; // 可選：默認 50
  includeFixSuggestions?: boolean; // 可選：默認 true
}

響應格式

interface AuditResult {
  requestId: string;
  issues: AuditIssue[];
  summary: AuditSummary;
  coverage: AuditCoverage;
  suggestions: AuditSuggestions;
  metrics: AuditMetrics;
  model: string;
  timestamp: string;
  version: string;
}

錯誤代碼

代碼	描述	解決方案
INVALID_REQUEST	請求格式錯誤	檢查必需參數
CODE_TOO_LARGE	代碼超過大小限制	拆分為較小的塊
LANGUAGE_NOT_SUPPORTED	不支持的語言	使用支持的語言
NO_AVAILABLE_MODEL	未找到合適的模型	安裝所需的模型
OLLAMA_UNAVAILABLE	Ollama服務不可用	啟動Ollama服務
MODEL_NOT_FOUND	請求的模型缺失	使用ollama pull拉取模型
GENERATION_FAILED	AI生成失敗	檢查模型健康狀況，重試
AUDIT_FAILED	一般審計失敗	檢查日誌，驗證配置

🤝 貢獻

我們歡迎貢獻！請參考貢獻指南獲取詳細信息。

開發環境設置

# 分叉並克隆倉庫
git clone https://github.com/your-username/code-audit-mcp.git
cd code-audit-mcp

# 安裝依賴
npm install

# 以開發模式運行
npm run dev

# 運行測試
npm test

# 提交拉取請求

代碼標準

• TypeScript：啟用嚴格模式
• ESLint：使用Airbnb配置
• Prettier：自動格式化代碼
• 測試：使用Jest，覆蓋率超過80%
• 文檔：為所有公共API使用JSDoc註釋

開發文檔

• 貢獻指南：介紹如何為項目做出貢獻
• VS Code設置：提供最佳的IDE配置
• 預提交鉤子：介紹自動質量檢查機制
• 故障排除：提供常見問題的解決方案

📄 許可證

本項目採用MIT許可證，詳情請參考LICENSE。

🙏 致謝

• Anthropic：提供Model Context Protocol規範
• Ollama：提供本地AI模型服務
• Meta：提供CodeLlama模型
• DeepSeek：提供專業的編碼模型
• BigCode：提供StarCoder模型

📞 支持

• 問題反饋：GitHub Issues
• 討論交流：GitHub Discussions
• 文檔查閱：Wiki

---

本項目由❤️ 打造，旨在通過AI分析提升代碼質量