@better_vibe/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,101 @@
+# BetterVibe MCP Server
+
+Audit your code health directly from your AI coding agent (Cursor, Claude Desktop, Windsurf, Cline).
+
+Just tell your agent: **"audit this repo"** — and it runs a full BetterVibe audit, returning your score, grade, and what to fix.
+
+## Setup
+
+### 1. Get an API key
+
+Go to [bettervibe.app/dashboard/keys](https://www.bettervibe.app/dashboard/keys) and create a key.
+
+### 2. Add to your AI agent
+
+#### Cursor
+
+Add to `.cursor/mcp.json` in your project (or global `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "bettervibe": {
+      "command": "npx",
+      "args": ["-y", "@bettervibe/mcp-server"],
+      "env": {
+        "BETTERVIBE_API_KEY": "bv_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "bettervibe": {
+      "command": "npx",
+      "args": ["-y", "@bettervibe/mcp-server"],
+      "env": {
+        "BETTERVIBE_API_KEY": "bv_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Alternative: config file
+
+Instead of setting the env var per-agent, create `~/.bettervibe`:
+
+```json
+{ "apiKey": "bv_live_your_key_here" }
+```
+
+### 3. Use it
+
+Just talk to your AI agent:
+
+- "Audit this repo"
+- "What's my code health score?"
+- "Audit this repo and fix any issues below 70"
+- "Run a BetterVibe check before I push"
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `audit_repo` | Full audit — score, grade, per-category breakdown, issues to fix |
+| `get_score` | Quick check — just the score and grade |
+
+## Available Prompts
+
+| Prompt | Description |
+|--------|-------------|
+| `audit-before-push` | Runs an audit and suggests fixes for anything below 70 |
+
+## How it works
+
+1. The MCP server auto-detects your GitHub repo from the local git remote
+2. Calls the BetterVibe API with your key
+3. Returns a structured audit result the AI agent can act on
+4. The agent can then suggest or apply fixes directly
+
+## Requirements
+
+- Node.js 18+
+- A GitHub repo (public, or private with GitHub App connected)
+- A BetterVibe API key ($9.99/mo Pro, or 3 free audits)
+
+## Local development
+
+```bash
+cd mcp-server
+npm install
+npm run build
+BETTERVIBE_API_KEY=bv_live_... node dist/index.js
+```

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getApiKey, detectRepoUrl, runAudit, formatAuditResult } from "./lib.js";
+const server = new McpServer({
+    name: "bettervibe",
+    version: "1.0.0",
+});
+// Tool: audit_repo
+server.registerTool("audit_repo", {
+    title: "Audit Code Health",
+    description: "Run a BetterVibe code health audit on a GitHub repo. Returns a 0-100 score, letter grade, and per-category breakdown (security, tests, architecture, secrets, duplication, CI/CD). If no repo URL is provided, auto-detects from the current git remote.",
+    inputSchema: {
+        repoUrl: z.string().optional().describe("GitHub repo URL (e.g. https://github.com/owner/repo). Auto-detected from git remote if omitted."),
+        deep: z.boolean().optional().describe("Run a Deep Audit with full tool suite (Semgrep, osv-scanner, secretlint, jscpd). Defaults to true."),
+    },
+}, async ({ repoUrl, deep }) => {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        return {
+            content: [{ type: "text", text: "❌ No BetterVibe API key found. Set BETTERVIBE_API_KEY environment variable or create ~/.bettervibe with {\"apiKey\": \"bv_live_...\"}. Get a key at https://www.bettervibe.app/dashboard/keys" }],
+            isError: true,
+        };
+    }
+    const url = repoUrl || detectRepoUrl();
+    if (!url) {
+        return {
+            content: [{ type: "text", text: "❌ Could not detect repo URL. Either provide a repoUrl parameter or run this from a directory with a GitHub git remote." }],
+            isError: true,
+        };
+    }
+    const result = await runAudit(url, apiKey, deep !== false);
+    if (result.error) {
+        return { content: [{ type: "text", text: `❌ Audit failed: ${result.error}` }], isError: true };
+    }
+    return { content: [{ type: "text", text: formatAuditResult(result, url) }] };
+});
+// Tool: get_score
+server.registerTool("get_score", {
+    title: "Get Code Health Score",
+    description: "Quick check — returns just the numeric score (0-100) and grade for a repo.",
+    inputSchema: {
+        repoUrl: z.string().optional().describe("GitHub repo URL. Auto-detected if omitted."),
+    },
+}, async ({ repoUrl }) => {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        return { content: [{ type: "text", text: "❌ No API key. Set BETTERVIBE_API_KEY env var." }], isError: true };
+    }
+    const url = repoUrl || detectRepoUrl();
+    if (!url) {
+        return { content: [{ type: "text", text: "❌ Could not detect repo URL." }], isError: true };
+    }
+    const result = await runAudit(url, apiKey, true);
+    if (result.error) {
+        return { content: [{ type: "text", text: `❌ ${result.error}` }], isError: true };
+    }
+    return { content: [{ type: "text", text: `${result.score}/100 (${result.grade})` }] };
+});
+// Prompt: pre-push audit
+server.registerPrompt("audit-before-push", {
+    title: "Audit Before Push",
+    description: "Run a code health audit and suggest fixes before pushing to GitHub.",
+}, () => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: "Run a BetterVibe audit on this repo. If the score is below 70, list the top issues and suggest specific code fixes I can make right now before pushing.",
+            },
+        },
+    ],
+}));
+// Start
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/lib.d.ts

@@ -0,0 +1,15 @@
+/** Get API key from env or ~/.bettervibe config file */
+export declare function getApiKey(): string | null;
+/** Detect the GitHub repo URL from the local git remote */
+export declare function detectRepoUrl(cwd?: string): string | null;
+export type AuditResult = {
+    score: number;
+    grade: string;
+    categories: any[];
+    error?: string;
+    cached?: boolean;
+};
+/** Call the BetterVibe audit API */
+export declare function runAudit(repoUrl: string, apiKey: string, deep: boolean, baseUrl?: string): Promise<AuditResult>;
+/** Format an audit result for display in an AI agent */
+export declare function formatAuditResult(result: AuditResult, repoUrl: string): string;

package/dist/lib.js

@@ -0,0 +1,74 @@
+import { execSync } from "child_process";
+import { readFileSync } from "fs";
+import { join } from "path";
+/** Get API key from env or ~/.bettervibe config file */
+export function getApiKey() {
+    if (process.env.BETTERVIBE_API_KEY)
+        return process.env.BETTERVIBE_API_KEY;
+    try {
+        const home = process.env.HOME || process.env.USERPROFILE || "";
+        const configPath = join(home, ".bettervibe");
+        const config = JSON.parse(readFileSync(configPath, "utf-8"));
+        return config.apiKey || null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Detect the GitHub repo URL from the local git remote */
+export function detectRepoUrl(cwd) {
+    try {
+        const remote = execSync("git remote get-url origin", {
+            cwd: cwd || process.cwd(),
+            encoding: "utf-8",
+            timeout: 5000,
+        }).trim();
+        // Convert SSH to HTTPS
+        if (remote.startsWith("git@github.com:")) {
+            return `https://github.com/${remote.slice(15).replace(/\.git$/, "")}`;
+        }
+        if (remote.includes("github.com")) {
+            return remote.replace(/\.git$/, "");
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Call the BetterVibe audit API */
+export async function runAudit(repoUrl, apiKey, deep, baseUrl = "https://www.bettervibe.app") {
+    const res = await fetch(`${baseUrl}/api/audit`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "X-API-Key": apiKey,
+        },
+        body: JSON.stringify({ repoUrl, deep }),
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        return { score: 0, grade: "error", categories: [], error: data.error || `HTTP ${res.status}` };
+    }
+    return data;
+}
+/** Format an audit result for display in an AI agent */
+export function formatAuditResult(result, repoUrl) {
+    const categoryLines = (result.categories || [])
+        .filter((c) => c.applicable !== false)
+        .map((c) => `  ${c.icon} ${c.name}: ${c.pct ?? 0}%`)
+        .join("\n");
+    const findings = (result.categories || [])
+        .flatMap((c) => (c.checkpoints || [])
+        .filter((cp) => cp.applicable && !cp.passed)
+        .map((cp) => `  ⚠️ ${cp.label}${cp.detail ? ` — ${cp.detail}` : ""}`))
+        .join("\n");
+    return `🛡️ BetterVibe Audit — ${result.score}/100 (${result.grade})${result.cached ? " (cached)" : ""}
+
+📊 Categories:
+${categoryLines}
+
+${findings ? `🔧 Issues to fix:\n${findings}` : "✅ No critical issues found."}
+
+Repo: ${repoUrl}`;
+}

package/dist/lib.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/lib.test.js

@@ -0,0 +1,146 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { getApiKey, detectRepoUrl, runAudit, formatAuditResult } from "./lib.js";
+describe("getApiKey", () => {
+    const originalEnv = process.env;
+    beforeEach(() => {
+        process.env = { ...originalEnv };
+    });
+    afterEach(() => {
+        process.env = originalEnv;
+    });
+    it("returns BETTERVIBE_API_KEY from env", () => {
+        process.env.BETTERVIBE_API_KEY = "bv_live_test123";
+        expect(getApiKey()).toBe("bv_live_test123");
+    });
+    it("returns null when no env var and no config file", () => {
+        delete process.env.BETTERVIBE_API_KEY;
+        process.env.HOME = "/nonexistent";
+        expect(getApiKey()).toBeNull();
+    });
+});
+describe("detectRepoUrl", () => {
+    it("detects the repo URL from this repo's git remote", () => {
+        // We're running from within the better-vibe repo
+        const url = detectRepoUrl(process.cwd());
+        // It should be a github URL (SSH or HTTPS)
+        if (url) {
+            expect(url).toContain("github.com");
+            expect(url).toContain("better-vibe");
+        }
+    });
+    it("converts SSH remote to HTTPS", () => {
+        // Test the conversion logic by calling from a known dir
+        // (the current repo uses SSH or HTTPS — either way it should return HTTPS)
+        const url = detectRepoUrl(process.cwd());
+        if (url) {
+            expect(url.startsWith("https://")).toBe(true);
+        }
+    });
+    it("returns null for a non-git directory", () => {
+        const url = detectRepoUrl("/tmp");
+        expect(url).toBeNull();
+    });
+});
+describe("runAudit", () => {
+    it("calls the BetterVibe API with correct headers", async () => {
+        const mockFetch = vi.fn().mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ score: 85, grade: "A", categories: [] }),
+        });
+        vi.stubGlobal("fetch", mockFetch);
+        const result = await runAudit("https://github.com/test/repo", "bv_live_testkey", true, "https://example.com");
+        expect(mockFetch).toHaveBeenCalledWith("https://example.com/api/audit", expect.objectContaining({
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "X-API-Key": "bv_live_testkey",
+            },
+            body: JSON.stringify({ repoUrl: "https://github.com/test/repo", deep: true }),
+        }));
+        expect(result.score).toBe(85);
+        expect(result.grade).toBe("A");
+        vi.unstubAllGlobals();
+    });
+    it("returns error on non-200 response", async () => {
+        const mockFetch = vi.fn().mockResolvedValue({
+            ok: false,
+            status: 402,
+            json: () => Promise.resolve({ error: "Free audit used." }),
+        });
+        vi.stubGlobal("fetch", mockFetch);
+        const result = await runAudit("https://github.com/test/repo", "bv_live_testkey", true, "https://example.com");
+        expect(result.error).toBe("Free audit used.");
+        expect(result.score).toBe(0);
+        vi.unstubAllGlobals();
+    });
+    it("passes deep=false when requested", async () => {
+        const mockFetch = vi.fn().mockResolvedValue({
+            ok: true,
+            json: () => Promise.resolve({ score: 70, grade: "B", categories: [] }),
+        });
+        vi.stubGlobal("fetch", mockFetch);
+        await runAudit("https://github.com/test/repo", "bv_live_testkey", false, "https://example.com");
+        const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+        expect(body.deep).toBe(false);
+        vi.unstubAllGlobals();
+    });
+});
+describe("formatAuditResult", () => {
+    it("formats a successful audit with categories", () => {
+        const result = {
+            score: 75,
+            grade: "B — solid, a few gaps",
+            categories: [
+                { id: "testing", name: "Test Coverage", icon: "🧪", pct: 100, applicable: true, checkpoints: [] },
+                { id: "security", name: "Security", icon: "🔐", pct: 80, applicable: true, checkpoints: [] },
+            ],
+        };
+        const text = formatAuditResult(result, "https://github.com/test/repo");
+        expect(text).toContain("75/100");
+        expect(text).toContain("B — solid, a few gaps");
+        expect(text).toContain("🧪 Test Coverage: 100%");
+        expect(text).toContain("🔐 Security: 80%");
+        expect(text).toContain("https://github.com/test/repo");
+        expect(text).toContain("✅ No critical issues found.");
+    });
+    it("shows issues when checkpoints fail", () => {
+        const result = {
+            score: 45,
+            grade: "C — needs work",
+            categories: [
+                {
+                    id: "security",
+                    name: "Security",
+                    icon: "🔐",
+                    pct: 30,
+                    applicable: true,
+                    checkpoints: [
+                        { id: "no-secrets", label: "No secrets in code", applicable: true, passed: false, detail: "3 secrets found" },
+                        { id: "deps-secure", label: "Dependencies secure", applicable: true, passed: true, detail: "" },
+                    ],
+                },
+            ],
+        };
+        const text = formatAuditResult(result, "https://github.com/test/repo");
+        expect(text).toContain("⚠️ No secrets in code — 3 secrets found");
+        expect(text).not.toContain("Dependencies secure"); // passed, shouldn't show
+    });
+    it("shows (cached) label when result is cached", () => {
+        const result = { score: 80, grade: "B", categories: [], cached: true };
+        const text = formatAuditResult(result, "https://github.com/test/repo");
+        expect(text).toContain("(cached)");
+    });
+    it("skips non-applicable categories", () => {
+        const result = {
+            score: 90,
+            grade: "A",
+            categories: [
+                { id: "testing", name: "Test Coverage", icon: "🧪", pct: 100, applicable: true, checkpoints: [] },
+                { id: "ci", name: "CI/CD", icon: "⚙️", pct: null, applicable: false, checkpoints: [] },
+            ],
+        };
+        const text = formatAuditResult(result, "https://github.com/test/repo");
+        expect(text).toContain("Test Coverage");
+        expect(text).not.toContain("CI/CD");
+    });
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@better_vibe/mcp-server",
+  "version": "1.0.0",
+  "description": "BetterVibe MCP server — audit your code health from any AI coding agent (Cursor, Claude Desktop, Windsurf, Kiro)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "bettervibe-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^4.1.10"
+  },
+  "keywords": ["mcp", "bettervibe", "code-audit", "vibe-coding", "cursor", "claude", "kiro", "windsurf"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sumitvairagar/better-vibe",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://www.bettervibe.app/dashboard/keys"
+}