@nullplatform/mcp 0.1.0

package/dist/tools/index.js

@@ -0,0 +1,39 @@
+import { approvalsTool } from "./approvals.js";
+import { buildsTool } from "./builds.js";
+import { createAppTool } from "./create-app.js";
+import { createReleaseTool } from "./create-release.js";
+import { createScopeTool } from "./create-scope.js";
+import { deployTool } from "./deploy.js";
+import { findAppsTool } from "./find-apps.js";
+import { logsTool } from "./logs.js";
+import { metricsTool } from "./metrics.js";
+import { overviewTool } from "./overview.js";
+import { paramsTool } from "./params.js";
+import { playbookGetTool } from "./playbook.js";
+import { servicesTool } from "./services.js";
+import { setParamsTool } from "./set-params.js";
+import { statusTool } from "./status.js";
+import { trafficTool } from "./traffic.js";
+/**
+ * The tool registry — the single extension point. To add a tool: create
+ * src/tools/<name>.ts exporting a defineTool({...}) and list it here. Its widget
+ * (if declared) is registered automatically by the server assembly.
+ */
+export const tools = [
+    statusTool,
+    overviewTool,
+    findAppsTool,
+    buildsTool,
+    logsTool,
+    paramsTool,
+    metricsTool,
+    deployTool,
+    trafficTool,
+    createReleaseTool,
+    setParamsTool,
+    createAppTool,
+    createScopeTool,
+    approvalsTool,
+    servicesTool,
+    playbookGetTool,
+];

package/dist/tools/logs.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, linkLine, next } from "../md.js";
+import { listScopes, readLogs } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, chooseScope, requireApp } from "./shared.js";
+export const logsTool = defineTool({
+    name: TOOL.applicationLogList,
+    title: "Read logs",
+    description: "Read recent application logs (optionally for one scope). Returns the latest lines, newest last — good for a quick 'why is it failing?' look.",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    widget: "logs",
+    errorKey: "logs.errorLabel",
+    onError: (message) => fail(`${translate("logs.errorLabel")}: ${message}\n${translate("logs.errorSuffix")}`),
+    inputSchema: {
+        app: appArg,
+        scope: z.string().optional().describe("Scope name (defaults to the only scope, or all)"),
+        lines: z.number().optional().describe("Max lines (default 50)"),
+        start_time: z
+            .string()
+            .optional()
+            .describe("ISO-8601 start of the time window, e.g. 2026-06-13T10:00:00Z"),
+        end_time: z.string().optional().describe("ISO-8601 end of the time window (defaults to now)"),
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        // Logs live per scope on the platform — resolve one before reading.
+        const scopes = await listScopes(context.np, app.id);
+        if (scopes.length === 0) {
+            return reply(translate("logs.noScopes", { app: app.name }) + next(translate("logs.noScopesHint")));
+        }
+        const picked = chooseScope(scopes, args.scope, {
+            nounKey: "logs.noun",
+            tool: TOOL.applicationLogList,
+            app,
+        });
+        if ("out" in picked)
+            return picked.out;
+        const scope = picked.scope;
+        const maxLines = args.lines ?? 50;
+        const page = await readLogs(context.np, {
+            application_id: app.id,
+            scope_id: scope.id,
+            start_time: args.start_time,
+            end_time: args.end_time,
+        });
+        const entries = (page.results ?? []).slice(-maxLines);
+        const scopeSuffix = ` · ${scope.name}`;
+        // The full scope list rides along so the widget can offer a scope switcher.
+        const scopeList = scopes.map((candidate) => ({ name: candidate.name, status: candidate.status }));
+        if (entries.length === 0) {
+            const orgSlug = await context.org.organizationSlug();
+            return reply(translate("logs.empty", { app: app.name, scope: scopeSuffix }) +
+                linkLine(translate("logs.openInDashboard"), dashboardLink(orgSlug, app.nrn)), { count: 0, app: `#${app.id}`, app_name: app.name, scope: scope.name, scopes: scopeList, lines: [] });
+        }
+        const body = entries
+            .map((entry) => {
+            const timestamp = entry.datetime ?? entry.timestamp;
+            const prefix = timestamp
+                ? `${new Date(timestamp).toISOString().slice(5, 19).replace("T", " ")}  `
+                : "";
+            return `${prefix}${(entry.message ?? "").trimEnd()}`;
+        })
+            .join("\n");
+        const markdown = `${translate("logs.lastLines", { app: app.name, scope: scopeSuffix, count: entries.length })}\n\n\`\`\`\n${body}\n\`\`\``;
+        return reply(markdown, {
+            count: entries.length,
+            next_page_token: page.next_page_token ?? null,
+            app: `#${app.id}`,
+            app_name: app.name,
+            scope: scope.name,
+            scopes: scopeList,
+            lines: entries.map((entry) => ({
+                ts: entry.datetime ?? entry.timestamp ?? null,
+                message: entry.message ?? "",
+            })),
+        });
+    },
+});

