@nonbot/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,43 @@
+Copyright (c) 2026 non.bot. All rights reserved.
+
+PROPRIETARY SOFTWARE — NOT OPEN SOURCE
+
+This software (the "@nonbot/mcp" package and all of its contents, the
+"Software") is the proprietary and confidential property of non.bot. It is
+published to the npm registry for the sole purpose of allowing authorized
+non.bot account holders to install and run it as the Model Context Protocol server that
+connects their AI client to the non.bot service.
+
+PERMITTED USE
+
+Subject to your compliance with the non.bot Terms of Service, you are granted
+a limited, non-exclusive, non-transferable, revocable license to download,
+install, and execute unmodified copies of the Software on machines you control,
+solely to connect to and operate the non.bot service.
+
+PROHIBITED WITHOUT PRIOR WRITTEN PERMISSION FROM non.bot
+
+  - Copying, redistributing, sublicensing, selling, or publishing the Software
+    or any portion of it;
+  - Modifying, adapting, translating, or creating derivative works;
+  - Reverse-engineering, decompiling, or disassembling the Software except to
+    the limited extent such restriction is prohibited by applicable law;
+  - Using the Software, or any technique, method, or design embodied in it, to
+    build, train, or operate a competing product or service.
+
+NO PATENT OR OTHER IP LICENSE
+
+No license to any patent, patent application, trademark, trade secret, or other
+intellectual-property right of non.bot is granted, whether expressly, by
+implication, by estoppel, or otherwise, except for the limited execution right
+stated above. All such rights are expressly reserved.
+
+NO WARRANTY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+non.bot BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM, OUT
+OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+Contact: legal@non.bot

package/README.md

