@nullplatform/mcp 0.1.12 → 0.1.14

package/dist/tools/metrics.js

@@ -8,7 +8,7 @@ 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.",
+    description: 'The golden signals of ONE scope — throughput (rpm), response time, error rate, CPU, memory — with sparkline trends, rendered as a metrics PANEL. Use it for "how is it performing?", "is it healthy?", or to watch a scope during a rollout. Pick the `window` (1h/3h/24h/7d, default 3h); omit `scope` to use the only one. Does NOT return logs or deploy state — use application_log_list or application_get. Read-only.',
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "metrics",
     errorKey: "metrics.errorLabel",

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 for org-wide 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). Does NOT show one app\'s full detail (use application_get), nor logs/metrics; to find the latest release or build ACROSS apps, gather headlessly with entity_list and compute it — don\'t call this. 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",

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

@@ -8,7 +8,7 @@ import { appArg, pickScope, 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). 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",

package/dist/tools/shared.js

@@ -75,6 +75,49 @@ 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).

package/dist/tools/status.js

@@ -41,7 +41,7 @@ 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. 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",
     errorKey: "status.errorLabel",

package/dist/tools/traffic.js

@@ -9,7 +9,7 @@ import { appArg, delays, requireApp, sleep } from "./shared.js";
 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. 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",
     errorKey: "traffic.errorLabel",

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullplatform/mcp",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "nullplatform from your code assistant — an MCP server that replaces the dashboard for the everyday developer journey",
   "license": "MIT",
   "author": "nullplatform",
@@ -41,6 +41,7 @@
     "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": {
@@ -49,6 +50,7 @@
     "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 +58,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",