@motionode/cli 0.1.2 → 0.2.1

package/lib/git_credential.js

@@ -0,0 +1,152 @@
+'use strict';
+
+/**
+ * Git access to Motionode-hosted repositories, through Motionode.
+ *
+ * A Motionode-hosted repository lives privately in Motionode's GitHub organization, so your own GitHub account does not
+ * reach it. `motionode clone` clones it from this Motionode's git proxy (<api>/git/<owner>/<repo>.git) and sets this
+ * CLI as the clone's git credential helper: each time git needs to authenticate, the helper asks Motionode for a
+ * short-lived credential for that one repository, as the connected computer. Plain git (and Cursor, VS Code, Claude
+ * Code) then just works in that folder. Nothing is written to your global git config.
+ */
+
+const path = require('path');
+const { spawn } = require('child_process');
+const { client } = require('./api');
+
+/** git credential protocol: key=value lines. */
+function parseCredentialInput(raw) {
+	const out = {};
+	for (const line of String(raw || '').split(/\r?\n/)) {
+		const i = line.indexOf('=');
+		if (i > 0) out[line.slice(0, i)] = line.slice(i + 1);
+	}
+	return out;
+}
+
+function readStdin() {
+	return new Promise((resolve) => {
+		let data = '';
+		process.stdin.setEncoding('utf8');
+		process.stdin.on('data', (chunk) => { data += chunk; });
+		process.stdin.on('end', () => resolve(data));
+		process.stdin.on('error', () => resolve(data));
+	});
+}
+
+/** Whether a git credential request is for this Motionode's git proxy. */
+function isForThisMotionode(config, input) {
+	try {
+		const api = new URL(config.apiUrl);
+		return String(input.host || '').toLowerCase() === api.host.toLowerCase()
+			&& String(input.protocol || '').toLowerCase() === api.protocol.replace(/:$/, '');
+	} catch (_e) {
+		return false;
+	}
+}
+
+/**
+ * `motionode git-credential <get|store|erase>` — git runs this as the clone's credential helper. Only `get` answers;
+ * a request for any other host gets no answer, so git falls back to whatever else is configured.
+ */
+async function helper(config, operation, { input = null, out = process.stdout } = {}) {
+	if (operation !== 'get') return null;
+	const fields = parseCredentialInput(input == null ? await readStdin() : input);
+	if (!isForThisMotionode(config, fields) || !config.token) return null;
+	const pathname = String(fields.path || '').replace(/^\/+/, '');
+	if (!pathname.startsWith('git/')) return null;
+	try {
+		const { credential } = await client(config).post('/git-credential', { path: pathname });
+		out.write(`username=${credential.username}\npassword=${credential.password}\n`);
+	} catch (err) {
+		// git shows helper stderr; say why, then give no credential (git then reports the refusal).
+		process.stderr.write(`motionode: ${err.message}\n`);
+	}
+	return null;
+}
+
+/** The proxy address of a Motionode-hosted repository on this Motionode. */
+function proxyUrl(config, { owner, repo }) {
+	return `${String(config.apiUrl).replace(/\/+$/, '')}/git/${owner}/${String(repo).replace(/\.git$/, '')}.git`;
+}
+
+/** owner/repo of a github.com URL or an "owner/repo" string. */
+function ownerRepoOf(value) {
+	const m = String(value || '').trim().match(/(?:github\.com[/:])?([^/\s:]+)\/([^/\s]+?)(?:\.git)?\/?$/);
+	return m ? { owner: m[1], repo: m[2] } : null;
+}
+
+/**
+ * owner/repo behind a Motionode git-proxy URL on this Motionode
+ * (`<api>/git/<owner>/<repo>.git`), or null for any other remote. The clone
+ * `motionode clone` makes has this remote, and `motionode link` needs the
+ * repository it stands for (QA-20261023T234000Z).
+ */
+function proxiedRepoOf(config, remoteUrl) {
+	try {
+		const remote = new URL(String(remoteUrl || ''));
+		const api = new URL(String(config?.apiUrl || ''));
+		if (remote.host.toLowerCase() !== api.host.toLowerCase()) return null;
+		const m = remote.pathname.match(/^\/git\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/);
+		return m ? { owner: decodeURIComponent(m[1]), repo: decodeURIComponent(m[2]) } : null;
+	} catch (_e) {
+		return null;
+	}
+}
+
+/** The git config that makes this CLI the credential helper for one folder (never global). */
+function helperConfig(config) {
+	const bin = path.resolve(__dirname, '..', 'bin', 'motionode.js');
+	const quote = (s) => `'${String(s).replace(/'/g, "'\\''")}'`;
+	return [
+		['credential.helper', ''],
+		['credential.helper', `!${quote(process.execPath)} ${quote(bin)} git-credential --api ${quote(config.apiUrl)}`],
+		['credential.useHttpPath', 'true'],
+	];
+}
+
+function git(args, { cwd = process.cwd() } = {}) {
+	return new Promise((resolve, reject) => {
+		const proc = spawn('git', args, { cwd, stdio: 'inherit' });
+		proc.on('error', reject);
+		proc.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`git ${args[0]} failed (exit ${code}).`))));
+	});
+}
+
+/**
+ * `motionode clone <service name | owner/repo> [dir]` — clone a Motionode-hosted repository through Motionode and
+ * keep this CLI as that folder's credential helper.
+ */
+async function clone(config, target, dir = null) {
+	if (!config.token) throw new Error('Connect this computer first: run `motionode connect`.');
+	if (!target) throw new Error('Usage: motionode clone <service name | owner/repo> [folder]');
+	let ref = String(target).includes('/') ? ownerRepoOf(target) : null;
+	if (!ref) {
+		const me = await client(config).get('/me');
+		const wanted = String(target).trim().toLowerCase();
+		const services = (me.projects || []).flatMap((p) => (p.services || []).map((s) => ({ ...s, project: p.name })));
+		const hits = services.filter((s) => s.hosting === 'motionode' && [s.name, s.uuid].map((v) => String(v || '').toLowerCase()).includes(wanted));
+		if (hits.length !== 1) {
+			throw new Error(hits.length
+				? `More than one service is called "${target}": ${hits.map((s) => `${s.name} (${s.project})`).join(', ')}. Use owner/repo.`
+				: `No Motionode-hosted service called "${target}" on your projects.`);
+		}
+		ref = ownerRepoOf(hits[0].repoUrl);
+		if (!ref) throw new Error(`"${target}" has no repository yet.`);
+	}
+	const folder = dir || ref.repo;
+	const settings = helperConfig(config);
+	const cloneArgs = [...settings.flatMap(([k, v]) => ['-c', `${k}=${v}`]), 'clone'];
+	await git([...cloneArgs, proxyUrl(config, ref), folder]);
+	// Keep the helper in the clone's own config, so later fetches and pulls authenticate the same way.
+	const cwd = path.resolve(folder);
+	await git(['config', '--local', '--unset-all', 'credential.helper'], { cwd }).catch(() => {});
+	for (const [k, v] of settings) {
+		// eslint-disable-next-line no-await-in-loop
+		await git(['config', '--local', '--add', k, v], { cwd });
+	}
+	console.log(`✓ Cloned ${ref.owner}/${ref.repo} into ${folder} through Motionode. Run \`motionode link\` inside it to tie it to your tickets.`);
+	return null;
+}
+
+module.exports = { helper, clone, parseCredentialInput, isForThisMotionode, proxyUrl, ownerRepoOf, proxiedRepoOf, helperConfig };

