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分析提升代码质量