crukx-mcp 0.1.2 → 0.1.4

package/README.md

@@ -1,8 +1,12 @@
 # crukx-mcp
 
-Crukx MCP server — reliability control plane for autonomous software engineering.
+> AI-powered code reliability engine for any MCP-compatible coding agent.
 
-Connect Cursor, Claude Desktop, or any MCP-compatible IDE to the Crukx 7-agent swarm.
+Crukx deploys a **7-agent swarm** (Stresser, Hunter, Red Teamer, Auditor, Scout, Stabilizer, Synthesizer) to audit your code for reliability, security, and correctness — directly inside your AI coding tool.
+
+Works with **VS Code + GitHub Copilot**, **Kiro**, **Cursor**, **Claude Desktop**, **opencode**, and any other MCP-compatible client.
+
+---
 
 ## Install
 
@@ -10,14 +14,80 @@ Connect Cursor, Claude Desktop, or any MCP-compatible IDE to the Crukx 7-agent s
 npm install -g crukx-mcp
 ```
 
-## Usage
+## Login
 
-### Login
 ```bash
 crukx login
+# Opens crukx.dev in your browser — sign in and return to terminal
+```
+
+## Add to your editor
+
+```bash
+crukx install
+# Auto-detects VS Code, Cursor, Claude Desktop, Kiro, opencode
+# and configures them all in one step
+```
+
+Restart your editor. Done — your AI agent can now use Crukx tools.
+
+---
+
+## Manual setup (if needed)
+
+### VS Code + GitHub Copilot
+
+Add to `.vscode/mcp.json` in your workspace (or `~/.vscode/mcp.json` globally):
+
+```json
+{
+  "servers": {
+    "crukx": {
+      "type": "stdio",
+      "command": "crukx",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Then in VS Code: open the Chat panel → Agent mode → select **crukx** from the tools list.
+
+### Kiro (Amazon)
+
+Add to `~/.kiro/settings/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "crukx": {
+      "command": "crukx",
+      "args": ["mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "crukx": {
+      "command": "crukx",
+      "args": ["mcp"]
+    }
+  }
+}
 ```
 
-### Add to Cursor / Claude Desktop
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
+or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
@@ -30,18 +100,113 @@ crukx login
 }
 ```
 
+### opencode
+
+Add to `~/.config/opencode/config.json`:
+
+```json
+{
+  "mcp": {
+    "crukx": {
+      "command": "crukx",
+      "args": ["mcp"],
+      "type": "local"
+    }
+  }
+}
+```
+
+### Any other MCP client
+
+Use `stdio` transport with:
+- **Command:** `crukx`
+- **Args:** `["mcp"]`
+
+---
+
 ## Tools
 
-| Tool | Description |
-|------|-------------|
-| `swarm_audit` | Full 7-agent reliability audit |
-| `security_scan` | Targeted security analysis |
-| `reliability_score` | Quick reliability score |
-| `report_fetch` | Fetch audit report by ID |
-| `suggest_fix` | Remediation suggestions |
-| `crukx_health` | Check gateway connectivity |
+Once connected, your AI agent can use these tools automatically:
+
+### `swarm_audit`
+Full 7-agent reliability audit. Returns a score (0–100), grade (A–F), gate status, and per-finding fix suggestions.
+
+```
+"Audit this diff for me"
+"Review the code I just wrote"
+"Run a full reliability check on this PR"
+```
+
+### `security_scan`
+Targeted security analysis — injection attacks, hardcoded secrets, auth flaws, OWASP Top 10.
+
+```
+"Is this code secure?"
+"Check for SQL injection in this query"
+"Scan my auth handler for vulnerabilities"
+```
+
+### `reliability_score`
+Fast pass/fail gate — score + critical/high count only. No full findings list.
+
+```
+"Quick score before I commit"
+"Is this safe to merge?"
+```
+
+### `suggest_fix`
+Concrete remediation for a specific issue or finding.
+
+```
+"How do I fix this SQL injection?"
+"Give me a fix for the finding in swarm_audit"
+```
+
+### `report_fetch`
+Retrieve a previous audit report by ID.
+
+```
+"Show me report abc-123"
+"Fetch the last audit"
+```
+
+### `crukx_health`
+Check gateway connectivity and auth status.
+
+```
+"Is Crukx connected?"
+"Why are the tools not working?"
+```
+
+---
+
+## Example output
+
+```
+# Crukx Audit Report
+
+**Score:** 74/100 (Grade C)
+**Gate:** 🟠 REVIEW — high severity issues found
+**Confidence:** 91%  |  **Agents:** Stresser, Hunter, Red Teamer, Auditor, Scout, Stabilizer, Synthesizer
+**Report ID:** `a3f9b2c1-...`
+
+## Severity Breakdown
+| Severity   | Count |
+|------------|-------|
+| 🔴 Critical | 0    |
+| 🟠 High     | 2    |
+| 🟡 Medium   | 5    |
+| 🔵 Low      | 3    |
+| ⚪ Info     | 1    |
+
+## 🟠 High Severity
+- **SQL_INJECTION** — `src/db.ts:42`: User input concatenated into query
+  > Fix: Use parameterized queries — `db.query('SELECT * FROM users WHERE id = $1', [userId])`
+```
+
+---
 
 ## Links
 
-- [crukx.dev](https://crukx.dev)
+- [crukx.dev](https://crukx.dev) — Dashboard and reports
 - [GitHub](https://github.com/Shafwansafi06/observability-hub)

package/dist/auth-J6323WQJ.js

@@ -0,0 +1,14 @@
+import {
+  CONFIG_PATH,
+  clearAuth,
+  isTokenExpired,
+  loadAuth,
+  saveAuth
+} from "./chunk-SC34H3N5.js";
+export {
+  CONFIG_PATH,
+  clearAuth,
+  isTokenExpired,
+  loadAuth,
+  saveAuth
+};

package/dist/bin/cli.js

@@ -59,7 +59,7 @@ import { fileURLToPath } from "url";
 import { join as join2, dirname as pathDirname } from "path";
 var __dirname = pathDirname(fileURLToPath(import.meta.url));
 var program = new Command();
-program.name("crukx").description("Crukx CLI \u2014 reliability control plane for autonomous software engineering").version("0.1.2");
+program.name("crukx").description("Crukx CLI \u2014 reliability control plane for autonomous software engineering").version("0.1.4");
 program.command("login").description("Authenticate with Crukx via browser").option("--api-url <url>", "Crukx gateway URL", getConfig().CRUKX_API_URL).action(async (opts) => {
   process.stderr.write("Opening browser to complete login\u2026\n");
   let startData;
@@ -137,6 +137,103 @@ Expires: ${auth.expires_at}
 API: ${auth.api_url}
 `);
 });
