@nullplatform/mcp 0.1.11 → 0.1.13

package/dist/i18n.js

@@ -354,6 +354,8 @@ const english = {
     "createApp.errorLabel": "Couldn't create the application",
     // — playbook_get tool —
     "playbook.errorLabel": "Couldn't load the playbook",
+    "entityList.errorLabel": "Couldn't list that",
+    "entityGet.errorLabel": "Couldn't read that",
     // — application_scope_create tool —
     "createScope.whichType": "Which scope type for **{name}**?",
     "createScope.typeHint": "name a scope type for **{name}** to create it.",
@@ -720,6 +722,8 @@ const spanish = {
     "createApp.errorLabel": "No pude crear la aplicación",
     // — playbook_get tool —
     "playbook.errorLabel": "No pude cargar el playbook",
+    "entityList.errorLabel": "No pude listar eso",
+    "entityGet.errorLabel": "No pude leer eso",
     "createScope.whichType": "¿Qué tipo de scope para **{name}**?",
     "createScope.typeHint": "nombrá un tipo de scope para **{name}** para crearlo.",
     "createScope.noTypes": 'No hay tipos de scope disponibles — pasá type explícito (p. ej. type:"web_pool").',
@@ -1101,6 +1105,8 @@ const portuguese = {
     "createApp.errorLabel": "Não foi possível criar a aplicação",
     // — playbook_get tool —
     "playbook.errorLabel": "Não foi possível carregar o playbook",
+    "entityList.errorLabel": "Não foi possível listar isso",
+    "entityGet.errorLabel": "Não foi possível ler isso",
     // — application_scope_create tool —
     "createScope.whichType": "Qual tipo de scope para **{name}**?",
     "createScope.typeHint": "informe um tipo de scope para **{name}** para criá-lo.",

package/dist/np/journey.js

@@ -1,3 +1,18 @@
+/**
+ * Generic entity navigation. The platform's REST surface is uniform — every entity in the core tree
+ * lists as `GET /<entity>?<parent>_id=<id>` (returning `{results}`) and reads as `GET /<entity>/<id>`.
+ * One pair of accessors therefore resolves the whole hierarchy (organization → account → namespace →
+ * application → scope → deployment, plus build/release under application) without a per-entity function.
+ * (NRN-scoped resources — parameters/services/links/approvals — use a different addressing scheme and
+ * keep their own typed functions.) This is the typed seam the generic read tools call.
+ */
+export async function listEntity(np, entity, query) {
+    const page = await np.get(`/${entity}`, query);
+    return Array.isArray(page) ? page : (page.results ?? []);
+}
+export async function getEntity(np, entity, id) {
+    return np.get(`/${entity}/${id}`);
+}
 /** Traffic percentages the platform accepts (same marks the dashboard slider snaps to). */
 export const TRAFFIC_MARKS = [0, 1, 5, 10, 25, 50, 75, 90, 95, 99, 100];
 export const snapTraffic = (percent) => TRAFFIC_MARKS.reduce((closest, mark) => (Math.abs(mark - percent) < Math.abs(closest - percent) ? mark : closest), 0);

package/dist/surfaces/developer.js

@@ -14,7 +14,9 @@ Every tool accepts \`language\`: ALWAYS set it to the language the user is conve
 
 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. Its panel is an interactive FORM that collects the namespace, template and repository. INFER the best-fitting namespace and account from what the app is FOR — a demo → a demos/examples namespace, a backend service → a services namespace — and pass them as \`namespace\`/\`account\` (plus \`name\` if given) so the form opens pre-selected on your inference; the user can still change it in the form. Do NOT gather those details in conversation first, and while the 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, and a separate "which namespace?" question on top of it is wrong. Just call \`application_create\` and let it drive; react only to what it reports back.
+When the user wants to create, scaffold, set up or import an application, drive it through the \`application_create\` FORM — its panel collects the namespace, template and repository. Two rules keep this clean. (1) Settle any genuinely STRUCTURAL question about WHAT to build — e.g. "is this one app or two, a frontend and an API?" — in one short turn BEFORE opening any form, since each app gets its own form. (2) Never gather FORM-FIELD details (namespace, template, new-vs-import repository, monorepo path) in conversation: INFER the best-fitting namespace and account from what the app is FOR — a demo → a demos/examples namespace, a backend service → a services namespace — and pass them as \`namespace\`/\`account\` (plus \`name\` if given) so the form opens pre-selected on your inference; the user changes it in the form if they want. Once a form is on screen, NEVER ask a clarifying question or use any question-asking tool about a field it covers — above all NEVER ask "which namespace?". And NEVER open the form, ask a question, then re-open the form: that form → question → form flow is the single worst thing you can do here. Open it once, pre-filled, and let it drive; react only to what it reports back.
+
+Creating a NEW app is the PLATFORM's job, never a local scaffold. nullplatform creates the GitHub repository from a template and provisions it — so for a new app you must NEVER run a generic brainstorm/design/implementation process, never \`git init\`, never create an empty repo, and never write code locally first. The flow is: settle what to build → \`application_create\` with a new repo and ONE OF THE PLATFORM'S TEMPLATES → the platform creates the repo on GitHub → THEN clone it, add code, push so CI builds. The available STACKS are exactly those templates for the chosen namespace — never invent or offer a stack of your own ("Next.js", "Express", …); the form lists the real templates, choose from those. And do NOT fire the rendering reads (\`application_list\`/\`application_get\`/\`application_build_list\`…) just to orient yourself before any of this — each renders a panel the user didn't ask for. To gather data for your OWN reasoning, navigate the entity tree headlessly with \`entity_list\` and \`entity_get\` — read-only, DATA-only, NO panel. \`entity_list\` lists a collection scoped to its parent (the tree is organization → account → namespace → application → {scope, build, release}; scope → deployment): e.g. \`entity_list entity:"application" parent_type:"namespace" parent_id:11\`, then \`entity_list entity:"build" parent_type:"application" parent_id:123\`. \`entity_get entity:"application" id:123\` reads one. Parameters, services, links and approvals list the same way under an application or scope (\`entity_list entity:"parameter" parent_type:"application" parent_id:123\`). That is how you learn where apps live, how they're named, and what's deployable without putting a list on the user's screen. Reserve the rendered reads (\`application_list\`/\`application_get\`/\`application_build_list\`/…) for when the user actually wants to SEE that data.
 
 Typical flows:
 - Ship: \`application_deployment_create\` (picks the latest build, cuts the release for you) → \`application_deployment_update percent:25/50/100\` → \`application_deployment_update action:"finalize"\`.

package/dist/tool-names.js

@@ -30,5 +30,7 @@ export const TOOL = {
     applicationParameterDelete: "application_parameter_delete",
     applicationApprovalList: "application_approval_list",
     organizationGet: "organization_get",
+    entityList: "entity_list",
+    entityGet: "entity_get",
     playbookGet: "playbook_get",
 };

package/dist/tools/entity-get.js

@@ -0,0 +1,36 @@
+import { z } from "zod";
+import { getEntity } from "../np/journey.js";
+import { defineTool, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+/**
+ * Generic read-only, DATA-only GET — NO widget, so nothing renders. Reads ONE core entity by id
+ * (`GET /<entity>/<id>`), the drill-in companion to `entity_list`. The model uses it to inspect a
+ * specific node while navigating the tree, without putting a panel on the user's screen. The rendered
+ * reads (application_get/…) stay for when the user wants to SEE it. See CLAUDE.md (data-only read).
+ */
+const ENTITIES = [
+    "organization",
+    "account",
+    "namespace",
+    "application",
+    "scope",
+    "build",
+    "release",
+    "deployment",
+];
+export const entityGetTool = defineTool({
+    name: TOOL.entityGet,
+    title: "Read an entity (data)",
+    description: 'Read-only, DATA-only fetch of ONE core entity by id — returns structuredContent and renders NO panel. Pass `entity` and `id` (e.g. entity:"application" id:123). Use this to drill into a specific entity while navigating with entity_list; use the rendered reads (application_get/…) when the USER wants to SEE it. Entities: organization, account, namespace, application, scope, build, release, deployment. (parameters/services/links/approvals have their own tools.)',
+    annotations: { readOnlyHint: true },
+    // No widget on purpose: data-only. See CLAUDE.md (the data-only read pattern).
+    errorKey: "entityGet.errorLabel",
+    inputSchema: {
+        entity: z.enum(ENTITIES).describe("Which entity type to read."),
+        id: z.number().describe("The entity's id."),
+    },
+    async handler(args, context) {
+        const result = await getEntity(context.np, args.entity, args.id);
+        return reply(`${args.entity} #${args.id}.`, { entity: args.entity, result });
+    },
+});

