@nullplatform/mcp 0.1.1 → 0.1.3

package/README.md

@@ -1,25 +1,35 @@
-# ai-mcp — nullplatform from your code assistant
-
-An MCP server that turns your code assistant (Claude Code, Cursor, Windsurf, …) into the
-**frontend for nullplatform**. Status, deploys, traffic, rollbacks, logs and config — from
-the place you already work, aware of the repo you're sitting in.
+<h2 align="center">
+    <a href="https://nullplatform.com" target="blank_">
+        <img height="100" alt="nullplatform" src="https://nullplatform.com/favicon/android-chrome-192x192.png" />
+    </a>
+    <br>
+    <br>
+    nullplatform MCP
+    <br>
+</h2>
+
+Turn your code assistant (Claude Code, Cursor, Claude Desktop, …) into the **frontend for nullplatform**.
+Deploy, move traffic, roll back, read logs and config — from the place you already work, aware of the
+repo you're in. Most actions take **zero arguments** inside a linked repo.
 
 ```text
-you  › deploy this
-claude › 🚀 Deploying #4312 on dev — ⏳ waiting for instances
+you    › deploy this
+claude › Deploying #4312 on dev — waiting for instances
          Created release 1.4.2 from build #991 (main @ab12cd34)
-         → Next: traffic percent:25 … traffic action:"finalize"
+         → Next: move traffic to 25%
 ```
 
-## Why
+## What it does
 
-The web dashboard walks you through create → build → release → scope → deploy → observe.
-Your assistant already knows your repo, your branch and what you just changed — so the same
-journey collapses into a sentence: most tools work with **zero arguments** inside a linked repo.
+- **Deploy & release** — ship the latest build, cut the release, walk traffic (canary → 100%), finalize or roll back.
+- **Observe** — recent builds, logs, and golden-signal metrics per scope.
+- **Configure** — environment variables & file parameters (secret values masked).
+- **"Is anything broken?"** — an org-wide digest across all your apps, no app name needed.
+- **Interactive** — on hosts that render MCP Apps (claude.ai, ChatGPT) you get live panels, a traffic slider, and log/metric views; terminals get clean markdown.
 
-## 60-second setup
+## Installation
 
-You need a nullplatform API key. The server runs locally via `npx` — no install, no clone.
+You need a nullplatform API key (create one in the dashboard, or run `np login`). It runs via `npx` — no install, no clone.
 
 **Claude Code**
 
@@ -27,7 +37,7 @@ You need a nullplatform API key. The server runs locally via `npx` — no instal
 claude mcp add nullplatform -e NP_API_KEY=<your-key> -- npx -y @nullplatform/mcp
 ```
 
-**Claude Desktop** — Settings → Developer → Edit Config (`claude_desktop_config.json`), then fully restart:
+**Claude Desktop** — Settings → Developer → Edit Config, then fully restart:
 
 ```json
 {
@@ -41,212 +51,37 @@ claude mcp add nullplatform -e NP_API_KEY=<your-key> -- npx -y @nullplatform/mcp
 }
 ```
 
-**Cursor / Windsurf / others** — same shape in their `mcp.json` (`command: "npx"`, `args: ["-y", "@nullplatform/mcp"]`).
+**Cursor / Windsurf / others** — same shape in their `mcp.json` (`command: "npx"`, `args: ["-y", "@nullplatform/mcp"]`, `env.NP_API_KEY`).
 
-**Remote/HTTP mode — bring your own key.** `npx -y @nullplatform/mcp --http 8080` → `http://host:8080/mcp`.
-The server holds **no credential** (it refuses to start if `NP_API_KEY`/`NP_BEARER` are in its
-environment). Every caller authenticates each request with their *own* key, so nullplatform's
-RBAC applies to each user individually — you can only see and do what your platform user can:
+## Usage
 
-```bash
-claude mcp add --transport http nullplatform https://host/mcp \
-  --header "Authorization: Bearer <your-NP_API_KEY>"
-```
+Open your assistant in a repo linked to a nullplatform application and just ask:
+
+- "what's the status?" · "is anything broken?"
+- "deploy this to dev"
+- "move traffic to 50%" · "finalize" · "roll me back"
+- "show logs" · "show metrics"
+- "set `DATABASE_URL` as a secret"
+
+Most tools infer the application from your git remote, so you rarely pass arguments. There are also three
+slash-command prompts: **/ship**, **/setup**, **/rollback**.
 
