@nullplatform/mcp 0.1.5 → 0.1.7

package/dist/np/journey.js

@@ -16,6 +16,17 @@ export function bumpSemver(semver) {
     const parts = /^(v?)(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
     return parts ? `${parts[1]}${parts[2]}.${parts[3]}.${Number(parts[4]) + 1}` : "0.0.1";
 }
+function mapBuild(build) {
+    return {
+        id: build.id,
+        status: build.status,
+        branch: build.branch,
+        commit: String(build.commit?.id ?? build.commit_id ?? "") || undefined,
+        commit_url: build.commit?.permalink,
+        description: build.description ?? undefined,
+        created_at: build.created_at,
+    };
+}
 export async function listBuilds(np, applicationId, options = {}) {
     const query = {
         application_id: applicationId,
@@ -29,13 +40,13 @@ export async function listBuilds(np, applicationId, options = {}) {
     if (options.offset)
         query.offset = options.offset;
     const page = await np.get("/build", query).catch(() => ({ results: [] }));
-    return (page.results ?? []).map((build) => ({
-        id: build.id,
-        status: build.status,
-        branch: build.branch,
-        commit: String(build.commit?.id ?? build.commit_id ?? "") || undefined,
-        created_at: build.created_at,
-    }));
+    return (page.results ?? []).map(mapBuild);
+}
+/** A single build by id (GET /build/{id}) — titles a build's asset view with its real status,
+ *  commit and description even when reached directly (not drilled in from the list). */
+export async function getBuild(np, buildId) {
+    const raw = await np.get(`/build/${buildId}`).catch(() => null);
+    return raw ? mapBuild(raw) : null;
 }
 function mapRelease(raw) {
     return {
@@ -232,11 +243,43 @@ export async function deploymentAction(np, deploymentId, action) {
         status: action === "finalize" ? "finalizing" : "cancelling",
     });
 }
+/** The scope id encoded in a value's NRN (…:scope=<id>), or null for an application-level value. */
+function scopeIdFromNrn(nrn) {
+    const match = nrn?.match(/:scope=(\d+)/);
+    return match ? Number(match[1]) : null;
+}
+function mapParameter(raw) {
+    const secret = !!raw.secret;
+    return {
+        id: raw.id,
+        name: raw.name,
+        variable: raw.variable,
+        destination_path: raw.destination_path,
+        type: raw.type,
+        secret,
+        read_only: raw.read_only,
+        values: (raw.values ?? []).map((entry) => {
+            const dimensions = entry.dimensions && Object.keys(entry.dimensions).length ? entry.dimensions : null;
+            const scopeId = scopeIdFromNrn(entry.nrn);
+            return {
+                id: entry.id,
+                // a value row only exists where a value is set, so secrets become a fixed marker (never plaintext)
+                value: secret ? "•••" : entry.value,
+                nrn: entry.nrn,
+                scope_id: scopeId,
+                dimensions,
+                base: !scopeId && !dimensions,
+            };
+        }),
+    };
+}
 /**
- * Upsert parameters. Agents retry, and re-running "set DATABASE_URL" must not accrete a
- * duplicate definition — so reuse the existing definition (matched by variable/name at this
- * NRN) and just add a value; only POST a new definition when none exists. Reports how many
- * were created vs updated.
+ * Upsert parameters, optionally targeting a scope (pin `nrn`) or a dimension set (`dimensions`).
+ * Agents retry, and re-running "set DATABASE_URL" must not accrete a duplicate definition — so
+ * reuse the existing definition (matched by variable/name at this NRN) and just add a value; only
+ * POST a new definition when none exists. The value write is convergent on (nrn, dimensions,
+ * value) server-side, so a retried set is a no-op new version, never a duplicate. Reports how
+ * many definitions were created vs reused.
  */
 export async function setParameters(np, nrn, params) {
     const existing = (await listParameters(np, nrn)) ?? [];
@@ -261,28 +304,24 @@ export async function setParameters(np, nrn, params) {
             definitionId = definition.id;
             created++;
         }
-        await np.post(`/parameter/${definitionId}/values`, { values: [{ nrn, value: param.value }] });
+        const valueBody = { nrn: param.nrn ?? nrn, value: param.value };
+        if (param.dimensions && Object.keys(param.dimensions).length) {
+            valueBody.dimensions = param.dimensions;
+        }
+        await np.post(`/parameter/${definitionId}/values`, { values: [valueBody] });
     }
     return { created, updated };
 }
-/** Read parameters — NRN-scoped on the public API; returns undefined when unavailable. */
+/** Read parameters with their full value set — NRN-scoped on the public API. Pass an application
+ *  NRN to get EVERY value (all dimensions + scopes); pass a scope NRN and the platform collapses
+ *  each parameter to the single effective value for that scope. undefined when unavailable. */
 export async function listParameters(np, nrn, options = {}) {
     try {
         const query = { nrn, limit: options.limit ?? 100 };
         if (options.offset)
             query.offset = options.offset;
         const page = await np.get("/parameter", query);
-        return (page.results ?? []).map((parameter) => ({
-            id: parameter.id,
-            name: parameter.name,
-            variable: parameter.variable,
-            type: parameter.type,
-            secret: !!parameter.secret,
-            values: (parameter.values ?? []).map((entry) => ({
-                value: parameter.secret ? "•••" : entry.value,
-                nrn: entry.nrn,
-            })),
-        }));
+        return (page.results ?? []).map(mapParameter);
     }
     catch {
         return undefined;
@@ -436,3 +475,176 @@ export async function listServiceSpecifications(bff, nrn) {
         .catch(() => ({ results: [] }));
     return (page.results ?? []).map((spec) => ({ id: spec.id, name: spec.name ?? spec.id }));
 }
+// ---- service provisioning & linking (WRITES — core API, like scopes/deployments) ----
+//
+// Grounded against the public service-api OpenAPI (request/response SHAPE) and the platform team's
+// np-developer-actions skill (BEHAVIOUR — the working implementation of exactly this flow).
+//
+// Provisioning is TWO sequential POSTs: `POST /service` creates the record in `pending`, then
+// `POST /service/{id}/action` enqueues the "create" action an external agent processes to `active`
+// (without #2 the service is `pending` forever). Linking is one OR two POSTs depending on the LINK
+// spec's `use_default_actions` — the SQL landmine, encoded in `linkService` so `status` is derived,
+// never an input. Reads `.catch` to empty; writes throw so the tool surfaces the platform error.
+const TERMINAL_SERVICE = new Set(["active", "failed", "cancelled"]);
+export const isServiceTerminal = (status) => TERMINAL_SERVICE.has(status ?? "");
+/**
+ * Provisionable dependency specs at an entity NRN, read from the CORE API (not the BFF projection
+ * that `listServiceSpecifications` uses) so the write flow can reach the action specs and
+ * `use_default_actions` the dashboard list omits.
+ */
+export async function listDependencySpecs(np, nrn) {
+    const page = await np
+        .get("/service_specification", { nrn, type: "dependency", limit: 100 })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((spec) => ({
+        id: spec.id,
+        name: spec.name ?? spec.id,
+        category: spec.selectors?.category,
+        subCategory: spec.selectors?.sub_category,
+        provider: spec.selectors?.provider,
+    }));
+}
+const mapActionSpec = (spec) => ({
+    id: spec.id,
+    type: spec.type ?? "",
+    name: spec.name,
+    slug: spec.slug,
+    schema: spec.parameters?.schema,
+});
+/** Every action spec of a service spec (`create`/`update`/`delete`/`custom`), mapped. The caller
+ *  filters by `type` — `custom` for run-an-action, `delete` for deprovision, `create` for provision. */
+export async function serviceActionSpecs(np, serviceSpecId) {
+    const page = await np
+        .get(`/service_specification/${serviceSpecId}/action_specification`)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map(mapActionSpec);
+}
+/** The "create" action spec drives provisioning; its `parameters.schema` is the input form. */
+export async function serviceCreateActionSpec(np, serviceSpecId) {
+    return (await serviceActionSpecs(np, serviceSpecId)).find((spec) => spec.type === "create");
+}
+/**
+ * `POST /service` — creates the record in `pending`. Never sends `status` (the backend sets it).
+ * Provisioning does NOT start until `createServiceAction` enqueues the create action.
+ */
+export async function provisionService(np, input) {
+    return np.post("/service", {
+        name: input.name,
+        specification_id: input.specification_id,
+        entity_nrn: input.entity_nrn,
+        linkable_to: input.linkable_to ?? [input.entity_nrn],
+        dimensions: input.dimensions ?? {},
+        selectors: { imported: false },
+    });
+}
+/** `POST /service/{id}/action` — enqueue an action (the create action provisions). */
+export async function createServiceAction(np, serviceId, action) {
+    return np.post(`/service/${serviceId}/action`, {
+        name: action.name,
+        specification_id: action.specification_id,
+        parameters: action.parameters ?? {},
+    });
+}
+export async function getService(np, serviceId) {
+    return np.get(`/service/${serviceId}`);
+}
+/** The link spec(s) that apply to a service spec — the OpenAPI maps them directly. Each carries
+ *  `use_default_actions`, which decides the linking flow (see `linkService`). */
+export async function linkSpecsForService(np, serviceSpecId) {
+    const page = await np
+        .get(`/service_specification/${serviceSpecId}/link_specification`)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((spec) => ({
+        id: spec.id,
+        name: spec.name ?? spec.id,
+        use_default_actions: spec.use_default_actions ?? false,
+    }));
+}
+/** Every action spec of a link spec — the caller filters by `type` (`custom`/`delete`/`create`). */
+export async function linkActionSpecs(np, linkSpecId) {
+    const page = await np
+        .get(`/link_specification/${linkSpecId}/action_specification`)
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map(mapActionSpec);
+}
+/** The create action spec of a LINK spec (only present when `use_default_actions` is true). */
+export async function linkCreateActionSpec(np, linkSpecId) {
+    return (await linkActionSpecs(np, linkSpecId)).find((spec) => spec.type === "create");
+}
+/** `POST /link`. `status` is the SQL landmine: it is DERIVED from the link spec's
+ *  `use_default_actions`, never passed in. Caller passes the resolved spec; this never takes a free
+ *  `status`. */
+export async function createLink(np, input) {
+    const body = {
+        name: input.name,
+        service_id: input.service_id,
+        entity_nrn: input.entity_nrn,
+        specification_id: input.specification_id,
+        dimensions: input.dimensions ?? {},
+    };
+    // use_default_actions=false → no agent exists, so `active` must be set or the link is stuck
+    // `pending` forever. use_default_actions=true → OMIT status; a follow-up create-action provisions
+    // credentials. Sending `active` there yields an active-but-credential-less, unrecoverable link.
+    if (input.activateImmediately)
+        body.status = "active";
+    return np.post("/link", body);
+}
+export async function createLinkAction(np, linkId, action) {
+    return np.post(`/link/${linkId}/action`, {
+        name: action.name,
+        specification_id: action.specification_id,
+        parameters: action.parameters ?? {},
+    });
+}
+export async function getLink(np, linkId) {
+    return np.get(`/link/${linkId}`);
+}
+/** Existing dependency services on an app (core API) — for convergence: a retried provision must
+ *  reuse a same-name service rather than spin up a second (cost-bearing) one. */
+export async function listAppServices(np, nrn) {
+    const page = await np
+        .get("/service", { nrn, type: "dependency", limit: 100 })
+        .catch(() => ({ results: [] }));
+    return (page.results ?? []).map((service) => ({
+        id: service.id,
+        name: service.name ?? service.id,
+        status: service.status ?? "",
+        specification_id: service.specification_id,
+    }));
+}
+/** Existing links on an app (core API) — for convergence: a retried link must reuse an existing one
+ *  for the same service+target rather than create a duplicate; also feeds the link picker (name) and
+ *  the link-action / link-delete flows (specification_id → the link spec's action specs). */
+export async function listLinks(np, nrn) {
+    const page = await np.get("/link", { nrn }).catch(() => ({ results: [] }));
+    return (page.results ?? []).map((link) => ({
+        id: link.id,
+        name: link.name ?? link.id,
+        status: link.status ?? "",
+        service_id: link.service_id,
+        entity_nrn: link.entity_nrn,
+        specification_id: link.specification_id,
+    }));
+}
+/** Poll one action of a service — `pending` → `in_progress` → `success`|`failed`. */
+export async function getServiceAction(np, serviceId, actionId) {
+    return np.get(`/service/${serviceId}/action/${actionId}`);
+}
+/** Poll one action of a link. */
+export async function getLinkAction(np, linkId, actionId) {
+    return np.get(`/link/${linkId}/action/${actionId}`);
+}
+/** `DELETE /service/{id}`. A `failed` service (no provisioned resources) deletes directly; an active
+ *  one needs `force` OR a prior delete-action that deprovisions — the tool decides which path. */
+export async function deleteService(np, serviceId, force = false) {
+    await np.del(`/service/${serviceId}`, force ? { force: true } : undefined);
+}
+/** `DELETE /link/{id}`. `force` skips the deprovisioning delete-action (orphans credentials), so the
+ *  tool only forces when there's no delete-action to run; otherwise it runs the action first. */
+export async function deleteLink(np, linkId, force = false) {
+    await np.del(`/link/${linkId}`, force ? { force: true } : undefined);
+}
+/** `DELETE /parameter/{id}` — removes a whole parameter definition (and all its values). */
+export async function deleteParameter(np, parameterId) {
+    await np.del(`/parameter/${parameterId}`);
+}

package/dist/surfaces/developer.js

@@ -12,7 +12,7 @@ You run in the developer's own environment, so fuse the local repo with platform
 
 Every tool accepts \`language\`: ALWAYS set it to the language the user is conversing in (ISO code, e.g. "es", "en") — answers come back in the user's language.
 
-Most tools render an interactive panel in clients that support it — the user sees apps, status, logs, metrics and parameters as live UI. When that panel renders, the user can already see the result: do NOT restate or summarise it in text (no re-listing applications, reprinting tables, or repeating status/metrics). Reply with at most one short sentence — the single key takeaway or next step — or nothing at all. Add prose only for something the panel doesn't already show.
+Most tools render an interactive panel in clients that support it — apps, status, builds, releases, deployments, logs, metrics, parameters and approvals all appear as live UI. **When a tool's panel renders, that panel IS the answer: do not reproduce its data in your text reply.** The user already sees every row, status and value. NEVER print a markdown table of the same rows, re-list the items, or restate per-row status — duplicating the panel in text is the single most common mistake. Reply with AT MOST one short sentence — the one key takeaway or the next step — or nothing at all. A one-line insight the panel doesn't itself show is fine ("builds 3 and 5 were never released"); re-rendering the list as a table is not.
 
 When the user wants to create, scaffold, set up or import an application, call \`application_create\` right away — pass a name if they gave one, otherwise no arguments. Its panel is an interactive FORM that collects the namespace, template and repository itself. Do NOT gather those details in conversation first, and while that form is on screen do NOT ask the user clarifying questions or use any question-asking tool for fields the form already covers (namespace, template, new-vs-import repository, monorepo path) — the form is the input surface. Just call \`application_create\` and let it drive; react only to what it reports back.
 

package/dist/tool-names.js

@@ -21,6 +21,13 @@ export const TOOL = {
     applicationReleaseCreate: "application_release_create",
     applicationScopeCreate: "application_scope_create",
     applicationServiceList: "application_service_list",
+    applicationServiceCreate: "application_service_create",
+    applicationServiceUpdate: "application_service_update",
+    applicationServiceDelete: "application_service_delete",
+    applicationLinkCreate: "application_link_create",
+    applicationLinkUpdate: "application_link_update",
+    applicationLinkDelete: "application_link_delete",
+    applicationParameterDelete: "application_parameter_delete",
     applicationApprovalList: "application_approval_list",
     organizationGet: "organization_get",
     playbookGet: "playbook_get",

package/dist/tools/action-flow.js

@@ -0,0 +1,94 @@
+import { translate } from "../i18n.js";
+import { linkLine, next, table } from "../md.js";
+import { fail, reply } from "../tool.js";
+import { delays, sleep } from "./shared.js";
+const slug = (text) => text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+const actionLabel = (spec) => spec.name ?? spec.slug ?? spec.id;
+/**
+ * The run-a-custom-action flow shared by `application_service_update` and `application_link_update`:
+ * pick which action → fill its parameters (form-first; nothing runs without `run:true`) → POST the
+ * action → poll it once → report. A custom action is an explicit operation (it is NOT idempotent —
+ * running a DML twice runs it twice), so the safety here is the form gate, not convergence.
+ */
+export async function runActionFlow(config, args) {
+    const { entity, entityName, specs, dashboard } = config;
+    if (specs.length === 0) {
+        return fail(translate("runAction.noActions", { name: entityName }) + linkLine(translate("md.dashboard"), dashboard));
+    }
+    // Match the requested action by name/slug; none or ambiguous → list the runnable actions.
+    const wanted = args.action?.toLowerCase();
+    const matched = wanted
+        ? specs.filter((spec) => actionLabel(spec).toLowerCase().includes(wanted) ||
+            (spec.slug ?? "").toLowerCase() === wanted ||
+            spec.id === args.action)
+        : [];
+    if (matched.length !== 1) {
+        const list = matched.length > 1 ? matched : specs;
+        const heading = translate(matched.length > 1 ? "runAction.matchAmbiguous" : "runAction.pickAction", {
+            name: entityName,
+        });
+        const md = `${heading}\n\n${table([translate("header.name"), translate("runAction.paramsHeader")], list.map((spec) => [
+            actionLabel(spec),
+            (spec.schema?.required ?? []).join(", ") || "—",
+        ]))}${next(translate("runAction.pickHint"))}`;
+        return reply(md, {
+            mode: "pick-action",
+            entity,
+            tool: config.tool,
+            app: config.appRef,
+            app_name: config.appName,
+            target: { id: config.entityId, name: entityName, status: config.entityStatus },
+            actions: list.map((spec) => ({ id: spec.id, name: actionLabel(spec), slug: spec.slug })),
+            dashboard,
+        });
+    }
+    const spec = matched[0];
+    // Form-first: no explicit run OR a required parameter still missing → return the form.
+    const requiredKeys = spec.schema?.required ?? [];
+    const missing = requiredKeys.filter((key) => args.parameters?.[key] === undefined);
+    if (!args.run || missing.length > 0) {
+        return reply(translate("runAction.form", { action: actionLabel(spec), name: entityName }) +
+            next(translate("runAction.formHint")), {
+            mode: "form",
+            entity,
+            tool: config.tool,
+            app: config.appRef,
+            app_name: config.appName,
+            target: { id: config.entityId, name: entityName, status: config.entityStatus },
+            action: { id: spec.id, name: actionLabel(spec), slug: spec.slug },
+            parameters_schema: spec.schema ?? null,
+            dashboard,
+        });
+    }
+    // ---- RUN THE ACTION ----
+    const fired = await config.run({
+        name: spec.slug ?? slug(actionLabel(spec)),
+        specification_id: spec.id,
+        parameters: args.parameters ?? {},
+    });
+    await sleep(delays.appPoll);
+    const action = await config
+        .poll(fired.id)
+        .catch(() => ({ id: fired.id, status: fired.status ?? "pending" }));
+    const md = `${translate("runAction.running", { action: actionLabel(spec), name: entityName, status: action.status })}` +
+        next(translate("runAction.ranHint")) +
+        linkLine(translate("md.dashboard"), dashboard);
+    return reply(md, {
+        mode: "progress",
+        entity,
+        tool: config.tool,
+        app: config.appRef,
+        app_name: config.appName,
+        target: { id: config.entityId, name: entityName, status: config.entityStatus },
+        action: {
+            id: action.id,
+            name: actionLabel(spec),
+            status: action.status,
+            results: action.results ?? null,
+        },
+        dashboard,
+    });
+}

package/dist/tools/approvals.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { translate } from "../i18n.js";
+import { plural, translate } from "../i18n.js";
 import { ago, dashboardLink, glyph, linkLine, next, table } from "../md.js";
 import { cancelApproval, executeApproval, isSafeApprovalId, listApprovals } from "../np/journey.js";
 import { defineTool, fail, reply } from "../tool.js";
@@ -52,7 +52,7 @@ export const approvalsTool = defineTool({
             return reply(translate("approvals.none", { app: app.name }), { app: `#${app.id}`, approvals: [] });
         }
         const markdown = [
-            translate("approvals.title", { app: app.name, count: approvals.length }),
+            plural(approvals.length, "approvals.title.one", "approvals.title.many", { app: app.name }),
             "",
             table([
                 translate("header.id"),

package/dist/tools/builds.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
-import { translate } from "../i18n.js";
+import { plural, translate } from "../i18n.js";
 import { ago, glyph, next, shortCommit, table } from "../md.js";
-import { listAssets, listBuilds, listReleases } from "../np/journey.js";
+import { getBuild, listAssets, listBuilds, listReleases } from "../np/journey.js";
 import { defineTool, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
@@ -33,10 +33,17 @@ export const buildsTool = defineTool({
             return resolved.out;
         const app = resolved.app;
         if (args.build) {
-            const assets = await listAssets(context.np, args.build);
+            // Fetch the build alongside its assets so the asset view shows the real status/commit and
+            // a no-assets message that fits the build's state (running vs failed vs simply none).
+            const [build, assets] = await Promise.all([
+                getBuild(context.np, args.build),
+                listAssets(context.np, args.build),
+            ]);
+            const buildData = build ?? { id: args.build, status: "" };
             if (assets.length === 0) {
-                return reply(translate("builds.noAssets", { build: args.build }), {
+                return reply(noAssetsText(build?.status, args.build), {
                     build_id: args.build,
+                    build: buildData,
                     assets: [],
                 });
             }
@@ -46,7 +53,7 @@ export const buildsTool = defineTool({
                 table([translate("header.asset"), translate("header.type"), translate("header.platform")], assets.map((asset) => [asset.name, asset.type, asset.platform ?? ""])),
                 next(translate("builds.deployHint", { build: args.build })),
             ].join("\n");
-            return reply(markdown, { build_id: args.build, assets });
+            return reply(markdown, { build_id: args.build, build: buildData, assets });
         }
         const [builds, releases] = await Promise.all([
             listBuilds(context.np, app.id, { limit: args.limit ?? 10, commit: args.commit, offset: args.offset }),
@@ -61,7 +68,7 @@ export const buildsTool = defineTool({
         const releasedBuildIds = new Set(releases.map((release) => release.build_id).filter(Boolean));
         const releaseByBuild = new Map(releases.map((release) => [release.build_id, release]));
         const markdown = [
-            translate("builds.title", { app: app.name, count: builds.length }),
+            plural(builds.length, "builds.title.one", "builds.title.many", { app: app.name }),
             "",
             table([
                 translate("header.id"),
@@ -92,6 +99,16 @@ export const buildsTool = defineTool({
         });
     },
 });
+/** No-assets message keyed to the build's state — "may still be running" only fits a build that
+ *  actually still is; a failed or finished one needs the truth. */
+function noAssetsText(status, build) {
+    if (status === "pending" || status === "in_progress") {
+        return translate("builds.noAssetsRunning", { build });
+    }
+    if (status === "failed")
+        return translate("builds.noAssetsFailed", { build });
+    return translate("builds.noAssets", { build });
+}
 function buildsHint(builds, releasedBuildIds) {
     const newestSuccessful = builds.find((build) => build.status === "successful");
     if (newestSuccessful && !releasedBuildIds.has(newestSuccessful.id)) {