package/dist/tools/entity-list.js

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { getApplication, getScope, listApprovals, listEntity, listLinks, listParameters, listServices, } from "../np/journey.js";
+import { defineTool, fail, reply } from "../tool.js";
+import { TOOL } from "../tool-names.js";
+/**
+ * Generic read-only, DATA-only LIST — NO widget, so nothing renders. One tool navigates the whole
+ * entity tree: pick an `entity` and the `parent_type`/`parent_id` it lives under. Two addressing
+ * schemes hide behind one uniform interface — the REST tree lists as `GET /<entity>?<parent>_id=<id>`,
+ * and the NRN-scoped resources (parameter/service/link/approval) list by the parent's NRN (resolved
+ * from `parent_id`, or passed directly as `nrn`). Each dispatches to its existing typed function in
+ * journey.ts (tools never touch NpClient directly). The model uses it to traverse the org and gather
+ * context without a panel; pair it with `entity_get` to drill into one. This is the data-only read
+ * pattern (see CLAUDE.md).
+ */
+/** REST-addressed collections — listed by `<parent_type>_id`. */
+const REST_ENTITIES = [
+    "account",
+    "namespace",
+    "application",
+    "scope",
+    "build",
+    "release",
+    "deployment",
+];
+/** NRN-addressed collections — listed by the parent's NRN (resolved from parent_id, or given as nrn). */
+const NRN_ENTITIES = ["parameter", "service", "link", "approval"];
+const ENTITIES = [...REST_ENTITIES, ...NRN_ENTITIES];
+/** The parents a collection can hang under — its id (REST) or its NRN (nrn-scoped) scopes the list. */
+const PARENTS = ["organization", "account", "namespace", "application", "scope"];
+const NRN_ENTITY_SET = new Set(NRN_ENTITIES);
+/** Resolve the NRN that scopes an nrn-addressed collection: the model's `nrn`, or its parent's. */
+async function resolveNrn(context, args) {
+    if (args.nrn)
+        return args.nrn;
+    if (args.parent_id === undefined)
+        return undefined;
+    if (args.parent_type === "application")
+        return (await getApplication(context.np, args.parent_id)).nrn;
+    if (args.parent_type === "scope")
+        return (await getScope(context.np, args.parent_id)).nrn;
+    return undefined;
+}
+/** List an nrn-scoped resource via its existing typed function (a different addressing scheme to REST). */
+async function listByNrn(context, entity, nrn) {
+    switch (entity) {
+        case "parameter":
+            return (await listParameters(context.np, nrn)) ?? [];
+        case "service":
+            return listServices(context.bff, nrn);
+        case "link":
+            return listLinks(context.np, nrn);
+        case "approval":
+            return listApprovals(context.bff, nrn);
+        default:
+            return [];
+    }
+}
+export const entityListTool = defineTool({
+    name: TOOL.entityList,
+    title: "List entities (data)",
+    description: 'Read-only, DATA-only list of an entity scoped to its parent — returns structuredContent and renders NO panel, so you can navigate the org and gather context without putting a widget on the user\'s screen. REST tree: organization → account → namespace → application → {scope, build, release}; scope → deployment — pass `entity` plus the `parent_type`+`parent_id` it lives under (e.g. entity:"build" parent_type:"application" parent_id:123; listing `account` needs no parent). NRN-scoped resources (parameter, service, link, approval) live under an application or scope — pass parent_type:"application"|"scope" + parent_id (the NRN is resolved for you), or `nrn` directly. Use this to reason for yourself; use the rendered reads (application_list/application_build_list/…) when the USER wants to SEE the data. For one entity by id use entity_get.',
+    annotations: { readOnlyHint: true },
+    // No widget on purpose: data-only navigation. See CLAUDE.md (the data-only read pattern).
+    errorKey: "entityList.errorLabel",
+    inputSchema: {
+        entity: z
+            .enum(ENTITIES)
+            .describe("Collection to list. REST tree: account, namespace, application, scope, build, release, deployment. NRN-scoped: parameter, service, link, approval."),
+        parent_type: z
+            .enum(PARENTS)
+            .optional()
+            .describe("The parent the collection lives under. REST: its `<parent_type>_id` scopes the list (required except `account`). NRN-scoped: application|scope, used to resolve the NRN."),
+        parent_id: z.number().optional().describe("The parent entity's id."),
+        nrn: z
+            .string()
+            .optional()
+            .describe("For nrn-scoped entities (parameter/service/link/approval): the scoping NRN directly, if you have it; otherwise pass parent_type + parent_id and it's resolved for you."),
+        limit: z.number().optional().describe("Max rows (default 100) — REST collections only."),
+    },
+    async handler(args, context) {
+        if (NRN_ENTITY_SET.has(args.entity)) {
+            const nrn = await resolveNrn(context, args);
+            if (!nrn) {
+                return fail(`Listing ${args.entity} needs an NRN — pass nrn, or parent_type:"application"|"scope" + parent_id.`);
+            }
+            const nrnResults = await listByNrn(context, args.entity, nrn);
+            return reply(`${nrnResults.length} ${args.entity}(s).`, { entity: args.entity, results: nrnResults });
+        }
+        const query = { limit: args.limit ?? 100 };
+        if (args.parent_type && args.parent_id !== undefined) {
+            query[`${args.parent_type}_id`] = args.parent_id;
+        }
+        else if (args.entity === "account") {
+            query.organization_id = (await context.org.getSkeleton()).orgId;
+        }
+        const results = await listEntity(context.np, args.entity, query);
+        return reply(`${results.length} ${args.entity}(s).`, { entity: args.entity, results });
+    },
+});

package/dist/tools/index.js

@@ -10,6 +10,8 @@ import { deleteParamTool } from "./delete-param.js";
 import { deleteServiceTool } from "./delete-service.js";
 import { deployTool } from "./deploy.js";
 import { deploymentsTool } from "./deployments.js";
+import { entityGetTool } from "./entity-get.js";
+import { entityListTool } from "./entity-list.js";
 import { findAppsTool } from "./find-apps.js";
 import { logsTool } from "./logs.js";
 import { metricsTool } from "./metrics.js";
@@ -45,6 +47,8 @@ export const tools = [
     createAppTool,
     createScopeTool,
     approvalsTool,
+    entityListTool,
+    entityGetTool,
     servicesTool,
     createServiceTool,
     updateServiceTool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nullplatform/mcp",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "nullplatform from your code assistant — an MCP server that replaces the dashboard for the everyday developer journey",
   "license": "MIT",
   "author": "nullplatform",