@vibeinfra/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VibeInfra
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# @vibeinfra/mcp-server
+
+Model Context Protocol server for [VibeInfra](https://vibeinfra.id) — lets an AI agent browse
+the SRE incident catalog, read one incident's full blueprint, check live sandbox capacity and
+look up infrastructure terminology.
+
+Every tool is **read-only** and **unauthenticated**: the VibeInfra catalog is public by design,
+so an agent can explore it with no credentials and no side effects.
+
+## Use it
+
+No install step — run it straight from npm:
+
+```bash
+npx -y @vibeinfra/mcp-server
+```
+
+### Claude Code
+
+```bash
+claude mcp add vibeinfra -- npx -y @vibeinfra/mcp-server
+```
+
+### Claude Desktop, or any client with a JSON config
+
+```json
+{
+  "mcpServers": {
+    "vibeinfra": {
+      "command": "npx",
+      "args": ["-y", "@vibeinfra/mcp-server"]
+    }
+  }
+}
+```
+
+The server speaks stdio and requires Node 18+.
+
+## Tools
+
+| Tool                         | What it does                                                                 |
+| ---------------------------- | ---------------------------------------------------------------------------- |
+| `list_incidents`             | Every incident and course in the catalog, with tier, stack, duration and link. |
+| `search_incidents`           | Free-text search plus filters for difficulty, category, domain, tech, free-only. |
+| `get_incident`               | One full blueprint by catalog ID, including objectives and chapters.           |
+| `get_platform_capacity`      | Live sandbox usage and queue length.                                           |
+| `lookup_infrastructure_term` | The VibeInfra infrastructure/SRE glossary.                                     |
+
+## Configuration
+
+| Environment variable     | Default                    | Purpose                              |
+| ------------------------ | -------------------------- | ------------------------------------ |
+| `VIBEINFRA_API_BASE_URL` | `https://api.vibeinfra.id` | Point the server at a local backend. |
+
+## Try it
+
+Ask your agent:
+
+> Find me an expert-tier Kafka incident on VibeInfra and summarise what it teaches.
+
+> Is VibeInfra busy right now, or can I start a lab straight away?
+
+## Related
+
+- Server card — <https://vibeinfra.id/.well-known/mcp.json>
+- Docs — <https://vibeinfra.id/docs/mcp/>
+- REST API and OpenAPI description — <https://vibeinfra.id/openapi.json>
+- JavaScript SDK (`@vibeinfra/sdk`) and Python SDK (`vibeinfra`) — <https://vibeinfra.id/developers/>
+
+## Development
+
+```bash
+npm install
+npm test
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,54 @@
+{
+  "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.",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "mcp-server",
+    "vibeinfra",
+    "sre",
+    "incident-response",
+    "infrastructure",
+    "devops",
+    "kubernetes"
+  ],
+  "homepage": "https://vibeinfra.id/docs/mcp/",
+  "bugs": {
+    "url": "https://github.com/ridwansswnto/vibeinfraid/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ridwansswnto/vibeinfraid.git",
+    "directory": "packages/mcp-server"
+  },
+  "license": "MIT",
+  "author": "VibeInfra",
+  "type": "module",
+  "main": "./src/server.js",
+  "bin": {
+    "vibeinfra-mcp": "src/cli.js",
+    "mcp-server": "src/cli.js"
+  },
+  "files": [
+    "src",
+    "server.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "start": "node src/cli.js",
+    "test": "node --test test/*.test.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^3.25.76"
+  },
+  "mcpName": "id.vibeinfra/catalog",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/server.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "id.vibeinfra/catalog",
+  "title": "VibeInfra Catalog",
+  "description": "Browse the VibeInfra SRE incident catalog, live sandbox capacity and infrastructure glossary.",
+  "websiteUrl": "https://vibeinfra.id/docs/mcp/",
+  "repository": {
+    "url": "https://github.com/ridwansswnto/vibeinfraid",
+    "source": "github",
+    "subfolder": "packages/mcp-server"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@vibeinfra/mcp-server",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "VIBEINFRA_API_BASE_URL",
+          "description": "Override the API origin. Defaults to https://api.vibeinfra.id; set this only to point the server at a local backend.",
+          "isRequired": false,
+          "isSecret": false,
+          "default": "https://api.vibeinfra.id"
+        }
+      ]
+    }
+  ]
+}

package/src/api.js

@@ -0,0 +1,76 @@
+/**
+ * A minimal client for the public VibeInfra API.
+ *
+ * This duplicates a slice of `@vibeinfra/sdk` on purpose: the MCP server is meant to be run
+ * with `npx -y @vibeinfra/mcp-server`, and every extra runtime dependency is another package
+ * an agent host has to resolve before the server can answer its first tool call.
+ */
+
+export const DEFAULT_BASE_URL = "https://api.vibeinfra.id";
+
+const API_VERSION = "v1";
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+/** The API answered with a non-2xx status. */
+export class ApiError extends Error {
+  constructor(status, url, message) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.url = url;
+  }
+}
+
+export class VibeInfraApi {
+  constructor({ baseUrl = DEFAULT_BASE_URL, timeoutMs = DEFAULT_TIMEOUT_MS, fetch: fetchImpl } = {}) {
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.timeoutMs = timeoutMs;
+    this.fetch = fetchImpl ?? globalThis.fetch;
+  }
+
+  async get(path, query) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value !== undefined && value !== null && value !== "") params.set(key, String(value));
+    }
+    const search = params.toString();
+    const url = `${this.baseUrl}/api/${API_VERSION}${path}${search ? `?${search}` : ""}`;
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    let response;
+    try {
+      response = await this.fetch(url, {
+        headers: { Accept: "application/json" },
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (!response.ok) {
+      throw new ApiError(response.status, url, `GET ${url} failed with ${response.status}`);
+    }
+    return response.json();
+  }
+
+  listCourses(locale) {
+    return this.get("/courses", { locale });
+  }
+
+  getCourse(courseId, locale) {
+    return this.get(`/courses/${encodeURIComponent(courseId)}`, { locale });
+  }
+
+  getGlossary(lang) {
+    return this.get("/glossary", { lang });
+  }
+
+  getCapacity() {
+    return this.get("/labs/capacity");
+  }
+
+  getLeaderboard() {
+    return this.get("/labs/leaderboard");
+  }
+}

package/src/cli.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * stdio entrypoint: `npx -y @vibeinfra/mcp-server`.
+ *
+ * Nothing is written to stdout except the protocol itself -- stdout is the transport, so a
+ * stray log line corrupts the stream. Diagnostics go to stderr.
+ */
+
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+import { createServer } from "./server.js";
+
+const server = createServer({ baseUrl: process.env.VIBEINFRA_API_BASE_URL });
+
+await server.connect(new StdioServerTransport());

package/src/server.js

@@ -0,0 +1,54 @@
+/**
+ * Builds the VibeInfra MCP server.
+ *
+ * Kept separate from `cli.js` so the server can be constructed and connected to an in-memory
+ * transport in tests, without a child process or a stdio pipe.
+ */
+
+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";
+
+/**
+ * @param {object} [options]
+ * @param {string} [options.baseUrl] API origin. Defaults to production.
+ * @param {VibeInfraApi} [options.api] Pre-built API client, for tests.
+ */
+export function createServer(options = {}) {
+  const api = options.api ?? new VibeInfraApi({ baseUrl: options.baseUrl });
+
+  const server = new McpServer(
+    { name: SERVER_NAME, title: "VibeInfra Catalog", version: SERVER_VERSION },
+    {
+      instructions:
+        "VibeInfra is a learn-by-doing infrastructure engineering platform: 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.",
+    },
+  );
+
+  for (const tool of tools) {
+    // Errors are reported as tool results rather than thrown: a transport-level failure would
+    // end the client's turn, where an isError result lets the model see what went wrong (a
+    // typo'd course ID, the API being down) and try something else.
+    server.registerTool(tool.name, tool.config, async (args) => {
+      try {
+        return await tool.handler(api, args);
+      } catch (error) {
+        return {
+          isError: true,
+          content: [{ type: "text", text: `${tool.name} failed: ${error.message}` }],
+        };
+      }
+    });
+  }
+
+  return server;
+}

package/src/tools.js

@@ -0,0 +1,190 @@
+/**
+ * The tools this MCP server exposes, defined independently of the transport.
+ *
+ * Each entry is a plain object with a name, a config and a handler taking `(api, args)`. That
+ * shape keeps the tools testable without standing up a stdio server, and keeps `server.js`
+ * down to wiring.
+ *
+ * Every tool is read-only and unauthenticated. The VibeInfra catalog is public by design --
+ * it is the platform's index -- so an agent can explore it with no credentials and no side
+ * effects, which is why each tool is annotated `readOnlyHint`.
+ */
+
+import { z } from "zod";
+
+const DIFFICULTIES = ["Beginner", "Intermediate", "Advanced", "Expert"];
+
+/** Render a value as the JSON text content MCP clients expect. */
+function jsonContent(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+
+/** The fields worth showing in a list. The full blueprint is a `get_incident` call away. */
+function summarise(course) {
+  return {
+    id: course.id,
+    title: course.title,
+    type: course.type,
+    category: course.category,
+    domain: course.domain,
+    difficulty: course.difficulty,
+    duration_minutes: course.duration_minutes,
+    xp_reward: course.xp_reward,
+    tech_stack: course.tech_stack,
+    status: course.status,
+    is_free: course.is_free,
+    description: course.description,
+    url: `https://vibeinfra.id/labs/overview/?course=${encodeURIComponent(course.id)}`,
+  };
+}
+
+/** Lower-cased searchable text for one course. */
+function haystack(course) {
+  return [course.title, course.description, course.category, course.domain]
+    .concat(course.tech_stack ?? [])
+    .filter(Boolean)
+    .join(" ")
+    .toLowerCase();
+}
+
+/** Apply the `search_incidents` filters. Shared with `list_incidents`, which is the no-query case. */
+function filterCourses(courses, { query, difficulty, category, domain, tech, freeOnly } = {}) {
+  const needle = query?.trim().toLowerCase();
+  return courses.filter((course) => {
+    if (difficulty && course.difficulty !== difficulty) return false;
+    if (category && course.category?.toLowerCase() !== category.toLowerCase()) return false;
+    if (domain && course.domain?.toLowerCase() !== domain.toLowerCase()) return false;
+    if (freeOnly && !course.is_free) return false;
+    if (tech && !(course.tech_stack ?? []).some((t) => t.toLowerCase() === tech.toLowerCase())) {
+      return false;
+    }
+    return !needle || haystack(course).includes(needle);
+  });
+}
+
+export const tools = [
+  {
+    name: "list_incidents",
+    config: {
+      title: "List VibeInfra incidents",
+      description:
+        "List every incident simulation and course in the VibeInfra catalog. Each entry includes " +
+        "its difficulty tier, tech stack, expected duration and a link to its landing page. Use " +
+        "this to see what is available; use search_incidents to narrow by topic.",
+      inputSchema: {
+        locale: z
+          .string()
+          .optional()
+          .describe("BCP 47 language tag, e.g. 'id'. Untranslated courses fall back to English."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    async handler(api, { locale } = {}) {
+      const courses = await api.listCourses(locale);
+      return jsonContent({ count: courses.length, incidents: courses.map(summarise) });
+    },
+  },
+  {
+    name: "search_incidents",
+    config: {
+      title: "Search VibeInfra incidents",
+      description:
+        "Find incident simulations by free-text query and/or by difficulty, category, domain, " +
+        "tech stack or free-to-run status. The query matches the title, description, category " +
+        "and tech stack. Returns the same summary shape as list_incidents.",
+      inputSchema: {
+        query: z
+          .string()
+          .optional()
+          .describe("Free text, e.g. 'kafka consumer lag' or 'certificate expiry'."),
+        difficulty: z.enum(DIFFICULTIES).optional().describe("Exact difficulty tier."),
+        category: z.string().optional().describe("Catalog category, e.g. 'Kubernetes'."),
+        domain: z.string().optional().describe("Skill-ladder domain, e.g. 'Observability'."),
+        tech: z.string().optional().describe("A single tech-stack entry, e.g. 'PostgreSQL'."),
+        free_only: z.boolean().optional().describe("Only incidents that are free to run."),
+        locale: z.string().optional().describe("BCP 47 language tag."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    async handler(api, args = {}) {
+      const courses = await api.listCourses(args.locale);
+      const matches = filterCourses(courses, { ...args, freeOnly: args.free_only });
+      return jsonContent({
+        count: matches.length,
+        searched: courses.length,
+        incidents: matches.map(summarise),
+      });
+    },
+  },
+  {
+    name: "get_incident",
+    config: {
+      title: "Get one VibeInfra incident",
+      description:
+        "Fetch the full blueprint for one incident by catalog ID (for example " +
+        "'incident-22-k8s-crashloop'), including its learning objectives, chapters where the " +
+        "course is step-graded, tech stack and access tier. IDs come from list_incidents.",
+      inputSchema: {
+        course_id: z.string().describe("Catalog ID, e.g. 'incident-36-kafka-consumer-lag'."),
+        locale: z.string().optional().describe("BCP 47 language tag."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    async handler(api, { course_id: courseId, locale } = {}) {
+      const course = await api.getCourse(courseId, locale);
+      return jsonContent({
+        ...course,
+        url: `https://vibeinfra.id/labs/overview/?course=${encodeURIComponent(courseId)}`,
+      });
+    },
+  },
+  {
+    name: "get_platform_capacity",
+    config: {
+      title: "Get live sandbox capacity",
+      description:
+        "Read how much VibeInfra sandbox capacity is in use right now and how many learners are " +
+        "queued. Worth checking before telling a user to start a lab: when the queue is long, " +
+        "a start request is queued rather than provisioned immediately.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    async handler(api) {
+      return jsonContent(await api.getCapacity());
+    },
+  },
+  {
+    name: "lookup_infrastructure_term",
+    config: {
+      title: "Look up an infrastructure term",
+      description:
+        "Look up infrastructure and SRE terminology in the VibeInfra glossary — the same " +
+        "definitions used across the incident catalog. Omit the term to return the whole glossary.",
+      inputSchema: {
+        term: z
+          .string()
+          .optional()
+          .describe("Term to look up. Matched case-insensitively against labels and IDs."),
+        lang: z.string().optional().describe("Language code, e.g. 'id'."),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    async handler(api, { term, lang } = {}) {
+      const entries = await api.getGlossary(lang);
+      if (!term) return jsonContent({ count: entries.length, entries });
+      const needle = term.trim().toLowerCase();
+      const exact = entries.filter(
+        (e) => e.label?.toLowerCase() === needle || e.id?.toLowerCase() === needle,
+      );
+      const matches = exact.length
+        ? exact
+        : entries.filter(
+            (e) =>
+              e.label?.toLowerCase().includes(needle) || e.id?.toLowerCase().includes(needle),
+          );
+      return jsonContent({ term, count: matches.length, entries: matches });
+    },
+  },
+];
+
+export { filterCourses, summarise };