+program.command("install").description("Auto-install Crukx into all detected MCP-compatible clients").option("--dry-run", "Show what would be changed without writing").action(async (opts) => {
+  const { existsSync: existsSync3, readFileSync: readFileSync3, writeFileSync: writeFileSync2 } = await import("fs");
+  const { homedir: homedir2 } = await import("os");
+  const home = homedir2();
+  const SERVER_ENTRY = { command: "crukx", args: ["mcp"] };
+  function injectMcpServers(raw, key) {
+    const cfg = raw ? JSON.parse(raw) : {};
+    cfg.mcpServers = { ...cfg.mcpServers ?? {}, [key]: SERVER_ENTRY };
+    return JSON.stringify(cfg, null, 2);
+  }
+  const clients = [
+    {
+      name: "VS Code (GitHub Copilot)",
+      configPath: join2(home, ".vscode", "mcp.json"),
+      detect: () => existsSync3(join2(home, ".vscode")) || existsSync3("/usr/share/code") || existsSync3("/Applications/Visual Studio Code.app"),
+      inject: (raw) => {
+        const cfg = raw ? JSON.parse(raw) : {};
+        cfg.servers = { ...cfg.servers ?? {}, crukx: { type: "stdio", ...SERVER_ENTRY } };
+        return JSON.stringify(cfg, null, 2);
+      }
+    },
+    {
+      name: "Cursor",
+      configPath: join2(home, ".cursor", "mcp.json"),
+      detect: () => existsSync3(join2(home, ".cursor")) || existsSync3("/Applications/Cursor.app"),
+      inject: (raw) => injectMcpServers(raw, "crukx")
+    },
+    {
+      name: "Claude Desktop",
+      configPath: process.platform === "darwin" ? join2(home, "Library", "Application Support", "Claude", "claude_desktop_config.json") : join2(home, "AppData", "Roaming", "Claude", "claude_desktop_config.json"),
+      detect: () => existsSync3("/Applications/Claude.app") || existsSync3(join2(home, "Library", "Application Support", "Claude")) || existsSync3(join2(home, "AppData", "Local", "AnthropicClaude")),
+      inject: (raw) => injectMcpServers(raw, "crukx")
+    },
+    {
+      name: "Kiro",
+      configPath: join2(home, ".kiro", "settings", "mcp.json"),
+      detect: () => existsSync3(join2(home, ".kiro")),
+      inject: (raw) => injectMcpServers(raw, "crukx")
+    },
+    {
+      name: "opencode",
+      configPath: join2(home, ".config", "opencode", "config.json"),
+      detect: () => existsSync3(join2(home, ".config", "opencode")),
+      inject: (raw) => {
+        const cfg = raw ? JSON.parse(raw) : {};
+        cfg.mcp = { ...cfg.mcp ?? {}, crukx: { ...SERVER_ENTRY, type: "local" } };
+        return JSON.stringify(cfg, null, 2);
+      }
+    }
+  ];
+  const detected = clients.filter((c) => c.detect());
+  if (detected.length === 0) {
+    process.stdout.write(
+      "No supported MCP clients detected.\n\nSupported: VS Code, Cursor, Claude Desktop, Kiro, opencode\n\nManual setup: https://crukx.dev/docs/mcp\n"
+    );
+    return;
+  }
+  process.stdout.write(`Found ${detected.length} client${detected.length > 1 ? "s" : ""}:
+
+`);
+  let installed = 0;
+  for (const client of detected) {
+    const raw = existsSync3(client.configPath) ? readFileSync3(client.configPath, "utf-8") : null;
+    try {
+      const parsed = raw ? JSON.parse(raw) : {};
+      if (parsed?.mcpServers?.crukx || parsed?.servers?.crukx || parsed?.mcp?.crukx) {
+        process.stdout.write(`  \u2705 ${client.name} \u2014 already configured
+`);
+        continue;
+      }
+    } catch {
+    }
+    const newContent = client.inject(raw);
+    if (opts.dryRun) {
+      process.stdout.write(`  \u{1F4DD} ${client.name} \u2014 would write: ${client.configPath}
+`);
+    } else {
+      mkdirSync2(dirname2(client.configPath), { recursive: true });
+      writeFileSync2(client.configPath, newContent, "utf-8");
+      process.stdout.write(`  \u2705 ${client.name} \u2014 configured
+`);
+      installed++;
+    }
+  }
+  process.stdout.write("\n");
+  if (opts.dryRun) {
+    process.stdout.write("Dry run complete. Remove --dry-run to apply.\n");
+  } else if (installed > 0) {
+    process.stdout.write(
+      `Installed in ${installed} client${installed > 1 ? "s" : ""}. Restart your editor, then ask:
+  "Run a Crukx audit on this file"
+`
+    );
+  } else {
+    process.stdout.write("All clients already configured.\n");
+  }
+});
 program.command("mcp").description("Start the Crukx MCP server (stdio transport)").action(() => {
   const serverPath = join2(__dirname, "server.js");
   const child = spawn(process.execPath, [serverPath], {

package/dist/chunk-SC34H3N5.js

@@ -0,0 +1,59 @@
+// src/auth/index.ts
+import { mkdirSync, writeFileSync, readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { dirname } from "path";
+
+// src/config/index.ts
+import "dotenv/config";
+import { z } from "zod";
+import { homedir } from "os";
+import { join } from "path";
+import { readFileSync, existsSync } from "fs";
+var ConfigSchema = z.object({
+  CRUKX_API_URL: z.string().url().default("https://crukx-gateway.salmonisland-7ebc5692.centralindia.azurecontainerapps.io"),
+  CRUKX_ACCESS_TOKEN: z.string().optional(),
+  CRUKX_WORKSPACE_ID: z.string().optional()
+});
+function loadLocalConfig() {
+  const configPath = join(homedir(), ".crukx", "config.json");
+  if (!existsSync(configPath)) return {};
+  try {
+    return JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function getConfig() {
+  const local = loadLocalConfig();
+  return ConfigSchema.parse({ ...local, ...process.env });
+}
+var CONFIG_PATH = join(homedir(), ".crukx", "config.json");
+
+// src/auth/index.ts
+function saveAuth(auth) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  const existing = loadAuth() ?? {};
+  writeFileSync(CONFIG_PATH, JSON.stringify({ ...existing, ...auth }, null, 2));
+}
+function loadAuth() {
+  if (!existsSync2(CONFIG_PATH)) return null;
+  try {
+    return JSON.parse(readFileSync2(CONFIG_PATH, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+function clearAuth() {
+  if (existsSync2(CONFIG_PATH)) writeFileSync(CONFIG_PATH, "{}");
+}
+function isTokenExpired(auth) {
+  return new Date(auth.expires_at) <= new Date(Date.now() + 6e4);
+}
+
+export {
+  getConfig,
+  CONFIG_PATH,
+  saveAuth,
+  loadAuth,
+  clearAuth,
+  isTokenExpired
+};

package/dist/server.js

@@ -1,81 +1,46 @@
+import {
+  getConfig,
+  loadAuth
+} from "./chunk-SC34H3N5.js";
+
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/tools/index.ts
-import { z as z3 } from "zod";
-
-// src/auth/index.ts
-import { mkdirSync, writeFileSync, readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
-import { dirname } from "path";
-
-// src/config/index.ts
-import "dotenv/config";
-import { z } from "zod";
-import { homedir } from "os";
-import { join } from "path";
-import { readFileSync, existsSync } from "fs";
-var ConfigSchema = z.object({
-  CRUKX_API_URL: z.string().url().default("https://crukx-gateway.salmonisland-7ebc5692.centralindia.azurecontainerapps.io"),
-  CRUKX_ACCESS_TOKEN: z.string().optional(),
-  CRUKX_WORKSPACE_ID: z.string().optional()
-});
-function loadLocalConfig() {
-  const configPath = join(homedir(), ".crukx", "config.json");
-  if (!existsSync(configPath)) return {};
-  try {
-    return JSON.parse(readFileSync(configPath, "utf-8"));
-  } catch {
-    return {};
-  }
-}
-function getConfig() {
-  const local = loadLocalConfig();
-  return ConfigSchema.parse({ ...local, ...process.env });
-}
-var CONFIG_PATH = join(homedir(), ".crukx", "config.json");
-
-// src/auth/index.ts
-function loadAuth() {
-  if (!existsSync2(CONFIG_PATH)) return null;
-  try {
-    return JSON.parse(readFileSync2(CONFIG_PATH, "utf-8"));
-  } catch {
-    return null;
-  }
-}
+import { z as z2 } from "zod";
 
 // src/api/client.ts
-import { z as z2 } from "zod";
+import { z } from "zod";
 import { randomUUID } from "crypto";
 var TIMEOUT_MS = 6e4;
-var AuditResultSchema = z2.object({
-  auditId: z2.string(),
-  findings: z2.array(z2.object({
-    id: z2.string(),
-    rule: z2.string(),
-    severity: z2.enum(["critical", "high", "medium", "low", "info"]),
-    message: z2.string(),
-    file: z2.string(),
-    line: z2.number(),
-    suggestion: z2.string().optional(),
-    confidence: z2.number(),
-    category: z2.string()
+var AuditResultSchema = z.object({
+  auditId: z.string(),
+  findings: z.array(z.object({
+    id: z.string(),
+    rule: z.string(),
+    severity: z.enum(["critical", "high", "medium", "low", "info"]),
+    message: z.string(),
+    file: z.string(),
+    line: z.number(),
+    suggestion: z.string().optional(),
+    confidence: z.number(),
+    category: z.string()
   })),
-  summary: z2.object({
-    totalFindings: z2.number(),
-    criticalCount: z2.number(),
-    highCount: z2.number(),
-    mediumCount: z2.number(),
-    lowCount: z2.number(),
-    infoCount: z2.number(),
-    reliabilityScore: z2.number(),
-    confidence: z2.number()
+  summary: z.object({
+    totalFindings: z.number(),
+    criticalCount: z.number(),
+    highCount: z.number(),
+    mediumCount: z.number(),
+    lowCount: z.number(),
+    infoCount: z.number(),
+    reliabilityScore: z.number(),
+    confidence: z.number()
   }),
-  metadata: z2.object({
-    processingTimeMs: z2.number(),
-    agentsUsed: z2.array(z2.string()),
-    swarmId: z2.string()
+  metadata: z.object({
+    processingTimeMs: z.number(),
+    agentsUsed: z.array(z.string()),
+    swarmId: z.string()
   })
 });
 async function request(path, init = {}) {
@@ -138,120 +103,320 @@ async function healthCheck() {
 }
 
 // src/tools/index.ts
-function formatFindings(result) {
+function gate(score, critical, high) {
+  if (critical > 0) return "\u{1F534} BLOCKED \u2014 critical issues must be fixed";
+  if (high > 0) return "\u{1F7E0} REVIEW \u2014 high severity issues found";
+  if (score >= 85) return "\u{1F7E2} PASSED";
+  if (score >= 70) return "\u{1F7E1} PASSED WITH WARNINGS";
+  return "\u{1F7E0} REVIEW \u2014 score below threshold";
+}
+function grade(score) {
+  if (score >= 90) return "A";
+  if (score >= 80) return "B";
+  if (score >= 70) return "C";
+  if (score >= 60) return "D";
+  return "F";
+}
+function formatFullAudit(result) {
   const { summary, findings, metadata } = result;
-  const grade = summary.reliabilityScore >= 90 ? "A" : summary.reliabilityScore >= 80 ? "B" : summary.reliabilityScore >= 70 ? "C" : "D";
   const lines = [
-    `## Crukx Reliability Score: ${summary.reliabilityScore}/100 (Grade ${grade})`,
-    `Confidence: ${summary.confidence}% | Agents: ${metadata.agentsUsed.join(", ")} | Time: ${metadata.processingTimeMs}ms`,
+    `# Crukx Audit Report`,
     ``,
+    `**Score:** ${summary.reliabilityScore}/100 (Grade ${grade(summary.reliabilityScore)})`,
+    `**Gate:** ${gate(summary.reliabilityScore, summary.criticalCount, summary.highCount)}`,
+    `**Confidence:** ${summary.confidence}%  |  **Agents:** ${metadata.agentsUsed.join(", ")}  |  **Time:** ${metadata.processingTimeMs}ms`,
+    `**Report ID:** \`${result.auditId}\``,
+    ``,
+    `## Severity Breakdown`,
     `| Severity | Count |`,
     `|----------|-------|`,
-    `| Critical | ${summary.criticalCount} |`,
-    `| High     | ${summary.highCount} |`,
-    `| Medium   | ${summary.mediumCount} |`,
-    `| Low      | ${summary.lowCount} |`,
-    `| Info     | ${summary.infoCount} |`
+    `| \u{1F534} Critical | ${summary.criticalCount} |`,
+    `| \u{1F7E0} High     | ${summary.highCount} |`,
+    `| \u{1F7E1} Medium   | ${summary.mediumCount} |`,
+    `| \u{1F535} Low      | ${summary.lowCount} |`,
+    `| \u26AA Info     | ${summary.infoCount} |`
   ];
-  if (findings.length > 0) {
-    lines.push("", "### Findings");
-    for (const f of findings.slice(0, 20)) {
-      lines.push(`- **[${f.severity.toUpperCase()}]** \`${f.file}:${f.line}\` \u2014 ${f.message}`);
-      if (f.suggestion) lines.push(`  > ${f.suggestion}`);
+  const critical = findings.filter((f) => f.severity === "critical");
+  const high = findings.filter((f) => f.severity === "high");
+  const rest = findings.filter((f) => f.severity !== "critical" && f.severity !== "high");
+  if (critical.length > 0) {
+    lines.push(``, `## \u{1F534} Critical Issues (must fix)`);
+    for (const f of critical) {
+      lines.push(``, `### ${f.rule}`);
+      lines.push(`**File:** \`${f.file}:${f.line}\``);
+      lines.push(`**Issue:** ${f.message}`);
+      if (f.suggestion) lines.push(`**Fix:** ${f.suggestion}`);
+    }
+  }
+  if (high.length > 0) {
+    lines.push(``, `## \u{1F7E0} High Severity`);
+    for (const f of high) {
+      lines.push(`- **${f.rule}** \u2014 \`${f.file}:${f.line}\`: ${f.message}`);
+      if (f.suggestion) lines.push(`  > Fix: ${f.suggestion}`);
+    }
+  }
+  if (rest.length > 0) {
+    const shown = rest.slice(0, 10);
+    lines.push(``, `## Other Findings (${rest.length} total)`);
+    for (const f of shown) {
+      const icon = f.severity === "medium" ? "\u{1F7E1}" : f.severity === "low" ? "\u{1F535}" : "\u26AA";
+      lines.push(`- ${icon} **[${f.severity}]** \`${f.file}:${f.line}\` \u2014 ${f.message}`);
     }
-    if (findings.length > 20) lines.push(`  ... and ${findings.length - 20} more`);
+    if (rest.length > 10) lines.push(`- ... and ${rest.length - 10} more`);
+  }
+  if (findings.length === 0) {
+    lines.push(``, `## \u2705 No issues found`);
+    lines.push(`The code passed all ${metadata.agentsUsed.length} agent checks.`);
+  }
+  return lines.join("\n");
+}
+function formatSecurityScan(result) {
+  const secFindings = result.findings.filter(
+    (f) => f.category === "security" || f.severity === "critical" || f.severity === "high"
+  );
+  if (secFindings.length === 0) {
+    return [
+      `# Security Scan \u2014 \u2705 Clean`,
+      ``,
+      `No security issues detected. Score: ${result.summary.reliabilityScore}/100`,
+      `Checked by: ${result.metadata.agentsUsed.join(", ")}`
+    ].join("\n");
+  }
+  const lines = [
+    `# Security Scan \u2014 ${secFindings.length} issue${secFindings.length > 1 ? "s" : ""} found`,
+    ``,
+    `**Gate:** ${gate(result.summary.reliabilityScore, result.summary.criticalCount, result.summary.highCount)}`,
+    ``
+  ];
+  for (const f of secFindings) {
+    const icon = f.severity === "critical" ? "\u{1F534}" : f.severity === "high" ? "\u{1F7E0}" : "\u{1F7E1}";
+    lines.push(`## ${icon} ${f.rule} [${f.severity.toUpperCase()}]`);
+    lines.push(`**Location:** \`${f.file}:${f.line}\``);
+    lines.push(`**Issue:** ${f.message}`);
+    if (f.suggestion) lines.push(`**Remediation:** ${f.suggestion}`);
+    lines.push(``);
   }
   return lines.join("\n");
 }
 function registerTools(server2) {
   server2.tool(
     "swarm_audit",
-    "Run a full Crukx 7-agent swarm audit on code. Returns reliability score, findings, and recommendations.",
+    [
+      "Run a full Crukx 7-agent reliability audit on code.",
+      "",
+      "Deploys 6 parallel agents (Stresser, Hunter, Red Teamer, Auditor, Scout, Stabilizer)",
+      "then a Synthesizer to produce a reliability score (0\u2013100), severity-graded findings,",
+      "and actionable fix suggestions for each issue.",
+      "",
+      "Use this tool when:",
+      "- The user asks to review, audit, or check code quality",
+      "- Before merging a PR or committing significant changes",
+      "- When the user wants a comprehensive reliability report",
+      "",
+      "Pass the code diff, snippet, or describe the file/repo to audit.",
+      "Returns: score, grade (A\u2013F), gate status (PASSED/BLOCKED), and per-finding fixes."
+    ].join("\n"),
     {
-      diff: z3.string().optional().describe("Unified diff or code snippet to audit"),
-      repoPath: z3.string().optional().describe("Repository path or name for context"),
-      focus: z3.string().optional().describe('Specific area to focus on (e.g. "security", "concurrency")')
+      diff: z2.string().optional().describe(
+        "The code to audit. Accepts: unified diff, raw code snippet, or a description of what to check. Example: paste the output of `git diff HEAD`."
+      ),
+      repoPath: z2.string().optional().describe(
+        'Repository name or path for context. Example: "my-app/src/auth.ts".'
+      ),
+      focus: z2.string().optional().describe(
+        'Narrow the audit to a specific concern. Examples: "security", "concurrency", "error handling", "SQL injection".'
+      )
     },
     async ({ diff, repoPath, focus }) => {
-      const result = await swarmAudit({ diff, repoPath, focus });
-      return { content: [{ type: "text", text: formatFindings(result) }] };
+      try {
+        const result = await swarmAudit({ diff, repoPath, focus });
+        return { content: [{ type: "text", text: formatFullAudit(result) }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `\u274C Audit failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+      }
     }
   );
   server2.tool(
     "security_scan",
-    "Run a targeted security scan using the Red Teamer and Hunter agents.",
+    [
+      "Run a targeted security analysis using the Red Teamer and Hunter agents.",
+      "",
+      "Detects: injection attacks (SQL, command, prompt), hardcoded secrets/API keys,",
+      "authentication and authorization flaws, insecure dependencies, XSS, CSRF,",
+      "path traversal, and other OWASP Top 10 vulnerabilities.",
+      "",
+      "Use this tool when:",
+      '- The user asks "is this secure?" or "check for vulnerabilities"',
+      "- Code handles user input, auth, file I/O, or external APIs",
+      "- You spot patterns that could be security risks",
+      "",
+      "Returns: per-vulnerability findings with severity, location, and remediation steps."
+    ].join("\n"),
     {
-      diff: z3.string().describe("Code diff or snippet to scan for security issues")
+      diff: z2.string().describe(
+        "Code to scan for security issues. Accepts diffs, snippets, or full files. Example: an auth handler, API route, or database query."
+      )
     },
     async ({ diff }) => {
-      const result = await swarmAudit({ diff, focus: "security vulnerabilities, injection attacks, secrets, authentication flaws" });
-      const secFindings = result.findings.filter((f) => f.category === "security" || f.severity === "critical" || f.severity === "high");
-      const lines = secFindings.length === 0 ? ["\u2705 No security issues detected."] : secFindings.map((f) => `- **[${f.severity.toUpperCase()}]** ${f.message}
-  File: \`${f.file}:${f.line}\`${f.suggestion ? `
-  Fix: ${f.suggestion}` : ""}`);
-      return { content: [{ type: "text", text: `## Security Scan Results
-
-${lines.join("\n")}` }] };
+      try {
+        const result = await swarmAudit({
+          diff,
+          focus: "security vulnerabilities, injection attacks, hardcoded secrets, authentication flaws, OWASP Top 10"
+        });
+        return { content: [{ type: "text", text: formatSecurityScan(result) }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `\u274C Security scan failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+      }
     }
   );
   server2.tool(
     "reliability_score",
-    "Get a reliability score for a code change without full findings detail.",
+    [
+      "Get a fast reliability score and pass/fail gate for a code change.",
+      "",
+      "Returns a score (0\u2013100), grade (A\u2013F), and gate status without the full findings list.",
+      "Faster than swarm_audit \u2014 use this for quick pre-commit or pre-merge checks.",
+      "",
+      "Use this tool when:",
+      "- The user wants a quick quality check before committing",
+      "- You need a pass/fail signal without detailed findings",
+      "- Checking if a small change is safe to merge"
+    ].join("\n"),
     {
-      diff: z3.string().describe("Code diff to score")
+      diff: z2.string().describe(
+        "Code diff or snippet to score. Example: paste `git diff --staged` output."
+      )
     },
     async ({ diff }) => {
-      const result = await swarmAudit({ diff });
-      const { reliabilityScore, confidence, criticalCount, highCount } = result.summary;
-      const passed = criticalCount === 0 && highCount === 0;
-      const text = [
-        `**Score:** ${reliabilityScore}/100`,
-        `**Gate:** ${passed ? "\u2705 PASSED" : "\u274C FAILED"}`,
-        `**Confidence:** ${confidence}%`,
-        `**Critical:** ${criticalCount} | **High:** ${highCount}`
-      ].join("\n");
-      return { content: [{ type: "text", text }] };
+      try {
+        const result = await swarmAudit({ diff });
+        const { reliabilityScore, confidence, criticalCount, highCount, mediumCount } = result.summary;
+        const text = [
+          `# Reliability Score`,
+          ``,
+          `**Score:** ${reliabilityScore}/100 (Grade ${grade(reliabilityScore)})`,
+          `**Gate:** ${gate(reliabilityScore, criticalCount, highCount)}`,
+          `**Confidence:** ${confidence}%`,
+          ``,
+          `| \u{1F534} Critical | \u{1F7E0} High | \u{1F7E1} Medium |`,
+          `|-------------|---------|-----------|`,
+          `| ${criticalCount} | ${highCount} | ${mediumCount} |`,
+          ``,
+          criticalCount > 0 || highCount > 0 ? `Run \`swarm_audit\` for full findings and fix suggestions.` : `\u2705 No blocking issues found.`
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `\u274C Score failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+      }
     }
   );
   server2.tool(
-    "report_fetch",
-    "Fetch a previously generated Crukx audit report by ID.",
+    "suggest_fix",
+    [
+      "Get targeted remediation suggestions for a specific code issue.",
+      "",
+      "Pass the problematic code or a description of the issue.",
+      "The Synthesizer agent returns concrete fix suggestions with code examples where possible.",
+      "",
+      "Use this tool when:",
+      '- The user asks "how do I fix this?"',
+      "- A swarm_audit or security_scan finding needs a detailed fix",
+      "- The user has a specific bug or vulnerability to remediate"
+    ].join("\n"),
     {
-      report_id: z3.string().uuid().describe("Audit run ID to fetch")
+      issue: z2.string().describe(
+        "The issue to fix. Can be: a code snippet with the problem, a finding message from swarm_audit, or a plain description. Example: \"SQL query built with string concatenation: `query = 'SELECT * FROM users WHERE id = ' + userId`\"."
+      ),
+      severity: z2.enum(["critical", "high", "medium", "low"]).optional().describe(
+        "Severity of the issue, if known. Helps prioritize the fix approach."
+      )
     },
-    async ({ report_id }) => {
-      const report = await fetchReport(report_id);
-      return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
+    async ({ issue, severity }) => {
+      try {
+        const focus = `Provide concrete remediation and fix suggestions for this issue${severity ? ` (severity: ${severity})` : ""}: ${issue}`;
+        const result = await swarmAudit({ diff: issue, focus });
+        const suggestions = result.findings.filter((f) => f.suggestion).map((f) => `### ${f.rule}
+**Issue:** ${f.message}
+**Fix:** ${f.suggestion}`).join("\n\n");
+        const text = suggestions.length > 0 ? `# Remediation Suggestions
+
+${suggestions}` : `# \u2705 No Issues Found
+
+The code looks clean \u2014 no specific remediation needed.`;
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `\u274C suggest_fix failed: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+      }
     }
   );
   server2.tool(
-    "suggest_fix",
-    "Get remediation suggestions for a specific finding or code issue.",
+    "report_fetch",
+    [
+      "Fetch a previously generated Crukx audit report by its ID.",
+      "",
+      "Use this tool when:",
+      '- The user references a past audit ("show me report abc-123")',
+      "- You want to retrieve findings from an earlier swarm_audit run",
+      "- The user wants to compare two audit runs",
+      "",
+      'The report ID is returned by swarm_audit as "Report ID".'
+    ].join("\n"),
     {
-      issue: z3.string().describe("Description of the issue or paste the problematic code"),
-      severity: z3.enum(["critical", "high", "medium", "low"]).optional().describe("Severity level")
+      report_id: z2.string().describe(
+        'The audit run ID to fetch. This is the UUID returned by swarm_audit in the "Report ID" field.'
+      )
     },
-    async ({ issue, severity }) => {
-      const focus = `remediation and fix suggestions for: ${issue}. Severity: ${severity ?? "unknown"}`;
-      const result = await swarmAudit({ diff: issue, focus });
-      const suggestions = result.findings.filter((f) => f.suggestion).map((f) => `- **${f.rule}**: ${f.suggestion}`).join("\n");
-      return {
-        content: [{
-          type: "text",
-          text: suggestions.length > 0 ? `## Remediation Suggestions
-
-${suggestions}` : "\u2705 No specific remediation needed \u2014 code looks clean."
-        }]
-      };
+    async ({ report_id }) => {
+      try {
+        const report = await fetchReport(report_id);
+        return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
+      } catch (err) {
+        return { content: [{ type: "text", text: `\u274C Report not found: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+      }
     }
   );
   server2.tool(
     "crukx_health",
-    "Check Crukx gateway connectivity and authentication status.",
+    [
+      "Check Crukx gateway connectivity and authentication status.",
+      "",
+      "Use this tool when:",
+      "- Other Crukx tools are returning errors",
+      "- The user asks if Crukx is connected or working",
+      "- Diagnosing auth or network issues",
+      "",
+      "Returns: gateway status, auth validity, and API URL in use."
+    ].join("\n"),
     {},
     async () => {
-      const result = await healthCheck();
-      return { content: [{ type: "text", text: `Crukx gateway: ${result.status} \u2705` }] };
+      try {
+        const result = await healthCheck();
+        const auth = (await import("./auth-J6323WQJ.js")).loadAuth();
+        const text = [
+          `# Crukx Gateway Status`,
+          ``,
+          `**Status:** ${result.status === "ok" ? "\u2705 Connected" : "\u274C " + result.status}`,
+          `**Auth:** ${auth?.access_token ? "\u2705 Authenticated" : "\u274C Not logged in \u2014 run `crukx login`"}`,
+          `**Workspace:** ${auth?.workspace_id ?? "unknown"}`,
+          `**API:** ${auth?.api_url ?? "default"}`,
+          `**Token expires:** ${auth?.expires_at ?? "unknown"}`
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
+      } catch (err) {
+        return {
+          content: [{
+            type: "text",
+            text: `# Crukx Gateway Status
+
+\u274C **Unreachable**
+
+${err instanceof Error ? err.message : String(err)}
+
+Run \`crukx login\` to re-authenticate.`
+          }],
+          isError: true
+        };
+      }
     }
   );
 }
@@ -259,7 +424,51 @@ ${suggestions}` : "\u2705 No specific remediation needed \u2014 code looks clean
 // src/server.ts
 var server = new McpServer({
   name: "crukx",
-  version: "0.1.0"
+  version: "0.1.3"
+}, {
+  instructions: `You have access to Crukx \u2014 a 7-agent AI reliability engine for code quality, security, and correctness.
+
+Use these tools proactively whenever the user:
+- Asks you to review, audit, or check code
+- Writes or edits code that could have security issues
+- Wants a reliability or quality score before merging
+- Asks about bugs, vulnerabilities, or code smells
+- Needs remediation suggestions for a specific issue
+
+## Available tools
+
+**swarm_audit** \u2014 Full 7-agent audit (Stresser, Hunter, Red Teamer, Auditor, Scout, Stabilizer, Synthesizer).
+Pass the code diff or snippet. Returns a reliability score (0\u2013100), severity breakdown, and per-finding suggestions.
+Use this for comprehensive reviews.
+
+**security_scan** \u2014 Focused security analysis using Red Teamer + Hunter agents.
+Detects injection attacks, secrets in code, auth flaws, insecure dependencies, and prompt injection.
+Use this when the user asks specifically about security.
+
+**reliability_score** \u2014 Fast pass/fail gate (score + critical/high count only).
+Use this for a quick check before a commit or PR merge.
+
+**suggest_fix** \u2014 Targeted remediation for a specific issue or code snippet.
+Use this when the user wants to fix a known problem.
+
+**report_fetch** \u2014 Retrieve a full audit report by its ID.
+Use this when the user references a previous audit run.
+
+**crukx_health** \u2014 Verify gateway connectivity and auth.
+Use this if tools are returning errors or the user asks about connection status.
+
+## When to use which tool
+
+| Situation | Tool |
+|-----------|------|
+| "Review this PR / diff" | swarm_audit |
+| "Is this code secure?" | security_scan |
+| "Quick score before merge" | reliability_score |
+| "How do I fix this?" | suggest_fix |
+| "Show me audit #abc" | report_fetch |
+| "Is Crukx connected?" | crukx_health |
+
+Always show the reliability score and gate status prominently. If critical or high findings exist, list them with their suggested fixes.`
 });
 registerTools(server);
 var transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crukx-mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Crukx MCP server — reliability control plane for autonomous software engineering",
   "type": "module",
   "main": "./dist/server.js",