@@ -1,3 +1,243 @@
-# Temporary Holding Version
+# @nonbot/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**One MCP server for your non.bot data.** Your terminal agent (Claude Code, Cursor, VS Code, or any MCP client) reads and reasons over your *real* portfolios, decision graph, and Runs, not a copy.
+
+```bash
+npx -y @nonbot/mcp
+```
+
+Built on the official MCP TypeScript SDK and **protocol `2025-11-25`**. Structured tool output, tool annotations, Resources, and Prompts throughout. Needs Node 18 or newer.
+
+> This is the unified successor to the separate `portfolio-mcp` and `context-graph` (WhyGraph) servers. The per-run fleet server is shipped inside `@nonbot/cli` as `nonbot run-mcp` (launched by the daemon, never installed by hand).
+
+---
+
+## Install
+
+### 1. Get a token
+
+Generate a Personal Access Token at **<https://non.bot/settings/connections>** → *API Tokens* → *Generate New Token*. Copy it (shown once). It looks like `pat_…`.
+
+Scoped tokens work too: a token with `portfolio:read` sees only the read tools' data; the table below says what each tool needs. If you have run `nonbot login` (the `@nonbot/cli` daemon) on this machine, you can omit the token entirely: the server falls back to the CLI's auth file.
+
+### 2. Add the server to your client
+
+**Claude Code** — one command:
+
+```bash
+claude mcp add nonbot -e NON_BOT_API_TOKEN=pat_<YOUR_TOKEN> -- npx -y @nonbot/mcp
+```
+
+or in `.mcp.json` (project) / `~/.claude.json` (user):
+
+```json
+{
+  "mcpServers": {
+    "nonbot": {
+      "command": "npx",
+      "args": ["-y", "@nonbot/mcp"],
+      "env": { "NON_BOT_API_TOKEN": "pat_<YOUR_TOKEN>" }
+    }
+  }
+}
+```
+
+**Cursor** — `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project), same shape:
+
+```json
+{
+  "mcpServers": {
+    "nonbot": {
+      "command": "npx",
+      "args": ["-y", "@nonbot/mcp"],
+      "env": { "NON_BOT_API_TOKEN": "pat_<YOUR_TOKEN>" }
+    }
+  }
+}
+```
+
+**VS Code** — `.vscode/mcp.json` (note the `servers` key; the token is a secret input, so the file is safe to commit):
+
+```json
+{
+  "inputs": [
+    { "id": "nonbot-pat", "type": "promptString", "description": "non.bot Personal Access Token", "password": true }
+  ],
+  "servers": {
+    "nonbot": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@nonbot/mcp"],
+      "env": { "NON_BOT_API_TOKEN": "${input:nonbot-pat}" }
+    }
+  }
+}
+```
+
+**Remote (Streamable HTTP)** — the same server runs as a Cloudflare Worker for clients that cannot spawn a local process. Auth is the same `pat_` token, sent as a bearer header:
+
+```json
+{
+  "mcpServers": {
+    "nonbot": {
+      "url": "https://nonbot-mcp-remote.conradwade.workers.dev/mcp",
+      "headers": { "Authorization": "Bearer pat_<YOUR_TOKEN>" }
+    }
+  }
+}
+```
+
+Claude Code: `claude mcp add --transport http nonbot https://nonbot-mcp-remote.conradwade.workers.dev/mcp --header "Authorization: Bearer pat_<YOUR_TOKEN>"`. Append `?readonly=1` to the URL for a read-only connection.
+
+> **Claude web and mobile:** claude.ai custom connectors authenticate with OAuth and cannot send a custom header, so the remote endpoint is not yet a one-click connector there. OAuth is the next step for the remote server (see `DISTRIBUTION-PLAN.md`); until it ships, use Claude Code, Cursor, or VS Code.
+
+### 3. Use it
+
+Ask your agent to "list my non.bot portfolios", "show what rules apply before I change auth", or run the `/wsjf_prioritize` prompt.
+
+---
+
+## Tools
+
+<!-- tool-table:start — generated by `npm run gen:tools`; tests/readme-tool-table.test.ts fails if this drifts from the code -->
+### Portfolio (18)
+
+The SAFe portfolio canvas: epics, features, stories, snapshots, personas, and the Run launch surface.
+
+| Tool | What it does | Kind | PAT scope |
+|---|---|---|---|
+| `portfolio_list` | List the portfolios the caller can access (owned, team, and shared). | read | `portfolio:read` |
+| `portfolio_get` | Fetch the full node/edge graph (plus viewport and version) for one portfolio. | read | `portfolio:read` |
+| `portfolio_get_activation` | Fetch the launch payload + story-brief snapshot for one activation (Act-3 ▶ Run). | read | `portfolio:read` |
+| `portfolio_subscribe_to_activations` | Poll the caller’s currently-pending activations (the Act-3 ▶ Run fallback). | read | `portfolio:read` |
+| `portfolio_versions` | List the saved version snapshots (time-travel restore points) for a portfolio — id, label, node count, created time. | read | `portfolio:read` |
+| `portfolio_version_get` | Load one snapshot’s full graph (nodes + edges + viewport) — the restore source. | read | `portfolio:read` |
+| `portfolio_characters` | List the Character personas the caller can see (their own + team), optionally scoped to a portfolio. | read | `portfolio:read` |
+| `portfolio_update` | Whole-graph replace: write the complete nodes + edges for a portfolio. | destructive | `portfolio:write` |
+| `portfolio_create_from_plan` | Create a DRAFT portfolio from an LLM-structured plan (epic + optional features/stories). | write | `portfolio:write` |
+| `portfolio_decompose` | Ask the server AI to decompose an item (epic→features or feature→stories) into SUGGESTED children for review. | write | `portfolio:write` |
+| `portfolio_attach_brief` | Attach metadata to one node: a markdown brief, acceptance criteria, description, and/or hypothesis. | write | `portfolio:write` |
+| `portfolio_link_chat_session` | Backlink a portfolio to the chat that birthed it. | write | `portfolio:write` |
+| `portfolio_publish_draft` | Flip a portfolio from "draft" → "active". | write | `portfolio:write` |
+| `portfolio_mark_run_ready` | Tag a story as ready for CLI pickup (or clear it with run_ready=false). | write | `portfolio:write` |
+| `portfolio_repo_path` | Your per-user local repo path for a portfolio — where ▶ Run activations cd before launching. | write | `portfolio:write` |
+| `portfolio_create_activation` | Create an activation (a ▶ Run launch request) for a story. | write | `portfolio:write` + `runs:fire` |
+| `portfolio_update_activation_status` | Transition an activation: pending → running \| failed \| cancelled. | write | `portfolio:write` |
+| `portfolio_snapshot` | Save a labeled version snapshot of a portfolio’s CURRENT graph — a time-travel restore point. | write | `portfolio:write` |
+
+### IP node (10)
+
+Patent and trademark disclosures on the canvas: read the bag, edit it as an op list, add server-sealed evidence, export the hash list.
+
+| Tool | What it does | Kind | PAT scope |
+|---|---|---|---|
+| `ip_list` | Every IP node (patent or trademark disclosure) in a portfolio: id, title, track, kind, started, live source count, live evidence count, filing date. | read | `portfolio:read` |
+| `ip_get` | One IP node's full disclosure bag (units with status, value, provenance; evidence incl. tombstones; events; filing) plus the graph version to pass as expected_… | read | `portfolio:read` |
+| `ip_evidence_list` | Evidence rows from the saved graph, tombstones included, with a seal verdict per row (true = sealed by this server, false = not, null = no signing key) and a w… | read | `portfolio:read` |
+| `ip_evidence_hashes` | The Export-hash-list file: one `id · sha256 · added(ISO)` line per row (never changed once written) plus a `#` trailer naming removed, missing, unsealed or alt… | read | `portfolio:read` |
+| `ip_packet` | The filing packet of an IP node as the Packet step shows it, rendered by the server from the saved graph: each document's id, name, status (queued / ready / ac… | read | `portfolio:read` |
+| `ip_packet_document` | One packet document's full text (markdown) and its text files (md / csv / txt / svg), rendered by the server from the saved graph. | read | `portfolio:read` |
+| `ip_update` | Apply an op list to one IP node in ONE versioned write: unit.set {unitId, value, expectedRev} · unit.confirm · unit.unconfirm · evidence.update {evId, patch} ·… | write | `portfolio:write` |
+| `ip_evidence_add` | Add one evidence row the SERVER hashes (SHA-256 of the stored copy), timestamps, seals and numbers. | write | `portfolio:write` |
+| `ip_witness_candidates` | Members who may witness evidence on this node (id + name only): editors of the portfolio other than the caller, never someone listed as an inventor in field 5. | write | `portfolio:write` |
+| `ip_build` | Runs `Build draft →` for a PATENT IP node on YOUR OWN model key (the token owner's Anthropic or Gemini key — non.bot never pays for it; no key = HTTP 402 no_ke… | write | `portfolio:write` |
+
+### WhyGraph (7)
+
+The PM decision graph. Read and reasoning only over token auth; writes stay cookie-only on the server.
+
+| Tool | What it does | Kind | PAT scope |
+|---|---|---|---|
+| `whygraph_search` | Search the PM decision graph by keyword, ranked by weight (how reinforced a decision is) then relevance. | read | `portfolio:read` |
+| `whygraph_context` | Given a task you are about to do, return the decisions that apply: the best keyword matches PLUS every LAW (locked, weight ≥ 5) — because LAWs always apply. | read | `portfolio:read` |
+| `whygraph_neighbors` | Graph reasoning the flat decision list cannot give you: starting from one decision, traverse RELATED_TO relationships breadth-first to surface every connected… | read | `portfolio:read` |
+| `whygraph_stats` | A dashboard view of the decision graph: total decisions, a per-category breakdown, the LAWs (locked, weight ≥ 5), and the most-violated decisions. | read | `portfolio:read` |
+| `whygraph_path` | Find the shortest chain of RELATED_TO links connecting one decision to another — how a decision reaches another through the graph. | read | `portfolio:read` |
+| `whygraph_conflicts` | Surface pairs of decisions that govern the SAME field but are NOT linked to each other — potential unreconciled overlap or contradiction to review. | read | `portfolio:read` |
+| `whygraph_recent_violations` | The most recent times decisions were violated — what broke, when, and which decision. | read | `portfolio:read` |
+
+### Run agent protocol (20)
+
+Called by a launched Run agent (telemetry, scope, reflections, close-out), not by a person.
+
+| Tool | What it does | Kind | PAT scope |
+|---|---|---|---|
+| `run_get_state` | Ground-truth run state: active_plan, ghost_plan, stickies, pending_violations, pending_reflections, trust_dial, last_user_intervention_at. | read | `portfolio:read` |
+| `run_load_activation` | Load the full context for a run: the story brief, acceptance criteria, applicable WhyGraph rules, and ensemble defaults. | write | `portfolio:write` |
+| `run_register_agent` | Register an ensemble member for this activation (creates the run on the first agent). | write | `portfolio:write` |
+| `run_declare_scope` | Lead declares the file allowlist + intent. | write | `portfolio:write` |
+| `run_request_scope_change` | Request expansion of the file allowlist. | write | `portfolio:write` |
+| `run_emit_diff` | Report a code diff. Triggers a WhyGraph rule-check + scope guard; returns { violations, reinforcements, blocked_paths }. | write | `portfolio:write` |
+| `run_emit_test_run` | Report a test run; updates the dashboard sparkline. | write | `portfolio:write` |
+| `run_emit_lint` | Report lint hits; updates the dashboard. | write | `portfolio:write` |
+| `run_emit_typecheck` | Report type-check errors; updates the dashboard. | write | `portfolio:write` |
+| `run_emit_build` | Report build status; updates the dashboard. | write | `portfolio:write` |
+| `run_emit_file_touch` | Report a file access (read\|write\|create); glows the living codebase map. | write | `portfolio:write` |
+| `run_emit_usage` | Report ONE turn's raw token counts so the command center's Metered Spend tile and per-run cost cap become truthful (instead of showing $0.00). | write | `portfolio:write` |
+| `run_request_reconsider` | Verifier nudges the Lead to reflect; inserts a pending reflection row. | write | `portfolio:write` |
+| `run_post_reflection` | Lead posts a reflection (response to a reconsider, or self-initiated). decision ∈ continue\|revise_plan\|escalate. | write | `portfolio:write` |
+| `run_resolve_violation` | Resolve a rule violation. action ∈ enforce (rollback) \| accept (weight decay) \| override (log). | write | `portfolio:write` |
+| `run_set_trust_dial` | Adjust the trust dial mid-run (0–10). | write | `portfolio:write` |
+| `run_pause_agent` | Pause one ensemble member by role. | write | `portfolio:write` |
+| `run_resume_agent` | Resume one paused ensemble member by role. | write | `portfolio:write` |
+| `run_emit_pr` | Announce that a PR is open; triggers the Act-5 closing sequence. | write | `portfolio:write` |
+| `run_finish` | Final close-out: triggers reinforcement + candidate-rule extraction, sets the story to shipped. | destructive | `portfolio:write` |
+
+### Run monitoring (9)
+
+The supervisor surface: what the daemon and the fleet are doing, plus the three actuators.
+
+| Tool | What it does | Kind | PAT scope |
+|---|---|---|---|
+| `run_feed` | The unified run feed — daemon heartbeat, fleet (active + last-24h runs with status/health/progress), needs-you items, and reconcile chips. | read | `runs:monitor` or `portfolio:read` |
+| `run_daemon_status` | Is the operator's daemon connected? | read | `runs:monitor` or `portfolio:read` |
+| `run_machines` | The operator's machines with a live daemon (multi-machine runs): machine id, name, terminal kind, last-seen, and (≥0.9.10) per-machine load stats. | read | `runs:monitor` or `portfolio:read` |
+| `run_activations_recent` | The last 10 activations with launch traces (spawn steps, launcher stderr/stdout/exit code), derived status incl. staleness, terminal used, and tmux pane. | read | `runs:monitor` or `portfolio:read` |
+| `run_prompts_list` | Mid-run prompts (a run paused on a menu/question). | read | `runs:monitor` or `portfolio:read` |
+| `run_snapshot_get` | Fetch the result of a run_snapshot_request. status "ready" carries the scrubbed pane tail; "pending" = the daemon hasn't served it yet (re-poll in ~5s, up to ~… | read | `runs:control` |
+| `run_snapshot_request` | Ask the operator's daemon to capture the last lines of a RUNNING run's terminal pane (secrets scrubbed, 16KB tail cap, stored server-side for 5 minutes only). | write | `runs:control` |
+| `run_prompt_answer` | Answer a mid-run prompt on the operator's behalf — the daemon types the answer into the live pane. | destructive | `runs:respond` (explicit; a wildcard token does not satisfy it) |
+| `run_stop_daemon` | The panic button — queue a remote shutdown for the operator's daemon (CLI ≥0.9.12). | destructive | `runs:control` |
+<!-- tool-table:end -->
+
+**Kind** is the tool's MCP annotation: *read* tools never change anything; *destructive* tools are confirm-gated (`portfolio_update` on large removals, `run_prompt_answer`, `run_stop_daemon`). `NON_BOT_MCP_READONLY=1` drops every non-read tool.
+
+**Resources** — `portfolio://<id>` (a portfolio graph) · `whygraph://decisions` (all decisions + edges)
+**Prompts** — `wsjf_prioritize(portfolioId)` · `decision_check(plan)`
+
+Safety rails on writes: `portfolio_update` pre-fetches the live version, backs the prior graph up to `~/.non.bot/backups/<id>-<unix-ts>.json`, validates the new graph (orphan parents, duplicate ids, unresolvable links) and writes with `expectedVersion`, so a concurrent edit on the canvas is a `409`, never a clobber.
+
+---
+
+## Environment variables
+
+| Var | Default | Purpose |
+|---|---|---|
+| `NON_BOT_API_TOKEN` | — | `pat_` token (https://non.bot/settings/connections). Optional when `nonbot login` has run on this machine: the server falls back to the CLI's auth file (`~/.config/nonbot/auth.json`; `NONBOT_CONFIG_DIR` / `NONBOT_PROFILE` respected), so a committed `.mcp.json` never carries a secret. |
+| `NON_BOT_API_BASE` | `https://non.bot` | Host-allowlisted: the token is only ever sent to non.bot / conrad.pm / deploy previews / localhost. |
+| `NON_BOT_MCP_READONLY` | unset | `1` drops every write and action tool, leaving the read tools. |
+
+---
+
+## Architecture (for contributors)
+
+`src/core/` is **Node-free** so the identical tool logic runs in both the local stdio process and the Cloudflare Worker (`../nonbot-mcp-remote`, which imports this package's `dist/`):
+
+- `core/config.ts` — `ApiContext` + the SSRF host-allowlist guard
+- `core/http.ts` — token-bound fetch wrapper
+- `core/validate.ts` — pre-flight graph validation
+- `core/server.ts` — `registerAll(server, ctx)` (the transport-agnostic heart) + `createNonbotMcpServer(ctx)`
+- `core/toolsets/{portfolio,whygraph,run,monitor,ip}.ts`, `core/resources.ts`, `core/prompts.ts`
+- `src/stdio.ts` — the `nonbot-mcp` bin: env/CLI-auth token + filesystem backup hook
+- `scripts/gen-tool-table.mjs` — prints the tool tables above from the live definitions (`--portfolio-mcp` does the same for the legacy server)
+
+```bash
+npm install
+npm run typecheck   # tsc --noEmit
+npm test            # vitest: tool contracts against a mocked non.bot + README/tool parity
+npm run build       # tsc → dist/ (comments stripped; this is what ships)
+npm run gen:tools   # regenerate the tool tables (paste between the markers in this README)
+npm pack --dry-run  # what the tarball would contain: dist/, README.md, LICENSE
+```
+
+Publishing is tag-driven (`bash deploy-npm.sh nonbot-mcp` from the repo root pushes `nonbot-mcp-v<version>`; GitHub Actions publishes via OIDC trusted publishing). `SERVER_VERSION` in `src/core/server.ts` must match `package.json`.

package/dist/core/config.d.ts

@@ -0,0 +1,8 @@
+export declare function resolveApiBase(raw0?: string): string;
+export interface ApiContext {
+    apiBase: string;
+    getToken: () => string;
+    readonly: boolean;
+    backup?: (id: string, json: unknown) => Promise<void>;
+    fetchImpl?: typeof fetch;
+}

package/dist/core/config.js

@@ -0,0 +1,34 @@
+const DEFAULT_API_BASE = 'https://non.bot';
+export function resolveApiBase(raw0) {
+    let raw = (raw0 || DEFAULT_API_BASE).replace(/\/$/, '');
+    if (!/^[a-z][a-z0-9+.-]*:\/\//i.test(raw))
+        raw = `https://${raw}`;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`non.bot API base is not a valid URL: ${raw}`);
+    }
+    const host = url.hostname.toLowerCase();
+    const isLocalhost = host === 'localhost' || host === '127.0.0.1' || host === '::1';
+    if (url.protocol === 'http:') {
+        if (!isLocalhost) {
+            throw new Error(`non.bot API base must use https:// — refusing to send the token in cleartext to ${host}. Plain http is only allowed for localhost.`);
+        }
+    }
+    else if (url.protocol !== 'https:') {
+        throw new Error(`non.bot API base must use https:// (got "${url.protocol}//${host}").`);
+    }
+    const allowed = host === 'non.bot' ||
+        host.endsWith('.non.bot') ||
+        host === 'conrad.pm' ||
+        host.endsWith('.conrad.pm') ||
+        host === 'conrad-pm.pages.dev' ||
+        host.endsWith('.conrad-pm.pages.dev') ||
+        isLocalhost;
+    if (!allowed) {
+        throw new Error(`non.bot API base host "${host}" is not allowlisted — the token may only be sent to non.bot, conrad.pm, conrad-pm.pages.dev (deploy previews), or localhost.`);
+    }
+    return raw;
+}

package/dist/core/http.d.ts

@@ -0,0 +1,3 @@
+import type { ApiContext } from './config.js';
+export declare function api(ctx: ApiContext, path: string, init?: RequestInit): Promise<Response>;
+export declare function expectJson<T = unknown>(res: Response, where: string): Promise<T>;

package/dist/core/http.js

@@ -0,0 +1,20 @@
+export async function api(ctx, path, init = {}) {
+    const token = ctx.getToken();
+    if (!token) {
+        throw new Error('No non.bot API token available. For stdio, set NON_BOT_API_TOKEN — generate one at https://non.bot/settings/connections.');
+    }
+    const headers = new Headers(init.headers);
+    headers.set('Authorization', `Bearer ${token}`);
+    if (init.body && !headers.has('Content-Type')) {
+        headers.set('Content-Type', 'application/json');
+    }
+    const doFetch = ctx.fetchImpl ?? fetch;
+    return doFetch(`${ctx.apiBase}${path}`, { ...init, headers });
+}
+export async function expectJson(res, where) {
+    if (!res.ok) {
+        const text = await res.text().catch(() => '');
+        throw new Error(`${where}: HTTP ${res.status} — ${text.slice(0, 200)}`);
+    }
+    return (await res.json());
+}

package/dist/core/prompts.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiContext } from './config.js';
+export declare function registerPrompts(server: McpServer, _ctx: ApiContext): void;

package/dist/core/prompts.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+export function registerPrompts(server, _ctx) {
+    server.registerPrompt('wsjf_prioritize', {
+        title: 'WSJF-prioritize a portfolio',
+        description: 'Rank a portfolio’s items by Weighted Shortest Job First.',
+        argsSchema: { portfolioId: z.string().describe('Portfolio id (from portfolio_list).') },
+    }, ({ portfolioId }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: [
+                        `Load portfolio "${portfolioId}" with the portfolio_get tool.`,
+                        'For each epic and feature, estimate the four WSJF inputs on a relative 1–10 scale:',
+                        'User/Business Value, Time Criticality, Risk Reduction & Opportunity Enablement, and Job Size.',
+                        'Compute WSJF = (Value + Time Criticality + Risk/Opportunity) / Job Size.',
+                        'Return a table ranked by WSJF (highest first) showing each input and the score,',
+                        'then recommend the top 5 to pull next, one line of justification each.',
+                    ].join(' '),
+                },
+            },
+        ],
+    }));
+    server.registerPrompt('decision_check', {
+        title: 'Check a plan against WhyGraph rules',
+        description: 'Evaluate a plan or decision against the team’s committed decisions and LAWs.',
+        argsSchema: { plan: z.string().describe('The plan, change, or decision to check.') },
+    }, ({ plan }) => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: [
+                        `Call whygraph_context with task="${plan}" to load the LAWs and prior decisions that apply.`,
+                        'Evaluate the plan against each. Treat a conflict with a LAW (locked decision) as a blocker;',
+                        'treat tension with a lower-weight decision as a caution. Cite the decision id for every point.',
+                        'If nothing conflicts, say so explicitly and name the decisions you checked against.',
+                    ].join(' '),
+                },
+            },
+        ],
+    }));
+}