package/lib/inbox.js

@@ -0,0 +1,75 @@
+'use strict';
+
+/**
+ * The local signal inbox: <repo>/.motionode/inbox.json.
+ * `motionode signals watch` writes signals here the moment Motionode pushes them;
+ * the hook and the MCP server read it locally (instant, no network, no model).
+ * A signal leaves the inbox when it is acknowledged (MCP ack_signal).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+function repoRoot(dir = process.cwd()) {
+	try {
+		return execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: dir, stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim() || dir;
+	} catch (_e) {
+		return dir;
+	}
+}
+
+function inboxPath(dir) {
+	return path.join(repoRoot(dir), '.motionode', 'inbox.json');
+}
+
+/** Keep .motionode/ out of git without touching the repo's tracked .gitignore. */
+function ensureExcluded(dir) {
+	try {
+		const root = repoRoot(dir);
+		const exclude = path.join(root, '.git', 'info', 'exclude');
+		if (!fs.existsSync(path.dirname(exclude))) return;
+		const current = fs.existsSync(exclude) ? fs.readFileSync(exclude, 'utf8') : '';
+		if (!/^\.motionode\/?$/m.test(current)) fs.appendFileSync(exclude, `${current.endsWith('\n') || !current ? '' : '\n'}.motionode/\n`);
+	} catch (_e) { /* best effort */ }
+}
+
+function read(dir) {
+	try {
+		const data = JSON.parse(fs.readFileSync(inboxPath(dir), 'utf8'));
+		return Array.isArray(data?.signals) ? data.signals : [];
+	} catch (_e) {
+		return [];
+	}
+}
+
+function write(dir, signals) {
+	const file = inboxPath(dir);
+	fs.mkdirSync(path.dirname(file), { recursive: true });
+	const tmp = `${file}.${process.pid}.tmp`;
+	fs.writeFileSync(tmp, JSON.stringify({ updatedAt: new Date().toISOString(), signals }, null, 2));
+	fs.renameSync(tmp, file);
+}
+
+function ticketRefOf(signal) {
+	if (signal?.toRoom?.kind === 'ticket') return signal.toRoom.uuid;
+	if (signal?.fromRoom?.kind === 'ticket') return signal.fromRoom.uuid;
+	return signal?.ticketRef || null;
+}
+
+function add(dir, signal) {
+	const list = read(dir);
+	if (list.some((s) => s.id === signal.id)) return false;
+	list.push({ ...signal, ticketRef: ticketRefOf(signal), receivedAt: new Date().toISOString() });
+	write(dir, list.slice(-200));
+	return true;
+}
+
+function remove(dir, id) {
+	const list = read(dir);
+	const next = list.filter((s) => Number(s.id) !== Number(id));
+	if (next.length !== list.length) write(dir, next);
+	return next.length !== list.length;
+}
+
+module.exports = { repoRoot, inboxPath, ensureExcluded, read, write, add, remove, ticketRefOf };

