@vibeinfra/mcp-server 0.1.0 → 0.3.0

package/README.md

@@ -38,6 +38,8 @@ The server speaks stdio and requires Node 18+.
 
 ## Tools
 
+### 🔍 Discovery & Catalog Tools (Public, Read-Only)
+
 | Tool                         | What it does                                                                 |
 | ---------------------------- | ---------------------------------------------------------------------------- |
 | `list_incidents`             | Every incident and course in the catalog, with tier, stack, duration and link. |
@@ -46,19 +48,59 @@ The server speaks stdio and requires Node 18+.
 | `get_platform_capacity`      | Live sandbox usage and queue length.                                           |
 | `lookup_infrastructure_term` | The VibeInfra infrastructure/SRE glossary.                                     |
 
+### ⚡ Interactive SRE Incident Drills, Diagnostics & Headless Troubleshooting
+
+| Tool                         | What it does                                                                 |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| `start_drill`                | Spawns a live disposable sandbox and returns session ID and web terminal.    |
+| `exec_in_sandbox`            | Runs diagnostic/remediation commands (`kubectl`, `df`, `systemctl`) in sandbox. |
+| `get_drill_hint`             | Provides spoiler-free progressive guidance and diagnostic nudges.             |
+| `grade_drill`                | Runs automated system-state evaluation against the live sandbox to score fixes. |
+| `get_drill_status`           | Returns real-time telemetry, node health status, and live topology.           |
+| `stop_drill`                 | Cleanly terminates and destroys the disposable sandbox container.            |
+
+## Authentication
+
+### Zero-Config CLI Login (Recommended)
+
+Authenticate your terminal or agent host in 5 seconds without touching JSON config files:
+
+```bash
+npx -y @vibeinfra/mcp-server login
+```
+
+This opens your browser to authorize your account and securely saves your Personal Access Token to `~/.vibeinfra/credentials.json` (POSIX `0600` permissions). Subsequent runs of `@vibeinfra/mcp-server` automatically discover this token.
+
+To log out:
+```bash
+npx -y @vibeinfra/mcp-server logout
+```
+
+### 1-Click Dashboard Token
+
+You can also generate a Personal Access Token from your VibeInfra Profile:
+1. Navigate to **[https://vibeinfra.id/profile](https://vibeinfra.id/profile)**.
+2. Under **AI Agents & MCP Integration**, click **Generate Agent Token**.
+3. Click **Copy Configuration** and paste it directly into your `.mcp.json` or Cursor / Claude Code settings.
+
 ## Configuration
 
 | Environment variable     | Default                    | Purpose                              |
 | ------------------------ | -------------------------- | ------------------------------------ |
 | `VIBEINFRA_API_BASE_URL` | `https://api.vibeinfra.id` | Point the server at a local backend. |
+| `VIBEINFRA_API_KEY`      | `""`                       | Bearer token / API key for authorized lab access. |
 
 ## Try it
 
 Ask your agent:
 
-> Find me an expert-tier Kafka incident on VibeInfra and summarise what it teaches.
+> Find me a beginner-friendly Kubernetes incident on VibeInfra.
+
+> Start an incident drill for incident-40-deployment-never-rolled-out.
+
+> I'm stuck on this drill — give me a spoiler-free hint.
 
-> Is VibeInfra busy right now, or can I start a lab straight away?
+> I applied my fix to the Kubernetes deployment — grade my drill now.
 
 ## Related
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@vibeinfra/mcp-server",
-  "version": "0.1.0",
-  "description": "Model Context Protocol server for VibeInfra — lets an AI agent browse the SRE incident catalog, read live sandbox capacity and look up infrastructure terms.",
+  "version": "0.3.0",
+  "description": "Model Context Protocol server for VibeInfra — enables AI agents to browse the SRE incident catalog, start live disposable sandboxes, coach learners with hints, and grade remediations.",
   "keywords": [
     "mcp",
     "modelcontextprotocol",

package/src/api.js

@@ -22,12 +22,21 @@ export class ApiError extends Error {
 }
 
 export class VibeInfraApi {
-  constructor({ baseUrl = DEFAULT_BASE_URL, timeoutMs = DEFAULT_TIMEOUT_MS, fetch: fetchImpl } = {}) {
+  constructor({ baseUrl = DEFAULT_BASE_URL, apiKey, timeoutMs = DEFAULT_TIMEOUT_MS, fetch: fetchImpl } = {}) {
     this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
     this.timeoutMs = timeoutMs;
     this.fetch = fetchImpl ?? globalThis.fetch;
   }
 
+  getHeaders() {
+    const headers = { Accept: "application/json" };
+    if (this.apiKey) {
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+    return headers;
+  }
+
   async get(path, query) {
     const params = new URLSearchParams();
     for (const [key, value] of Object.entries(query ?? {})) {
@@ -41,7 +50,7 @@ export class VibeInfraApi {
     let response;
     try {
       response = await this.fetch(url, {
-        headers: { Accept: "application/json" },
+        headers: this.getHeaders(),
         signal: controller.signal,
       });
     } finally {
@@ -54,6 +63,42 @@ export class VibeInfraApi {
     return response.json();
   }
 
+  async post(path, body) {
+    const url = `${this.baseUrl}/api/${API_VERSION}${path}`;
+    const headers = {
+      ...this.getHeaders(),
+      "Content-Type": "application/json",
+    };
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetch(url, {
+        method: "POST",
+        headers,
+        body: JSON.stringify(body ?? {}),
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (!response.ok) {
+      let errorMsg = `POST ${url} failed with ${response.status}`;
+      try {
+        const errorBody = await response.json();
+        if (errorBody && errorBody.message) {
+          errorMsg = errorBody.message;
+        }
+      } catch {
+        // Fall back to default errorMsg if response body is not JSON
+      }
+      throw new ApiError(response.status, url, errorMsg);
+    }
+    return response.json();
+  }
+
   listCourses(locale) {
     return this.get("/courses", { locale });
   }
@@ -73,4 +118,36 @@ export class VibeInfraApi {
   getLeaderboard() {
     return this.get("/labs/leaderboard");
   }
+
+  startLab(courseId, forceFresh = false) {
+    return this.post("/labs/start", { course_id: courseId, force_fresh: forceFresh });
+  }
+
+  checkLab(sessionId, courseId) {
+    return this.post("/labs/check", { session_id: sessionId, course_id: courseId });
+  }
+
+  getHint(sessionId) {
+    return this.post("/labs/hint", { session_id: sessionId });
+  }
+
+  destroyLab(sessionId) {
+    return this.post("/labs/destroy", { session_id: sessionId });
+  }
+
+  getLabTelemetry(sessionId) {
+    return this.get("/labs/telemetry", { session_id: sessionId });
+  }
+
+  getLabTopology(sessionId) {
+    return this.get("/labs/topology", { session_id: sessionId });
+  }
+
+  execInSandbox(sessionId, command, timeoutSec = 15) {
+    return this.post("/labs/exec", {
+      session_id: sessionId,
+      command,
+      timeout_sec: timeoutSec,
+    });
+  }
 }

package/src/cli.js

@@ -9,7 +9,34 @@
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 import { createServer } from "./server.js";
+import { getStoredApiKey, runLogin, runLogout } from "./login.js";
 
-const server = createServer({ baseUrl: process.env.VIBEINFRA_API_BASE_URL });
+const command = process.argv[2];
+
+if (command === "login") {
+  try {
+    await runLogin({
+      webBaseUrl: process.env.VIBEINFRA_WEB_URL || "https://vibeinfra.id",
+    });
+    process.exit(0);
+  } catch (err) {
+    console.error("❌ Login failed:", err.message || err);
+    process.exit(1);
+  }
+}
+
+if (command === "logout") {
+  runLogout();
+  process.exit(0);
+}
+
+// Automatically resolve API key from environment or ~/.vibeinfra/credentials.json
+const resolvedApiKey = process.env.VIBEINFRA_API_KEY || getStoredApiKey();
+
+const server = createServer({
+  baseUrl: process.env.VIBEINFRA_API_BASE_URL,
+  apiKey: resolvedApiKey,
+});
 
 await server.connect(new StdioServerTransport());
+

package/src/login.js

@@ -0,0 +1,142 @@
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import crypto from "node:crypto";
+import { exec } from "node:child_process";
+
+const CONFIG_DIR = path.join(os.homedir(), ".vibeinfra");
+const CREDENTIALS_FILE = path.join(CONFIG_DIR, "credentials.json");
+
+/**
+ * Read the stored API token from ~/.vibeinfra/credentials.json
+ */
+export function getStoredApiKey() {
+  try {
+    if (fs.existsSync(CREDENTIALS_FILE)) {
+      const data = JSON.parse(fs.readFileSync(CREDENTIALS_FILE, "utf-8"));
+      if (data && data.api_key) {
+        return data.api_key;
+      }
+    }
+  } catch {
+    // Ignore unreadable or corrupted config
+  }
+  return null;
+}
+
+/**
+ * Persist the API token with strict POSIX 0600 permissions
+ */
+export function saveApiKey(apiKey) {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+  fs.writeFileSync(
+    CREDENTIALS_FILE,
+    JSON.stringify(
+      {
+        api_key: apiKey,
+        saved_at: new Date().toISOString(),
+      },
+      null,
+      2
+    ),
+    { mode: 0o600 }
+  );
+}
+
+/**
+ * Wipe stored credentials
+ */
+export function clearApiKey() {
+  try {
+    if (fs.existsSync(CREDENTIALS_FILE)) {
+      fs.unlinkSync(CREDENTIALS_FILE);
+    }
+  } catch {
+    // Ignore error
+  }
+}
+
+function openBrowser(url) {
+  const platform = os.platform();
+  if (platform === "darwin") {
+    exec(`open "${url}"`);
+  } else if (platform === "win32") {
+    exec(`start "" "${url}"`);
+  } else {
+    exec(`xdg-open "${url}"`);
+  }
+}
+
+/**
+ * Run interactive OAuth loopback flow
+ */
+export function runLogin({ webBaseUrl = "https://vibeinfra.id", port = 49152 } = {}) {
+  return new Promise((resolve, reject) => {
+    const stateNonce = crypto.randomBytes(16).toString("hex");
+
+    const server = http.createServer((req, res) => {
+      const reqUrl = new URL(req.url, `http://127.0.0.1:${port}`);
+
+      if (reqUrl.pathname === "/callback") {
+        const token = reqUrl.searchParams.get("token");
+        const state = reqUrl.searchParams.get("state");
+
+        if (!token || state !== stateNonce) {
+          res.writeHead(400, { "Content-Type": "text/html" });
+          res.end("<h3>Invalid authentication request or state mismatch.</h3>");
+          server.close();
+          return reject(new Error("State nonce mismatch or missing token"));
+        }
+
+        saveApiKey(token);
+
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(`
+          <!DOCTYPE html>
+          <html>
+            <head><title>VibeInfra CLI Authorized</title></head>
+            <body style="font-family: system-ui, -apple-system, sans-serif; background: #09090b; color: #fff; display: flex; align-items: center; justify-content: center; height: 100vh; margin: 0;">
+              <div style="text-align: center; max-width: 440px; padding: 2rem; border-radius: 1rem; background: #18181b; border: 1px solid #27272a;">
+                <h2 style="color: #34d399; margin-top: 0;">✓ Successfully Authorized!</h2>
+                <p style="color: #a1a1aa; font-size: 0.95rem; line-height: 1.5;">
+                  Your Personal Access Token has been saved securely to <code style="color: #e4e4e7; background: #27272a; padding: 2px 6px; border-radius: 4px;">~/.vibeinfra/credentials.json</code>.
+                </p>
+                <p style="color: #71717a; font-size: 0.85rem; margin-top: 1.5rem;">You can close this tab and return to your terminal.</p>
+              </div>
+            </body>
+          </html>
+        `);
+
+        server.close();
+        console.error("\n✅ Successfully authenticated with VibeInfra!");
+        console.error(`Token securely saved to ${CREDENTIALS_FILE} (mode 0600).\n`);
+        return resolve();
+      }
+
+      res.writeHead(404);
+      res.end("Not found");
+    });
+
+    server.on("error", (err) => {
+      reject(err);
+    });
+
+    server.listen(port, "127.0.0.1", () => {
+      const authUrl = `${webBaseUrl.replace(/\/+$/, "")}/auth/cli?port=${port}&state=${stateNonce}`;
+      console.error("\n🚀 Opening browser to authenticate with VibeInfra...");
+      console.error(`If the browser does not open automatically, visit:\n${authUrl}\n`);
+      openBrowser(authUrl);
+    });
+  });
+}
+
+/**
+ * Handle logout CLI command
+ */
+export function runLogout() {
+  clearApiKey();
+  console.error("\n👋 Successfully logged out. Removed credentials from ~/.vibeinfra/credentials.json\n");
+}

package/src/server.js

@@ -10,27 +10,30 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { VibeInfraApi } from "./api.js";
 import { tools } from "./tools.js";
 
-export const SERVER_NAME = "id.vibeinfra/catalog";
-export const SERVER_VERSION = "0.1.0";
+export const SERVER_NAME = "id.vibeinfra/platform";
+export const SERVER_VERSION = "0.2.0";
 
 /**
  * @param {object} [options]
  * @param {string} [options.baseUrl] API origin. Defaults to production.
+ * @param {string} [options.apiKey] API key / Bearer token. Defaults to VIBEINFRA_API_KEY env.
  * @param {VibeInfraApi} [options.api] Pre-built API client, for tests.
  */
 export function createServer(options = {}) {
-  const api = options.api ?? new VibeInfraApi({ baseUrl: options.baseUrl });
+  const apiKey = options.apiKey ?? process.env.VIBEINFRA_API_KEY;
+  const api = options.api ?? new VibeInfraApi({ baseUrl: options.baseUrl, apiKey });
 
   const server = new McpServer(
-    { name: SERVER_NAME, title: "VibeInfra Catalog", version: SERVER_VERSION },
+    { name: SERVER_NAME, title: "VibeInfra Platform", version: SERVER_VERSION },
     {
       instructions:
-        "VibeInfra is a learn-by-doing infrastructure engineering platform: engineers " +
+        "VibeInfra is an incident-readiness platform for infrastructure engineers: engineers " +
         "troubleshoot realistic production incidents (Linux kernel, Docker, Kubernetes, Nginx, " +
-        "PostgreSQL, Kafka, AWS) in live disposable sandboxes with automated grading. Use these " +
-        "tools to find an incident that matches what someone wants to learn, to read its " +
-        "blueprint, and to check whether the platform has capacity right now. Every tool is " +
-        "read-only and needs no credentials.",
+        "PostgreSQL, Kafka, AWS) in live disposable sandboxes with automated grading. " +
+        "Use these tools to discover incidents, start live incident drills (start_drill), " +
+        "coach learners with progressive hints without spoilers (get_drill_hint), " +
+        "inspect live telemetry/topology (get_drill_status), and grade fixes against the live " +
+        "system state (grade_drill).",
     },
   );
 

package/src/tools.js

@@ -185,6 +185,174 @@ export const tools = [
       return jsonContent({ term, count: matches.length, entries: matches });
     },
   },
+  {
+    name: "start_drill",
+    config: {
+      title: "Start an SRE incident drill",
+      description:
+        "Provision and launch a live disposable sandbox for an SRE incident simulation. " +
+        "Returns the active session_id, web terminal URL, objectives, and scenario briefing. " +
+        "When finished, evaluate your fix with grade_drill.",
+      inputSchema: {
+        course_id: z
+          .string()
+          .describe("Catalog ID of the incident simulation, e.g. 'incident-40-deployment-never-rolled-out'."),
+        force_fresh: z
+          .boolean()
+          .optional()
+          .describe("If true, terminates any existing sandbox and boots a fresh container."),
+      },
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+    async handler(api, { course_id: courseId, force_fresh: forceFresh } = {}) {
+      const result = await api.startLab(courseId, forceFresh);
+      let blueprint = null;
+      try {
+        blueprint = await api.getCourse(courseId);
+      } catch {
+        // Blueprint fetch is best-effort enrichment
+      }
+
+      return jsonContent({
+        status: result.status ?? "success",
+        session_id: result.session_id || result.SessionID,
+        course_id: courseId,
+        title: blueprint?.title ?? courseId,
+        difficulty: blueprint?.difficulty,
+        tasks: blueprint?.tasks ?? [],
+        web_terminal_url: `https://vibeinfra.id/labs/overview/?course=${encodeURIComponent(courseId)}&session=${encodeURIComponent(result.session_id || result.SessionID || "")}`,
+        message: result.message ?? "Ephemeral incident sandbox provisioned successfully.",
+      });
+    },
+  },
+  {
+    name: "get_drill_hint",
+    config: {
+      title: "Get progressive hint for active drill",
+      description:
+        "Fetch spoiler-free progressive guidance for an active incident session. " +
+        "Provides diagnostic nudges without revealing the direct solution.",
+      inputSchema: {
+        session_id: z.string().describe("Active session ID returned by start_drill."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    async handler(api, { session_id: sessionId } = {}) {
+      const hintResult = await api.getHint(sessionId);
+      return jsonContent(hintResult);
+    },
+  },
+  {
+    name: "grade_drill",
+    config: {
+      title: "Grade and evaluate an incident drill fix",
+      description:
+        "Run automated system-state evaluation against the live sandbox to verify if the " +
+        "incident has been resolved. Inspects kernel sockets, container states, and ingress health. " +
+        "Returns pass/fail status, completed steps, and earned XP.",
+      inputSchema: {
+        session_id: z.string().describe("Active session ID returned by start_drill."),
+        course_id: z.string().describe("Catalog ID of the incident, e.g. 'incident-40-deployment-never-rolled-out'."),
+      },
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+    async handler(api, { session_id: sessionId, course_id: courseId } = {}) {
+      const evalResult = await api.checkLab(sessionId, courseId);
+      return jsonContent({
+        passed: evalResult.passed ?? evalResult.Passed ?? false,
+        status: evalResult.status ?? (evalResult.passed ? "passed" : "failed"),
+        message: evalResult.message ?? evalResult.Message ?? "",
+        steps_completed: evalResult.steps_completed ?? evalResult.StepsCompleted ?? 0,
+        steps_total: evalResult.steps_total ?? evalResult.StepsTotal ?? 0,
+        score_xp: evalResult.score_xp ?? evalResult.ScoreXP ?? 0,
+        completion_time_sec: evalResult.completion_time_sec ?? evalResult.CompletionTimeSec ?? 0,
+      });
+    },
+  },
+  {
+    name: "get_drill_status",
+    config: {
+      title: "Get live drill telemetry and topology status",
+      description:
+        "Inspect real-time telemetry, node health statuses, and network topology for an active drill session.",
+      inputSchema: {
+        session_id: z.string().describe("Active session ID returned by start_drill."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    async handler(api, { session_id: sessionId } = {}) {
+      let telemetry = null;
+      let topology = null;
+      try {
+        telemetry = await api.getLabTelemetry(sessionId);
+      } catch {
+        // Best effort
+      }
+      try {
+        topology = await api.getLabTopology(sessionId);
+      } catch {
+        // Best effort
+      }
+      return jsonContent({
+        session_id: sessionId,
+        telemetry,
+        topology,
+      });
+    },
+  },
+  {
+    name: "stop_drill",
+    config: {
+      title: "Stop and destroy an incident sandbox",
+      description:
+        "Permanently terminates and tears down the disposable sandbox container for a completed or aborted session.",
+      inputSchema: {
+        session_id: z.string().describe("Active session ID to terminate."),
+      },
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+    async handler(api, { session_id: sessionId } = {}) {
+      const destroyResult = await api.destroyLab(sessionId);
+      return jsonContent({
+        session_id: sessionId,
+        status: destroyResult?.status ?? "destroyed",
+        message: destroyResult?.message ?? "Sandbox destroyed successfully.",
+      });
+    },
+  },
+  {
+    name: "exec_in_sandbox",
+    config: {
+      title: "Execute shell command inside incident sandbox",
+      description:
+        "Run an arbitrary diagnostic, triage, or remediation command directly inside the live container sandbox. " +
+        "Returns stdout, stderr, and exit_code. Enables headless incident troubleshooting without opening a browser.",
+      inputSchema: {
+        session_id: z.string().describe("Active session ID returned by start_drill."),
+        command: z
+          .string()
+          .describe("Shell command to execute, e.g. 'kubectl get pods -A', 'df -h', 'systemctl status nginx'."),
+        timeout_sec: z
+          .number()
+          .optional()
+          .describe("Command execution timeout in seconds (default 15, max 30)."),
+      },
+      annotations: { readOnlyHint: false, openWorldHint: true },
+    },
+    async handler(api, { session_id: sessionId, command, timeout_sec: timeoutSec } = {}) {
+      const result = await api.execInSandbox(sessionId, command, timeoutSec);
+      return jsonContent({
+        session_id: sessionId,
+        command,
+        exit_code: result.exit_code ?? 0,
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        status: result.status ?? (result.exit_code === 0 ? "success" : "failed"),
+        error: result.error,
+      });
+    },
+  },
 ];
 
 export { filterCourses, summarise };
+