package/dist/tools/metrics.js

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { dashboardLink, fmtNum, linkLine, next, spark, table } from "../md.js";
+import { listScopes, readGoldenMetrics, windowHours } from "../np/journey.js";
+import { defineTool, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, chooseScope, requireApp } from "./shared.js";
+export const metricsTool = defineTool({
+    name: TOOL.applicationMetricList,
+    title: "Performance metrics",
+    description: "The golden signals of a scope — throughput (rpm), response time, error rate, CPU and memory — with sparkline trends over a time window. Use to answer 'how is it performing?' or to watch health during a rollout.",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    widget: "metrics",
+    errorKey: "metrics.errorLabel",
+    inputSchema: {
+        app: appArg,
+        scope: z.string().optional().describe("Scope name (defaults to the only scope)"),
+        window: z.enum(["1h", "3h", "24h", "7d"]).optional().describe("Time window (default 3h)"),
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        const scopes = await listScopes(context.np, app.id);
+        if (scopes.length === 0) {
+            return reply(translate("metrics.noScopes", { app: app.name }) + next(translate("metrics.noScopesHint")));
+        }
+        const picked = chooseScope(scopes, args.scope, {
+            nounKey: "metrics.noun",
+            tool: TOOL.applicationMetricList,
+            app,
+        });
+        if ("out" in picked)
+            return picked.out;
+        const scope = picked.scope;
+        const window = args.window ?? "3h";
+        const series = await readGoldenMetrics(context.bff, {
+            application_id: app.id,
+            scope_id: scope.id,
+            scope_type: scope.type,
+            hours: windowHours(args.window),
+        });
+        const withData = series.filter((metric) => metric.points.length > 0);
+        if (withData.length === 0) {
+            const orgSlug = await context.org.organizationSlug();
+            return reply(translate("metrics.empty", { app: app.name, scope: scope.name, window }) +
+                linkLine(translate("metrics.openInDashboard"), dashboardLink(orgSlug, scope.nrn)), { app: `#${app.id}`, scope: scope.name, window, series: [] });
+        }
+        const markdown = [
+            translate("metrics.title", { app: app.name, scope: scope.name, window }),
+            "",
+            table([
+                translate("header.metric"),
+                translate("header.now"),
+                translate("header.avg"),
+                translate("header.max"),
+                translate("header.trend"),
+            ], series.map((metric) => [
+                metric.label,
+                metric.points.length ? `${fmtNum(metric.last)} ${metric.unit}` : "—",
+                fmtNum(metric.avg),
+                fmtNum(metric.max),
+                spark(metric.points.map((point) => point.v)),
+            ])),
+        ].join("\n");
+        return reply(markdown, {
+            app: `#${app.id}`,
+            app_name: app.name,
+            scope: scope.name,
+            window,
+            series: series.map((metric) => ({
+                id: metric.id,
+                label: metric.label,
+                unit: metric.unit,
+                last: metric.last ?? null,
+                avg: metric.avg ?? null,
+                max: metric.max ?? null,
+                points: metric.points,
+            })),
+        });
+    },
+});