package/lib/mcp.js

@@ -0,0 +1,327 @@
+'use strict';
+
+/**
+ * `motionode mcp`: a stdio MCP server so Claude Code, Cursor or any MCP client
+ * can work a Motionode ticket as a first-class worker (team-coordination spec §4.3).
+ * Every tool calls Motionode's /api/v1/agent as the connected person; Motionode
+ * applies the same permission checks as the web app.
+ *
+ * Transport: newline-delimited JSON-RPC 2.0 on stdin/stdout. Logs go to stderr only.
+ */
+
+const readline = require('readline');
+const pkg = require('../package.json');
+const { agentClient } = require('./agent_api');
+const Inbox = require('./inbox');
+
+const FALLBACK_PROTOCOL = '2025-06-18';
+const DISCOVER_VERSIONS = ['2026-07-28'];
+
+const TOOLS = [
+	{
+		name: 'my_work',
+		description: 'Tickets assigned to me in Motionode, with their current step and how many signals are waiting.',
+		inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+		run: (api) => api.get('/my_work'),
+	},
+	{
+		name: 'get_ticket',
+		description: 'One ticket: description, acceptance criteria, current step, branches per service, and pending signals. ref = ticket id like T11-604 or its uuid.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' } }, required: ['ref'], additionalProperties: false },
+		run: (api, a) => api.get(`/ticket/${encodeURIComponent(a.ref)}`),
+	},
+	{
+		name: 'get_signals',
+		description: 'Signals for a ticket that I have not resolved yet (requirement changes, questions answered, overlaps, conflicts, failed checks). Check these at every task boundary.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' } }, required: ['ref'], additionalProperties: false },
+		run: (api, a) => api.get(`/ticket/${encodeURIComponent(a.ref)}/signals`),
+	},
+	{
+		name: 'ack_signal',
+		description: 'Acknowledge a signal. Set incorporated=true (with how = one sentence) only once your work actually reflects it.',
+		inputSchema: {
+			type: 'object',
+			properties: { ref: { type: 'string' }, id: { type: 'number' }, incorporated: { type: 'boolean' }, how: { type: 'string' } },
+			required: ['ref', 'id'],
+			additionalProperties: false,
+		},
+		run: async (api, a) => {
+			const out = await api.post(`/ticket/${encodeURIComponent(a.ref)}/signals/${Number(a.id)}/ack`, { incorporated: !!a.incorporated, how: a.how || null });
+			Inbox.remove(process.cwd(), a.id);
+			return out;
+		},
+	},
+	{
+		name: 'start_step',
+		description: 'Start my assigned step on the ticket and register this session as its worker.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' } }, required: ['ref'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/start_step`, {}),
+	},
+	{
+		name: 'report_progress',
+		description: 'One short line about what you are doing now (shown to the team; not a log).',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, text: { type: 'string' }, percent: { type: 'number' } }, required: ['ref', 'text'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/progress`, { text: a.text, percent: a.percent ?? null }),
+	},
+	{
+		name: 'ask_question',
+		description: 'Ask a question you cannot answer from the ticket. Motionode routes it (rules, the project manager, or the client) and the answer arrives as a signal.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, question: { type: 'string' } }, required: ['ref', 'question'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/question`, { question: a.question }),
+	},
+	{
+		name: 'report_discovery',
+		description: 'You found something that may affect other work (a changed contract, a new status, a shared function). Motionode tells the tickets that change the same files, and the topic the work came from.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, text: { type: 'string' }, files: { type: 'array', items: { type: 'string' } } }, required: ['ref', 'text'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/discovery`, { text: a.text, files: a.files || [] }),
+	},
+	{
+		name: 'request_review',
+		description: 'You finished the step: propose completion with a short summary. A person accepts it in Motionode.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, summary: { type: 'string' } }, required: ['ref', 'summary'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/review`, { summary: a.summary }),
+	},
+	// ---- C1 coordination records: claims, observations, decisions, blockers, evidence (team-coordination C1) ----
+	{
+		name: 'claim_step',
+		description: 'Claim the ticket\'s current step before working on it (and start it). Exclusive: if another worker holds it you get who and until when. The claim is a lease (30 min default) that every call you make on the ticket renews; release it when you stop. Needs MOTIONODE_AGENT (your agent name).',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, lease_min: { type: 'number' }, note: { type: 'string' } }, required: ['ref'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/claim`, { lease_min: a.lease_min ?? null, note: a.note || null }),
+	},
+	{
+		name: 'release_step',
+		description: 'Release your claim on the ticket\'s step: reason "done" (your part is finished) or "handoff" (someone else should take it; say why in note).',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, reason: { type: 'string', enum: ['done', 'handoff'] }, note: { type: 'string' } }, required: ['ref', 'reason'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/release`, { reason: a.reason, note: a.note || null }),
+	},
+	{
+		name: 'report_observation',
+		description: 'Record something you or a tester SAW (a symptom), with its evidence: steps, env, sha, screenshots, preview url. It stays on this ticket; the coordinator links it to the one root-cause ticket.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, text: { type: 'string' }, title: { type: 'string' }, evidence: { type: 'object' } }, required: ['ref', 'text'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/observation`, { text: a.text, title: a.title || null, evidence: a.evidence || null }),
+	},
+	{
+		name: 'report_finding',
+		description: 'Record a cause. verified=true only when established by evidence that holds (not suspected); root_cause=true when it names the one accountable problem.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, text: { type: 'string' }, title: { type: 'string' }, verified: { type: 'boolean' }, root_cause: { type: 'boolean' }, evidence: { type: 'object' } }, required: ['ref', 'text'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/finding`, { text: a.text, title: a.title || null, verified: a.verified === true, root_cause: a.root_cause === true, evidence: a.evidence || null }),
+	},
+	{
+		name: 'link_observation',
+		description: 'Coordinator/manager: this ticket is the root cause of that observation (its uuid, on any ticket of the project). note = why. undo=true reverses it.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, observation: { type: 'string' }, note: { type: 'string' }, undo: { type: 'boolean' } }, required: ['ref', 'observation', 'note'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/link_observation`, { observation: a.observation, note: a.note, undo: a.undo === true }),
+	},
+	{
+		name: 'relate_work',
+		description: 'Coordinator/manager: kind "duplicate_of" (this ticket is the same problem as other ticket) or "affects" (this root cause also affects other: a ticket, request or topic, whose people are told). note = why. undo=true reverses it.',
+		inputSchema: {
+			type: 'object',
+			properties: { ref: { type: 'string' }, kind: { type: 'string', enum: ['duplicate_of', 'affects'] }, other_type: { type: 'string', enum: ['ticket', 'request', 'topic'] }, other_ref: { type: 'string' }, note: { type: 'string' }, undo: { type: 'boolean' } },
+			required: ['ref', 'kind', 'other_type', 'other_ref', 'note'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/relate`, { kind: a.kind, other: { type: a.other_type, ref: a.other_ref }, note: a.note, undo: a.undo === true }),
+	},
+	{
+		name: 'ask_decision',
+		description: 'A decision only a person can take, with at least two options (label + consequence). One owner (a user uuid; default the project manager), due in due_hours (default 24). Past due it is re-sent. The choice arrives as a "decided" signal.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				ref: { type: 'string' },
+				question: { type: 'string' },
+				options: { type: 'array', items: { type: 'object', properties: { key: { type: 'string' }, label: { type: 'string' }, consequence: { type: 'string' } }, required: ['label'] } },
+				owner: { type: 'string' },
+				backup: { type: 'string' },
+				due_hours: { type: 'number' },
+			},
+			required: ['ref', 'question', 'options'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/decision`, { question: a.question, options: a.options, owner: a.owner || null, backup: a.backup || null, due_hours: a.due_hours ?? null }),
+	},
+	{
+		name: 'choose_decision',
+		description: 'Record the option taken on a decision (its uuid) -- only its owner, an addressee or a project decider may.',
+		inputSchema: { type: 'object', properties: { decision: { type: 'string' }, option: { type: 'string' }, note: { type: 'string' } }, required: ['decision', 'option'], additionalProperties: false },
+		run: (api, a) => api.post(`/decision/${encodeURIComponent(a.decision)}/choose`, { option: a.option, note: a.note || null }),
+	},
+	{
+		name: 'report_blocker',
+		description: 'The current step cannot go on. It goes Waiting with your reason. Say what it waits on: blocking_ticket (another ticket, a real dependency) or decision {question, options} (a person\'s choice). category: CLIENT, VENDOR, INTERNAL, DEPENDENCY or OTHER.',
+		inputSchema: {
+			type: 'object',
+			properties: {
+				ref: { type: 'string' },
+				reason: { type: 'string' },
+				category: { type: 'string', enum: ['CLIENT', 'VENDOR', 'INTERNAL', 'DEPENDENCY', 'OTHER'] },
+				blocking_ticket: { type: 'string' },
+				decision: { type: 'object', properties: { question: { type: 'string' }, options: { type: 'array' }, owner: { type: 'string' }, due_hours: { type: 'number' } }, required: ['question', 'options'] },
+			},
+			required: ['ref', 'reason'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/blocker`, { reason: a.reason, category: a.category || null, ticket: a.blocking_ticket || null, decision: a.decision || null }),
+	},
+	{
+		name: 'submit_evidence',
+		description: 'Evidence your fix rests on, bound to a commit. kind fails_without: data {test, command, without:{sha, output}, with:{sha, output}}. suite_baseline: sha + data {suites, before:{passed,failed}, after:{passed,failed}}. preview_check: record = the browser-check run id. tester_recheck: record = a person\'s QA result id (you cannot be the tester). Returns the ticket\'s readiness.',
+		inputSchema: {
+			type: 'object',
+			properties: { ref: { type: 'string' }, kind: { type: 'string', enum: ['fails_without', 'suite_baseline', 'preview_check', 'tester_recheck'] }, sha: { type: 'string' }, record: { type: 'string' }, note: { type: 'string' }, data: { type: 'object' } },
+			required: ['ref', 'kind'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/evidence`, { kind: a.kind, sha: a.sha || null, ref: a.record || null, note: a.note || null, data: a.data || null }),
+	},
+	{
+		name: 'open_hotfix',
+		description: 'Project manager / owner only: ship one verified fix to staging ahead of the batch (a one-member release, built at once). reason = why it cannot wait. Needs fails_without + a clean suite_baseline; the person\'s re-check may follow the ship.',
+		inputSchema: { type: 'object', properties: { ref: { type: 'string' }, reason: { type: 'string' } }, required: ['ref', 'reason'], additionalProperties: false },
+		run: (api, a) => api.post(`/ticket/${encodeURIComponent(a.ref)}/hotfix`, { reason: a.reason }),
+	},
+	// C1-031: file work and keep project notes (project = uuid or exact name).
+	{
+		name: 'list_deliverables',
+		description: 'A project\'s deliverables (display id, title, uuid), to file work under. project = its uuid or exact name.',
+		inputSchema: { type: 'object', properties: { project: { type: 'string' } }, required: ['project'], additionalProperties: false },
+		run: (api, a) => api.get(`/project/${encodeURIComponent(a.project)}/deliverables`),
+	},
+	{
+		name: 'create_work_item',
+		description: 'File a work item (a ticket in setup; nothing starts). An open ticket with the same title refuses with that ticket: add to it instead, or pass confirmed_new if this is genuinely separate. Related open work comes back as similar. deliverable = display id, uuid or title (default: the project\'s Interrupt deliverable); new_deliverable = a deliverable by name (reused if the project has one).',
+		inputSchema: {
+			type: 'object',
+			properties: { project: { type: 'string' }, title: { type: 'string' }, description: { type: 'string' }, deliverable: { type: 'string' }, new_deliverable: { type: 'string' }, acceptance_criteria: { type: 'array', items: { type: 'string' } }, confirmed_new: { type: 'boolean' } },
+			required: ['project', 'title'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.post(`/project/${encodeURIComponent(a.project)}/work_items`, {
+			title: a.title, description: a.description || '', deliverable: a.deliverable || null, newDeliverable: a.new_deliverable || null,
+			acceptanceCriteria: a.acceptance_criteria || [], confirmedNew: a.confirmed_new === true,
+		}),
+	},
+	{
+		name: 'update_work_item',
+		description: 'Change a work item\'s title and/or description, as me (I need edit rights on its project). ref = its code (T2-21) or uuid. Status changes aren\'t available yet: Motionode has no cancel or close for a work item.',
+		inputSchema: {
+			type: 'object',
+			properties: { project: { type: 'string' }, ref: { type: 'string' }, title: { type: 'string' }, description: { type: 'string' } },
+			required: ['project', 'ref'],
+			additionalProperties: false,
+		},
+		run: (api, a) => api.patch(`/project/${encodeURIComponent(a.project)}/work_items/${encodeURIComponent(a.ref)}`, {
+			...(typeof a.title === 'string' ? { title: a.title } : {}),
+			...(typeof a.description === 'string' ? { description: a.description } : {}),
+		}),
+	},
+	{
+		name: 'list_notes',
+		description: 'The project notes I may read: uuid, title (first line), where attached, size.',
+		inputSchema: { type: 'object', properties: { project: { type: 'string' } }, required: ['project'], additionalProperties: false },
+		run: (api, a) => api.get(`/project/${encodeURIComponent(a.project)}/notes`),
+	},
+	{
+		name: 'read_note',
+		description: 'One project note: its text and HTML.',
+		inputSchema: { type: 'object', properties: { project: { type: 'string' }, uuid: { type: 'string' } }, required: ['project', 'uuid'], additionalProperties: false },
+		run: (api, a) => api.get(`/project/${encodeURIComponent(a.project)}/notes/${encodeURIComponent(a.uuid)}`),
+	},
+	{
+		name: 'write_note',
+		description: 'Create a project note from markdown, or replace one (uuid given; you must have written it or have it shared with you). deliverable or ticket makes it a team note the project team sees; otherwise it is a board note, shared with share_with (emails or user uuids of the project).',
+		inputSchema: {
+			type: 'object',
+			properties: { project: { type: 'string' }, uuid: { type: 'string' }, markdown: { type: 'string' }, category: { type: 'string' }, deliverable: { type: 'string' }, ticket: { type: 'string' }, share_with: { type: 'array', items: { type: 'string' } } },
+			required: ['project', 'markdown'],
+			additionalProperties: false,
+		},
+		run: (api, a) => (a.uuid
+			? api.patch(`/project/${encodeURIComponent(a.project)}/notes/${encodeURIComponent(a.uuid)}`, { markdown: a.markdown, category: a.category || null })
+			: api.post(`/project/${encodeURIComponent(a.project)}/notes`, { markdown: a.markdown, category: a.category || null, deliverable: a.deliverable || null, ticket: a.ticket || null, shareWith: a.share_with || [] })),
+	},
+];
+
+/** Tools a Motionode older than the CLI may not serve yet (a 404 from them means "not offered", not "not found"). */
+const NEWER_TOOLS = new Set(TOOLS.map((t) => t.name).filter((n) => !['my_work', 'get_ticket', 'get_signals', 'ack_signal'].includes(n)));
+
+function send(msg) {
+	process.stdout.write(`${JSON.stringify(msg)}\n`);
+}
+
+async function handle(msg, api) {
+	const { id, method, params } = msg || {};
+	if (method === 'initialize') {
+		return {
+			protocolVersion: params?.protocolVersion || FALLBACK_PROTOCOL,
+			capabilities: { tools: {} },
+			serverInfo: { name: 'motionode', version: pkg.version },
+			instructions: 'Motionode tickets. claim_step before working a step and release_step when you stop. Call get_signals at every task boundary and before finishing; ack_signal with incorporated=true once your work reflects a change. Report what you saw with report_observation, causes with report_finding, blockers with report_blocker, and back every fix with submit_evidence (fails_without + suite_baseline).',
+		};
+	}
+	// Newer MCP handshake (protocol 2026-07-28): server/discover instead of initialize.
+	if (method === 'server/discover') {
+		return {
+			resultType: 'complete',
+			supportedVersions: DISCOVER_VERSIONS,
+			capabilities: { tools: {} },
+			_meta: { 'io.modelcontextprotocol/serverInfo': { name: 'motionode', version: pkg.version } },
+		};
+	}
+	if (method === 'ping') return {};
+	if (method === 'tools/list') {
+		return { resultType: 'complete', tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) };
+	}
+	if (method === 'tools/call') {
+		const tool = TOOLS.find((t) => t.name === params?.name);
+		if (!tool) return { resultType: 'complete', content: [{ type: 'text', text: `Unknown tool ${params?.name}.`, isError: true }], isError: true };
+		try {
+			const out = await tool.run(api, params?.arguments || {});
+			const pending = Inbox.read(process.cwd()).length;
+			const text = JSON.stringify({ ...out, signals_pending: pending }, null, 2);
+			return { resultType: 'complete', content: [{ type: 'text', text }] };
+		} catch (err) {
+			const newer = NEWER_TOOLS.has(tool.name);
+			const msgText = err.status === 404 && newer && /cannot (get|post)|not found$/i.test(err.message || '')
+				? 'This Motionode does not offer that yet.'
+				: err.message;
+			return { resultType: 'complete', content: [{ type: 'text', text: msgText, isError: true }], isError: true };
+		}
+	}
+	if (id === undefined || id === null) return undefined; // notification (e.g. notifications/initialized)
+	const e = new Error(`Method not found: ${method}`);
+	e.code = -32601;
+	throw e;
+}
+
+function serve(config) {
+	const api = agentClient(config);
+	const rl = readline.createInterface({ input: process.stdin, terminal: false });
+	const inflight = new Set();
+	rl.on('line', (line) => {
+		const job = onLine(line);
+		inflight.add(job);
+		job.finally(() => inflight.delete(job));
+	});
+	async function onLine(line) {
+		const trimmed = line.trim();
+		if (!trimmed) return;
+		let msg;
+		try { msg = JSON.parse(trimmed); } catch (_e) {
+			send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+			return;
+		}
+		try {
+			const result = await handle(msg, api);
+			if (msg.id !== undefined && msg.id !== null && result !== undefined) send({ jsonrpc: '2.0', id: msg.id, result });
+		} catch (err) {
+			if (msg.id !== undefined && msg.id !== null) send({ jsonrpc: '2.0', id: msg.id, error: { code: err.code || -32603, message: err.message } });
+		}
+	}
+	// Input closed: answer what is still running, then exit.
+	rl.on('close', async () => { await Promise.allSettled([...inflight]); process.exit(0); });
+	process.stderr.write(`motionode mcp ${pkg.version} serving ${api.base}\n`);
+}
+
+module.exports = { serve, handle, TOOLS };