@andinolabs/nebula-mcp 1.0.0

package/README.md

@@ -0,0 +1,134 @@
+# nebula-mcp
+
+MCP server for the **Nebula Control Plane API**. Install via npm — no clone or local build required.
+
+## Quick start
+
+Add one entry to your MCP config (Claude Desktop, Claude Code `.mcp.json`, or Cursor):
+
+```json
+{
+  "mcpServers": {
+    "nebula": {
+      "command": "npx",
+      "args": ["-y", "@andinolabs/nebula-mcp"],
+      "env": {
+        "NEBULA_API_URL": "https://admin.nebula.andinolabs.ai"
+      }
+    }
+  }
+}
+```
+
+`npx -y` fetches and caches the package on first use.
+
+Or via Claude Code CLI:
+
+```bash
+claude mcp add nebula -- npx -y @andinolabs/nebula-mcp
+```
+
+Set `NEBULA_API_URL` in the environment when adding if your control plane URL differs.
+
+## Environment variables
+
+| Var | Default | Description |
+|---|---|---|
+| `NEBULA_API_URL` | `http://localhost:8080` | Nebula Control Plane base URL |
+| `NEBULA_API_TOKEN` | _(empty)_ | Bearer token for headless/CI (optional) |
+
+## Authentication
+
+### Interactive login (default)
+
+When `NEBULA_API_TOKEN` is not set, the server opens your browser to complete an
+OAuth 2.0 + PKCE login on the first request. Tokens are persisted to
+`~/.config/nebula/tokens.json` and refreshed automatically. The browser only
+re-opens when the refresh token expires (~30–90 days).
+
+### Headless / CI
+
+Set `NEBULA_API_TOKEN` to a long-lived API key. This bypasses the browser flow
+entirely and no token file is read or written.
+
+## Tools exposed
+
+| Tool | Domain |
+|---|---|
+| `login` | Auth |
+| `health_check` | Health |
+| `list_apps` / `get_app` | Platform apps |
+| `list_clusters` / `get_cluster` | Platform clusters |
+| `list_tenants` / `get_tenant` / `create_tenant` | Catalog – Tenants |
+| `get_tenant_github_status` / `list_tenant_github_repos` | Catalog – GitHub |
+| `get_tenant_jira_status` / `list_tenant_jira_projects` | Catalog – Jira |
+| `list_environments` / `get_environment` | Catalog – Environments |
+| `list_applications` / `get_application` | Catalog – Applications |
+| `list_application_jira_issues` | Catalog – Jira Issues |
+| `list_cd_clusters` / `get_cd_cluster` | CD – Clusters |
+| `list_cd_pipelines` / `get_cd_pipeline` | CD – Pipelines |
+| `list_cloud_providers` | Cloud – Providers |
+| `list_cloud_resources` / `provision_cloud_resource` / `preview_terraform` | Cloud – Resources |
+| `list_capture_topics` / `get_capture_topic` | Capture – Topics |
+| `list_capture_sessions` / `get_capture_session_summary` | Capture – Sessions |
+
+## Development
+
+For contributors working from this repository:
+
+```bash
+pnpm install
+pnpm run build
+```
+
+Register a local build in MCP config:
+
+```json
+{
+  "mcpServers": {
+    "nebula": {
+      "command": "node",
+      "args": ["/absolute/path/to/claude-mcp/dist/index.js"],
+      "env": {
+        "NEBULA_API_URL": "http://localhost:8080"
+      }
+    }
+  }
+}
+```
+
+Hot-reload during development:
+
+```bash
+NEBULA_API_URL=http://localhost:8080 pnpm run dev
+```
+
+## Publishing
+
+Published to the public npm registry under **@andinolabs** (`@andinolabs/nebula-mcp`).
+
+Publishing uses an **npm access token** only — no interactive login or 2FA OTP at publish time.
+
+### Create a publish token (one-time)
+
+1. Join the [andinolabs](https://www.npmjs.com/org/andinolabs) org on npm with publish permission.
+2. Open [Access Tokens](https://www.npmjs.com/settings/~/tokens) → **Generate New Token** → **Granular Access Token**.
+3. Configure:
+   - **Organizations:** `andinolabs` — **Read and write**
+   - **Packages:** `@andinolabs/nebula-mcp` (or all org packages)
+   - **Expiration:** per your security policy
+   - **Bypass 2FA for automation:** enabled (required for non-interactive publish)
+4. Copy the token (`npm_…`) — it is shown only once.
+
+Store the token in your password manager or CI secret `NPM_TOKEN`. Never commit it.
+
+### Publish locally
+
+```bash
+export NPM_TOKEN=npm_xxxxxxxx
+just publish
+```
+
+### CI
+
+Set the same granular token as the `NPM_TOKEN` repository/organization secret; the publish recipe writes a temporary `.npmrc` and removes it on exit.

package/dist/index.js

@@ -0,0 +1,515 @@
+#!/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 { createHash, randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { execFile } from "node:child_process";
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+const BASE_URL = process.env.NEBULA_API_URL ?? "http://localhost:8080";
+const API_TOKEN = process.env.NEBULA_API_TOKEN ?? "";
+const TOKEN_FILE = join(homedir(), ".config", "nebula", "tokens.json");
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+let cachedTokens = null;
+// ---------------------------------------------------------------------------
+// PKCE helpers
+// ---------------------------------------------------------------------------
+function generateCodeVerifier() {
+    return randomBytes(32).toString("base64url");
+}
+function codeChallenge(verifier) {
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+// ---------------------------------------------------------------------------
+// Token persistence
+// ---------------------------------------------------------------------------
+async function loadTokens() {
+    try {
+        const raw = await readFile(TOKEN_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+async function saveTokens(tokens) {
+    await mkdir(join(homedir(), ".config", "nebula"), { recursive: true });
+    await writeFile(TOKEN_FILE, JSON.stringify(tokens, null, 2), "utf-8");
+    cachedTokens = tokens;
+}
+// ---------------------------------------------------------------------------
+// Token refresh
+// ---------------------------------------------------------------------------
+async function refreshAccessToken(refreshToken) {
+    const res = await fetch(`${BASE_URL}/v1/auth/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ grant_type: "refresh_token", refresh_token: refreshToken }),
+    });
+    if (!res.ok)
+        throw new Error(`Refresh failed: ${res.status}`);
+    const data = await res.json();
+    const tokens = {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token ?? refreshToken,
+        expires_at: data.expires_in
+            ? new Date(Date.now() + data.expires_in * 1000).toISOString()
+            : undefined,
+    };
+    await saveTokens(tokens);
+    return tokens;
+}
+// ---------------------------------------------------------------------------
+// Browser login (OAuth 2.0 + PKCE)
+// ---------------------------------------------------------------------------
+async function openBrowser(url) {
+    const [cmd, ...args] = process.platform === "darwin" ? ["open", url] :
+        process.platform === "win32" ? ["cmd", "/c", "start", "", url] :
+            ["xdg-open", url];
+    try {
+        await new Promise((resolve, reject) => execFile(cmd, args, (err) => (err ? reject(err) : resolve())));
+    }
+    catch {
+        // Non-fatal: URL is printed to stderr for manual visit
+    }
+}
+function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+/** Loopback OAuth callback page styled like the Control Plane login screen. */
+function oauthCallbackHtml(message, isError) {
+    const safeMessage = escapeHtml(message);
+    const messageColor = isError ? "#fecaca" : "#cbd5e1";
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Nebula Control Plane</title>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body {
+      min-height: 100vh;
+      font-family: "Familjen Grotesk", system-ui, -apple-system, sans-serif;
+      background: #020617;
+      color: #e2e8f0;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 1.5rem;
+    }
+    .cosmos {
+      position: fixed;
+      inset: 0;
+      pointer-events: none;
+      background:
+        radial-gradient(ellipse 60% 50% at 80% 20%, rgba(99, 102, 241, 0.12), transparent 60%),
+        radial-gradient(ellipse 50% 40% at 15% 85%, rgba(59, 130, 246, 0.08), transparent 60%);
+    }
+    .card {
+      position: relative;
+      z-index: 1;
+      width: 100%;
+      max-width: 28rem;
+      padding: 2rem;
+      border-radius: 1rem;
+      border: 1px solid rgba(51, 65, 85, 0.8);
+      background: rgba(2, 6, 23, 0.8);
+      box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.5);
+      text-align: center;
+    }
+    h1 {
+      font-size: 1.25rem;
+      font-weight: 600;
+      letter-spacing: 0.025em;
+      color: #f1f5f9;
+      margin-bottom: 1rem;
+    }
+    p {
+      font-size: 0.875rem;
+      line-height: 1.625;
+      color: ${messageColor};
+    }
+  </style>
+</head>
+<body>
+  <div class="cosmos" aria-hidden="true"></div>
+  <div class="card">
+    <h1>Nebula Control Plane</h1>
+    <p role="${isError ? "alert" : "status"}">${safeMessage}</p>
+  </div>
+</body>
+</html>`;
+}
+async function browserLogin() {
+    const verifier = generateCodeVerifier();
+    const challenge = codeChallenge(verifier);
+    const state = randomBytes(16).toString("base64url");
+    // Start a local callback server and capture its port before building the auth URL
+    const { port, waitForCode } = await new Promise((resolveSetup) => {
+        let resolveCode;
+        let rejectCode;
+        const codePromise = new Promise((res, rej) => {
+            resolveCode = res;
+            rejectCode = rej;
+        });
+        const server = createServer((req, httpRes) => {
+            const parsed = new URL(req.url ?? "/", "http://localhost");
+            const code = parsed.searchParams.get("code");
+            const returnedState = parsed.searchParams.get("state");
+            const error = parsed.searchParams.get("error");
+            httpRes.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            if (code) {
+                if (returnedState !== state) {
+                    httpRes.end(oauthCallbackHtml("Authentication failed: state mismatch.", true));
+                    server.close();
+                    rejectCode(new Error("OAuth state mismatch"));
+                    return;
+                }
+                httpRes.end(oauthCallbackHtml("Authentication successful. You can close this tab.", false));
+                server.close();
+                resolveCode(code);
+            }
+            else {
+                httpRes.end(oauthCallbackHtml(`Authentication failed: ${error ?? "unknown"}.`, true));
+                server.close();
+                rejectCode(new Error(`OAuth error: ${error ?? "no code returned"}`));
+            }
+        });
+        server.listen(0, "localhost", () => {
+            const { port } = server.address();
+            resolveSetup({
+                port,
+                waitForCode: () => {
+                    const timeout = setTimeout(() => {
+                        server.close();
+                        rejectCode(new Error("Login timed out after 5 minutes"));
+                    }, LOGIN_TIMEOUT_MS);
+                    return codePromise.finally(() => clearTimeout(timeout));
+                },
+            });
+        });
+    });
+    const redirectUri = `http://localhost:${port}/callback`;
+    const authUrl = new URL(`${BASE_URL}/login`);
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("code_challenge", challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    authUrl.searchParams.set("state", state);
+    console.error(`\nOpening browser for Nebula authentication...`);
+    console.error(`If the browser does not open, visit:\n  ${authUrl.toString()}\n`);
+    await openBrowser(authUrl.toString());
+    const code = await waitForCode();
+    const res = await fetch(`${BASE_URL}/v1/auth/oauth/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            code_verifier: verifier,
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`Token exchange failed: ${res.status}`);
+    const data = await res.json();
+    const tokens = {
+        access_token: data.access_token,
+        refresh_token: data.refresh_token,
+        expires_at: data.expires_in
+            ? new Date(Date.now() + data.expires_in * 1000).toISOString()
+            : undefined,
+    };
+    await saveTokens(tokens);
+    console.error("Authentication successful.\n");
+    return tokens;
+}
+// ---------------------------------------------------------------------------
+// Token resolution
+// ---------------------------------------------------------------------------
+async function getAccessToken() {
+    // Static env token (CI / headless) — bypass file-based auth entirely
+    if (API_TOKEN)
+        return API_TOKEN;
+    if (!cachedTokens)
+        cachedTokens = await loadTokens();
+    // Return cached token if it's still valid (with 60s buffer before expiry)
+    if (cachedTokens?.access_token) {
+        if (!cachedTokens.expires_at)
+            return cachedTokens.access_token;
+        const expiresAt = new Date(cachedTokens.expires_at).getTime();
+        if (Date.now() < expiresAt - 60_000)
+            return cachedTokens.access_token;
+    }
+    // Try refresh before falling back to browser
+    if (cachedTokens?.refresh_token) {
+        try {
+            const refreshed = await refreshAccessToken(cachedTokens.refresh_token);
+            return refreshed.access_token;
+        }
+        catch {
+            console.error("Token refresh failed, opening browser for re-authentication...");
+        }
+    }
+    const tokens = await browserLogin();
+    return tokens.access_token;
+}
+// ---------------------------------------------------------------------------
+// HTTP helper
+// ---------------------------------------------------------------------------
+async function call(method, path, body) {
+    const makeRequest = async (token) => {
+        const headers = {
+            "Content-Type": "application/json",
+            Accept: "application/json",
+        };
+        if (token)
+            headers["Authorization"] = `Bearer ${token}`;
+        return fetch(`${BASE_URL}${path}`, {
+            method,
+            headers,
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+    };
+    const isHtmlResponse = (text) => {
+        const t = text.trimStart();
+        return t.startsWith("<!DOCTYPE") || t.startsWith("<html");
+    };
+    let res = await makeRequest(await getAccessToken());
+    // On 401, force browser re-auth (skip refresh — server already rejected the token) and retry once
+    if (res.status === 401 && !API_TOKEN) {
+        console.error("Session expired, re-authenticating...");
+        cachedTokens = null;
+        const tokens = await browserLogin();
+        res = await makeRequest(tokens.access_token);
+    }
+    const text = await res.text();
+    // The API returns the SPA's index.html (200) instead of 401 when the session expires.
+    // Treat HTML responses as auth failures and retry once with a fresh browser login.
+    if (isHtmlResponse(text) && !API_TOKEN) {
+        console.error("Received HTML response (likely auth redirect), re-authenticating...");
+        cachedTokens = null;
+        const tokens = await browserLogin();
+        const retryRes = await makeRequest(tokens.access_token);
+        const retryText = await retryRes.text();
+        if (isHtmlResponse(retryText)) {
+            throw new Error(`Nebula API ${method} ${path} → ${retryRes.status}: received HTML after re-auth (endpoint may not exist)`);
+        }
+        try {
+            return JSON.parse(retryText);
+        }
+        catch {
+            return retryText;
+        }
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        data = text;
+    }
+    if (!res.ok) {
+        throw new Error(`Nebula API ${method} ${path} → ${res.status}: ${JSON.stringify(data)}`);
+    }
+    return data;
+}
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+const server = new McpServer({
+    name: "nebula",
+    version: "1.0.0",
+    description: "MCP server for the Nebula Control Plane API",
+});
+// ── Auth ─────────────────────────────────────────────────────────────────────
+server.tool("login", "Authenticate with Nebula via browser-based OAuth login. Call this when you get a 401 error.", {}, async () => {
+    cachedTokens = null;
+    await browserLogin();
+    return { content: [{ type: "text", text: "Authentication successful. You can now call other Nebula tools." }] };
+});
+// ── Health ──────────────────────────────────────────────────────────────────
+server.tool("health_check", "Check if the Nebula API is alive", {}, async () => {
+    const data = await call("GET", "/healthz");
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── Platform / Apps ─────────────────────────────────────────────────────────
+server.tool("list_apps", "List all platform applications (ArgoCD/platform layer)", {}, async () => {
+    const data = await call("GET", "/v1/apps");
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_app", "Get a platform application by name", { name: z.string().describe("Application name") }, async ({ name }) => {
+    const data = await call("GET", `/v1/apps/${encodeURIComponent(name)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── Platform / Clusters ──────────────────────────────────────────────────────
+server.tool("list_clusters", "List all platform clusters (hub + spokes)", {}, async () => {
+    const data = await call("GET", "/v1/clusters");
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_cluster", "Get a platform cluster by name", { name: z.string().describe("Cluster name") }, async ({ name }) => {
+    const data = await call("GET", `/v1/clusters/${encodeURIComponent(name)}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── Catalog / Tenants ────────────────────────────────────────────────────────
+server.tool("list_tenants", "List all Nebula tenants (Miinsys, Serhafen, Busko…)", {}, async () => {
+    const data = await call("GET", "/v1/catalog/tenants");
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_tenant", "Get a tenant by UUID", { id: z.string().uuid().describe("Tenant UUID") }, async ({ id }) => {
+    const data = await call("GET", `/v1/catalog/tenants/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("create_tenant", "Create a new tenant in the Nebula catalog", {
+    name: z.string(),
+    slug: z.string().optional(),
+    cloud_provider: z.string().optional(),
+}, async (body) => {
+    const data = await call("POST", "/v1/catalog/tenants", body);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_tenant_github_status", "Check if a tenant has GitHub tokens configured", { id: z.string().uuid().describe("Tenant UUID") }, async ({ id }) => {
+    const data = await call("GET", `/v1/catalog/tenants/${id}/github`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("list_tenant_github_repos", "List GitHub repositories accessible to a tenant's token", { id: z.string().uuid().describe("Tenant UUID") }, async ({ id }) => {
+    const data = await call("GET", `/v1/catalog/tenants/${id}/github/repositories`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_tenant_jira_status", "Check if a tenant has Jira credentials configured", { id: z.string().uuid().describe("Tenant UUID") }, async ({ id }) => {
+    const data = await call("GET", `/v1/catalog/tenants/${id}/jira`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("list_tenant_jira_projects", "List Jira projects accessible to a tenant", { id: z.string().uuid().describe("Tenant UUID") }, async ({ id }) => {
+    const data = await call("GET", `/v1/catalog/tenants/${id}/jira/projects`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── Catalog / Environments ───────────────────────────────────────────────────
+server.tool("list_environments", "List environments for a tenant", { tenantId: z.string().uuid().describe("Tenant UUID") }, async ({ tenantId }) => {
+    const data = await call("GET", `/v1/catalog/tenants/${tenantId}/environments`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_environment", "Get a specific environment", {
+    tenantId: z.string().uuid(),
+    id: z.string().uuid().describe("Environment UUID"),
+}, async ({ tenantId, id }) => {
+    const data = await call("GET", `/v1/catalog/tenants/${tenantId}/environments/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── Catalog / Applications ───────────────────────────────────────────────────
+server.tool("list_applications", "List catalog applications (optionally filter by tenant)", {
+    tenant_id: z.string().uuid().optional().describe("Filter by tenant UUID"),
+    include_shared: z.boolean().optional().default(false),
+    include_archived: z.boolean().optional().default(false),
+}, async ({ tenant_id, include_shared, include_archived }) => {
+    const params = new URLSearchParams();
+    if (tenant_id)
+        params.set("tenant_id", tenant_id);
+    if (include_shared)
+        params.set("include_shared", "true");
+    if (include_archived)
+        params.set("include_archived", "true");
+    const qs = params.toString();
+    const data = await call("GET", `/v1/catalog/applications${qs ? `?${qs}` : ""}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_application", "Get a catalog application by UUID", { id: z.string().uuid() }, async ({ id }) => {
+    const data = await call("GET", `/v1/catalog/applications/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("list_application_jira_issues", "List Jira issues bound to a catalog application", {
+    id: z.string().uuid().describe("Application UUID"),
+    q: z.string().optional().describe("Search query"),
+}, async ({ id, q }) => {
+    const qs = q ? `?q=${encodeURIComponent(q)}` : "";
+    const data = await call("GET", `/v1/catalog/applications/${id}/jira/issues${qs}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── CD / Clusters ────────────────────────────────────────────────────────────
+server.tool("list_cd_clusters", "List CD clusters for a tenant (ArgoCD destinations)", { tenantId: z.string().uuid() }, async ({ tenantId }) => {
+    const data = await call("GET", `/v1/cd/tenants/${tenantId}/clusters`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_cd_cluster", "Get a CD cluster by id", { tenantId: z.string().uuid(), id: z.string().uuid() }, async ({ tenantId, id }) => {
+    const data = await call("GET", `/v1/cd/tenants/${tenantId}/clusters/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── CD / Pipelines ───────────────────────────────────────────────────────────
+server.tool("list_cd_pipelines", "List CD pipelines for a tenant", { tenantId: z.string().uuid() }, async ({ tenantId }) => {
+    const data = await call("GET", `/v1/cd/tenants/${tenantId}/pipelines`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_cd_pipeline", "Get a CD pipeline by id", { tenantId: z.string().uuid(), id: z.string().uuid() }, async ({ tenantId, id }) => {
+    const data = await call("GET", `/v1/cd/tenants/${tenantId}/pipelines/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── Cloud / Providers ────────────────────────────────────────────────────────
+server.tool("list_cloud_providers", "List cloud provider connections for a tenant (Azure, GCP, AWS)", { id: z.string().uuid().describe("Tenant UUID") }, async ({ id }) => {
+    const data = await call("GET", `/v1/cloud/tenants/${id}/cloud-providers`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── Cloud / Resources ────────────────────────────────────────────────────────
+server.tool("list_cloud_resources", "List cloud resources (AKS, GKE, Postgres, ECR…) for a tenant", {
+    tenantId: z.string().uuid(),
+    provider_id: z.string().uuid().optional(),
+    kind: z.string().optional().describe("e.g. container_registry, postgres_database, gcp_gke"),
+}, async ({ tenantId, provider_id, kind }) => {
+    const params = new URLSearchParams();
+    if (provider_id)
+        params.set("provider_id", provider_id);
+    if (kind)
+        params.set("kind", kind);
+    const qs = params.toString();
+    const data = await call("GET", `/v1/cloud/tenants/${tenantId}/resources${qs ? `?${qs}` : ""}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("provision_cloud_resource", "Trigger Terraform provisioning for pending cloud resources (fires Argo Workflow)", { tenantId: z.string().uuid() }, async ({ tenantId }) => {
+    const data = await call("POST", `/v1/cloud/tenants/${tenantId}/resources/terraform-provision`, {});
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("preview_terraform", "Preview generated Terraform for all pending cloud resources for a tenant", { tenantId: z.string().uuid() }, async ({ tenantId }) => {
+    const data = await call("GET", `/v1/cloud/tenants/${tenantId}/resources/terraform-preview`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ── Capture / Topics ─────────────────────────────────────────────────────────
+server.tool("list_capture_topics", "List Capture topics for a tenant (Discovery stakeholder interview topics)", { tenantId: z.string().uuid() }, async ({ tenantId }) => {
+    const data = await call("GET", `/v1/capture/tenants/${tenantId}/topics`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_capture_topic", "Get a Capture topic and its sessions", { tenantId: z.string().uuid(), id: z.string().uuid() }, async ({ tenantId, id }) => {
+    const data = await call("GET", `/v1/capture/tenants/${tenantId}/topics/${id}`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("list_capture_sessions", "List Capture sessions for a topic", { tenantId: z.string().uuid(), topicId: z.string().uuid() }, async ({ tenantId, topicId }) => {
+    const data = await call("GET", `/v1/capture/tenants/${tenantId}/topics/${topicId}/sessions`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+server.tool("get_capture_session_summary", "Get the AI-generated summary of a Capture session", {
+    tenantId: z.string().uuid(),
+    topicId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+}, async ({ tenantId, topicId, sessionId }) => {
+    const data = await call("GET", `/v1/capture/tenants/${tenantId}/topics/${topicId}/sessions/${sessionId}/summary`);
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+});
+// ---------------------------------------------------------------------------
+// Bootstrap
+// ---------------------------------------------------------------------------
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Nebula MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@andinolabs/nebula-mcp",
+  "version": "1.0.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "MCP server for the Nebula Control Plane API",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": { "nebula-mcp": "dist/index.js" },
+  "files": ["dist/"],
+  "engines": { "node": ">=18" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/andinolabs-tech/ai-agent-army"
+  },
+  "license": "MIT",
+  "keywords": ["mcp", "nebula", "claude"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "pnpm run build",
+    "dev": "tsx index.ts",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.0"
+  }
+}