@moikas/code-audit-mcp

v1.0.7

Published

6 months ago

AI-powered code auditing via MCP using local Ollama models for security, performance, and quality analysis

Downloads

135

0High
0Medium
0Low

moikapy

mcp code-audit ollama typescript ai security code-analysis static-analysis code-quality cli global model-context-protocol

MCP Code Audit Server

AI-powered code auditing using local Ollama models with Model Context Protocol (MCP) integration

A comprehensive TypeScript MCP server that performs intelligent code audits for security, completeness, performance, quality, architecture, testing, and documentation using local AI models via Ollama.

🚀 Features

Multi-Dimensional Code Analysis

Security: OWASP Top 10 vulnerabilities, authentication flaws, injection attacks
Completeness: TODOs, empty functions, missing error handling, unfinished implementations
Performance: Algorithmic complexity, memory leaks, optimization opportunities
Quality: Code smells, SOLID principles, maintainability issues
Architecture: Design patterns, separation of concerns, dependency management
Testing: Testability issues, missing coverage, race conditions
Documentation: API docs, code comments, compliance standards

Intelligent Model Selection

Multi-model support: CodeLlama, DeepSeek-Coder, StarCoder2, Granite-Code, Qwen2.5-Coder
Specialization-based routing: Different models for different audit types
Fallback strategies: Automatic model fallback on failures
Performance optimization: Fast vs. thorough modes

Advanced Features

Context-aware analysis: Framework-specific checks (React, Express, Django, etc.)
Priority-based auditing: Fast mode (security + completeness) for rapid feedback
Language support: 10+ programming languages with language-specific rules
Configurable severity: Customizable issue severity thresholds
Auto-fix suggestions: Confidence-scored fix recommendations
Complexity analysis: Cyclomatic, cognitive, and maintainability metrics

📋 Requirements

Node.js: 18.0.0 or higher
Ollama: Latest version (Download)
RAM: 8GB+ recommended (for larger models)
Storage: 10GB+ for essential models, 50GB+ for comprehensive setup

🛠️ Installation

Global Installation (Recommended)

# Install globally from npm
npm install -g @moikas/code-audit-mcp

# Run interactive setup (includes MCP configuration)
code-audit setup

# Or setup with automatic MCP configuration
code-audit setup --auto

# Start the MCP server
code-audit start

Development Installation

# Clone the repository
git clone <repository-url>
cd code-audit-mcp

# Install dependencies
npm install

# Build the package
npm run build

# Test locally
npm run test-local

🚀 Development Setup

Prerequisites

Node.js: v18.0.0 or higher
npm: v8.0.0 or higher
Git: For version control and pre-commit hooks
VS Code: Recommended IDE (see .vscode/extensions.json for extensions)

Initial Setup

# Clone and enter directory
git clone https://github.com/warrengates/code-audit-mcp.git
cd code-audit-mcp

# Install dependencies (includes husky setup)
npm install

# Build the project
npm run build

# Run quality checks
npm run quality-check

# Test the setup
npm run test-local

Pre-commit Hooks

This project uses Husky and lint-staged for automatic code quality checks:

ESLint: Checks code for errors and style issues
Prettier: Formats code consistently
TypeScript: Type checks all TypeScript files

Pre-commit hooks run automatically on git commit. To manually run quality checks:

# Run all quality checks
npm run quality-check

# Fix auto-fixable issues
npm run quality-fix

# Individual checks
npm run lint          # ESLint check
npm run format:check  # Prettier check
npm run type-check    # TypeScript check

The setup script will:

✅ Check prerequisites (Node.js, npm, tsx)
🩺 Verify Ollama installation and health
📦 Install recommended AI models
🧪 Test MCP server functionality
📝 Generate example configuration

Manual Setup

If you prefer manual installation:

# Install dependencies
npm install

# Install essential models
ollama pull codellama:7b
ollama pull granite-code:8b

# Build the project
npm run build

# Test the server
npm run dev

🎯 Usage

CLI Commands

# Interactive setup wizard
code-audit setup

# Start MCP server (foreground)
code-audit start

# Start as background daemon
code-audit start --daemon

# Stop running server
code-audit stop

# Check system health
code-audit health

# Manage AI models
code-audit models --list
code-audit models --pull codellama:7b

# Configuration management
code-audit config --show
code-audit config --set ollama.host=http://remote:11434

# MCP server management
code-audit mcp status
code-audit mcp configure
code-audit mcp remove

# Check for updates
code-audit update

Development Mode

# Development mode with hot reload
npm run dev

# Build TypeScript
npm run build

# Test package locally
npm run test-local

MCP Integration

Automatic Configuration (Recommended)

The setup wizard now automatically configures code-audit as an MCP server:

# Configure during setup
code-audit setup

# Or configure after installation
code-audit mcp configure

This will automatically add code-audit to:

Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Code (Global): ~/.config/claude/mcp-settings.json
Claude Code (Project): .claude/mcp-settings.json

Manual Configuration

If you prefer manual configuration, add to your MCP configuration:

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

For more details, see:

Available Tools

`audit_code` - Main audit tool

{
  "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"
    }
  }
}

Parameters:

