@nullplatform/mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { createMcpHttpHandler, hardenServerTimeouts } from "./http.js";
+import { resolveLocale, setDefaultLocale } from "./i18n.js";
+import { buildDeps, buildServer } from "./server.js";
+import { selectSurface } from "./surfaces/index.js";
+// Minimal .env loader (dev convenience; real installs pass env via the MCP client config).
+function loadDotEnv() {
+    try {
+        for (const line of readFileSync(".env", "utf8").split("\n")) {
+            const entry = /^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/.exec(line);
+            const key = entry?.[1];
+            if (key && entry[2] !== undefined && !(key in process.env)) {
+                process.env[key] = entry[2].replace(/^["']|["']$/g, "");
+            }
+        }
+    }
+    catch {
+        /* no .env — fine */
+    }
+}
+async function main() {
+    loadDotEnv();
+    // stdio speaks the operator's language; HTTP resolves Accept-Language per request.
+    setDefaultLocale(resolveLocale(process.env.NP_LANG ?? process.env.LANG));
+    // Which audience this process serves; a sibling package would default NP_SURFACE differently.
+    const surface = selectSurface(process.env.NP_SURFACE);
+    const httpFlag = process.argv.indexOf("--http");
+    if (httpFlag !== -1) {
+        const portArg = process.argv[httpFlag + 1];
+        const port = portArg && /^\d+$/.test(portArg) ? Number(portArg) : 3000;
+        // Multi-user: refuses to start with credentials in the environment — callers bring their own.
+        const config = loadConfig(process.env, "forbid");
+        const allowedOrigins = (process.env.NP_ALLOWED_ORIGINS ?? "")
+            .split(",")
+            .map((origin) => origin.trim())
+            .filter(Boolean);
+        const rateLimitEnv = process.env.NP_RATE_LIMIT_RPM?.trim();
+        const handler = createMcpHttpHandler(config, {
+            allowedOrigins,
+            surface,
+            ...(rateLimitEnv && /^\d+$/.test(rateLimitEnv) ? { rateLimitRpm: Number(rateLimitEnv) } : {}),
+            trustProxy: process.env.NP_TRUST_PROXY === "1" || process.env.NP_TRUST_PROXY === "true",
+        });
+        const http = createServer((request, response) => void handler(request, response));
+        // Slowloris guard: bound how long a client may take to deliver a request.
+        hardenServerTimeouts(http);
+        http.listen(port, () => {
+            console.error(`[ai-mcp] streamable HTTP on :${port}/mcp (${surface.key}) — per-user auth (Authorization: Bearer <NP_API_KEY>)`);
+            // Every request carries a bearer credential; plain HTTP would expose it in cleartext.
+            console.error("[ai-mcp] SECURITY: terminate TLS in a reverse proxy on a trusted network — never expose this port directly over plain HTTP.");
+        });
+        return;
+    }
+    // stdio (default) — single user, their key from the env; stdout is the protocol channel.
+    // Widgets register only if this client negotiates the MCP Apps extension.
+    const config = loadConfig(process.env, "require");
+    const server = buildServer(buildDeps(config), { uiRegistration: "negotiated", surface });
+    await server.connect(new StdioServerTransport());
+    console.error(`[ai-mcp] ready (stdio, ${surface.key})`);
+}
+process.on("unhandledRejection", (reason) => {
+    // Never crash a serving process on a stray promise; surface it on stderr (stdout is protocol).
+    console.error("[ai-mcp] unhandled rejection:", reason);
+});
+main().catch((caught) => {
+    console.error(`[ai-mcp] ${caught instanceof Error ? caught.message : caught}`);
+    process.exit(1);
+});

package/dist/md.js

@@ -0,0 +1,110 @@
+import { translate } from "./i18n.js";
+/**
+ * The output design language. Every tool answer is markdown a developer scans in a
+ * terminal or chat pane: a bold header line, tight tables, one status glyph per row,
+ * and a single "Next:" hint so the obvious follow-up is one step away.
+ */
+const GLYPHS = {
+    // healthy / done
+    active: "🟢",
+    successful: "🟢",
+    finalized: "🟢",
+    running: "🟢",
+    // in flight
+    pending: "⏳",
+    creating: "⏳",
+    updating: "⏳",
+    building: "⏳",
+    waiting_for_instances: "⏳",
+    switching_traffic: "🔵",
+    finalizing: "⏳",
+    cancelling: "⏳",
+    rolling_back: "⏳",
+    creating_approval: "✋",
+    // bad / terminal
+    failed: "🔴",
+    cancelled: "⚪",
+    rolled_back: "↩️",
+    deleted: "⚪",
+    inactive: "⚪",
+    creating_approval_denied: "🚫",
+};
+export function glyph(status) {
+    if (!status)
+        return "·";
+    return GLYPHS[status] ?? "·";
+}
+/** Localized status word when the catalog knows it; humanized raw status otherwise. */
+function statusWord(status) {
+    const key = `status.${status}`;
+    return status in GLYPHS ? translate(key) : status.replace(/_/g, " ");
+}
+export function statusLabel(status) {
+    if (!status)
+        return translate("md.unknown");
+    return `${glyph(status)} ${statusWord(status)}`;
+}
+export function ago(iso) {
+    if (!iso)
+        return "";
+    const elapsedMs = Date.now() - new Date(iso).getTime();
+    if (!Number.isFinite(elapsedMs) || elapsedMs < 0)
+        return "";
+    const minutes = Math.floor(elapsedMs / 60_000);
+    if (minutes < 1)
+        return translate("md.justNow");
+    if (minutes < 60)
+        return translate("md.minutesAgo", { count: minutes });
+    const hours = Math.round(minutes / 60);
+    if (hours < 48)
+        return translate("md.hoursAgo", { count: hours });
+    return translate("md.daysAgo", { count: Math.round(hours / 24) });
+}
+export function table(headers, rows) {
+    if (rows.length === 0)
+        return translate("md.none");
+    const head = `| ${headers.join(" | ")} |`;
+    const separator = `|${headers.map(() => "---").join("|")}|`;
+    const body = rows.map((row) => `| ${row.join(" | ")} |`).join("\n");
+    return [head, separator, body].join("\n");
+}
+export function next(hint) {
+    return `\n→ **${translate("md.next")}:** ${hint}`;
+}
+const SPARK = "▁▂▃▄▅▆▇█";
+/** Unicode sparkline — the terminal-native chart. */
+export function spark(values, buckets = 24) {
+    if (!values.length)
+        return "";
+    const step = Math.max(1, Math.ceil(values.length / buckets));
+    const sampled = [];
+    for (let index = 0; index < values.length; index += step) {
+        const chunk = values.slice(index, index + step);
+        sampled.push(chunk.reduce((sum, value) => sum + value, 0) / chunk.length);
+    }
+    const minimum = Math.min(...sampled);
+    const maximum = Math.max(...sampled);
+    const range = maximum - minimum || 1;
+    return sampled.map((value) => SPARK[Math.min(7, Math.floor(((value - minimum) / range) * 8))]).join("");
+}
+export function fmtNum(value) {
+    if (value === undefined || value === null || Number.isNaN(value))
+        return "—";
+    if (Math.abs(value) >= 100)
+        return String(Math.round(value));
+    if (Math.abs(value) >= 1)
+        return value.toFixed(1);
+    return value.toFixed(2);
+}
+export function shortCommit(commit) {
+    return commit ? String(commit).slice(0, 8) : "";
+}
+/** Deep link into the web dashboard for any entity NRN (the dashboard has an /:nrn redirect). */
+export function dashboardLink(orgSlug, nrn) {
+    if (!orgSlug || !nrn)
+        return undefined;
+    return `https://${orgSlug}.app.nullplatform.io/nrn/${encodeURIComponent(nrn)}`;
+}
+export function linkLine(label, url) {
+    return url ? `\n[${label}](${url})` : "";
+}

package/dist/np/auth.js

@@ -0,0 +1,130 @@
+import { translate } from "../i18n.js";
+/** Pull the nullplatform organization id out of a Cognito JWT's cognito:groups claim. */
+export function orgIdFromJwt(jwt) {
+    try {
+        const payloadSegment = jwt.split(".")[1];
+        if (!payloadSegment)
+            return undefined;
+        // JWT segments are base64url; Node's base64 decoder tolerates it, but be explicit.
+        const payload = JSON.parse(Buffer.from(payloadSegment, "base64url").toString("utf8"));
+        for (const group of payload["cognito:groups"] ?? []) {
+            const orgMatch = /@nullplatform\/organization=(\d+)/.exec(group);
+            if (orgMatch)
+                return Number(orgMatch[1]);
+        }
+    }
+    catch {
+        /* not a decodable JWT */
+    }
+    return undefined;
+}
+/** The platform said no to this credential — an auth-boundary error, not a tool error. */
+export class CredentialRejectedError extends Error {
+    constructor(message) {
+        super(message ?? translate("error.credentialRejected", { status: 401 }));
+        this.name = "CredentialRejectedError";
+    }
+}
+export class TokenManager {
+    options;
+    fetchImpl;
+    accessToken;
+    refreshToken;
+    expiresAt = 0;
+    inflight;
+    organizationId;
+    constructor(options, fetchImpl = fetch) {
+        this.options = options;
+        this.fetchImpl = fetchImpl;
+        if (options.bearer) {
+            this.accessToken = options.bearer;
+            this.expiresAt = Number.MAX_SAFE_INTEGER;
+            this.organizationId = orgIdFromJwt(options.bearer);
+        }
+    }
+    async getToken() {
+        if (this.options.bearer)
+            return this.options.bearer;
+        const skewMs = 60_000;
+        if (this.accessToken && Date.now() < this.expiresAt - skewMs)
+            return this.accessToken;
+        // Single-flight: concurrent callers share one exchange — the api_key crosses
+        // the wire once, and the platform never sees a burst of parallel exchanges.
+        this.inflight ??= (this.refreshToken ? this.refresh() : this.exchange()).finally(() => {
+            this.inflight = undefined;
+        });
+        return this.inflight;
+    }
+    invalidate() {
+        if (this.options.bearer)
+            return; // can't refresh a static token
+        this.accessToken = undefined;
+        this.expiresAt = 0;
+    }
+    async exchange() {
+        if (!this.options.apiKey)
+            throw new Error("no api_key configured for token exchange");
+        return this.call({ api_key: this.options.apiKey });
+    }
+    async refresh() {
+        try {
+            return await this.call({
+                refresh_token: this.refreshToken,
+                organization_id: String(this.organizationId),
+            });
+        }
+        catch {
+            this.refreshToken = undefined; // fall back to api_key
+            return this.exchange();
+        }
+    }
+    async call(body) {
+        const exchanged = await callTokenEndpoint(this.options.apiBase, body, this.fetchImpl);
+        this.accessToken = exchanged.accessToken;
+        this.refreshToken = exchanged.refreshToken ?? this.refreshToken;
+        this.organizationId = exchanged.organizationId ?? this.organizationId;
+        this.expiresAt = exchanged.expiresAt;
+        return exchanged.accessToken;
+    }
+}
+/**
+ * One api_key -> access-token exchange, stateless: the key exists only in this call's
+ * scope. Multi-user servers use this so the customer's key is never retained — each
+ * request brings it again, and only the platform-issued token is worth caching.
+ */
+export async function exchangeApiKey(apiBase, apiKey, fetchImpl = fetch) {
+    return callTokenEndpoint(apiBase, { api_key: apiKey }, fetchImpl);
+}
+/** Token exchanges must time out like every other platform call — a hung /token
+ *  otherwise pins the request and leaks the HTTP layer's in-flight verification entry. */
+const TOKEN_EXCHANGE_TIMEOUT_MS = 20_000;
+/** A short, whitespace-collapsed slice of an upstream body — never dump a full payload into
+ *  logs or error text (secret hygiene: credential-adjacent failures stay terse and bounded). */
+function bodySnippet(text, max = 200) {
+    const collapsed = text.replace(/\s+/g, " ").trim();
+    return collapsed.length > max ? `${collapsed.slice(0, max)}…` : collapsed;
+}
+async function callTokenEndpoint(apiBase, body, fetchImpl) {
+    const response = await fetchImpl(`${apiBase}/token`, {
+        signal: AbortSignal.timeout(TOKEN_EXCHANGE_TIMEOUT_MS),
+        method: "POST",
+        headers: { "content-type": "application/json", accept: "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        // Don't echo the response body here — keep credential failures terse and log-safe.
+        throw new CredentialRejectedError(translate("error.credentialRejected", { status: response.status }));
+    }
+    if (!response.ok) {
+        // Bound the upstream body: operator-log-only, but a hostile/huge body must not flood the
+        // logs, and credential-adjacent failures stay terse per the secret-hygiene contract.
+        throw new Error(`token exchange failed: ${response.status} ${bodySnippet(await response.text())}`);
+    }
+    const data = (await response.json());
+    return {
+        accessToken: data.access_token,
+        organizationId: data.organization_id,
+        expiresAt: data.token_expires_at ?? Date.now() + 3_600_000,
+        refreshToken: data.refresh_token,
+    };
+}

package/dist/np/client.js

@@ -0,0 +1,72 @@
+export class NpApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "NpApiError";
+    }
+}
+/**
+ * Thin client for the nullplatform public API (api.nullplatform.com).
+ * Paths are UNVERSIONED and bodies are snake_case — pass them through as-is.
+ */
+export class NpClient {
+    opts;
+    fetchImpl;
+    constructor(opts, fetchImpl = fetch) {
+        this.opts = opts;
+        this.fetchImpl = fetchImpl;
+    }
+    url(path, query) {
+        const queryString = query
+            ? Object.entries(query)
+                .filter(([, value]) => value !== undefined && value !== null)
+                .map(([name, value]) => `${encodeURIComponent(name)}=${encodeURIComponent(String(value))}`)
+                .join("&")
+            : "";
+        return `${this.opts.apiBase}${path}${queryString ? `?${queryString}` : ""}`;
+    }
+    async request(method, path, query, body, retry = true) {
+        const token = await this.opts.getToken();
+        const extra = this.opts.getExtraHeaders ? await this.opts.getExtraHeaders() : {};
+        const res = await this.fetchImpl(this.url(path, query), {
+            signal: AbortSignal.timeout(this.opts.timeoutMs ?? 20_000),
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "content-type": "application/json",
+                accept: "application/json",
+                ...extra,
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (res.status === 401 && retry && this.opts.onUnauthorized) {
+            await this.opts.onUnauthorized();
+            return this.request(method, path, query, body, false);
+        }
+        const text = await res.text();
+        const parsed = text ? safeJson(text) : null;
+        if (!res.ok)
+            throw new NpApiError(res.status, parsed, `${method} ${path} -> ${res.status}`);
+        return parsed;
+    }
+    get(path, query) {
+        return this.request("GET", path, query);
+    }
+    post(path, body, query) {
+        return this.request("POST", path, query, body);
+    }
+    patch(path, body, query) {
+        return this.request("PATCH", path, query, body);
+    }
+}
+function safeJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/np/context.js

@@ -0,0 +1,201 @@
+import { normalizeRepoUrl, repoName } from "../git.js";
+/** Base of a new application's repository, from the account's git provider + org prefix
+ *  (e.g. provider "github" + prefix "acme" -> "https://github.com/acme"). Undefined when the
+ *  account has no provider configured — the create form then asks for a full URL instead. */
+export function baseRepoUrl(provider, prefix) {
+    if (!prefix)
+        return undefined;
+    const host = provider === "gitlab"
+        ? "https://gitlab.com"
+        : provider === "azure" || provider === "azure-devops"
+            ? "https://dev.azure.com"
+            : "https://github.com";
+    return `${host}/${prefix}`;
+}
+/** Default ceiling for a single app search — used as the per-namespace fetch cap AND the
+ *  overall result cap. Beyond it the tool reports truncation and asks the user to narrow.
+ *  (The old value of 50 silently hid larger orgs behind a flat "50 applications".) */
+export const DEFAULT_APP_LIMIT = 200;
+/** Concurrency-limited parallel map — fast fan-out without hammering the API. */
+export async function pmap(items, mapItem, limit = 12) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const worker = async () => {
+        while (nextIndex < items.length) {
+            const index = nextIndex++;
+            results[index] = await mapItem(items[index]); // index < items.length by loop guard
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length || 1) }, worker));
+    return results;
+}
+/**
+ * The public list endpoints are NRN-authorized and need explicit scoping (account needs
+ * organization_id, namespace needs account_id, application needs namespace_id). There is no
+ * org-wide app list, so we fan out in parallel and cache the account+namespace skeleton so
+ * repeated lookups are near-instant within a session.
+ */
+export class NpContext {
+    np;
+    skeleton = null;
+    appByRepo = new Map();
+    orgSlug;
+    orgSlugFetched = false;
+    static CACHE_TTL_MS = 120_000;
+    constructor(np) {
+        this.np = np;
+    }
+    async organizationId() {
+        const me = await this.np.get("/token");
+        return me.organization_id;
+    }
+    async getSkeleton(refresh = false) {
+        if (!refresh && this.skeleton && Date.now() - this.skeleton.at < NpContext.CACHE_TTL_MS)
+            return this.skeleton;
+        const orgId = await this.organizationId();
+        const accountsResp = await this.np.get("/account", {
+            organization_id: orgId,
+            limit: 200,
+        });
+        const perAccount = await pmap(accountsResp.results ?? [], async (account) => {
+            const namespacesPage = await this.np
+                .get("/namespace", { account_id: account.id, limit: 200 })
+                .catch(() => ({ results: [] }));
+            const accountBaseRepoUrl = baseRepoUrl(account.repository_provider, account.repository_prefix);
+            return (namespacesPage.results ?? []).map((namespace) => ({
+                id: namespace.id,
+                name: namespace.name,
+                nrn: namespace.nrn,
+                account_id: account.id,
+                account_name: account.name,
+                base_repo_url: accountBaseRepoUrl,
+            }));
+        });
+        this.skeleton = { orgId, at: Date.now(), namespaces: perAccount.flat() };
+        return this.skeleton;
+    }
+    /** Best-effort org slug for dashboard deep links; the API may not expose it — degrade silently. */
+    async organizationSlug() {
+        if (this.orgSlugFetched)
+            return this.orgSlug;
+        this.orgSlugFetched = true;
+        try {
+            const orgId = await this.organizationId();
+            const org = await this.np.get(`/organization/${orgId}`);
+            this.orgSlug = org?.slug ?? undefined;
+        }
+        catch {
+            this.orgSlug = undefined;
+        }
+        return this.orgSlug;
+    }
+    mapApp(raw, namespace) {
+        return {
+            id: raw.id,
+            name: raw.name,
+            status: raw.status,
+            nrn: raw.nrn,
+            repository_url: raw.repository_url,
+            namespace_id: namespace?.id ?? raw.namespace_id,
+            namespace: namespace?.name,
+            account: namespace?.account_name,
+        };
+    }
+    /** Search apps by partial name (and/or namespace name) across the whole org — parallel + cached. */
+    async findApps(args = {}) {
+        const skeleton = await this.getSkeleton();
+        const namespaceFilter = args.namespace?.toLowerCase();
+        const namespaces = namespaceFilter
+            ? skeleton.namespaces.filter((namespace) => namespace.name.toLowerCase().includes(namespaceFilter))
+            : skeleton.namespaces;
+        const nameFilter = args.query?.toLowerCase();
+        const perNamespace = await pmap(namespaces, async (namespace) => {
+            try {
+                const query = {
+                    namespace_id: namespace.id,
+                    limit: DEFAULT_APP_LIMIT,
+                };
+                if (args.query)
+                    query["name:contains"] = args.query; // server-side when supported
+                const page = await this.np.get("/application", query);
+                return (page.results ?? []).map((app) => this.mapApp(app, namespace));
+            }
+            catch {
+                return [];
+            }
+        });
+        const seen = new Set();
+        return perNamespace
+            .flat()
+            .filter((app) => !nameFilter || (app.name ?? "").toLowerCase().includes(nameFilter)) // client-side fallback filter
+            .filter((app) => app.status !== "deleted")
+            .filter((app) => {
+            if (seen.has(app.id))
+                return false;
+            seen.add(app.id);
+            return true;
+        })
+            .slice(0, args.limit ?? DEFAULT_APP_LIMIT);
+    }
+    /** Match the current git repo to a nullplatform application by repository_url (then by name). */
+    async inferAppFromRepo(repoUrl) {
+        const key = normalizeRepoUrl(repoUrl);
+        const cached = this.appByRepo.get(key);
+        if (cached)
+            return cached;
+        const all = await this.findApps({});
+        const byUrl = all.find((candidate) => candidate.repository_url && normalizeRepoUrl(candidate.repository_url) === key);
+        // Only the repository_url match is authoritative — cache it. A name-only fallback is a
+        // best-effort guess (two apps can share a name across namespaces, and list filtering can
+        // leave the wrong sole survivor), so return it but never persist it for the session.
+        if (byUrl) {
+            this.appByRepo.set(key, byUrl);
+            return byUrl;
+        }
+        const name = repoName(repoUrl);
+        const byName = all.filter((candidate) => candidate.name.toLowerCase() === name.toLowerCase());
+        return byName.length === 1 ? byName[0] : undefined;
+    }
+    async getApp(applicationId) {
+        const raw = await this.np.get(`/application/${applicationId}`);
+        return { ...this.mapApp(raw), messages: raw.messages ?? [] };
+    }
+}
+/**
+ * Unified app resolution used by every tool:
+ *   - `app` numeric or "#123"  -> fetch by id
+ *   - `app` string             -> org-wide name search
+ *   - nothing                  -> infer from the workspace git remote
+ */
+export async function resolveApp(context, args, repoUrl) {
+    const reference = args.app;
+    if (reference !== undefined && reference !== null && String(reference).trim() !== "") {
+        const idMatch = /^#?(\d+)$/.exec(String(reference).trim());
+        if (idMatch) {
+            try {
+                return { ok: true, app: await context.getApp(Number(idMatch[1])) };
+            }
+            catch {
+                return { ok: false, reason: "not_found", cause: "id", ref: idMatch[1] };
+            }
+        }
+        const matches = await context.findApps({ query: String(reference), limit: 10 });
+        if (matches.length === 1)
+            return { ok: true, app: matches[0] };
+        if (matches.length > 1) {
+            const exact = matches.filter((candidate) => candidate.name.toLowerCase() === String(reference).toLowerCase());
+            if (exact.length === 1)
+                return { ok: true, app: exact[0] };
+            return { ok: false, reason: "ambiguous", matches };
+        }
+        return { ok: false, reason: "not_found", cause: "name", ref: String(reference) };
+    }
+    const url = await repoUrl();
+    if (url) {
+        const app = await context.inferAppFromRepo(url);
+        if (app)
+            return { ok: true, app };
+        return { ok: false, reason: "not_found", cause: "repo_unlinked", url };
+    }
+    return { ok: false, reason: "not_found", cause: "no_input" };
+}