package/dist/core/resources.d.ts

@@ -0,0 +1,3 @@
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiContext } from './config.js';
+export declare function registerResources(server: McpServer, ctx: ApiContext): void;

package/dist/core/resources.js

@@ -0,0 +1,23 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { api, expectJson } from './http.js';
+export function registerResources(server, ctx) {
+    server.registerResource('portfolio', new ResourceTemplate('portfolio://{id}', { list: undefined }), {
+        title: 'Portfolio graph',
+        description: 'The full node/edge graph for one portfolio as JSON. Read portfolio://<id> (id from portfolio_list) to load it directly as context — no tool call needed.',
+        mimeType: 'application/json',
+    }, async (uri, variables) => {
+        const id = String(variables.id);
+        const res = await api(ctx, `/api/portfolio/graph?id=${encodeURIComponent(id)}`);
+        const data = await expectJson(res, 'portfolio resource');
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.registerResource('whygraph-decisions', 'whygraph://decisions', {
+        title: 'WhyGraph decisions',
+        description: 'Every PM decision plus the RELATED_TO relationships between them, as JSON.',
+        mimeType: 'application/json',
+    }, async (uri) => {
+        const res = await api(ctx, '/api/whygraph/decisions');
+        const data = await expectJson(res, 'whygraph resource');
+        return { contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/core/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiContext } from './config.js';
+export declare const SERVER_NAME = "nonbot-mcp";
+export declare const SERVER_VERSION = "0.1.0";
+export declare const INSTRUCTIONS: string;
+export declare function registerAll(server: McpServer, ctx: ApiContext): void;
+export declare function createNonbotMcpServer(ctx: ApiContext): McpServer;

package/dist/core/server.js

@@ -0,0 +1,41 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerPortfolioTools } from './toolsets/portfolio.js';
+import { registerIpTools } from './toolsets/ip.js';
+import { registerWhygraphTools } from './toolsets/whygraph.js';
+import { registerRunTools } from './toolsets/run.js';
+import { registerMonitorTools } from './toolsets/monitor.js';
+import { registerResources } from './resources.js';
+import { registerPrompts } from './prompts.js';
+export const SERVER_NAME = 'nonbot-mcp';
+export const SERVER_VERSION = '0.1.0';
+export const INSTRUCTIONS = [
+    'non.bot MCP — work against the caller’s real product-management data, not a copy.',
+    'Two domains: PORTFOLIOS (the SAFe portfolio canvas — epics → features → stories) and',
+    'WHYGRAPH (the PM decision graph — the rules and decisions the team has committed to).',
+    'Read before you write: call the *_list / *_get / *_search tools first.',
+    'Portfolio edits are whole-graph: portfolio_get to load the current graph + version,',
+    'edit the full node/edge set, then portfolio_update (pass expectedVersion for safe',
+    'concurrent editing). There are no per-node mutators by design.',
+    'Before a non-trivial decision, call whygraph_context to surface the LAWs and prior',
+    'decisions that apply. WhyGraph is read/reasoning-only over this transport.',
+    'MONITORING: run_feed / run_daemon_status / run_machines / run_prompts_list answer',
+    '"what are my runs and daemon doing?"; run_snapshot_request + run_snapshot_get read a',
+    'live run’s terminal output; run_prompt_answer unblocks a waiting run (supervisor',
+    'tokens with the explicit runs:respond scope only).',
+    'IP NODES: ip_list / ip_get read a patent or trademark disclosure; ip_update edits it (op list + expected_version);',
+    'ip_evidence_add adds evidence the SERVER hashes, timestamps and numbers — never send a hash or a time.',
+].join(' ');
+export function registerAll(server, ctx) {
+    registerPortfolioTools(server, ctx);
+    registerIpTools(server, ctx);
+    registerWhygraphTools(server, ctx);
+    registerRunTools(server, ctx);
+    registerMonitorTools(server, ctx);
+    registerResources(server, ctx);
+    registerPrompts(server, ctx);
+}
+export function createNonbotMcpServer(ctx) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION }, { instructions: INSTRUCTIONS });
+    registerAll(server, ctx);
+    return server;
+}

package/dist/core/toolsets/ip.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiContext } from '../config.js';
+export declare function registerIpTools(server: McpServer, ctx: ApiContext): void;

