@nullplatform/mcp 0.1.13 → 0.1.15

package/dist/tools/overview.js

@@ -14,7 +14,7 @@ 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.",
+    description: 'A cross-application health digest for the WHOLE org, rendered as a panel: what\'s mid-rollout right now, and which scopes\' last deployment failed or rolled back. Use it ONLY for org-wide HEALTH questions that name no app — "is anything broken?", "what\'s deploying?", "any failed rollouts?". Scans up to the first ~30 applications (truncation is reported, never silent). This is HEALTH only — do NOT call it to understand org STRUCTURE or to gather context for CREATING an app (where apps live, which accounts/namespaces exist, where to place a new one): navigate that headlessly with entity_list (account → namespace → application), which renders no panel. Also does NOT show one app\'s detail (use application_get) or logs/metrics, and for the latest release/build ACROSS apps use entity_list and compute it. Read-only.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "overview",
     errorKey: "overview.errorLabel",

package/dist/tools/params.js

@@ -24,7 +24,7 @@ function valueSummary(parameter, scopeNameById) {
 export const paramsTool = defineTool({
     name: TOOL.applicationParameterList,
     title: "Parameters",
-    description: "List an application's configuration parameters and every value they hold across scopes and dimensions (env vars / files; secret values are masked). Pass `scope` to resolve the single effective value per parameter for that scope. Use application_parameter_create to add or change them.",
+    description: 'List ONE application\'s configuration parameters and EVERY value each holds across scopes and dimensions (env vars / files; secret values are masked, never shown in plaintext), rendered as a PANEL. Use it for "what env vars does this app have", "show the config", "what\'s DATABASE_URL set to". Pass `scope` to have the PLATFORM resolve the single effective value per parameter for that scope (it collapses scope value › most-specific dimension match › app default — never reimplement that precedence yourself). Does NOT change anything — use application_parameter_create to add/update, application_parameter_delete to remove. Read-only.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "params",
     errorKey: "params.errorLabel",
@@ -61,7 +61,13 @@ export const paramsTool = defineTool({
             resolvedScope = { id: picked.scope.id, name: picked.scope.name };
             readNrn = picked.scope.nrn;
         }
-        const parameters = await listParameters(context.np, readNrn, { offset: args.offset });
+        // A scope read interpolates so the platform resolves the EFFECTIVE value per parameter (scope
+        // value › most-specific dimension match › app default) — app-level/dimension values inherit
+        // down. Without it a scope NRN returns only values pinned at that exact scope (usually none).
+        const parameters = await listParameters(context.np, readNrn, {
+            offset: args.offset,
+            interpolate: Boolean(resolvedScope),
+        });
         if (parameters === undefined) {
             return reply(translate("params.unavailable") + linkLine(translate("params.viewInDashboard"), dashboard), { available: false, ...appRef });
         }

package/dist/tools/playbook.js

@@ -14,7 +14,7 @@ const playbookBody = (markdown) => markdown.replace(/^---\n[\s\S]*?\n---\n?/, ""
 export const playbookGetTool = defineTool({
     name: TOOL.playbookGet,
     title: "Operating playbooks",
-    description: "Read a nullplatform operating playbook — the methodology to follow BEFORE the matching non-trivial work (e.g. deploying-safely before a deploy, incident-response when something is broken, configuring-safely before changing parameters or secrets). The server instructions carry the full catalog; call this with no name to list them too.",
+    description: 'Read a nullplatform operating PLAYBOOK — model-facing methodology for RISKY or MULTI-STEP work: deploying-safely (canary steps + metric gates for a production rollout), incident-response (triage when something is broken), configuring-safely (changing parameters or secrets carefully). Renders NO panel — prose for YOU to consult, NOT a step you must run before every action. Reach for it only when you genuinely want the grounded procedure for a non-trivial operation; for a direct, simple command ("deploy", "set X", "roll back") just use that action\'s tool — do not detour here first. Call with no `name` to list the catalog (also in the server instructions).',
     annotations: { readOnlyHint: true },
     // No widget: a playbook is model-facing methodology prose, not an interactive entity — it
     // renders as text (the markdown below) for the model to read and act on. See CLAUDE.md.

package/dist/tools/releases.js

@@ -12,7 +12,7 @@ import { appArg, offsetArg, pageOf, requireApp } from "./shared.js";
 export const releasesTool = defineTool({
     name: TOOL.applicationReleaseList,
     title: "Releases",
-    description: "List an application's releases — semver, status (active/deprecated/unstable/failed), the build each pins, and age. Use to pick a release to deploy or promote, or to see what's shippable.",
+    description: "List ONE application's releases as a PANEL for the user — semver, status (active/deprecated/unstable/failed), the build each pins, and age. Use to pick a release to deploy or promote, or to see what's shippable. Do NOT call this once per app to compare across apps (it renders a panel each time): for an AGGREGATE like 'the latest release across all my apps' use entity_list (entity:\"release\"), gather headlessly, and compute the answer.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "releases",
     errorKey: "releaseList.errorLabel",

package/dist/tools/services.js

@@ -13,7 +13,7 @@ import { appArg, requireApp } from "./shared.js";
 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.",
+    description: 'List the dependency services (databases, queues, caches…) attached to ONE application, plus the catalog of dependency types available to provision, rendered as a PANEL. Use it for "what databases/queues does this app use", "show its dependencies", "what can I provision". To provision a new dependency use application_service_create; to connect one to a scope use application_link_create. Read-only — it does not provision or link anything itself.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "services",
     errorKey: "services.errorLabel",

package/dist/tools/set-params.js

@@ -5,10 +5,26 @@ import { listParameters, listScopes, setParameters } from "../np/journey.js";
 import { defineTool, errorMessage, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 import { appArg, pickScope, requireApp } from "./shared.js";
+/** Honest upsert summary: "created N" / "updated N" / a mixed count — so a retry reads as "0 new". */
+function paramSummary(result, app, names) {
+    if (result.updated === 0) {
+        return plural(result.created, "setParams.created.one", "setParams.created.many", { app, names });
+    }
+    if (result.created === 0) {
+        return plural(result.updated, "setParams.updated.one", "setParams.updated.many", { app, names });
+    }
+    return translate("setParams.mixed", {
+        created: result.created,
+        updated: result.updated,
+        total: result.created + result.updated,
+        app,
+        names,
+    });
+}
 export const setParamsTool = defineTool({
     name: TOOL.applicationParameterCreate,
     title: "Set parameters",
-    description: "Create or update application configuration parameters (environment variables or files; mark secrets). Target a value at the application (default — every scope), by dimension (applies to any matching scope), or pinned to one scope. Values apply on the NEXT deploy.",
+    description: 'Create or UPDATE application configuration parameters — environment variables or files, secrets supported (stored masked, updatable; NOT write-once). A parameter is a value-SET: one definition holds many values keyed by target. Target a value at the APPLICATION (default — every scope), BY DIMENSION (e.g. environment=production — applies to any matching scope), or pinned to ONE scope (dimensions and a scope are mutually exclusive). Use it for "set DATABASE_URL", "add an env var", "change a secret", "set a prod-only value". Values apply on the NEXT deploy. Renders the parameters panel after applying. Convergent: reuses the existing definition and updates in place rather than duplicating. View current values with application_parameter_list; remove with application_parameter_delete.',
     annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: true },
     widget: "params",
     errorKey: "setParams.errorLabel",
@@ -72,24 +88,7 @@ export const setParamsTool = defineTool({
             const result = await setParameters(context.np, app.nrn, inputs);
             const names = args.params.map((param) => `\`${param.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
-                ? plural(result.created, "setParams.created.one", "setParams.created.many", {
-                    app: app.name,
-                    names,
-                })
-                : result.created === 0
-                    ? plural(result.updated, "setParams.updated.one", "setParams.updated.many", {
-                        app: app.name,
-                        names,
-                    })
-                    : translate("setParams.mixed", {
-                        created: result.created,
-                        updated: result.updated,
-                        total,
-                        app: app.name,
-                        names,
-                    });
+            const summary = paramSummary(result, app.name, names);
             // Mirror the params widget's shape so the SAME panel renders the resulting set (with its
             // scope picker + add affordance) after the write; the markdown stays the plain confirmation.
             const parameters = await listParameters(context.np, app.nrn).catch(() => undefined);

package/dist/tools/shared.js

@@ -75,12 +75,64 @@ export async function requireApp(context, args) {
     }
     return { out: fail(notFoundMessage(resolution), { not_found: true }) };
 }
+/**
+ * The ONE pre-selection rule for every create/fill form selector (namespace, template, service spec,
+ * scope type…). It turns the model's soft inference — an explicit id, or the free-text stack/type it
+ * reasoned out of the conversation — into a concrete option, or `undefined` when it's a genuine
+ * unhinted choice. It NEVER returns an arbitrary first entry: a wrong pre-selection is worse than an
+ * honest blank. Division of labour (see CLAUDE.md): the MODEL infers (it holds the context) and passes
+ * the hint as a tool arg; the TOOL resolves it here; the WIDGET only mirrors the result.
+ *
+ * Order, most to least certain: explicit id → exact name → every query token present in the option's
+ * haystack (fuzzy "sql database") → an option name contained in the hint ("Golang Hexagonal - API" ⊃
+ * the "golang-hexagonal" template) → with `pinOnly`, the sole candidate. `haystack` widens the
+ * searchable text per field (name + tags, name + category…); it defaults to the option's name.
+ */
+export function resolveChoice(options, hint, settings = {}) {
+    if (hint.id != null) {
+        const byId = options.find((option) => option.id === hint.id);
+        if (byId)
+            return byId;
+    }
+    const query = hint.text?.trim().toLowerCase();
+    if (query) {
+        const haystackOf = settings.haystack ?? ((option) => option.name);
+        const exact = options.filter((option) => option.name.trim().toLowerCase() === query);
+        if (exact.length === 1)
+            return exact[0];
+        const tokens = query.split(/\s+/).filter(Boolean);
+        const tokenMatch = options.filter((option) => {
+            const haystack = haystackOf(option).toLowerCase();
+            return tokens.every((token) => haystack.includes(token));
+        });
+        if (tokenMatch.length === 1)
+            return tokenMatch[0];
+        const contained = options.filter((option) => {
+            const name = option.name.trim().toLowerCase();
+            return name.length >= 2 && query.includes(name);
+        });
+        if (contained.length === 1)
+            return contained[0];
+    }
+    if (settings.pinOnly && options.length === 1)
+        return options[0];
+    return undefined;
+}
 /**
  * Match scopes by name OR by dimensions: "dev" (name substring), "production"
  * (dimension value substring), "environment=production" (exact key=value).
  */
 export function matchScopes(scopes, wanted) {
     const query = wanted.trim().toLowerCase();
+    // "#<id>" — an exact, unambiguous scope id. This is the form widgets send from their scope picker
+    // (the option value is the numeric id) and a documented `scope` arg form. Matched FIRST so a numeric
+    // id never falls through to name/substring matching — which can't see `id` and would return nothing,
+    // failing the call before it ever reads parameters (the widget scope-resolve bug).
+    const byId = /^#(\d+)$/.exec(query);
+    if (byId) {
+        const id = Number(byId[1]);
+        return scopes.filter((scope) => scope.id === id);
+    }
     const keyValue = /^([a-z0-9_-]+)\s*=\s*(.+)$/.exec(query);
     if (keyValue?.[1] && keyValue[2] !== undefined) {
         const [, dimensionKey, dimensionValue] = keyValue;

package/dist/tools/status.js

@@ -25,9 +25,9 @@ async function scopeViews(context, applicationId) {
     });
 }
 /**
- * Build an application's full status view (the np-panel overview payload). Exported so write
+ * Build an application's full status view (the app overview payload). Exported so write
  * tools that should hand off into the same live panel — e.g. create-scope, after provisioning a
- * new deploy target — can return this exact shape and let np-panel render the app + Deploy.
+ * new deploy target — can return this exact shape and let the status panel render the app + Deploy.
  */
 export async function buildAppStatus(context, app) {
     const [views, builds, releases, orgSlug] = await Promise.all([
@@ -41,9 +41,9 @@ export async function buildAppStatus(context, app) {
 export const statusTool = defineTool({
     name: TOOL.applicationGet,
     title: "Application status",
-    description: "THE place to start. Shows an application's full picture: scopes with what's live on each (release + traffic), latest build, latest release, and the one obvious next action. Call with no arguments inside a repo to use the linked app. Pass deployment:<id> to watch one rollout in detail.",
+    description: 'THE place to start for ONE application\'s live status — renders a status PANEL: each scope with what\'s live on it (release + traffic), the latest build, the latest release, and the single obvious next action. Use it for "what\'s the status of my app", "what\'s deployed where", "is it healthy" — a STATUS question. For a DIRECT action ("deploy", "send traffic", "show logs/metrics") reach for that action\'s own tool instead of starting here; only read status first when you genuinely need to see state before acting. To LOOK UP a field for your OWN work — the repository_url to clone/edit, the app id, where it lives, its nrn — read it HEADLESSLY with entity_get (entity:"application", id:<id>); do NOT render this status panel just to grab a value. Call with NO arguments inside a git repo to use the linked app; pass `app` (name or "#id") for a different one; pass `deployment:<id>` to watch one rollout\'s live detail. Does NOT return logs, metrics, parameters, or a build\'s assets — use application_log_list / application_metric_list / application_parameter_list / application_build_list for those. Do NOT loop this to WAIT for a build or deployment to finish: it repaints the whole panel every call (stacking duplicate panels) — poll headlessly with entity_get (entity:"build" or "deployment", id:<id>) instead, and show this panel once at the end.',
     annotations: { readOnlyHint: true, openWorldHint: true },
-    widget: "np-panel",
+    widget: "status",
     errorKey: "status.errorLabel",
     inputSchema: {
         app: appArg,

package/dist/tools/traffic.js

@@ -6,12 +6,43 @@ import { renderRollout } from "../render.js";
 import { defineTool, fail, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 import { appArg, delays, requireApp, sleep } from "./shared.js";
+/**
+ * Find which deployment to steer. An explicit `deployment_id` wins; otherwise resolve the app and
+ * fan out across its scopes for the single non-terminal rollout. Mirrors requireApp's shape:
+ * returns { deploymentId, scope } or an `out` reply — a `fail` when nothing is in flight, or the
+ * disambiguation table when several rollouts are active at once (pass deployment_id to pick one).
+ */
+async function resolveActiveRollout(context, args) {
+    if (args.deployment_id)
+        return { deploymentId: args.deployment_id };
+    const resolved = await requireApp(context, args);
+    if ("out" in resolved)
+        return { out: resolved.out };
+    const scopes = await listScopes(context.np, resolved.app.id);
+    const activeRollouts = [];
+    for (const candidate of scopes) {
+        const deployments = await listScopeDeployments(context.np, candidate.id, 3);
+        const active = deployments.find((deployment) => !isDeploymentTerminal(deployment.status));
+        if (active)
+            activeRollouts.push({ deploymentId: active.id, scope: candidate, status: active.status });
+    }
+    if (activeRollouts.length === 0) {
+        return { out: fail(translate("traffic.noActive", { app: resolved.app.name })) };
+    }
+    if (activeRollouts.length > 1) {
+        return {
+            out: reply(`${translate("traffic.several")}\n\n${table([translate("header.deployment"), translate("header.scope"), translate("header.status")], activeRollouts.map((rollout) => [`#${rollout.deploymentId}`, rollout.scope.name, rollout.status]))}`),
+        };
+    }
+    const only = activeRollouts[0]; // length === 1 checked above
+    return { deploymentId: only.deploymentId, scope: only.scope };
+}
 export const trafficTool = defineTool({
     name: TOOL.applicationDeploymentUpdate,
     title: "Update traffic",
-    description: 'Drive an in-flight rollout: move traffic to the new version (percent snaps to 0,1,5,10,25,50,75,90,95,99,100), finalize it (action:"finalize" — retire the old version), or roll it back (action:"rollback" — traffic returns to the old version). Finds the app\'s active deployment automatically.',
+    description: 'Drive an IN-FLIGHT rollout — the step AFTER application_deployment_create. Call it DIRECTLY with `percent` (snaps to 0,1,5,10,25,50,75,90,95,99,100) to move traffic, action:"finalize" to retire the old version, or action:"rollback" to return traffic to the previous version (the safety hatch). You do NOT need to read status or look up a deployment id first — it finds the app\'s single active rollout automatically (pass `deployment_id` only when several are in flight at once). Use it for "send 25% traffic", "promote to 100%", "finalize", "roll back". Renders the live rollout panel. Call it ONLY for a single move the user explicitly named — in a ui client the rollout panel application_deployment_create renders already has a traffic slider, auto-advance (ramps to 100%) and finalize/rollback that drive this for the user; do NOT call this yourself to step 25 → 50 → 100 → finalize (each call stacks another rollout panel). Does NOT create a deployment — use application_deployment_create first; this only steers one that already exists.',
     annotations: { destructiveHint: true, openWorldHint: true },
-    widget: "np-panel",
+    widget: "status",
     errorKey: "traffic.errorLabel",
     inputSchema: {
         app: appArg,
@@ -23,30 +54,11 @@ export const trafficTool = defineTool({
         if (args.percent === undefined && !args.action) {
             return fail(translate("traffic.sayWhat"));
         }
-        let deploymentId = args.deployment_id;
-        let scope;
-        if (!deploymentId) {
-            const resolved = await requireApp(context, args);
-            if ("out" in resolved)
-                return resolved.out;
-            const scopes = await listScopes(context.np, resolved.app.id);
-            const activeRollouts = [];
-            for (const candidate of scopes) {
-                const deployments = await listScopeDeployments(context.np, candidate.id, 3);
-                const active = deployments.find((deployment) => !isDeploymentTerminal(deployment.status));
-                if (active)
-                    activeRollouts.push({ deploymentId: active.id, scope: candidate, status: active.status });
-            }
-            if (activeRollouts.length === 0) {
-                return fail(translate("traffic.noActive", { app: resolved.app.name }));
-            }
-            if (activeRollouts.length > 1) {
-                return reply(`${translate("traffic.several")}\n\n${table([translate("header.deployment"), translate("header.scope"), translate("header.status")], activeRollouts.map((rollout) => [`#${rollout.deploymentId}`, rollout.scope.name, rollout.status]))}`);
-            }
-            const only = activeRollouts[0]; // length === 1 checked above
-            deploymentId = only.deploymentId;
-            scope = only.scope;
-        }
+        const rollout = await resolveActiveRollout(context, args);
+        if ("out" in rollout)
+            return rollout.out;
+        const deploymentId = rollout.deploymentId;
+        let scope = rollout.scope;
         if (args.action === "finalize")
             await deploymentAction(context.np, deploymentId, "finalize");
         else if (args.action === "rollback")

package/dist/tools/update-link.js

@@ -15,7 +15,7 @@ import { appArg, requireApp } from "./shared.js";
 export const updateLinkTool = defineTool({
     name: TOOL.applicationLinkUpdate,
     title: "Run link action",
-    description: "Run a custom action on a link (a service↔application connection) — the platform-team-defined operations its link specification exposes. Pass `link` to choose which one (by name) and `action` to choose which action; call WITHOUT `run:true` first to open the form. Not every link has custom actions.",
+    description: 'Run a CUSTOM ACTION on a link (a service↔application connection) — the platform-team-defined operations its link specification exposes. Use it for "run the <action> on the <link>". Pass `link` (by name) and `action`; call WITHOUT `run:true` first to open the form, the user confirms by submitting. Not every link has custom actions. Renders the action panel. Not for creating (application_link_create) or deleting (application_link_delete) a link.',
     annotations: { destructiveHint: false, openWorldHint: true },
     widget: "service-action",
     errorKey: "runAction.errorLabel",

package/dist/tools/update-service.js

@@ -16,7 +16,7 @@ import { appArg, requireApp } from "./shared.js";
 export const updateServiceTool = defineTool({
     name: TOOL.applicationServiceUpdate,
     title: "Run service action",
-    description: "Run a custom action on a provisioned service — the platform-team-defined operations a service exposes (e.g. a Postgres database's DML/DDL query runners). Pass `service` to choose which one (by name) and `action` to choose which action; call WITHOUT `run:true` first to open the form, the user confirms by submitting it. A custom action is an explicit operation (not idempotent), so it never runs without that submit.",
+    description: 'Run a CUSTOM ACTION on a provisioned service — the platform-team-defined operations a service exposes (e.g. a Postgres database\'s DML/DDL query runners). Use it for "run a query on <db>", "run the <action> on <service>". Pass `service` (by name) and `action`; call WITHOUT `run:true` first to open the form, the user confirms by submitting. A custom action is an explicit operation (NOT idempotent), so it never runs without that submit. Renders the action panel. Not for provisioning (application_service_create) or deleting (application_service_delete) a service.',
     annotations: { destructiveHint: false, openWorldHint: true },
     widget: "service-action",
     errorKey: "runAction.errorLabel",

package/dist/ui.js

@@ -13,7 +13,7 @@ import { EXTENSION_ID, RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY, registerAppRes
 export { EXTENSION_ID, RESOURCE_MIME_TYPE };
 /** Every widget this server can serve, by file name -> human title. */
 export const WIDGETS = {
-    "np-panel": "Application panel",
+    status: "Application panel",
     "create-app": "Create application",
     params: "Parameters",
     logs: "Logs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullplatform/mcp",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "nullplatform from your code assistant — an MCP server that replaces the dashboard for the everyday developer journey",
   "license": "MIT",
   "author": "nullplatform",
@@ -41,14 +41,17 @@
     "pretest": "node scripts/build-widgets.mjs",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
+    "eval": "tsx scripts/eval/run.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p src/widgets-react/tsconfig.json --noEmit"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "pino": "^10.3.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
+    "@anthropic-ai/sdk": "^0.105.0",
     "@biomejs/biome": "2.4.16",
     "@jsonforms/core": "^3.5.1",
     "@jsonforms/react": "^3.5.1",
@@ -56,6 +59,7 @@
     "@types/node": "^20.14.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
+    "dotenv": "^17.4.2",
     "esbuild": "^0.28.0",
     "happy-dom": "^20.10.3",
     "preact": "^10.29.2",