@nullplatform/mcp 0.1.1 → 0.1.2

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

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