package/dist/core/toolsets/ip.js

@@ -0,0 +1,130 @@
+import { z } from 'zod';
+import { api, expectJson } from '../http.js';
+const READ = { readOnlyHint: true, openWorldHint: true };
+const WRITE = { readOnlyHint: false, destructiveHint: false, openWorldHint: true };
+const SUPPORTS = ['problem', 'mechanism', 'novelty', 'RTP', 'disclosure'];
+const SECTIONS = ['whatsnew', 'spec', 'numerals', 'search'];
+const KINDS = ['note', 'email', 'commit', 'field', 'doc', 'meeting', 'image'];
+const textResult = (data) => ({ content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }] });
+const q = (o) => new URLSearchParams(o).toString();
+const ids = { portfolio_id: z.string().min(1).max(128).describe('Portfolio id.'), node_id: z.string().min(1).max(128).describe('The IP node id (radmod-ip-…).') };
+async function getJson(ctx, path) {
+    return expectJson(await api(ctx, path), `GET ${path}`);
+}
+async function patchNode(ctx, body) {
+    return expectJson(await api(ctx, '/api/ip/node', { method: 'PATCH', body: JSON.stringify(body) }), 'PATCH /api/ip/node');
+}
+export function registerIpTools(server, ctx) {
+    server.registerTool('ip_list', {
+        title: 'List IP nodes',
+        description: 'Every IP node (patent or trademark disclosure) in a portfolio: id, title, track, kind, started, live source count, live evidence count, filing date. Read before ip_get.',
+        inputSchema: { portfolio_id: ids.portfolio_id },
+        annotations: READ,
+    }, async (a) => textResult(await getJson(ctx, `/api/ip/nodes?${q({ portfolioId: a.portfolio_id })}`)));
+    server.registerTool('ip_get', {
+        title: 'Read one IP node',
+        description: 'One IP node\'s full disclosure bag (units with status, value, provenance; evidence incl. tombstones; events; filing) plus the graph version to pass as expected_version, and its live sources.',
+        inputSchema: ids,
+        annotations: READ,
+    }, async (a) => textResult(await getJson(ctx, `/api/ip/nodes?${q({ portfolioId: a.portfolio_id, nodeId: a.node_id })}`)));
+    server.registerTool('ip_evidence_list', {
+        title: 'List IP evidence with verdicts',
+        description: 'Evidence rows from the saved graph, tombstones included, with a seal verdict per row (true = sealed by this server, false = not, null = no signing key) and a witness verdict per row carrying a request.',
+        inputSchema: ids,
+        annotations: READ,
+    }, async (a) => textResult(await getJson(ctx, `/api/ip/evidence?${q({ portfolioId: a.portfolio_id, nodeId: a.node_id })}`)));
+    server.registerTool('ip_evidence_hashes', {
+        title: 'Export the evidence hash list',
+        description: 'The Export-hash-list file: one `id · sha256 · added(ISO)` line per row (never changed once written) plus a `#` trailer naming removed, missing, unsealed or altered rows.',
+        inputSchema: ids,
+        annotations: READ,
+    }, async (a) => {
+        const path = `/api/ip/evidence/hashes?${q({ portfolioId: a.portfolio_id, nodeId: a.node_id })}`;
+        const res = await api(ctx, path);
+        if (!res.ok)
+            await expectJson(res, `GET ${path}`);
+        return textResult(await res.text());
+    });
+    server.registerTool('ip_packet', {
+        title: 'List the packet documents',
+        description: 'The filing packet of an IP node as the Packet step shows it, rendered by the server from the saved graph: each document\'s id, name, status (queued / ready / accepted / needs_you) and formats, plus how many evidence copies the zip would bundle. Read a document with ip_packet_document. The .docx and .zip files are assembled in the browser (Packet step) — not available here.',
+        inputSchema: ids,
+        annotations: READ,
+    }, async (a) => {
+        const p = await getJson(ctx, `/api/ip/packet?${q({ portfolioId: a.portfolio_id, nodeId: a.node_id })}`);
+        return textResult({
+            title: p.title,
+            documents: (p.docs ?? []).map(d => ({ id: d.id, name: d.packetName ?? d.name, status: d.status, formats: d.formats })),
+            bundle: { stored: p.bundle?.stored?.length ?? 0, text: p.bundle?.text?.length ?? 0, notBundled: p.bundle?.skipped?.length ?? 0 },
+        });
+    });
+    server.registerTool('ip_packet_document', {
+        title: 'Read one packet document',
+        description: 'One packet document\'s full text (markdown) and its text files (md / csv / txt / svg), rendered by the server from the saved graph. `document` is an id from ip_packet (disclosure, evidence, clocks, risk, inventorship, tradesecret, spec, figures, priorart, cover — or teas, ids, specimens, firstuse, owner, knockout for a trademark).',
+        inputSchema: { ...ids, document: z.string().min(1).max(32).regex(/^[a-z]+$/).describe('A document id from ip_packet.') },
+        annotations: READ,
+    }, async (a) => {
+        const p = await getJson(ctx, `/api/ip/packet?${q({ portfolioId: a.portfolio_id, nodeId: a.node_id, doc: a.document })}`);
+        const d = p.docs?.[0];
+        if (!d)
+            return textResult('That document does not exist on this node.');
+        return textResult([d.text, ...d.files.filter(f => !f.name.endsWith('.md')).map(f => `\n--- ${f.name} ---\n${f.text}`)].join('\n') + `\n\nfiles: ${d.files.map(f => f.name).join(', ')}`);
+    });
+    if (ctx.readonly)
+        return;
+    server.registerTool('ip_update', {
+        title: 'Edit an IP node (op list)',
+        description: 'Apply an op list to one IP node in ONE versioned write: unit.set {unitId, value, expectedRev} · unit.confirm · unit.unconfirm · evidence.update {evId, patch} · evidence.remove {evId} (a tombstone) · evidence.witness {evId, witness:{for,name,line}|null} · evidence.add (max 5 per request; identical adds collapse into one row) · event.upsert · event.remove · filing.set · meta.set. A stale expected_version is HTTP 409 version_conflict with currentVersion — re-read with ip_get and retry.',
+        inputSchema: { ...ids, expected_version: z.number().int().describe('The graph version from ip_get.'), ops: z.array(z.record(z.unknown())).min(1).max(50).refine(o => o.filter(x => x.op === 'evidence.add').length <= 5, 'At most 5 evidence.add ops per request.').describe('The op list.') },
+        annotations: WRITE,
+    }, async (a) => textResult(await patchNode(ctx, { portfolioId: a.portfolio_id, nodeId: a.node_id, expectedVersion: a.expected_version, ops: a.ops })));
+    server.registerTool('ip_evidence_add', {
+        title: 'Add evidence (server-sealed)',
+        description: 'Add one evidence row the SERVER hashes (SHA-256 of the stored copy), timestamps, seals and numbers. `from` is one source and must match `kind`: kind note or email takes {text} (at most 2000 characters), commit takes {commit:{sha?,repo?,pr?}}, field takes {field:{itemId,field}} for a source item\'s field, doc or meeting takes {module:{moduleId}} for an attached Document or radMeeting, image takes {asset} for your own uploaded image key. Returns the new row id in evIds. Two adds with identical bytes (same content, time and author) collapse into ONE row and report the same id, so add each distinct piece once; the server accepts at most 5 evidence.add ops per request (ip_update).',
+        inputSchema: {
+            ...ids,
+            expected_version: z.number().int().describe('The graph version from ip_get.'),
+            kind: z.enum(KINDS),
+            from: z.record(z.unknown()).describe('Exactly one source (see description).'),
+            title: z.string().min(1).max(300),
+            describes: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('The date the evidence describes (YYYY-MM-DD).'),
+            supports: z.array(z.enum(SUPPORTS)).max(5).optional(),
+            visibility: z.enum(['private', 'team', 'nda', 'public']).optional().describe('Who could see it at the time.'),
+            shows: z.string().max(600).optional(),
+        },
+        annotations: WRITE,
+    }, async (a) => {
+        const op = { op: 'evidence.add', kind: a.kind, from: a.from, title: a.title };
+        for (const k of ['describes', 'supports', 'visibility', 'shows'])
+            if (a[k] !== undefined)
+                op[k] = a[k];
+        return textResult(await patchNode(ctx, { portfolioId: a.portfolio_id, nodeId: a.node_id, expectedVersion: a.expected_version, ops: [op] }));
+    });
+    server.registerTool('ip_witness_candidates', {
+        title: 'List possible witnesses',
+        description: 'Members who may witness evidence on this node (id + name only): editors of the portfolio other than the caller, never someone listed as an inventor in field 5. Needs a write token (it is a step of asking for a witness), so it is absent in read-only mode. Use an id as `for` in an evidence.witness op.',
+        inputSchema: ids,
+        annotations: WRITE,
+    }, async (a) => textResult(await getJson(ctx, `/api/ip/witness-candidates?${q({ portfolioId: a.portfolio_id, nodeId: a.node_id })}`)));
+    server.registerTool('ip_build', {
+        title: 'Build the draft (one model pass)',
+        description: 'Runs `Build draft →` for a PATENT IP node on YOUR OWN model key (the token owner\'s Anthropic or Gemini key — non.bot never pays for it; no key = HTTP 402 no_key). Each call spends YOUR OWN model usage (draft_mode best = the larger, costlier model): one model pass that writes the What\'s-new elements, the specification paragraphs (each citing the disclosure / code / evidence it rests on, or shown unverified), the reference numerals and prior-art SEARCH SEEDS, then saves them to the node with OCC on expected_version (HTTP 409 version_conflict with currentVersion → re-read with ip_get). Every ★ disclosure field must be confirmed first (HTTP 400 gate). A trademark packet needs no model (HTTP 400 trademark_no_model). `sections` limits the pass (default all four). During a live collaborative session the saved draft can be overwritten by that session — prefer running when no one has the canvas open.',
+        inputSchema: {
+            ...ids,
+            expected_version: z.number().int().describe('The graph version from ip_get.'),
+            sections: z.array(z.enum(SECTIONS)).min(1).max(4).optional(),
+            steer: z.string().max(300).optional().describe('A short steer, e.g. "shorter background".'),
+            draft_mode: z.enum(['fast', 'best']).optional(),
+        },
+        annotations: WRITE,
+    }, async (a) => {
+        const body = { portfolioId: a.portfolio_id, nodeId: a.node_id, persist: true, expectedVersion: a.expected_version };
+        if (a.sections)
+            body.sections = a.sections;
+        if (a.steer)
+            body.steer = a.steer;
+        if (a.draft_mode)
+            body.draftMode = a.draft_mode;
+        return textResult(await expectJson(await api(ctx, '/api/ip/build', { method: 'POST', body: JSON.stringify(body) }), 'POST /api/ip/build'));
+    });
+}

package/dist/core/toolsets/monitor.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ApiContext } from '../config.js';
+export declare function registerMonitorTools(server: McpServer, ctx: ApiContext): void;