thuban-mcp

MCP Server for Thuban AI Code Verification — let AI agents scan, fix, and verify code quality through the Model Context Protocol.

Thuban catches what linters miss: hallucinated APIs, dead code, copy-paste clones, taint flows, and 84 detection rules across security, reliability, performance, and maintainability.

Installation

npm install -g thuban-mcp

The MCP server shells out to the Thuban CLI, so you also need:

npm install -g thuban

Or use npx — the server automatically falls back to npx thuban if the global binary is not found.

Configuration

Claude Desktop / Verdent

Add to your MCP configuration file (mcp.json or claude_desktop_config.json):

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

Cursor

Add to .cursor/mcp.json in your project root:

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

VS Code Copilot

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "thuban": {
        "command": "npx",
        "args": ["thuban-mcp"]
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

Available Tools

| Tool | Description | |---|---| | thuban_scan | Scan a file or directory for code-quality and security issues | | thuban_fix | Auto-fix issues in a file (safe, deterministic fixes) | | thuban_hallucinate | Check for AI-hallucinated APIs, imports, and options | | thuban_ghosts | Find dead/unused code — exports, functions, variables, files | | thuban_clones | Detect copy-paste duplicate code clusters | | thuban_health | Get codebase health score and grade (A–F) | | thuban_taint | Run cross-file taint analysis (source → sink tracing) |

Available Resources

| Resource URI | Description | |---|---| | thuban://rules | List all 84 detection rules with IDs, severities, and descriptions | | thuban://config | Current scanner configuration |

Example Usage

Once configured, ask your AI agent:

"Scan this project for security issues"

The agent will call thuban_scan with your project path and return a structured report of issues, trust score, and recommendations.

"Check if any of the APIs I'm using are hallucinated"

The agent calls thuban_hallucinate to verify that every import, method call, and configuration option actually exists in the referenced packages.

"Find dead code in src/"

The agent calls thuban_ghosts to identify unused exports, uncalled functions, and orphan files.

"What's the health score of this codebase?"

The agent calls thuban_health and returns a grade (A–F) with category breakdowns for security, reliability, performance, and maintainability.

How It Works

The MCP server acts as a bridge between AI agents and the Thuban CLI:

1. AI agent sends a tool call via the MCP protocol (JSON-RPC over stdio)
2. thuban-mcp translates the call into a Thuban CLI command
3. The CLI runs the analysis and returns structured JSON
4. thuban-mcp forwards the results back to the AI agent

AI Agent  ←→  MCP Protocol (stdio)  ←→  thuban-mcp  ←→  thuban CLI

Detection Rules

Thuban ships with 84 detection rules across 7 categories:

• Security (20 rules) — SQL injection, XSS, SSRF, hardcoded secrets, and more
• Taint Analysis (10 rules) — Cross-file data flow from user input to sensitive sinks
• AI Hallucination (10 rules) — Phantom imports, non-existent APIs, wrong signatures
• Dead Code (10 rules) — Unused exports, uncalled functions, orphan files
• Clone Detection (8 rules) — Exact duplicates, near-duplicates, copy-paste errors
• Reliability (10 rules) — Unhandled promises, null derefs, race conditions
• Maintainability (8 rules) — God functions, deep nesting, circular dependencies
• Performance (8 rules) — N+1 queries, sync I/O, memory leaks

Use the thuban://rules resource to get the full list programmatically.

License

MIT