package/dist/tools/overview.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { ago, glyph, next, table } from "../md.js";
+import { pmap } from "../np/context.js";
+import { isDeploymentTerminal, listScopeDeployments, listScopes } from "../np/journey.js";
+import { defineTool, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+/**
+ * Org-wide health digest — a question agents ask that the web has no page for: "is anything
+ * unhealthy / mid-rollout right now?". Bounded parallel fan-out over the org's apps and their
+ * scopes' latest deployments; truncation is reported, never silent.
+ */
+const MAX_APPS = 30;
+export const overviewTool = defineTool({
+    name: TOOL.organizationGet,
+    title: "Organization overview",
+    description: "A cross-application health digest for the whole org: what's mid-rollout right now, and which scopes' last deployment failed or rolled back. Answers 'is anything broken?' / 'what's deploying?' without naming an app. Scans up to the first ~30 applications.",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errorKey: "overview.errorLabel",
+    inputSchema: {
+        query: z.string().optional().describe("Limit the scan to apps whose name contains this"),
+    },
+    async handler(args, context) {
+        const apps = await context.org.findApps({ query: args.query, limit: MAX_APPS + 1 });
+        const truncated = apps.length > MAX_APPS;
+        const scanned = apps.slice(0, MAX_APPS);
+        const active = [];
+        const trouble = [];
+        await pmap(scanned, async (app) => {
+            const scopes = await listScopes(context.np, app.id).catch(() => []);
+            await pmap(scopes, async (scope) => {
+                const deployments = await listScopeDeployments(context.np, scope.id, 1).catch(() => []);
+                const latest = deployments[0];
+                if (!latest)
+                    return;
+                if (!isDeploymentTerminal(latest.status)) {
+                    active.push({
+                        app: app.name,
+                        scope: scope.name,
+                        deployment_id: latest.id,
+                        status: latest.status,
+                        traffic: latest.strategy_data?.switchedTraffic,
+                        when: latest.created_at,
+                    });
+                }
+                else if (latest.status === "failed" || latest.status === "rolled_back") {
+                    trouble.push({
+                        app: app.name,
+                        scope: scope.name,
+                        status: latest.status,
+                        when: latest.created_at,
+                    });
+                }
+            }, 6);
+        }, 8);
+        return reply(renderOverview({ active, trouble, scanned: scanned.length, truncated }), {
+            scanned: scanned.length,
+            truncated,
+            active_rollouts: active,
+            trouble,
+        });
+    },
+});
+function renderOverview(args) {
+    const { active, trouble, scanned, truncated } = args;
+    const lines = [translate("overview.title", { count: scanned })];
+    if (truncated)
+        lines.push(translate("overview.truncated", { count: MAX_APPS }));
+    lines.push("");
+    lines.push(`**${translate("overview.activeRollouts", { count: active.length })}**`);
+    if (active.length) {
+        lines.push(table([
+            translate("header.app"),
+            translate("header.scope"),
+            translate("header.deployment"),
+            translate("header.status"),
+            translate("header.traffic"),
+            translate("header.when"),
+        ], active.map((rollout) => [
+            rollout.app,
+            rollout.scope,
+            `#${rollout.deployment_id}`,
+            `${glyph(rollout.status)} ${rollout.status.replace(/_/g, " ")}`,
+            rollout.traffic !== undefined ? `${rollout.traffic}%` : "",
+            ago(rollout.when),
+        ])));
+    }
+    lines.push("");
+    lines.push(`**${translate("overview.trouble", { count: trouble.length })}**`);
+    if (trouble.length) {
+        lines.push(table([
+            translate("header.app"),
+            translate("header.scope"),
+            translate("header.status"),
+            translate("header.when"),
+        ], trouble.map((entry) => [
+            entry.app,
+            entry.scope,
+            `${glyph(entry.status)} ${entry.status.replace(/_/g, " ")}`,
+            ago(entry.when),
+        ])));
+    }
+    const hint = active.length
+        ? translate("overview.hintActive", { app: active[0]?.app ?? "" })
+        : trouble.length
+            ? translate("overview.hintTrouble", { app: trouble[0]?.app ?? "" })
+            : translate("overview.hintCalm");
+    lines.push(next(hint));
+    return lines.join("\n");
+}

package/dist/tools/params.js

@@ -0,0 +1,58 @@
+import { plural, translate } from "../i18n.js";
+import { dashboardLink, linkLine, next, table } from "../md.js";
+import { listParameters } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, requireApp } from "./shared.js";
+export const paramsTool = defineTool({
+    name: TOOL.applicationParameterList,
+    title: "List parameters",
+    description: "List an application's configuration parameters (env vars / files; secret values are masked). Use application_parameter_create to add or change them.",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    widget: "params",
+    errorKey: "params.errorLabel",
+    inputSchema: { app: appArg },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        if (!app.nrn)
+            return fail(translate("resolve.noNrn", { app: app.name }));
+        const [parameters, orgSlug] = await Promise.all([
+            listParameters(context.np, app.nrn),
+            context.org.organizationSlug(),
+        ]);
+        const dashboard = dashboardLink(orgSlug, app.nrn);
+        const appRef = { app: `#${app.id}`, app_name: app.name };
+        if (parameters === undefined) {
+            return reply(translate("params.unavailable") + linkLine(translate("params.viewInDashboard"), dashboard), { available: false, ...appRef });
+        }
+        if (parameters.length === 0) {
+            return reply(translate("params.none", { app: app.name }) + next(translate("params.noneHint")), {
+                available: true,
+                params: [],
+                ...appRef,
+            });
+        }
+        const markdown = [
+            plural(parameters.length, "params.count.one", "params.count.many", { app: app.name }),
+            "",
+            table([
+                translate("header.name"),
+                translate("header.variable"),
+                translate("header.type"),
+                translate("header.secret"),
+                translate("header.value"),
+            ], parameters.map((parameter) => [
+                parameter.name,
+                parameter.variable ?? "",
+                parameter.type ?? "ENVIRONMENT",
+                parameter.secret ? "🔒" : "",
+                parameter.values[0]?.value ?? translate("params.unset"),
+            ])),
+            next(translate("params.applyHint")),
+        ].join("\n");
+        return reply(markdown, { available: true, params: parameters, ...appRef });
+    },
+});