code (required): Code to audit
language (required): Programming language
auditType: security | completeness | performance | quality | architecture | testing | documentation | all
priority: fast (security + completeness only) | thorough (all audit types)
context: Additional context for framework-specific analysis
maxIssues: Limit number of issues returned (default: 50)

`health_check` - Server health status

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

`list_models` - Available AI models

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

🔧 Configuration

Server Configuration

Create a configuration file or use environment variables:

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,
  },
};

Auditor Configuration

Each auditor can be individually configured:

{
  enabled: boolean;              // Enable/disable auditor
  severity: Severity[];          // Severity levels to include
  rules: Record<string, boolean>; // Specific rules to enable/disable
  thresholds: Record<string, number>; // Numeric thresholds
}

Model Selection

Configure model preferences for different scenarios:

// Performance-critical code
const performanceConfig = {
  strategy: 'PerformanceModelSelectionStrategy', // Always prefer fast models
  fallbackModels: ['codellama:7b', 'granite-code:8b'],
};

// Quality-focused analysis
const qualityConfig = {
  strategy: 'QualityModelSelectionStrategy', // Always prefer accurate models
  fallbackModels: ['deepseek-coder:33b', 'codellama:13b'],
};

🤖 Supported Models

Essential Models (Recommended)

CodeLlama 7B: Fast, general-purpose code analysis
Granite Code 8B: Excellent for security analysis

Comprehensive Setup

CodeLlama 13B: Better accuracy for complex analysis
DeepSeek-Coder 6.7B: Superior performance analysis
StarCoder2 7B: Specialized for testing analysis
Qwen2.5-Coder 7B: Good for documentation analysis

Full Setup (Advanced)

DeepSeek-Coder 33B: Highest accuracy (requires 16GB+ RAM)
StarCoder2 15B: Advanced testing and architecture analysis
Llama 3.1 8B: Excellent for documentation

Model Installation

# Essential models (~7GB)
ollama pull codellama:7b
ollama pull granite-code:8b

# Comprehensive setup (~30GB)
ollama pull codellama:13b
ollama pull deepseek-coder:6.7b
ollama pull starcoder2:7b
ollama pull qwen2.5-coder:7b

# Full setup (~80GB)
ollama pull deepseek-coder:33b
ollama pull starcoder2:15b
ollama pull llama3.1:8b

🌐 Language Support

Fully Supported

JavaScript/TypeScript: React, Node.js, Express-specific checks
Python: Django, Flask, FastAPI-specific analysis
Java: Spring Boot, security-focused analysis
Go: Goroutine safety, performance patterns
Rust: Memory safety, performance optimization

Well Supported

C#: .NET patterns, security analysis
PHP: Laravel, WordPress security checks
Ruby: Rails-specific patterns
Swift: iOS-specific patterns
Kotlin: Android-specific analysis

Basic Support

C/C++: Memory safety, performance
SQL: Injection detection, query optimization
HTML/CSS: XSS prevention, performance
Docker: Security configuration
YAML/JSON: Configuration validation

📊 Example Output

{
  "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
    }
  }
}

⚡ Performance Optimization

Fast Mode for Rapid Development

{
  "auditType": "all",
  "priority": "fast" // Only security + completeness
}

Context-Aware Analysis

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

Caching Configuration

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

🔍 Audit Types Deep Dive

Security Audit

OWASP Top 10 Coverage: SQL injection, XSS, authentication flaws
Language-specific: Prototype pollution (JS), pickle usage (Python)
Framework-specific: CSRF protection (Express), SQL injection (Django)

Performance Audit

Algorithmic Analysis: O(n²) detection, nested loop optimization
Memory Management: Leak detection, object pooling opportunities
Database Optimization: N+1 queries, missing indexes
Async Patterns: Blocking operations, Promise handling

Quality Audit

Code Smells: Long methods, large classes, duplicate code
SOLID Principles: SRP, OCP, LSP, ISP, DIP violations
Maintainability: Cyclomatic complexity, cognitive load
Naming Conventions: Consistency, clarity, domain alignment

🛠️ Development

VS Code Setup

This project includes comprehensive VS Code configuration for optimal development experience:

Recommended Extensions

Install recommended extensions for the best experience:

# Install all recommended extensions
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

Or open VS Code and accept the workspace recommendations popup.

Workspace Settings

The .vscode/settings.json includes:

Auto-formatting: Format on save with Prettier
Linting: Real-time ESLint feedback
TypeScript: Enhanced IntelliSense and error checking
Import management: Auto-import and path intellisense
Git integration: Pre-configured for the workflow

Debugging

Use the included debug configurations:

Debug Server: Launch and debug the MCP server
Debug CLI: Debug CLI commands
Debug Tests: Step through test execution

Press F5 or use the Debug panel to start debugging.

Project Structure

