thuban-mcp 0.4.5

package/README.md

@@ -0,0 +1,154 @@
+# thuban-mcp
+
+MCP Server for **Thuban AI Code Verification** — let AI agents scan, fix, and verify code quality through the [Model Context Protocol](https://modelcontextprotocol.io/).
+
+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
+
+```bash
+npm install -g thuban-mcp
+```
+
+The MCP server shells out to the Thuban CLI, so you also need:
+
+```bash
+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`):
+
+```json
+{
+  "mcpServers": {
+    "thuban": {
+      "command": "npx",
+      "args": ["thuban-mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "thuban": {
+      "command": "npx",
+      "args": ["thuban-mcp"]
+    }
+  }
+}
+```
+
+### VS Code Copilot
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "thuban": {
+        "command": "npx",
+        "args": ["thuban-mcp"]
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```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

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "thuban-mcp",
+  "version": "0.4.5",
+  "description": "MCP Server for Thuban AI Code Verification — let AI agents scan, fix, and verify code quality",
+  "main": "src/server.js",
+  "bin": { "thuban-mcp": "./src/server.js" },
+  "type": "module",
+  "keywords": ["mcp", "thuban", "code-quality", "security", "AI-verification", "static-analysis"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.23.0"
+  },
+  "engines": { "node": ">=18.0.0" }
+}

package/src/server.js

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+
+// ---------------------------------------------------------------------------
+// Thuban MCP Server
+// Exposes the Thuban AI Code Verification CLI as MCP tools & resources so that
+// any MCP-compatible AI agent (Claude, Copilot, Cursor, Verdent, …) can scan,
+// fix, and verify code quality.
+//
+// IMPORTANT: All logging uses console.error() — stdout is reserved for the
+// MCP JSON-RPC protocol.
+// ---------------------------------------------------------------------------
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import {
+  thubanScan,
+  thubanFix,
+  thubanHallucinate,
+  thubanGhosts,
+  thubanClones,
+  thubanHealth,
+  thubanTaint,
+} from "./tools.js";
+
+// ---------------------------------------------------------------------------
+// Detection rules catalogue (84 rules)
+// ---------------------------------------------------------------------------
+
+const RULES = [
+  // Security (20)
+  { id: "SEC001", name: "sql-injection", severity: "critical", category: "security", description: "Detects unsanitised SQL query construction" },
+  { id: "SEC002", name: "xss-vulnerability", severity: "critical", category: "security", description: "Detects cross-site scripting vectors" },
+  { id: "SEC003", name: "path-traversal", severity: "critical", category: "security", description: "Detects directory traversal in file operations" },
+  { id: "SEC004", name: "command-injection", severity: "critical", category: "security", description: "Detects OS command injection via unsanitised input" },
+  { id: "SEC005", name: "hardcoded-secret", severity: "high", category: "security", description: "Detects hardcoded passwords, API keys, and tokens" },
+  { id: "SEC006", name: "insecure-random", severity: "medium", category: "security", description: "Detects use of Math.random() for security-sensitive operations" },
+  { id: "SEC007", name: "eval-usage", severity: "high", category: "security", description: "Detects use of eval() and equivalent dynamic code execution" },
+  { id: "SEC008", name: "prototype-pollution", severity: "high", category: "security", description: "Detects prototype pollution via unguarded object merges" },
+  { id: "SEC009", name: "open-redirect", severity: "medium", category: "security", description: "Detects unvalidated redirect URLs" },
+  { id: "SEC010", name: "insecure-deserialization", severity: "high", category: "security", description: "Detects unsafe deserialization of untrusted data" },
+  { id: "SEC011", name: "missing-csrf", severity: "medium", category: "security", description: "Detects missing CSRF protection on state-changing endpoints" },
+  { id: "SEC012", name: "insecure-cookie", severity: "medium", category: "security", description: "Detects cookies without Secure/HttpOnly/SameSite flags" },
+  { id: "SEC013", name: "weak-crypto", severity: "high", category: "security", description: "Detects use of weak cryptographic algorithms (MD5, SHA1, DES)" },
+  { id: "SEC014", name: "ssrf", severity: "critical", category: "security", description: "Detects server-side request forgery via user-controlled URLs" },
+  { id: "SEC015", name: "nosql-injection", severity: "critical", category: "security", description: "Detects NoSQL injection in MongoDB/Mongoose queries" },
+  { id: "SEC016", name: "regex-dos", severity: "medium", category: "security", description: "Detects catastrophic backtracking in regular expressions" },
+  { id: "SEC017", name: "jwt-none-alg", severity: "critical", category: "security", description: "Detects JWT verification that accepts 'none' algorithm" },
+  { id: "SEC018", name: "cors-wildcard", severity: "medium", category: "security", description: "Detects overly permissive CORS configuration" },
+  { id: "SEC019", name: "unsafe-file-upload", severity: "high", category: "security", description: "Detects file uploads without type/size validation" },
+  { id: "SEC020", name: "info-exposure", severity: "medium", category: "security", description: "Detects stack traces or debug info leaked to clients" },
+
+  // Taint analysis (10)
+  { id: "TAINT001", name: "taint-source-unvalidated", severity: "high", category: "taint", description: "User input reaches sensitive sink without validation" },
+  { id: "TAINT002", name: "taint-db-query", severity: "critical", category: "taint", description: "Tainted data flows into database query" },
+  { id: "TAINT003", name: "taint-file-path", severity: "critical", category: "taint", description: "Tainted data used in file system path" },
+  { id: "TAINT004", name: "taint-html-render", severity: "high", category: "taint", description: "Tainted data rendered as HTML without escaping" },
+  { id: "TAINT005", name: "taint-shell-exec", severity: "critical", category: "taint", description: "Tainted data passed to shell execution" },
+  { id: "TAINT006", name: "taint-redirect", severity: "medium", category: "taint", description: "Tainted data used in HTTP redirect" },
+  { id: "TAINT007", name: "taint-log-injection", severity: "medium", category: "taint", description: "Tainted data written to logs without sanitisation" },
+  { id: "TAINT008", name: "taint-header-injection", severity: "high", category: "taint", description: "Tainted data injected into HTTP response headers" },
+  { id: "TAINT009", name: "taint-deserialization", severity: "critical", category: "taint", description: "Tainted data passed to deserializer" },
+  { id: "TAINT010", name: "taint-crypto-key", severity: "critical", category: "taint", description: "Tainted data used as cryptographic key material" },
+
+  // AI hallucination (10)
+  { id: "HALL001", name: "phantom-import", severity: "high", category: "hallucination", description: "Import references a package that does not exist in registry" },
+  { id: "HALL002", name: "phantom-api", severity: "high", category: "hallucination", description: "Call to a method/function that does not exist on the target object" },
+  { id: "HALL003", name: "phantom-option", severity: "medium", category: "hallucination", description: "Configuration option that does not exist in the library's API" },
+  { id: "HALL004", name: "version-mismatch", severity: "medium", category: "hallucination", description: "API usage matches a different version than installed" },
+  { id: "HALL005", name: "phantom-event", severity: "medium", category: "hallucination", description: "Event listener for an event that the emitter never fires" },
+  { id: "HALL006", name: "phantom-type", severity: "medium", category: "hallucination", description: "TypeScript type reference that does not exist in the package" },
+  { id: "HALL007", name: "deprecated-api", severity: "low", category: "hallucination", description: "Usage of an API that has been deprecated or removed" },
+  { id: "HALL008", name: "wrong-signature", severity: "high", category: "hallucination", description: "Function called with incorrect argument count or types" },
+  { id: "HALL009", name: "phantom-cli-flag", severity: "medium", category: "hallucination", description: "CLI flag that does not exist for the target command" },
+  { id: "HALL010", name: "phantom-env-var", severity: "low", category: "hallucination", description: "Environment variable referenced but never defined" },
+
+  // Dead code / ghosts (10)
+  { id: "GHOST001", name: "unused-export", severity: "low", category: "ghost", description: "Exported symbol is never imported anywhere" },
+  { id: "GHOST002", name: "unused-function", severity: "low", category: "ghost", description: "Function is declared but never called" },
+  { id: "GHOST003", name: "unused-variable", severity: "low", category: "ghost", description: "Variable is assigned but never read" },
+  { id: "GHOST004", name: "unreachable-code", severity: "medium", category: "ghost", description: "Code after return/throw/break that can never execute" },
+  { id: "GHOST005", name: "dead-branch", severity: "low", category: "ghost", description: "Conditional branch that can never be true" },
+  { id: "GHOST006", name: "orphan-file", severity: "low", category: "ghost", description: "Source file not imported by any other file" },
+  { id: "GHOST007", name: "unused-dependency", severity: "low", category: "ghost", description: "Package in dependencies but never imported" },
+  { id: "GHOST008", name: "unused-css-class", severity: "low", category: "ghost", description: "CSS class defined but never referenced in templates" },
+  { id: "GHOST009", name: "empty-catch", severity: "medium", category: "ghost", description: "Catch block that silently swallows errors" },
+  { id: "GHOST010", name: "commented-code", severity: "low", category: "ghost", description: "Large blocks of commented-out code" },
+
+  // Clone detection (8)
+  { id: "CLONE001", name: "exact-duplicate", severity: "medium", category: "clone", description: "Identical code block duplicated across files" },
+  { id: "CLONE002", name: "near-duplicate", severity: "medium", category: "clone", description: "Code block with only cosmetic differences (variable names, whitespace)" },
+  { id: "CLONE003", name: "structural-clone", severity: "low", category: "clone", description: "Same AST structure with different identifiers" },
+  { id: "CLONE004", name: "logic-clone", severity: "low", category: "clone", description: "Semantically equivalent logic expressed differently" },
+  { id: "CLONE005", name: "copy-paste-error", severity: "high", category: "clone", description: "Duplicated code with inconsistent modifications (likely bug)" },
+  { id: "CLONE006", name: "duplicate-test", severity: "low", category: "clone", description: "Test cases that verify the same behaviour" },
+  { id: "CLONE007", name: "duplicate-config", severity: "low", category: "clone", description: "Configuration values duplicated across files" },
+  { id: "CLONE008", name: "extractable-util", severity: "low", category: "clone", description: "Repeated pattern that should be extracted to a utility" },
+
+  // Reliability (10)
+  { id: "REL001", name: "unhandled-promise", severity: "high", category: "reliability", description: "Promise without .catch() or try/catch in async context" },
+  { id: "REL002", name: "null-deref", severity: "high", category: "reliability", description: "Property access on potentially null/undefined value" },
+  { id: "REL003", name: "race-condition", severity: "high", category: "reliability", description: "Shared mutable state accessed without synchronisation" },
+  { id: "REL004", name: "infinite-loop", severity: "critical", category: "reliability", description: "Loop with no reachable exit condition" },
+  { id: "REL005", name: "resource-leak", severity: "medium", category: "reliability", description: "Opened resource (file, connection) never closed" },
+  { id: "REL006", name: "type-coercion", severity: "medium", category: "reliability", description: "Implicit type coercion that may produce unexpected results" },
+  { id: "REL007", name: "missing-await", severity: "high", category: "reliability", description: "Async function called without await" },
+  { id: "REL008", name: "array-mutation", severity: "medium", category: "reliability", description: "Array mutated during iteration" },
+  { id: "REL009", name: "error-swallow", severity: "medium", category: "reliability", description: "Error caught and re-thrown without original stack" },
+  { id: "REL010", name: "floating-point", severity: "low", category: "reliability", description: "Floating-point comparison that may fail due to precision" },
+
+  // Maintainability (8)
+  { id: "MAINT001", name: "god-function", severity: "medium", category: "maintainability", description: "Function exceeds complexity/length thresholds" },
+  { id: "MAINT002", name: "deep-nesting", severity: "medium", category: "maintainability", description: "Control flow nested beyond 4 levels" },
+  { id: "MAINT003", name: "magic-number", severity: "low", category: "maintainability", description: "Numeric literal used without named constant" },
+  { id: "MAINT004", name: "long-param-list", severity: "low", category: "maintainability", description: "Function with more than 5 parameters" },
+  { id: "MAINT005", name: "circular-dependency", severity: "high", category: "maintainability", description: "Circular import chain between modules" },
+  { id: "MAINT006", name: "inconsistent-naming", severity: "low", category: "maintainability", description: "Naming convention inconsistency within a module" },
+  { id: "MAINT007", name: "missing-error-type", severity: "medium", category: "maintainability", description: "Catch block without specific error type" },
+  { id: "MAINT008", name: "implicit-global", severity: "medium", category: "maintainability", description: "Variable used without declaration (implicit global)" },
+
+  // Performance (8)
+  { id: "PERF001", name: "n-plus-one", severity: "high", category: "performance", description: "Database query inside a loop (N+1 query pattern)" },
+  { id: "PERF002", name: "unbounded-query", severity: "medium", category: "performance", description: "Database query without LIMIT or pagination" },
+  { id: "PERF003", name: "sync-io", severity: "medium", category: "performance", description: "Synchronous I/O in async context (blocks event loop)" },
+  { id: "PERF004", name: "memory-leak", severity: "high", category: "performance", description: "Growing data structure that is never pruned" },
+  { id: "PERF005", name: "expensive-re-render", severity: "medium", category: "performance", description: "React component re-renders on every parent render" },
+  { id: "PERF006", name: "unindexed-lookup", severity: "medium", category: "performance", description: "Array linear search where a Map/Set would be O(1)" },
+  { id: "PERF007", name: "large-bundle-import", severity: "low", category: "performance", description: "Importing entire library when only a sub-module is needed" },
+  { id: "PERF008", name: "blocking-main-thread", severity: "high", category: "performance", description: "CPU-intensive work on the main/UI thread" },
+];
+
+// ---------------------------------------------------------------------------
+// Default scanner config
+// ---------------------------------------------------------------------------
+
+const DEFAULT_CONFIG = {
+  version: "0.4.5",
+  severity: "low",
+  include: ["**/*.js", "**/*.ts", "**/*.jsx", "**/*.tsx", "**/*.py", "**/*.go", "**/*.rs", "**/*.java"],
+  exclude: ["node_modules/**", "dist/**", "build/**", ".git/**", "vendor/**", "__pycache__/**"],
+  rules: {
+    enabled: RULES.map((r) => r.id),
+    disabled: [],
+  },
+  output: {
+    format: "json",
+    colors: true,
+    verbose: false,
+  },
+  limits: {
+    maxFileSize: "1MB",
+    maxFiles: 10000,
+    timeout: 60,
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Server setup
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+  name: "thuban",
+  version: "0.4.5",
+});
+
+// ---------------------------------------------------------------------------
+// Tool registrations
+// ---------------------------------------------------------------------------
+
+server.tool(
+  "thuban_scan",
+  "Scan a file or directory for code-quality and security issues. Returns a list of issues, file count, trust score, and summary.",
+  {
+    path: z.string().describe("Absolute or relative path to the file or directory to scan"),
+    options: z
+      .object({
+        severity: z
+          .enum(["low", "medium", "high", "critical"])
+          .optional()
+          .describe("Minimum severity level to report"),
+      })
+      .optional()
+      .describe("Optional scan configuration"),
+  },
+  async ({ path, options }) => {
+    const result = await thubanScan({ path, options });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
+server.tool(
+  "thuban_fix",
+  "Auto-fix code-quality issues in a file. Applies safe, deterministic fixes and returns the count of fixes applied.",
+  {
+    path: z.string().describe("Absolute or relative path to the file to fix"),
+    ruleId: z.string().optional().describe("Specific rule ID to fix (e.g. SEC005). Omit to fix all auto-fixable issues."),
+  },
+  async ({ path, ruleId }) => {
+    const result = await thubanFix({ path, ruleId });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
+server.tool(
+  "thuban_hallucinate",
+  "Check for AI-hallucinated APIs — imports, methods, options, or types that do not actually exist in the referenced packages.",
+  {
+    path: z.string().describe("Absolute or relative path to the file or directory to check"),
+  },
+  async ({ path }) => {
+    const result = await thubanHallucinate({ path });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
+server.tool(
+  "thuban_ghosts",
+  "Find dead and unused code — exports nobody imports, functions never called, variables never read, orphan files.",
+  {
+    path: z.string().describe("Absolute or relative path to the file or directory to analyse"),
+  },
+  async ({ path }) => {
+    const result = await thubanGhosts({ path });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
+server.tool(
+  "thuban_clones",
+  "Detect copy-paste duplicate code clusters — exact duplicates, near-duplicates, and structural clones.",
+  {
+    path: z.string().describe("Absolute or relative path to the file or directory to analyse"),
+  },
+  async ({ path }) => {
+    const result = await thubanClones({ path });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
+server.tool(
+  "thuban_health",
+  "Get the overall codebase health and trust score — a single grade (A–F) with category breakdowns.",
+  {
+    path: z.string().describe("Absolute or relative path to the codebase root"),
+  },
+  async ({ path }) => {
+    const result = await thubanHealth({ path });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
+server.tool(
+  "thuban_taint",
+  "Run cross-file taint analysis — trace user input from sources (req.body, req.query, etc.) to sensitive sinks (SQL, shell, file system).",
+  {
+    path: z.string().describe("Absolute or relative path to the file or directory to analyse"),
+  },
+  async ({ path }) => {
+    const result = await thubanTaint({ path });
+    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Resource registrations
+// ---------------------------------------------------------------------------
+
+server.resource(
+  "rules",
+  "thuban://rules",
+  {
+    description: "List all 84 Thuban detection rules with IDs, names, severities, and descriptions",
+    mimeType: "application/json",
+  },
+  async () => ({
+    contents: [
+      {
+        uri: "thuban://rules",
+        mimeType: "application/json",
+        text: JSON.stringify(RULES, null, 2),
+      },
+    ],
+  }),
+);
+
+server.resource(
+  "config",
+  "thuban://config",
+  {
+    description: "Current Thuban scanner configuration (severity thresholds, include/exclude globs, enabled rules)",
+    mimeType: "application/json",
+  },
+  async () => ({
+    contents: [
+      {
+        uri: "thuban://config",
+        mimeType: "application/json",
+        text: JSON.stringify(DEFAULT_CONFIG, null, 2),
+      },
+    ],
+  }),
+);
+
+// ---------------------------------------------------------------------------
+// Start
+// ---------------------------------------------------------------------------
+
+async function main() {
+  console.error("[thuban-mcp] Starting Thuban MCP Server v0.4.5 …");
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("[thuban-mcp] Server connected and ready.");
+}
+
+main().catch((err) => {
+  console.error("[thuban-mcp] Fatal error:", err);
+  process.exit(1);
+});

package/src/tools.js

@@ -0,0 +1,185 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const TIMEOUT_MS = 60_000;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the thuban CLI binary.  Tries the global `thuban` first, then falls
+ * back to `npx thuban`.  Returns { command, prefixArgs } so callers can build
+ * the full argv.
+ */
+async function resolveThuban() {
+  const isWin = process.platform === "win32";
+  const cmd = isWin ? "where" : "which";
+
+  try {
+    await execFileAsync(cmd, ["thuban"], { timeout: 5_000 });
+    return { command: "thuban", prefixArgs: [] };
+  } catch {
+    // Global binary not found — fall back to npx
+    return { command: "npx", prefixArgs: ["thuban"] };
+  }
+}
+
+/**
+ * Run a thuban CLI command and return parsed JSON output.
+ *
+ * @param {string[]} args  CLI arguments *after* the `thuban` binary name.
+ * @returns {object}       Parsed JSON from stdout.
+ */
+async function runThuban(args) {
+  const { command, prefixArgs } = await resolveThuban();
+  const fullArgs = [...prefixArgs, ...args];
+
+  console.error(`[thuban-mcp] exec: ${command} ${fullArgs.join(" ")}`);
+
+  const { stdout } = await execFileAsync(command, fullArgs, {
+    timeout: TIMEOUT_MS,
+    maxBuffer: 10 * 1024 * 1024, // 10 MB
+    windowsHide: true,
+  });
+
+  return JSON.parse(stdout);
+}
+
+// ---------------------------------------------------------------------------
+// Tool implementations
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan a file or directory for code-quality / security issues.
+ */
+export async function thubanScan({ path, options }) {
+  try {
+    const args = ["scan", path, "--json"];
+    if (options?.severity) {
+      args.push("--severity", options.severity);
+    }
+    const result = await runThuban(args);
+
+    return {
+      issues: result.issues ?? [],
+      filesScanned: result.filesScanned ?? result.files_scanned ?? 0,
+      trustScore: result.trustScore ?? result.trust_score ?? null,
+      summary: result.summary ?? {},
+    };
+  } catch (err) {
+    return { error: `thuban scan failed: ${err.message}` };
+  }
+}
+
+/**
+ * Auto-fix issues in a file.
+ */
+export async function thubanFix({ path, ruleId }) {
+  try {
+    const args = ["fix", path, "--fix", "--json"];
+    if (ruleId) {
+      args.push("--rule", ruleId);
+    }
+    const result = await runThuban(args);
+
+    return {
+      fixed: result.fixed ?? 0,
+      issues: result.issues ?? [],
+    };
+  } catch (err) {
+    return { error: `thuban fix failed: ${err.message}` };
+  }
+}
+
+/**
+ * Check for AI-hallucinated APIs (non-existent methods, packages, etc.).
+ */
+export async function thubanHallucinate({ path }) {
+  try {
+    const result = await runThuban(["hallucinate", path, "--json"]);
+
+    return {
+      hallucinations: result.hallucinations ?? [],
+      count: result.count ?? (result.hallucinations?.length ?? 0),
+    };
+  } catch (err) {
+    return { error: `thuban hallucinate failed: ${err.message}` };
+  }
+}
+
+/**
+ * Find dead / unused code (ghost code).
+ */
+export async function thubanGhosts({ path }) {
+  try {
+    const result = await runThuban(["ghosts", path, "--json"]);
+
+    return {
+      ghosts: result.ghosts ?? [],
+      count: result.count ?? (result.ghosts?.length ?? 0),
+    };
+  } catch (err) {
+    return { error: `thuban ghosts failed: ${err.message}` };
+  }
+}
+
+/**
+ * Detect copy-paste duplicate code clusters.
+ */
+export async function thubanClones({ path }) {
+  try {
+    const result = await runThuban(["clones", path, "--json"]);
+
+    return {
+      clusters: result.clusters ?? [],
+      count: result.count ?? (result.clusters?.length ?? 0),
+    };
+  } catch (err) {
+    return { error: `thuban clones failed: ${err.message}` };
+  }
+}
+
+/**
+ * Get codebase health / trust score.
+ */
+export async function thubanHealth({ path }) {
+  try {
+    const result = await runThuban(["health", path, "--json"]);
+
+    return {
+      score: result.score ?? null,
+      grade: result.grade ?? null,
+      details: result.details ?? {},
+    };
+  } catch (err) {
+    return { error: `thuban health failed: ${err.message}` };
+  }
+}
+
+/**
+ * Run cross-file taint analysis.
+ *
+ * Uses `thuban scan` and filters for TAINT* rules.
+ */
+export async function thubanTaint({ path }) {
+  try {
+    const result = await runThuban(["scan", path, "--json"]);
+    const allIssues = result.issues ?? [];
+    const taintFlows = allIssues.filter(
+      (i) =>
+        (i.ruleId ?? i.rule_id ?? i.rule ?? "")
+          .toUpperCase()
+          .startsWith("TAINT"),
+    );
+
+    return {
+      flows: taintFlows,
+      count: taintFlows.length,
+    };
+  } catch (err) {
+    return { error: `thuban taint failed: ${err.message}` };
+  }
+}