ultron-mcp

A self-contained, local-first code intelligence and architectural security auditing CLI for your terminal. It scans your codebase, extracts module structure, and invokes a local Ollama LLM to perform deep audits on file complexity, security vulnerabilities, and dependency graphs.

Unlike cloud-based AI tools, ultron-mcp runs 100% locally with zero external API calls, ensuring complete privacy for your codebase. It is database-free (no ChromaDB/MongoDB required) and features a rich, interactive console UI.

🔍 Key Features

• ⚡ Zero-Config Scanning: Recursively scans directories to discover TypeScript (.ts, .tsx), JavaScript (.js, .jsx), and Markdown (.md) files.
• 📂 Auto-Module Architecture: Automatically groups files by their parent directory structure (e.g., src/auth/ becomes the auth module).
• 🤖 Local AI Auditing: Integrates directly with your local Ollama runtime using open-source models like llama3, mistral, or custom system prompts.
• 🎨 Premium Terminal UI: Beautiful pastel-themed status banners, interactive multi-select menus, real-time spinners, and color-coded audit cards.
• 🎛️ Granular Control: Interactively audit the entire workspace, select specific modules, or target individual files.

🚀 Quick Start

Run Instantly (No Installation)

Use npx to execute the auditor on-demand on the current directory:

npx ultron-mcp

Or Install Globally

Install the package globally via npm:

npm install -g ultron-mcp

Once installed, you can use any of the following command aliases from any codebase directory:

ultron-mcp
# or
ultron-ai
# or
ultron-audit

🛠️ Prerequisites

1. Install and run Ollama locally.
2. Pull your preferred model to use for the auditing process. For example:

   ollama pull llama3

📖 CLI Usage & Options

ultron-mcp [options]

Available Options

| Option | Shorthand | Description | Default | | ------------------- | --------- | --------------------------------------------------------------------- | ---------------------------------------------- | | --model <name> | -m | Ollama model to use for auditing | llama3 (or falls back to interactive choice) | | --url <url> | -u | Ollama API base URL | http://127.0.0.1:11434 | | --all | -a | Audits all found source files immediately without interactive prompts | false | | --module <name> | | Filter scanning scope to a single module | | | --file <path> | | Audit a single file relative to current directory | | | --save | | Save the session report automatically to .ultron/reports/ | false | | --output <path> | | Specific file path to save the report to | | | --format <format> | | Target report format: json, markdown, sarif | json | | --help | -h | Output usage information | |

Examples

Interactive Selection Mode: Run inside any codebase to choose modules or files interactively:

ultron-mcp

Audit the entire project with a specific model:

ultron-mcp --all --model mistral

Audit a specific file and save as Markdown:

ultron-mcp --file src/lib/parser/index.ts --save --format markdown

Audit a specific module/directory statically (no AI/Ollama required):

ultron-mcp static src/auth --save

⚙️ Configuration File: ultron.rules.json

Customize your quality guidelines, file exclusions, and security policy by placing an ultron.rules.json file in your project root. Ultron automatically detects this configuration during static and AI audits.

Configuration Fields

• ignore: Array of glob patterns defining files or directories to skip during scanning (e.g. tests or build artifacts).
• rulePacks: Set default rule packs to execute (e.g., ["security", "react", "complexity"]).
• i18n.allowedStringPatterns: Regexes matching strings that are allowed to be hardcoded without triggering i18n warnings.
• security.forbiddenImports: Packages that should trigger a severity-high security finding if imported (e.g., axios).
• security.requiredImports: Map of file glob paths to arrays of packages that must be imported.
• thresholds: Define code limits:
  • maxFileLines: Max lines of code allowed in a file.
  • maxFunctionLines: Max lines of code allowed in any single function.
  • maxComplexity: Max cyclomatic complexity score permitted.
• customRules: Custom regex-based code checks applied on specific file globs.

Example ultron.rules.json

{
  "$schema": "https://ultron-mcp.dev/schemas/rules.json",
  "ignore": ["**/*.test.tsx", "**/mock/**", "dist/**"],
  "rulePacks": [
    "security",
    "react",
    "a11y",
    "i18n",
    "typescript",
    "complexity"
  ],
  "i18n": {
    "allowedStringPatterns": ["^[A-Z_]+$", "^tabler-"]
  },
  "security": {
    "forbiddenImports": ["axios"],
    "requiredImports": {
      "src/app/api/**": ["@/lib/api/client"]
    }
  },
  "thresholds": {
    "maxFileLines": 500,
    "maxFunctionLines": 80,
    "maxComplexity": 15
  },
  "customRules": [
    {
      "id": "require-use-client",
      "glob": "src/components/ui/*.tsx",
      "pattern": "\"use client\"",
      "message": "Primitive UI components should run client-side",
      "severity": "medium",
      "matchType": "absent"
    }
  ]
}

📊 Reporting & Persistence

Save and manage audit reports locally without databases. Ultron generates session details containing vulnerability counts, severity distributions, and maintainability profiles.

Supported Formats

1. JSON (json): Raw structured report. Perfect for parsing or archiving.
2. Markdown (markdown / md): Highly readable format with severity badges, metrics tables, and code snippets.
3. SARIF (sarif): Static Analysis Results Interchange Format. Fully compatible with GitHub Code Scanning, VS Code problem panels, and CI/CD pipelines.

CLI Report Tooling

Ultron features a built-in report subcommand:

View saved report summary:

ultron-ai report view .ultron/reports/audit-latest.json

Export JSON reports to other formats:

ultron-ai report export .ultron/reports/audit-latest.json --format markdown --output audit-report.md

🔌 MCP Server Mode (Ollama-Free)

Ultron can be run as a Model Context Protocol (MCP) server. In this mode, Ollama is NOT required on your system. Instead, the MCP server acts as a code-reading and scanning provider for the connected AI agent (such as Cursor, Windsurf, or Claude Desktop). The AI agent's own LLM performs the architectural audit and security analysis.

Running MCP Server

To start the MCP server on stdio transport, run:

ultron-mcp mcp

Configuration in AI Clients

Cursor / Windsurf

Add a new MCP server in your editor settings:

• Type: command
• Name: ultron-mcp
• Command: npx -y ultron-mcp mcp (or path to your global/local installation)

Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "ultron-mcp": {
      "command": "npx",
      "args": ["-y", "ultron-mcp", "mcp"]
    }
  }
}

Available MCP Tools

Once connected, your AI agent will have access to the following tools to audit your project:

• 📂 ultron_scan_project: Recursively scans the directory and returns a structured list of files grouped into modules.
• 📖 ultron_read_file: Reads the contents of a specific file along with language metadata.
• 📚 ultron_read_files_batch: Reads up to 20 files in a single request.
• 📊 ultron_project_stats: Retrieves language percentages, file count, and lines-of-code statistics.
• 📋 ultron_get_audit_prompt: Retrieves the expert audit system prompt used by Ultron.
• 🩺 ultron_check_ollama: Checks if local Ollama is online (optional helper).
• 💾 ultron_save_report: Saves the JSON audit report to .ultron/reports/.
• 📁 ultron_load_report: Loads a saved JSON report by ID.
• 📤 ultron_export_report: Exports saved JSON reports to Markdown or SARIF files.

🛠️ Local Development & Contributing

If you want to run or build the CLI locally:

1. Clone the repository and navigate to the cli/ directory.
2. Install dependencies:

   npm install

3. Build the TypeScript bundle:

   npm run build

4. Link the command globally for local testing:

   npm link

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.