@nonbot/mcp 0.0.0-stage → 0.2.0

package/dist/core/toolsets/build.js

@@ -0,0 +1,367 @@
+import { z } from 'zod';
+import { api, expectJson } from '../http.js';
+import { validateGraph } from '../validate.js';
+import { LEVELS, applyLayout, layoutTimeline, scheduleFields, todayColumn, columnOf, isItem, PX_PER_WEEK } from '../layout.js';
+import { emptyIp, IP_KINDS, IP_NODE_SIZE } from '../ipShape.js';
+const STATES = ['funnel', 'reviewing', 'analyzing', 'ready', 'implementing', 'done'];
+const OKR_STATUSES = ['on-track', 'at-risk', 'behind'];
+const RESERVED = new Set(['hierarchyLevel', 'parentItemId', 'linkedEpicIds', 'id', '__proto__', 'constructor', 'prototype']);
+const MAX_ITEMS = 200;
+const MAX_ASSET_BYTES = 2_200_000;
+const text = (obj) => ({ type: 'text', text: JSON.stringify(obj, null, 2) });
+const fail = (msg) => ({ content: [{ type: 'text', text: msg }], isError: true });
+const escHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+export const toHtml = (s) => /^\s*</.test(s) ? s : s.split(/\n{2,}/).map(p => `<p>${escHtml(p.trim()).replace(/\n/g, '<br>')}</p>`).join('');
+export function newItemId(now = Date.now()) { return `pf-${now}-${Math.random().toString(36).slice(2, 11)}`; }
+async function loadGraph(ctx, id) {
+    const data = await expectJson(await api(ctx, `/api/portfolio/graph?id=${encodeURIComponent(id)}`), 'load portfolio');
+    const g = (data.graph ?? data);
+    return {
+        name: String(data.name ?? g.name ?? ''),
+        description: String(data.description ?? g.description ?? ''),
+        nodes: Array.isArray(g.nodes) ? g.nodes : [],
+        edges: Array.isArray(g.edges) ? g.edges : [],
+        viewport: g.viewport ?? { x: 0, y: 0, zoom: 1 },
+        version: typeof g.version === 'number' ? g.version : undefined,
+    };
+}
+async function saveGraph(ctx, id, before, after, expectedVersion) {
+    const problems = validateGraph(after.nodes, after.edges);
+    if (problems.length)
+        return { ok: false, message: `Refusing to write — ${problems.length} problem(s):\n` + problems.map(p => `  - ${p}`).join('\n') };
+    if (ctx.backup) {
+        try {
+            await ctx.backup(id, before);
+        }
+        catch { }
+    }
+    const res = await api(ctx, '/api/portfolio/graph', {
+        method: 'PUT',
+        body: JSON.stringify({ id, name: after.name, description: after.description, nodes: after.nodes, edges: after.edges, viewport: after.viewport, expectedVersion: expectedVersion ?? before.version }),
+    });
+    if (res.status === 409) {
+        const c = (await res.json().catch(() => ({})));
+        return { ok: false, message: `Refused (409) — the portfolio changed since it was read (now version ${c.currentVersion ?? '?'}). Nothing was written; call again.` };
+    }
+    const out = await expectJson(res, 'save portfolio');
+    return { ok: true, version: typeof out.version === 'number' ? out.version : undefined };
+}
+const itemSpec = z.object({
+    key: z.string().max(64).optional().describe('A local name for this item, so other items in the SAME call can name it as parent / okr / depends_on before it has an id.'),
+    level: z.enum(LEVELS),
+    title: z.string().min(1).max(200),
+    description: z.string().max(20000).optional().describe('Plain text (blank lines = paragraphs) or HTML.'),
+    bluf: z.string().max(4000).optional().describe('Bottom line up front — the sentence the card shows.'),
+    acceptance_criteria: z.string().max(8000).optional(),
+    hypothesis: z.string().max(4000).optional().describe('Hypothesis statement ("We believe … will … measured by …").'),
+    state: z.enum(STATES).optional().describe('Default funnel.'),
+    parent: z.string().optional().describe('Parent item id, or a key from this call. Epic → feature/enabler/milestone, feature → story/enabler/milestone, objective → key-result.'),
+    okr: z.array(z.string()).max(10).optional().describe('Epics only: key-result ids/keys this epic contributes to (an okr-link edge + the KR roll-up).'),
+    depends_on: z.array(z.string()).max(20).optional().describe('Finish-to-start predecessors (ids or keys).'),
+    start_week: z.number().int().min(-52).max(156).optional().describe('Start, in weeks from the Monday of the current week (negative = past). Ignored when start_date is given.'),
+    start_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
+    duration_weeks: z.number().min(0).max(156).optional().describe('Default: epic 8, feature 4, story 1, enabler 2, milestone 0, objective / key-result 12.'),
+    tags: z.array(z.string().max(40)).max(20).optional(),
+    wsjf: z.tuple([z.number(), z.number(), z.number(), z.number()]).optional().describe('[business value, time criticality, risk reduction, job size].'),
+    owner: z.string().max(80).optional(),
+    kr_target: z.string().max(200).optional(),
+    kr_current: z.string().max(200).optional(),
+    okr_status: z.enum(OKR_STATUSES).optional(),
+    images: z.array(z.string().max(2048)).max(8).optional().describe('Image URLs from portfolio_asset_upload — the first is the card hero.'),
+    fields: z.record(z.unknown()).optional().describe('Any other PortfolioItemData fields, merged last (structural keys are refused).'),
+});
+const DEFAULT_WEEKS = { epic: 8, feature: 4, story: 1, enabler: 2, milestone: 0, objective: 12, 'key-result': 12 };
+const LEGAL_PARENT = {
+    epic: [], objective: [], 'key-result': ['objective'], feature: ['epic'], story: ['feature', 'epic'], enabler: ['epic', 'feature'], milestone: ['epic', 'feature'],
+};
+export function buildItems(g, specs, now = new Date()) {
+    const errors = [];
+    const ids = {};
+    const t0 = now.getTime();
+    const idOf = specs.map((s, i) => { const id = newItemId(t0 + i); ids[s.key ?? `#${i}`] = id; return id; });
+    const levelById = new Map(g.nodes.filter(isItem).map(n => [n.id, String(n.data?.hierarchyLevel)]));
+    specs.forEach((s, i) => levelById.set(idOf[i], s.level));
+    const resolve = (ref) => ids[ref] ?? (levelById.has(ref) ? ref : null);
+    const base = todayColumn(now);
+    const nodes = [];
+    const edges = [];
+    const krLinks = new Map();
+    specs.forEach((s, i) => {
+        const self = idOf[i];
+        const label = s.key ?? s.title;
+        const d = { hierarchyLevel: s.level, title: s.title, description: s.description ? toHtml(s.description) : '', state: s.state ?? 'funnel', createdAt: t0, updatedAt: t0 };
+        if (s.parent) {
+            const p = resolve(s.parent);
+            if (!p)
+                errors.push(`${label}: parent "${s.parent}" is neither an id in the portfolio nor a key in this call`);
+            else if (!(LEGAL_PARENT[s.level] ?? []).includes(levelById.get(p) ?? ''))
+                errors.push(`${label}: a ${s.level} cannot sit under a ${levelById.get(p)} (allowed: ${(LEGAL_PARENT[s.level] ?? []).join(', ') || 'none — top level'})`);
+            else {
+                d.parentItemId = p;
+                edges.push({ id: `edge-${p}-${self}`, source: p, target: self, dependencyType: 'hierarchy' });
+            }
+        }
+        const weeks = s.duration_weeks ?? DEFAULT_WEEKS[s.level] ?? 1;
+        const col = s.start_date ? columnOf(new Date(Number(s.start_date.slice(0, 4)), Number(s.start_date.slice(5, 7)) - 1, Number(s.start_date.slice(8, 10))), now) : base + (s.start_week ?? 0);
+        Object.assign(d, scheduleFields(col, weeks, now));
+        if (s.bluf)
+            d.bluf = toHtml(s.bluf);
+        if (s.acceptance_criteria)
+            d.acceptanceCriteria = toHtml(s.acceptance_criteria);
+        if (s.hypothesis)
+            d.hypothesisStatement = s.hypothesis;
+        if (s.tags)
+            d.tags = s.tags;
+        if (s.owner)
+            d.owner = s.owner;
+        if (s.wsjf)
+            Object.assign(d, { wsjfBusinessValue: s.wsjf[0], wsjfTimeCriticality: s.wsjf[1], wsjfRiskReduction: s.wsjf[2], wsjfJobSize: s.wsjf[3] });
+        if (s.kr_target)
+            d.krTarget = s.kr_target;
+        if (s.kr_current)
+            d.krCurrent = s.kr_current;
+        if (s.okr_status)
+            d.okrStatus = s.okr_status;
+        if (s.images?.length)
+            d.pastedImages = s.images;
+        if (s.level === 'epic')
+            d.innerLoopExpanded = false;
+        for (const [k, v] of Object.entries(s.fields ?? {})) {
+            if (RESERVED.has(k))
+                errors.push(`${label}: fields.${k} is structural — use the tool's own parameter`);
+            else
+                d[k] = v;
+        }
+        for (const kr of s.okr ?? []) {
+            const k = resolve(kr);
+            if (s.level !== 'epic')
+                errors.push(`${label}: okr links are for epics`);
+            else if (!k || levelById.get(k) !== 'key-result')
+                errors.push(`${label}: okr "${kr}" is not a key result`);
+            else {
+                edges.push({ id: `edge-${k}-${self}`, source: k, target: self, dependencyType: 'okr-link' });
+                krLinks.set(k, [...(krLinks.get(k) ?? []), self]);
+            }
+        }
+        for (const dep of s.depends_on ?? []) {
+            const p = resolve(dep);
+            if (!p)
+                errors.push(`${label}: depends_on "${dep}" not found`);
+            else
+                edges.push({ id: `edge-${p}-${self}`, source: p, target: self, dependencyType: 'finish-to-start', label: 'FS' });
+        }
+        nodes.push({ id: self, type: 'portfolio-item', position: { x: col * PX_PER_WEEK, y: 0 }, data: d });
+    });
+    const patched = new Map();
+    for (const [kr, epics] of krLinks) {
+        const fresh = nodes.find(n => n.id === kr);
+        const old = g.nodes.find(n => n.id === kr);
+        const data = { ...((fresh ?? old)?.data ?? {}) };
+        data.linkedEpicIds = [...new Set([...(data.linkedEpicIds ?? []), ...epics])];
+        if (fresh)
+            fresh.data = data;
+        else if (old)
+            patched.set(kr, data);
+    }
+    return { nodes, edges, ids, errors, patched };
+}
+export function registerBuildTools(server, ctx) {
+    if (ctx.readonly)
+        return;
+    server.registerTool('portfolio_create', {
+        title: 'Create an empty portfolio',
+        description: 'Create a new, empty portfolio owned by the caller and return its id + version. Fill it with portfolio_add_items (any level) and ip_create; set its context text and palette with portfolio_set_meta.',
+        inputSchema: {
+            name: z.string().min(1).max(200),
+            description: z.string().max(2000).optional(),
+            status: z.enum(['active', 'draft']).optional().describe('Default active (the CREATE path alone leaves a new row as draft).'),
+        },
+        outputSchema: { id: z.string(), version: z.number().optional(), url: z.string(), status: z.string() },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        const out = await expectJson(await api(ctx, '/api/portfolio/graph', {
+            method: 'PUT', body: JSON.stringify({ name: a.name, description: a.description ?? '', nodes: [], edges: [], viewport: { x: 0, y: 0, zoom: 1 } }),
+        }), 'portfolio_create');
+        const id = String(out.id ?? '');
+        if (!id)
+            return fail('portfolio_create: the server did not return an id.');
+        const status = a.status ?? 'active';
+        if (status !== 'draft')
+            await expectJson(await api(ctx, '/api/portfolio/graph', { method: 'PUT', body: JSON.stringify({ id, metaOnly: true, status }) }), 'portfolio_create (status)');
+        const structured = { id, ...(typeof out.version === 'number' ? { version: out.version } : {}), url: `${ctx.apiBase}/portfolio/${id}`, status };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_add_items', {
+        title: 'Add items to a portfolio',
+        description: 'Add up to 200 items of any level (objective, key-result, epic, feature, story, enabler, milestone) in one versioned write. Parents, OKR links and dependencies may name existing ids OR `key`s of other items in the same call, so a whole tree goes in at once. The tool makes the ids, the hierarchy / okr-link / finish-to-start edges, the dates and sprint labels from start_week + duration_weeks, and (unless layout is "none") re-lays the whole portfolio on the Timeline so nothing overlaps. Returns key → id. Rich text fields accept plain text or HTML.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            items: z.array(itemSpec).min(1).max(MAX_ITEMS),
+            layout: z.enum(['timeline', 'none']).optional().describe('Default timeline: re-lay every item after adding. "none": new items get their date x and y 0.'),
+            expected_version: z.number().int().optional().describe('Optional OCC guard; default = the version read at call time.'),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const keys = a.items.map(s => s.key).filter(Boolean);
+        if (new Set(keys).size !== keys.length)
+            return fail('Two items share a key — keys must be unique within one call.');
+        const built = buildItems(g, a.items);
+        if (built.errors.length)
+            return fail(`Nothing was written — ${built.errors.length} problem(s):\n` + built.errors.map(e => `  - ${e}`).join('\n'));
+        let nodes = [...g.nodes.map(n => built.patched.has(n.id) ? { ...n, data: built.patched.get(n.id) } : n), ...built.nodes];
+        if ((a.layout ?? 'timeline') === 'timeline')
+            nodes = applyLayout(nodes, layoutTimeline(nodes));
+        const after = { ...g, nodes, edges: [...g.edges, ...built.edges] };
+        const r = await saveGraph(ctx, a.portfolio_id, g, after, a.expected_version);
+        if (!r.ok)
+            return fail(r.message);
+        const structured = { ok: true, added: built.nodes.length, edges: built.edges.length, ids: built.ids, ...(r.version !== undefined ? { version: r.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_patch_item', {
+        title: 'Patch one item',
+        description: 'Change fields of ONE portfolio item without rewriting the graph (PATCH /api/portfolio/graph/node): `set` writes allowlisted PortfolioItemData fields (title, description, bluf, acceptanceCriteria, hypothesisStatement, state, tags, wsjf*, krTarget, pastedImages, durationWeeks, startDate, …), `unset` deletes them. Rich text is stored as given (pass HTML, or plain text which is wrapped in <p>). A stale version answers 409 — nothing is written.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            item_id: z.string(),
+            set: z.record(z.unknown()).optional(),
+            unset: z.array(z.string()).max(40).optional(),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        if (!a.set && !a.unset)
+            return fail('Provide set and/or unset.');
+        let version = a.expected_version;
+        if (version === undefined)
+            version = (await loadGraph(ctx, a.portfolio_id)).version;
+        const set = {};
+        for (const [k, v] of Object.entries(a.set ?? {}))
+            set[k] = typeof v === 'string' && ['description', 'bluf', 'acceptanceCriteria'].includes(k) ? toHtml(v) : v;
+        const res = await api(ctx, '/api/portfolio/graph/node', { method: 'PATCH', body: JSON.stringify({ graphId: a.portfolio_id, nodeId: a.item_id, expectedVersion: version, ...(a.set ? { set } : {}), ...(a.unset ? { unset: a.unset } : {}) }) });
+        if (res.status === 409)
+            return fail('Refused (409) — the portfolio changed since it was read. Call again.');
+        const out = await expectJson(res, 'portfolio_patch_item');
+        const structured = { ok: true, ...(typeof out.version === 'number' ? { version: out.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_layout', {
+        title: 'Lay out a portfolio on the Timeline',
+        description: 'Re-position every item so the Timeline reads cleanly: x from each item\'s start date (the canvas reads dates off x), y top-down — objectives, key results, then one block per epic (epic, features, stories + enablers, milestones), each row lane-packed so overlapping items stack, IP nodes directly above their first source. Short items get a minimum painted width so titles fit. Content is untouched. `heights` overrides the estimated card height per id (px) when a card measures taller on screen.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            heights: z.record(z.number().min(20).max(2000)).optional(),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const res = layoutTimeline(g.nodes, { heights: a.heights });
+        const r = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes: applyLayout(g.nodes, res) }, a.expected_version);
+        if (!r.ok)
+            return fail(r.message);
+        const structured = { ok: true, positioned: res.positions.size, ...(r.version !== undefined ? { version: r.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_set_meta', {
+        title: 'Set portfolio settings',
+        description: 'Graph-level settings that travel with the portfolio (the `__graph_meta__` record): `context_text` (the portfolio\'s context notes — what a newcomer reads first), `palette` ({ id, name, swatches: [{hex, label?}] ≤ 10, roles?: {epic, feature, story, …: hex | "p:N"} }), `canvas_style`, `sprint_settings`. Only the keys you pass change; everything else in the record is kept.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            context_text: z.string().max(20000).optional(),
+            palette: z.object({ id: z.string().min(1).max(64), name: z.string().min(1).max(64), swatches: z.array(z.object({ hex: z.string().regex(/^#[0-9a-fA-F]{6}$/), label: z.string().max(32).optional() })).max(10), roles: z.record(z.string()).optional() }).optional(),
+            canvas_style: z.record(z.unknown()).optional(),
+            sprint_settings: z.record(z.unknown()).optional(),
+            expected_version: z.number().int().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async (a) => {
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const cur = g.nodes.find(n => n.id === '__graph_meta__' || n.type === 'graph-meta');
+        const data = { ...(cur?.data ?? {}) };
+        if (a.context_text !== undefined)
+            data.contextText = a.context_text;
+        if (a.palette)
+            data.palette = { ...a.palette, swatches: a.palette.swatches.map(s => ({ ...s, hex: s.hex.toUpperCase() })), roles: a.palette.roles ?? {} };
+        if (a.canvas_style)
+            data.canvasStyle = { ...(data.canvasStyle ?? {}), ...a.canvas_style };
+        if (a.sprint_settings)
+            data.sprintSettings = { ...(data.sprintSettings ?? {}), ...a.sprint_settings };
+        const meta = { id: '__graph_meta__', type: 'graph-meta', position: { x: 0, y: 0 }, data };
+        const nodes = cur ? g.nodes.map(n => n === cur ? meta : n) : [...g.nodes, meta];
+        const r = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes }, a.expected_version);
+        if (!r.ok)
+            return fail(r.message);
+        const structured = { ok: true, keys: Object.keys(data), ...(r.version !== undefined ? { version: r.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('portfolio_asset_upload', {
+        title: 'Upload an image',
+        description: 'Store one image (PNG / JPEG / WebP / GIF, ≤ 2.2 MB — downscale first; the app keeps images at 1024 px JPEG) in your private asset store and get back its URL, for an item\'s `images` (card hero) or IP evidence (`ip_evidence_add` kind image with {asset: key}). Pass `data_url`, or `file_path` when this server runs locally (stdio).',
+        inputSchema: {
+            data_url: z.string().regex(/^data:image\/(png|jpeg|webp|gif);base64,/).optional(),
+            file_path: z.string().max(1024).optional(),
+        },
+        outputSchema: { url: z.string(), key: z.string().optional(), bytes: z.number() },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        let dataUrl = a.data_url;
+        if (!dataUrl && a.file_path) {
+            if (!ctx.readLocalImage)
+                return fail('file_path is only available when the MCP server runs locally — pass data_url instead.');
+            dataUrl = await ctx.readLocalImage(a.file_path);
+        }
+        if (!dataUrl)
+            return fail('Provide data_url or file_path.');
+        const bytes = Math.floor((dataUrl.length - dataUrl.indexOf(',') - 1) * 3 / 4);
+        if (bytes > MAX_ASSET_BYTES)
+            return fail(`The image is ${(bytes / 1e6).toFixed(1)} MB; the limit is 2.2 MB. Downscale it (1024 px JPEG is what the app stores) and retry.`);
+        const out = await expectJson(await api(ctx, '/api/portfolio/storyboard-assets', { method: 'POST', body: JSON.stringify({ dataUrl }) }), 'portfolio_asset_upload');
+        const url = out.url ? String(out.url) : out.key ? `/api/portfolio/asset?key=${encodeURIComponent(String(out.key))}` : '';
+        if (!url)
+            return fail('portfolio_asset_upload: the server returned no url.');
+        const structured = { url, ...(out.key ? { key: String(out.key) } : {}), bytes };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+    server.registerTool('ip_create', {
+        title: 'Create an IP node',
+        description: 'Add an IP node — a patent or trademark disclosure — to a portfolio, wired to its source items (the cards the disclosure is prepared FROM: their title, description, BLUF, acceptance criteria and hypothesis). Placed above its first source like the canvas does, with an empty disclosure bag; then fill it in the app (Continue → prefills from the sources on your key) or with ip_update. Requires the IP node feature to be on for the caller.',
+        inputSchema: {
+            portfolio_id: z.string(),
+            track: z.enum(['patent', 'trademark']),
+            kind: z.enum(['provisional', 'nonprovisional', 'design', 'application']).optional().describe('patent: provisional (default) / nonprovisional / design; trademark: application.'),
+            title: z.string().max(200).optional().describe('The filing\'s working title shown on the card.'),
+            sources: z.array(z.string()).min(1).max(20).describe('Item ids the disclosure reads from (first = the one it sits above).'),
+            layout: z.enum(['timeline', 'none']).optional().describe('Default timeline: re-lay the portfolio so the node gets its own row above its source. "none": place it 40 px above the source and move nothing else.'),
+            expected_version: z.number().int().optional(),
+        },
+        outputSchema: { nodeId: z.string(), version: z.number().optional() },
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    }, async (a) => {
+        const track = a.track;
+        if (a.kind && !IP_KINDS[track].includes(a.kind))
+            return fail(`kind ${a.kind} is not a ${track} kind (${IP_KINDS[track].join(', ')}).`);
+        const g = await loadGraph(ctx, a.portfolio_id);
+        const items = new Map(g.nodes.filter(isItem).map(n => [n.id, n]));
+        const missing = a.sources.filter(s => !items.has(s));
+        if (missing.length)
+            return fail(`Not items in this portfolio: ${missing.join(', ')}`);
+        const src = items.get(a.sources[0]);
+        const nodeId = `radmod-ip-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const bag = { ...emptyIp(track, a.kind), title: a.title ?? '' };
+        const node = {
+            id: nodeId, type: 'rad-module',
+            position: { x: (src.position?.x ?? 0) + 8 - IP_NODE_SIZE.width / 2, y: (src.position?.y ?? 0) - IP_NODE_SIZE.height - 40 },
+            data: { subtype: 'ip', moduleData: bag, width: IP_NODE_SIZE.width, height: IP_NODE_SIZE.height, attachedItemIds: [...new Set(a.sources)] },
+        };
+        let nodes = [...g.nodes, node];
+        if ((a.layout ?? 'timeline') === 'timeline')
+            nodes = applyLayout(nodes, layoutTimeline(nodes));
+        const r = await saveGraph(ctx, a.portfolio_id, g, { ...g, nodes }, a.expected_version);
+        if (!r.ok)
+            return fail(r.message);
+        const structured = { nodeId, ...(r.version !== undefined ? { version: r.version } : {}) };
+        return { content: [text(structured)], structuredContent: structured };
+    });
+}

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;