package/dist/tools/playbook.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { loadSkills } from "../skills.js";
+import { defineTool, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+/**
+ * Delivers the operating playbooks (skills/<name>/SKILL.md) to the model. Tools are the one MCP
+ * primitive every coding assistant exposes to the model, so this works uniformly across Claude
+ * Code, Cursor, Claude Desktop, etc. — unlike the old `skill://` resource, which Claude Desktop
+ * misrouted to its native Agent Skills executor ("Unknown skill"). The model is told in the
+ * instructions which playbook to read before which task; here it reads the actual methodology.
+ */
+/** Strip the `--- frontmatter ---` block, leaving the playbook body. */
+const playbookBody = (markdown) => markdown.replace(/^---\n[\s\S]*?\n---\n?/, "").trim();
+export const playbookGetTool = defineTool({
+    name: TOOL.playbookGet,
+    title: "Read an operating playbook",
+    description: "Read a nullplatform operating playbook — the methodology to follow before the matching non-trivial work: deploying-safely before a deploy/rollout, incident-response when something is broken, platform-conventions for entity/versioning/traffic semantics. Call with no name to list the available playbooks.",
+    annotations: { readOnlyHint: true },
+    errorKey: "playbook.errorLabel",
+    inputSchema: {
+        name: z.string().optional().describe('Playbook name, e.g. "deploying-safely". Omit to list them.'),
+    },
+    async handler(args) {
+        const playbooks = loadSkills();
+        if (!args.name) {
+            const catalog = playbooks
+                .map((playbook) => `- **${playbook.name}** — ${playbook.description}`)
+                .join("\n");
+            return reply(`Operating playbooks — call \`playbook_get name:"<name>"\` to read one:\n\n${catalog}`, {
+                playbooks: playbooks.map((playbook) => ({ name: playbook.name, description: playbook.description })),
+            });
+        }
+        const match = playbooks.find((playbook) => playbook.name === args.name);
+        if (!match) {
+            return reply(`No playbook named "${args.name}". Available: ${playbooks.map((playbook) => playbook.name).join(", ")}.`);
+        }
+        return reply(playbookBody(match.markdown), { name: match.name });
+    },
+});

package/dist/tools/services.js

@@ -0,0 +1,58 @@
+import { translate } from "../i18n.js";
+import { dashboardLink, glyph, linkLine, next, table } from "../md.js";
+import { listServiceSpecifications, listServices } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, requireApp } from "./shared.js";
+/**
+ * Services = an app's provisioned dependencies (databases, queues, caches…). Read-first by
+ * design: listing what's attached and what's available to provision is safe and high-value;
+ * actual provisioning/linking is a multi-step spec-driven flow with real cost, so this tool
+ * shows it and deep-links into the dashboard to create — it does not provision blind.
+ */
+export const servicesTool = defineTool({
+    name: TOOL.applicationServiceList,
+    title: "Services & dependencies",
+    description: "List the dependency services (databases, queues, caches…) attached to an application, plus the catalog of dependency types available to provision. Read-only: provisioning a new dependency is a guided flow, so this links you into the dashboard to create one.",
+    annotations: { readOnlyHint: true, openWorldHint: true },
+    errorKey: "services.errorLabel",
+    inputSchema: { app: appArg },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        if (!app.nrn)
+            return fail(translate("resolve.noNrn", { app: app.name }));
+        const [services, catalog, orgSlug] = await Promise.all([
+            listServices(context.bff, app.nrn),
+            listServiceSpecifications(context.bff, app.nrn),
+            context.org.organizationSlug(),
+        ]);
+        const dashboard = linkLine(translate("md.dashboard"), dashboardLink(orgSlug, app.nrn));
+        const sections = [];
+        if (services.length === 0) {
+            sections.push(translate("services.none", { app: app.name }));
+        }
+        else {
+            sections.push(translate("services.attached", { app: app.name, count: services.length }));
+            sections.push("");
+            sections.push(table([translate("header.name"), translate("services.specification"), translate("header.status")], services.map((service) => [
+                service.name,
+                service.specification ?? "",
+                `${glyph(service.status)} ${service.status ?? ""}`,
+            ])));
+        }
+        if (catalog.length) {
+            sections.push("");
+            sections.push(translate("services.catalog", { catalog: catalog.map((spec) => spec.name).join(", ") }));
+        }
+        sections.push(next(translate("services.provisionHint")) + dashboard);
+        return reply(sections.join("\n"), {
+            app: `#${app.id}`,
+            app_name: app.name,
+            services,
+            catalog,
+        });
+    },
+});