code-audit-mcp/
├── src/
│   ├── server.ts              # Main MCP server
│   ├── types.ts               # TypeScript interfaces
│   ├── auditors/              # Audit implementations
│   │   ├── base.ts           # Base auditor class
│   │   ├── security.ts       # Security auditor
│   │   ├── completeness.ts   # Completeness auditor
│   │   ├── performance.ts    # Performance auditor
│   │   └── ...
│   ├── ollama/               # Ollama integration
│   │   ├── client.ts         # HTTP client wrapper
│   │   ├── models.ts         # Model configuration
│   │   └── prompts.ts        # Audit prompts
│   └── utils/                # Utilities
│       ├── codeParser.ts     # Code parsing
│       ├── complexity.ts     # Complexity analysis
│       └── logger.ts         # Logging utilities
├── cli/
│   └── setup.ts              # Setup script
├── .vscode/                  # VS Code configuration
│   ├── settings.json        # Workspace settings
│   ├── extensions.json      # Recommended extensions
│   └── launch.json          # Debug configurations
├── .husky/                   # Git hooks
│   └── pre-commit           # Pre-commit checks
└── tests/                    # Test suites

Building and Testing

# Development
npm run dev                   # Start with hot reload
npm run build                 # Compile TypeScript
npm run lint                  # Run ESLint
npm run format               # Format with Prettier

# Testing
npm test                     # Run test suite
npm run test:watch          # Watch mode
npm run test:coverage       # Coverage report

# Production
npm run start               # Start production server

Adding Custom Auditors

Create a new auditor class extending BaseAuditor:

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

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

  // Override methods for custom logic
  protected async postProcessIssues(rawIssues, request, language) {
    // Custom post-processing
    return super.postProcessIssues(rawIssues, request, language);
  }
}

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

export const auditorClasses = {
  // ... existing auditors
  custom: CustomAuditor,
};

Add configuration:

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

🐛 Troubleshooting

Common Issues

Ollama Connection Failed

# Check if Ollama is running
ollama list

# Start Ollama service
ollama serve

# Check port availability
curl http://localhost:11434/api/tags

Model Not Found

# List installed models
ollama list

# Install missing model
ollama pull codellama:7b

# Check model availability in server
curl -X POST http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{"model": "codellama:7b", "prompt": "test"}'

TypeScript Compilation Errors

# Clear build cache
rm -rf dist/
rm -rf node_modules/
npm install

# Check TypeScript configuration
npx tsc --noEmit

# Update dependencies
npm update

Memory Issues

# Check available memory
free -h

# Use smaller models
ollama pull codellama:7b  # Instead of codellama:34b

# Reduce concurrent audits
{
  "performance": {
    "maxConcurrentAudits": 1
  }
}

Performance Tuning

Model Selection Optimization

// For CI/CD environments - prioritize speed
const ciConfig = {
  strategy: 'PerformanceModelSelectionStrategy',
  priority: 'fast',
};

// For code review - prioritize accuracy
const reviewConfig = {
  strategy: 'QualityModelSelectionStrategy',
  priority: 'thorough',
};

Resource Management

{
  ollama: {
    timeout: 60000,        // Increase for large files
    retryAttempts: 5,      // More retries for reliability
    healthCheckInterval: 30000  // More frequent health checks
  },
  performance: {
    maxConcurrentAudits: 2,    // Reduce for limited RAM
    cacheEnabled: true,        // Enable for repeated analysis
    cacheTtl: 600             // 10-minute cache
  }
}

📚 API Reference

Tool Schemas

audit_code

interface AuditRequest {
  code: string; // Required: Code to audit
  language: string; // Required: Programming language
  auditType: AuditType; // Optional: Default 'all'
  file?: string; // Optional: File path for context
  context?: AuditContext; // Optional: Additional context
  priority?: 'fast' | 'thorough'; // Optional: Default 'thorough'
  maxIssues?: number; // Optional: Default 50
  includeFixSuggestions?: boolean; // Optional: Default true
}

Response Format

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

Error Codes

| Code | Description | Resolution | | ------------------------ | ----------------------- | -------------------------------- | | INVALID_REQUEST | Malformed request | Check required parameters | | CODE_TOO_LARGE | Code exceeds size limit | Split into smaller chunks | | LANGUAGE_NOT_SUPPORTED | Unsupported language | Use supported language | | NO_AVAILABLE_MODEL | No suitable model found | Install required models | | OLLAMA_UNAVAILABLE | Ollama service down | Start Ollama service | | MODEL_NOT_FOUND | Requested model missing | Pull model with ollama pull | | GENERATION_FAILED | AI generation failed | Check model health, retry | | AUDIT_FAILED | General audit failure | Check logs, verify configuration |

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Fork and clone the repository
git clone https://github.com/your-username/code-audit-mcp.git
cd code-audit-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Submit a pull request

Code Standards

TypeScript: Strict mode enabled
ESLint: Airbnb configuration
Prettier: Automated formatting
Testing: Jest with >80% coverage
Documentation: JSDoc for all public APIs

📚 Development Documentation

Contributing Guidelines: How to contribute to the project
VS Code Setup: Optimal IDE configuration
Pre-commit Hooks: Automated quality checks
Troubleshooting: Solutions to common issues

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Anthropic for the Model Context Protocol specification
Ollama for local AI model serving
Meta for CodeLlama models
DeepSeek for specialized coding models
BigCode for StarCoder models

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

Built with ❤️ for better code quality through AI-powered analysis