-A pre-issued JWT works in place of the api key, and hosts that reserve `Authorization` can send
-`X-NP-API-Key: <key>` instead. Unauthenticated requests get a `401` + `WWW-Authenticate` hint.
-`GET /healthz` is the unauthenticated liveness probe. Requests carrying a browser `Origin` are
-rejected unless allow-listed (DNS-rebinding guard), there's a 1 MiB body cap, and a generous
-per-IP rate limit (default 600 req/min, tunable) so a key-rotating caller can't amplify load
-against the platform's `/token`.
-
-**Deploy it behind a TLS-terminating reverse proxy on a trusted network** — every request
-carries a bearer credential, so plain HTTP must never be exposed. The proxy should also enforce
-its own per-IP rate limits and connection caps; the in-process limiter is a backstop, not a
-replacement. `X-Forwarded-For` is only trusted when `NP_TRUST_PROXY` is set.
-
-The api_key → access-token **exchange is the trust boundary** and is treated like one. The
-customer's key is **never retained**: it arrives with each request, exists only in that
-request's async scope, and is used at most once per expiry window to (re)exchange — what's
-cached per user (keyed by the key's SHA-256, never the key) is only the platform-issued
-short-lived access token. Every credential is verified with the platform *before* it reaches
-any tool (invalid ones stop at the edge as `401 invalid_token`), verification and exchange are
-single-flighted per credential across concurrent requests, rejected keys are negative-cached
-for a minute (they can't hammer the platform's `/token` or evict verified users), and secrets
-never appear in logs or error bodies.
-
-| Env | Meaning |
-| --- | --- |
-| `NP_API_KEY` | **stdio only** — your API key (exchanged for a bearer automatically) |
-| `NP_BEARER` | **stdio only** — a pre-issued token instead (expires; for quick tests) |
-| `NP_API_BASE` | Override the API host (default `https://api.nullplatform.com`) |
-| `NP_BFF_BASE` | Override the dashboard BFF host (metrics) |
-| `NP_ALLOWED_ORIGINS` | `--http` only: comma-separated browser origins allowed to call (server-to-server MCP clients send no Origin and always pass) |
-| `NP_RATE_LIMIT_RPM` | `--http` only: per-IP requests/minute (default `600`; `0` disables — rely on the fronting proxy then) |
-| `NP_TRUST_PROXY` | `--http` only: set to `1`/`true` to key the rate limit off `X-Forwarded-For` (only behind a proxy that sets it) |
-| `NP_LANG` | Fallback answer language (`en`/`es`). The real driver is the **conversation**: every tool takes a `language` argument the assistant sets to the language the user is speaking, which wins over `Accept-Language` (HTTP) and `NP_LANG`/`LANG` (stdio). |
-
-## The tools (15)
-
-Every answer is scannable markdown with one **→ Next:** hint, plus structured JSON for the model.
-Write tools are **convergent under retries** — an agent that re-issues a call after a timeout
-converges instead of duplicating (see "Built for agents, not browsers" below).
-
-| Tool | What it does |
-| --- | --- |
-| `application_get` | **Start here.** Scopes × what's live (release + traffic), latest build/release, next action. Zero-arg in a linked repo; `deployment:<id>` watches one rollout. |
-| `organization_get` | Org-wide digest with no web equivalent: what's mid-rollout and what last failed, across all apps. Answers "is anything broken?" without naming an app. |
-| `application_list` | Org-wide app search (parallel + cached). |
-| `application_build_list` | Recent CI builds — status, branch, commit, age, whether released. Closes the push→CI→deploy gap; `build:<id>` shows its assets. |
-| `application_log_list` | Recent log lines for the app/scope. |
-| `application_parameter_list` | List configuration parameters (secrets masked). |
-| `application_metric_list` | Golden signals per scope — throughput, response time, error rate, CPU, memory — with sparkline trends (1h/3h/24h/7d). |
-| `application_deployment_create` | Ship: picks the latest successful build, cuts the release for you (semver bump), targets the only scope — all overridable. Reuses an in-flight rollout on retry. |
-| `application_deployment_update` | Move traffic (snaps to 1/5/10/25/50/75/90/95/99/100), `finalize`, or `rollback`. Finds the active rollout itself. |
-| `application_release_create` | Cut a release from a build explicitly (reuses an existing one for the same build). |
-| `application_parameter_create` | Create/update env vars & file params (mark `secret`) — upserts, never duplicates. Apply on next deploy. |
-| `application_create` | Link the current repo as a new application (name/URL inferred from the git remote). Returns the existing app if already linked. |
-| `application_scope_create` | Create a deploy target (lists the org's scope types when ambiguous). Returns the existing scope if the name is taken. |
-| `application_approval_list` | List the approvals gating an app (e.g. a deploy stuck on a policy) and `approve`/`cancel` one — using your own permissions, so the platform denies what you can't do. |
-| `application_service_list` | List an app's dependency services (DBs, queues…) and the provisionable catalog; deep-links into the dashboard to create. |
-
-Plus three slash-command prompts: **/ship** (deploy + walk traffic to 100% with health checks),
-**/setup** (link this repo), **/rollback** (get me out, now).
-
-## Built for agents, not browsers
-
-MCP usage differs from web usage, and the tools are shaped for it:
-
-- **Convergent writes.** Agents retry on timeout; a web user doesn't double-submit a form. So
-  every write reconciles against current state instead of blindly POSTing: `application_parameter_create` reuses
-  an existing parameter definition, `application_release_create` reuses a release already cut from the same
-  build, `application_create`/`application_scope_create` return the existing entity, and `application_deployment_create` returns the
-  in-flight rollout for the same release. Re-running a tool is safe.
-- **Org-wide reads.** `organization_get` answers cross-application questions ("what's broken?") that the
-  dashboard only answers one entity-page at a time.
-- **Approvals as a loop, not a notification.** When a deploy blocks on a policy, `application_approval_list`
-  lets the agent see and (if permitted) clear the gate rather than dead-ending.
-- **Honest async + permissions.** Long operations say so and hand back an id to re-query;
-  `401`/`403` surface in plain language because every call carries the caller's own token.
-
-## Interactive UI (MCP Apps)
-
-On hosts that render MCP Apps (claude.ai web/desktop, ChatGPT), the journey is interactive —
-text-only hosts (terminals) keep the markdown answers automatically:
-
-| Widget | Bound to | What you can do in it |
-| --- | --- | --- |
-| **Application panel** | `application_get`, `application_deployment_create`, `application_deployment_update` | Scope cards with live release/traffic/domain, release chips with one-click **ship**, **Deploy latest**, create-scope when empty — and it morphs into the live rollout: traffic slider (snapped marks), **Finalize**/**Rollback** with confirm, deployment log, self-refreshing. |
-| **Create application** | `application_create` | Name + repo + namespace form (opens automatically when no git remote is inferable), creates and reports provisioning. |
-| **Parameters** | `application_parameter_list` | Editable table — add env vars/files, mark secrets, save via `application_parameter_create`. |
-| **Logs** | `application_log_list` | Terminal pane with filter, refresh and auto-tail. |
-| **Metrics** | `application_metric_list` | Golden-signal cards with live canvas charts, window selector (1h/3h/24h/7d), auto-refresh. |
-| **Applications** | `application_list` | Filterable picker — click an app to open its panel. |
-
-Widgets are single self-contained HTML files (~330KB: Preact-compat runtime + the ext-apps
-SDK, whose embedded zod accounts for most of it) built inline with esbuild — the sandbox
-blocks CDN fetches. They speak MCP Apps protocol `2026-01-26`. They **adopt the host's
-design tokens** (`hostContext.styles`: colors, border radii, fonts) so the UI looks native —
-Claude-styled in Claude, ChatGPT-styled in ChatGPT — with dark/light handled live and our own
-palette only as the fallback for hosts that don't send tokens.
-
-## Skills ship with the server
-
-The connector also ships **operating playbooks** — the methodology travels with the tools:
-
-| Playbook | Teaches |
-| --- | --- |
-| `deploying-safely` | Pre-flight checks, canary traffic steps gated on metrics, finalize/rollback criteria |
-| `incident-response` | Mitigate-first triage: rollback, then read logs/metrics/params for the cause |
-| `platform-conventions` | Entity chain semantics, dimensions, versioning, parameters, traffic lifecycle, known gotchas |
-
-They're plain markdown under `skills/` — platform teams change agent behavior by editing
-text, no server redeploy. The model reads them through the **`playbook_get` tool**: a tool is
-the one MCP primitive every coding assistant (Claude Code, Cursor, Claude Desktop, …) exposes
-to the model, so this works everywhere and on demand. The server instructions carry the
-catalog (name + when-to-use) so the model knows which to read before which task; they're also
-listed as passive `playbook://nullplatform/<name>` resources. MCP has no "skills" primitive —
-standard Agent Skills load client-side — and the earlier `skill://` scheme made Claude Desktop
-route to its native Agent Skills executor ("Unknown skill") instead, which is why this is a
-tool.
-
-## How it knows your app
-
-1. Your client's MCP **roots** (workspace folders) → `git remote get-url origin`
-2. Fallback: the server's working directory
-3. The remote URL is matched against applications' `repository_url` (ssh/https equivalent), then by repo name
-4. No match? Tools say exactly that and offer `application_create` / `application_list`
-
-## Design principles
-
-- **Journey-shaped, not endpoint-shaped** — one tool per developer intent; the API chain
-  (build → asset → release → deployment) is the server's problem.
-- **Defaults that match what you meant** — `application_deployment_create` does what the dashboard needs five screens for.
-- **Markdown is the UI** — tables, status glyphs, a traffic bar, one next-step per answer.
-- **Honest writes** — provisioning/asynchronous things say so and tell you how to watch;
-  errors carry the platform's message, never a stack trace.
-- **The dashboard stays one click away** — entities link to `https://<org>.app.nullplatform.io/nrn/<nrn>`.
-
-## Develop
+## Self-hosting (multi-user)
+
+Run it as a shared HTTP server where every caller brings their own key:
 
 ```bash
-npm install
-npm test           # unit + full in-memory MCP round-trips over a fake API (builds widgets first)
-npm run lint       # Biome (lint + format)
-npm run typecheck  # server + widgets, strict (noUncheckedIndexedAccess on)
-npm run dev        # stdio server (tsx)
-npm run build      # dist/ + minified widgets (NP_WIDGET_DEBUG=1 keeps identifiers)
+npx -y @nullplatform/mcp --http 8080   # → http://host:8080/mcp
 ```
 
-### Testing (the MCP way)
-
-The suite covers every level a real client exercises, without ever touching the live platform:
-
-| Layer | File | What it proves |
-| --- | --- | --- |
-| Unit | `test/unit.test.ts` | pure logic: semver, traffic snapping, locale matching, credential parsing, the presenter |
-| Protocol round-trip | `test/tools.test.ts` | the **SDK pattern**: a real MCP `Client` over `InMemoryTransport` against the real server — tool surface, text replies, structured contracts, widget bindings, skills, UI negotiation |
-| Tool scenarios | `test/scenarios.test.ts` | the behavior matrix: ask-backs (which scope?), dimension targeting, action side effects asserted on the recorded platform calls, 403→permission mapping, partial failures, `#id`/git-remote resolution, prompt rendering per language |
-| Widget DOM | `test/widgets.test.tsx` | **ui-mode**: widgets render each tool's `structuredContent` and user actions go back through the (mocked) host bridge as `tools/call` — ship chips, traffic slider snapping, confirm gates, form submission |
-| Transport boundary | `test/http.test.ts` | multi-user HTTP: per-request auth, token-exchange trust boundary, isolation, guards, per-request language |
-| Black box | `test/stdio.test.ts` | the **raw pattern**: spawns `src/index.ts` as a child process and speaks MCP over stdio like an installed client — entry point, env credential policy, negotiated text-only surface |
-
-Everything runs against `test/fake-api.ts`, an in-memory fake of the nullplatform API faithful
-to the live-verified contract (query scoping, snake_case bodies, async statuses, the multi-asset
-deploy trap) — fast, deterministic, and it records every call so action tests assert exactly
-what hit the platform.
-
-### Layers
-
-| Layer | Where | What it owns |
-| --- | --- | --- |
-| Platform API | `src/np/` | auth + token exchange, HTTP client, org context/caches, the typed journey API (builds → releases → scopes → deployments → metrics/logs). Tools never call the raw client — they go through `journey.ts`. |
-| Tool framework | `src/tool.ts` | `ToolSpec`/`ToolReply`, the presenter (one place replies become wire results), the per-tool error net |
-| Tools | `src/tools/` | one file per tool + `index.ts` registry + `shared.ts` resolution helpers |
-| Prompts | `src/prompts.ts` | declarative slash-command prompts |
-| Presentation (text) | `src/md.ts`, `src/render.ts` | the markdown design language and views |
-| Presentation (ui) | `src/ui.ts`, `src/widgets-react/` | widget registry, MCP Apps glue, the React widgets |
-| i18n | `src/i18n.ts` | `en`/`es` catalogs (compile-checked), locale scoping |
-| Transport | `src/http.ts`, `src/index.ts` | multi-user HTTP boundary (per-request auth, per-user backends, guards) and stdio entry |
-| Assembly | `src/server.ts` | Config → Deps → McpServer, wired from the registries |
-
-### Dual-mode replies
-
-Every tool returns one `ToolReply { markdown, data }`: the markdown is the complete answer
-for text hosts, the data feeds both the model (structuredContent) and the bound widget on
-ui hosts. In stdio sessions widgets are only registered once the client actually negotiates
-the MCP Apps extension; in stateless HTTP they're always offered and hosts that don't speak
-the extension simply ignore them (that's the spec's graceful degradation).
-
-### Extend
-
-- **New tool**: create `src/tools/<name>.ts` exporting `defineTool({...})` (schema, handler
-  returning a `ToolReply`, optional `widget` binding), add it to `src/tools/index.ts`. Its
-  widget auto-registers; the framework supplies error handling and presentation.
-- **New widget**: drop `src/widgets-react/widgets/<name>.tsx`, add it to the `WIDGETS` map in
-  `src/ui.ts`, bind it from a tool spec. The build picks it up.
-- **New prompt**: append a spec to `src/prompts.ts`.
-- **New playbook**: drop `skills/<name>/SKILL.md` — picked up automatically by the `playbook_get`
-  tool and the instruction catalog.
-- **New language**: add one catalog object in `src/i18n.ts` — completeness is compile-checked.
-- **New platform call**: add a typed function to `src/np/journey.ts`; tools never touch the raw client.
+The server holds **no credentials** — each request authenticates with the caller's own nullplatform key, so
+platform RBAC applies per user. Run it behind a TLS-terminating reverse proxy on a trusted network.
+
+## Documentation
+
+Full tool reference, the multi-user security model, design rationale, and the development guide:
+**[docs/ARCHITECTURE.md](https://github.com/nullplatform/ai-mcp/blob/main/docs/ARCHITECTURE.md)**.
+
+## License
+
+MIT

package/dist/i18n.js

@@ -160,6 +160,7 @@ const english = {
     "builds.commit": "Commit",
     "builds.released": "Released",
     "builds.none": "**{app}** has no builds yet.",
+    "builds.noneForCommit": "No build in **{app}** for commit `{commit}` — it may not have built yet, or the commit isn't on a built branch.",
     "builds.noneHint": "push a commit so CI produces one, then `application_deployment_create`.",
     "builds.deployHint": "`application_deployment_create build_id:{build}` ships it (cuts the release for you).",
     "builds.waiting": "build #{build} is still running — `application_build_list` again in a moment to check.",
@@ -423,6 +424,7 @@ const spanish = {
     "builds.commit": "Commit",
     "builds.released": "Released",
     "builds.none": "**{app}** todavía no tiene builds.",
+    "builds.noneForCommit": "Ningún build en **{app}** para el commit `{commit}` — puede que todavía no haya buildeado, o que el commit no esté en una branch que buildea.",
     "builds.noneHint": "pusheá un commit para que CI genere uno, después `application_deployment_create`.",
     "builds.deployHint": "`application_deployment_create build_id:{build}` lo publica (crea la release por vos).",
     "builds.waiting": "el build #{build} sigue corriendo — `application_build_list` de nuevo en un momento para chequear.",

package/dist/np/context.js

@@ -12,10 +12,15 @@ export function baseRepoUrl(provider, prefix) {
             : "https://github.com";
     return `${host}/${prefix}`;
 }
-/** Default ceiling for a single app search — used as the per-namespace fetch cap AND the
- *  overall result cap. Beyond it the tool reports truncation and asks the user to narrow.
- *  (The old value of 50 silently hid larger orgs behind a flat "50 applications".) */
-export const DEFAULT_APP_LIMIT = 200;
+/** Org-wide app discovery must fan out across namespaces: the public `/application` endpoint is
+ *  namespace-scoped, with no org-wide list and no name search — so the name filter is client-side
+ *  by necessity. We page each namespace to completion and bound the AGGREGATE at this cap, which
+ *  is generous and lift-able via NP_MAX_APPS, reporting truncation past it instead of silently
+ *  hiding a large org (the old code capped the whole org at 200 with a flat `.slice`). */
+const MAX_APPS = Math.max(1, Number(process.env.NP_MAX_APPS) || 1000);
+export const DEFAULT_APP_LIMIT = MAX_APPS;
+/** Safety ceiling when paging the account/namespace skeleton (both rarely exceed one page). */
+const SKELETON_CAP = 2000;
 /** Concurrency-limited parallel map — fast fan-out without hammering the API. */
 export async function pmap(items, mapItem, limit = 12) {
     const results = new Array(items.length);
@@ -29,6 +34,20 @@ export async function pmap(items, mapItem, limit = 12) {
     await Promise.all(Array.from({ length: Math.min(limit, items.length || 1) }, worker));
     return results;
 }
+/** Page an offset-based list endpoint to completion, bounded by `max` items. No list response
+ *  carries a total, so the boundary is the standard offset heuristic: a page shorter than the
+ *  requested limit is the last one. */
+async function fetchPaged(fetchPage, max, pageSize = 200) {
+    const rows = [];
+    for (let offset = 0; offset < max; offset += pageSize) {
+        const limit = Math.min(pageSize, max - offset);
+        const page = await fetchPage(offset, limit);
+        rows.push(...page);
+        if (page.length < limit)
+            break;
+    }
+    return rows;
+}
 /**
  * The public list endpoints are NRN-authorized and need explicit scoping (account needs
  * organization_id, namespace needs account_id, application needs namespace_id). There is no
@@ -53,16 +72,17 @@ export class NpContext {
         if (!refresh && this.skeleton && Date.now() - this.skeleton.at < NpContext.CACHE_TTL_MS)
             return this.skeleton;
         const orgId = await this.organizationId();
-        const accountsResp = await this.np.get("/account", {
-            organization_id: orgId,
-            limit: 200,
-        });
-        const perAccount = await pmap(accountsResp.results ?? [], async (account) => {
-            const namespacesPage = await this.np
-                .get("/namespace", { account_id: account.id, limit: 200 })
-                .catch(() => ({ results: [] }));
+        const accounts = await fetchPaged((offset, limit) => this.np
+            .get("/account", { organization_id: orgId, offset, limit })
+            .then((page) => page.results ?? [])
+            .catch(() => []), SKELETON_CAP);
+        const perAccount = await pmap(accounts, async (account) => {
+            const accountNamespaces = await fetchPaged((offset, limit) => this.np
+                .get("/namespace", { account_id: account.id, offset, limit })
+                .then((page) => page.results ?? [])
+                .catch(() => []), SKELETON_CAP);
             const accountBaseRepoUrl = baseRepoUrl(account.repository_provider, account.repository_prefix);
-            return (namespacesPage.results ?? []).map((namespace) => ({
+            return accountNamespaces.map((namespace) => ({
                 id: namespace.id,
                 name: namespace.name,
                 nrn: namespace.nrn,
@@ -109,21 +129,12 @@ export class NpContext {
             ? skeleton.namespaces.filter((namespace) => namespace.name.toLowerCase().includes(namespaceFilter))
             : skeleton.namespaces;
         const nameFilter = args.query?.toLowerCase();
-        const perNamespace = await pmap(namespaces, async (namespace) => {
-            try {
-                const query = {
-                    namespace_id: namespace.id,
-                    limit: DEFAULT_APP_LIMIT,
-                };
-                if (args.query)
-                    query["name:contains"] = args.query; // server-side when supported
-                const page = await this.np.get("/application", query);
-                return (page.results ?? []).map((app) => this.mapApp(app, namespace));
-            }
-            catch {
-                return [];
-            }
-        });
+        // `/application` is namespace-scoped with no name filter, so page each namespace to completion
+        // and filter by name client-side (below). This lifts the old silent 200-per-org cap.
+        const perNamespace = await pmap(namespaces, async (namespace) => fetchPaged((offset, limit) => this.np
+            .get("/application", { namespace_id: namespace.id, offset, limit })
+            .then((page) => page.results ?? [])
+            .catch(() => []), MAX_APPS).then((rows) => rows.map((app) => this.mapApp(app, namespace))));
         const seen = new Set();
         return perNamespace
             .flat()

package/dist/np/journey.js

@@ -11,13 +11,22 @@ const TERMINAL = new Set([
 ]);
 export const isDeploymentTerminal = (status) => !!status && TERMINAL.has(status);
 export function bumpSemver(semver) {
-    const parts = /^v?(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
-    return parts ? `${parts[1]}.${parts[2]}.${Number(parts[3]) + 1}` : "0.0.1";
+    // Preserve the optional `v` prefix: an org that enforces a v-prefixed version pattern
+    // rejects a bare bump, and dropping it makes the release history inconsistent.
+    const parts = /^(v?)(\d+)\.(\d+)\.(\d+)/.exec(semver ?? "");
+    return parts ? `${parts[1]}${parts[2]}.${parts[3]}.${Number(parts[4]) + 1}` : "0.0.1";
 }
-export async function listBuilds(np, applicationId, limit = 10) {
-    const page = await np
-        .get("/build", { application_id: applicationId, sort: "created_at:desc", limit })
-        .catch(() => ({ results: [] }));
+export async function listBuilds(np, applicationId, options = {}) {
+    const query = {
+        application_id: applicationId,
+        sort: "created_at:desc",
+        limit: options.limit ?? 10,
+    };
+    // The public API filters builds by full commit SHA via the `commit.id` query param (in the
+    // canonical OpenAPI contract) — this is how a change is traced from a commit to its build.
+    if (options.commit)
+        query["commit.id"] = options.commit;
+    const page = await np.get("/build", query).catch(() => ({ results: [] }));
     return (page.results ?? []).map((build) => ({
         id: build.id,
         status: build.status,

package/dist/surfaces/developer.js

@@ -6,7 +6,9 @@ import { tools } from "../tools/index.js";
  */
 const INSTRUCTIONS = `nullplatform is where this code gets built, released, deployed and observed — these tools replace its web dashboard for the everyday developer journey.
 
-The tools are repo-aware: inside a git repo, omit \`app\` and the linked application is inferred from the git remote. Start with \`application_get\` — it shows what's live where and suggests the next action.
+The tools are repo-aware: inside a git repo, omit \`app\` and the linked application is inferred from the git remote. "This app", or a request that names nothing, means the repo's app — infer it; pass \`app\` only when the user means a different, explicitly named application. Start with \`application_get\` — it shows what's live where and suggests the next action.
+
+You run in the developer's own environment, so fuse the local repo with platform state. Read the git remote, branch, HEAD commit, the diff being shipped, and config files (\`.env\`, \`package.json\`, Dockerfile), and correlate them with what the platform reports: does the local HEAD match a built or released commit, does a local config value match what a scope resolves. That correlation is this integration's edge over the web dashboard, which only sees the platform half.
 
 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.
 

package/dist/tools/builds.js

@@ -12,14 +12,18 @@ import { appArg, requireApp } from "./shared.js";
  */
 export const buildsTool = defineTool({
     name: TOOL.applicationBuildList,
-    title: "List builds",
-    description: "List an application's recent CI builds — status, branch, commit, age, and whether each is already released. Use it to answer 'did my push build yet?' and to pick a build_id to deploy. Pass build:<id> to see that build's assets.",
+    title: "Builds",
+    description: "List an application's recent CI builds — status, branch, commit, age, and whether each is already released. Use it to answer 'did my push build yet?' and to pick a build_id to deploy. Pass build:<id> to see that build's assets, or commit:<sha> to find the build for a specific commit (tracing a change to its build and release).",
     annotations: { readOnlyHint: true, openWorldHint: true },
     errorKey: "builds.errorLabel",
     inputSchema: {
         app: appArg,
         build: z.number().optional().describe("Build id — show this build's assets instead of the list"),
         limit: z.number().optional().describe("How many recent builds (default 10)"),
+        commit: z
+            .string()
+            .optional()
+            .describe("Full commit SHA — list only the build(s) for that commit (tracing a change to its build/release)"),
     },
     async handler(args, context) {
         const resolved = await requireApp(context, args);
@@ -43,11 +47,14 @@ export const buildsTool = defineTool({
             return reply(markdown, { build_id: args.build, assets });
         }
         const [builds, releases] = await Promise.all([
-            listBuilds(context.np, app.id, args.limit ?? 10),
+            listBuilds(context.np, app.id, { limit: args.limit ?? 10, commit: args.commit }),
             listReleases(context.np, app.id, { limit: 50 }),
         ]);
         if (builds.length === 0) {
-            return reply(translate("builds.none", { app: app.name }) + next(translate("builds.noneHint")));
+            const empty = args.commit
+                ? translate("builds.noneForCommit", { app: app.name, commit: shortCommit(args.commit) })
+                : translate("builds.none", { app: app.name }) + next(translate("builds.noneHint"));
+            return reply(empty, { app: `#${app.id}`, app_name: app.name, builds: [], commit: args.commit ?? null });
         }
         const releasedBuildIds = new Set(releases.map((release) => release.build_id).filter(Boolean));
         const releaseByBuild = new Map(releases.map((release) => [release.build_id, release]));

package/dist/tools/create-release.js

@@ -24,7 +24,7 @@ export const createReleaseTool = defineTool({
         let buildId = args.build_id;
         let buildNote = "";
         if (!buildId) {
-            const builds = await listBuilds(context.np, app.id, 5);
+            const builds = await listBuilds(context.np, app.id, { limit: 5 });
             const successful = builds.find((build) => build.status === "successful");
             if (!successful)
                 return fail(translate("createRelease.noBuilds", { app: app.name }));

package/dist/tools/deploy.js

@@ -15,7 +15,7 @@ async function resolveRelease(context, applicationId, args) {
     // code under its name — so search deep enough that only pathologically active apps miss.
     const [releases, builds] = await Promise.all([
         listReleases(context.np, applicationId, { status: "active", limit: 200 }),
-        listBuilds(context.np, applicationId, 5),
+        listBuilds(context.np, applicationId, { limit: 5 }),
     ]);
     const successfulBuild = builds.find((build) => build.status === "successful");
     if (args.release_id) {

package/dist/tools/find-apps.js

@@ -7,7 +7,7 @@ import { defineTool, reply } from "../tool.js";
 import { TOOL } from "../tool-names.js";
 export const findAppsTool = defineTool({
     name: TOOL.applicationList,
-    title: "Find applications",
+    title: "Applications",
     description: "Search applications across the whole organization by partial name (and optionally namespace). Fast (parallel + cached). Use when the repo isn't linked or the user names an app you don't know.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "find-apps",

package/dist/tools/logs.js

@@ -7,7 +7,7 @@ import { TOOL } from "../tool-names.js";
 import { appArg, chooseScope, requireApp } from "./shared.js";
 export const logsTool = defineTool({
     name: TOOL.applicationLogList,
-    title: "Read logs",
+    title: "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",

package/dist/tools/params.js

@@ -6,7 +6,7 @@ import { TOOL } from "../tool-names.js";
 import { appArg, requireApp } from "./shared.js";
 export const paramsTool = defineTool({
     name: TOOL.applicationParameterList,
-    title: "List parameters",
+    title: "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",

package/dist/tools/playbook.js

@@ -13,8 +13,8 @@ import { TOOL } from "../tool-names.js";
 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.",
+    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.",
     annotations: { readOnlyHint: true },
     errorKey: "playbook.errorLabel",
     inputSchema: {

package/dist/tools/status.js

@@ -26,7 +26,7 @@ async function scopeViews(context, applicationId) {
 }
 export const statusTool = defineTool({
     name: TOOL.applicationGet,
-    title: "nullplatform status",
+    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.",
     annotations: { readOnlyHint: true, openWorldHint: true },
     widget: "np-panel",
@@ -54,7 +54,7 @@ export const statusTool = defineTool({
             return resolved.out;
         const [views, builds, releases, orgSlug] = await Promise.all([
             scopeViews(context, resolved.app.id),
-            listBuilds(context.np, resolved.app.id, 5),
+            listBuilds(context.np, resolved.app.id, { limit: 5 }),
             listReleases(context.np, resolved.app.id, { limit: 5 }),
             context.org.organizationSlug(),
         ]);

package/dist/tools/traffic.js

@@ -8,8 +8,8 @@ import { TOOL } from "../tool-names.js";
 import { appArg, delays, requireApp, sleep } from "./shared.js";
 export const trafficTool = defineTool({
     name: TOOL.applicationDeploymentUpdate,
-    title: "Traffic / finalize / rollback",
-    description: 'Drive an in-flight rollout: move traffic to the new version (percent snaps to 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.',
+    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.',
     annotations: { destructiveHint: true, openWorldHint: true },
     widget: "np-panel",
     errorKey: "traffic.errorLabel",

package/package.json

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