package/dist/tools/set-params.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { translate } from "../i18n.js";
+import { next } from "../md.js";
+import { setParameters } from "../np/journey.js";
+import { defineTool, errorMessage, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+import { appArg, requireApp } from "./shared.js";
+export const setParamsTool = defineTool({
+    name: TOOL.applicationParameterCreate,
+    title: "Set parameters",
+    description: "Create or update application configuration parameters (environment variables or files; mark secrets). Values apply on the NEXT deploy.",
+    annotations: { destructiveHint: false, openWorldHint: true },
+    errorKey: "setParams.errorLabel",
+    inputSchema: {
+        app: appArg,
+        params: z
+            .array(z.object({
+            name: z.string().describe("Variable name, e.g. DATABASE_URL"),
+            value: z.string(),
+            secret: z.boolean().optional().describe("Mask the value (default false)"),
+            type: z.enum(["ENVIRONMENT", "FILE"]).optional().describe("Default ENVIRONMENT"),
+        }))
+            .min(1),
+    },
+    async handler(args, context) {
+        const resolved = await requireApp(context, args);
+        if ("out" in resolved)
+            return resolved.out;
+        const app = resolved.app;
+        if (!app.nrn)
+            return fail(translate("resolve.noNrn", { app: app.name }));
+        try {
+            const result = await setParameters(context.np, app.nrn, args.params);
+            const names = args.params.map((parameter) => `\`${parameter.name}\``).join(", ");
+            const total = result.created + result.updated;
+            // Honest about upsert: say how many were new vs changed so a retry reads as "0 new".
+            const summary = result.updated === 0
+                ? translate("setParams.created", { count: result.created, app: app.name, names })
+                : result.created === 0
+                    ? translate("setParams.updated", { count: result.updated, app: app.name, names })
+                    : translate("setParams.mixed", {
+                        created: result.created,
+                        updated: result.updated,
+                        app: app.name,
+                        names,
+                    });
+            return reply(summary + next(translate("setParams.applyHint")), {
+                created: result.created,
+                updated: result.updated,
+                total,
+            });
+        }
+        catch (caught) {
+            // Parameters are applied one by one — a midway failure leaves the earlier ones in place.
+            return fail(translate("setParams.partial", { message: errorMessage(caught) }));
+        }
+    },
+});