@sabaiway/agent-workflow-kit 5.11.2 → 7.0.0

package/tools/mcp-registration.mjs

@@ -0,0 +1,283 @@
+// mcp-registration.mjs — the READ-ONLY half of the `mcp` mode: is the kit's stdio MCP server
+// registered in THIS project? It answers for two consumers that must never reach a writer — the
+// `mcp-channel` advisor item and `uninstall`'s report — and the writer (mcp.mjs) composes its bodies
+// from the same merges, so "what is there" and "what would be written" can never drift apart.
+//
+// Split out for the reason bridge-settings-read.mjs was (bridges 2.3.0, D6): a read-only consumer
+// that imports the writer pulls in the atomic-write core, which read-graph-purity.test.mjs forbids.
+// That is also why the two settings-path literals are NOT imported from velocity-profile.mjs (a
+// write module) — the equality is pinned by a test instead.
+//
+// It reads through fs-read-nofollow.mjs rather than velocity's readSettingsFile because that reader
+// follows a symlink: a symlinked `.mcp.json` whose TARGET is a perfect registration would report
+// registered over a file the writer must refuse to touch. Every never-committable dirent class
+// (the sandbox's own device masks, a FIFO, a socket) is a NAMED state, classified by lstat BEFORE
+// any open. Nothing here throws: every failure is a state with its own reason.
+//
+// RESIDUAL, stated as a BOUNDARY. What this module closes is the STATIC case: a symlink, device,
+// FIFO or socket ALREADY at a path is classified, named, and never read — a target decided FOREIGN
+// is never opened. (A target decided REGULAR is of course opened; that is the read.)
+//
+// Against a path that CHANGES under it, this module promises nothing, and the two races are NOT the
+// same shape:
+//   • the LEAF is protected by the shared reader as far as a path-based reader can go — it opens
+//     `O_NOFOLLOW`, fstats the DESCRIPTOR and reads through it, so a swapped SYMLINK cannot be
+//     followed. What it cannot catch is substitution by another REGULAR FILE, which needs the open
+//     bound to an earlier inode observation — inside fs-read-nofollow.mjs, which four consumers
+//     share, so that is the leaf's decision rather than this one's.
+//   • the CONTAINER cannot be closed that way at all: no property of the leaf's descriptor says
+//     anything about the directory the path was resolved through. That needs directory-relative
+//     opening (`openat`), which Node does not expose — so it is a platform limit, not a missing check.
+// Classifying `.claude` before reading inside it closes the STATIC symlinked container — the real and
+// reachable case, where a settings file outside the work tree became a verdict; a container swapped
+// mid-flight is not closed, for the reason above. Earlier drafts of this comment enumerated windows
+// and were corrected three rounds running, each time for being one window too generous. The bar this
+// module meets: no STATIC foreign path is followed or read, and no target decided FOREIGN is opened.
+//
+// Dependency-free, Node >= 22. No writes, no CLI, no side effects on import.
+
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describeNonRegular, lstatNoFollowRead, readRegularFileNoFollow } from './fs-read-nofollow.mjs';
+import { refuseDirectRun } from './direct-run.mjs';
+import { SERVER_NAME, TOOLS } from './mcp-server.mjs';
+
+export { SERVER_NAME };
+
+export const MCP_JSON_REL = '.mcp.json';
+export const CLAUDE_DIR_REL = '.claude';
+export const SETTINGS_REL = '.claude/settings.json';
+export const SERVERS_KEY = 'mcpServers';
+export const ENABLED_KEY = 'enabledMcpjsonServers';
+// OUT OF SCOPE, deliberately and by name: `disabledMcpjsonServers`. A server listed there is rejected
+// by the client in every mode, so a project can hold our entry, the enable and both rules and still
+// have a dark channel — this mode does NOT detect that, and `registered` therefore means "the three
+// things this mode writes are in place", never "the client will load it".
+//
+// It was implemented during review and then SUBTRACTED. The reason is worth keeping: honouring a veto
+// means reading it from every scope the client merges, and each scope has its own masked, symlinked,
+// malformed and unreadable states — in each of which a hidden deny still yields a confident answer.
+// Three review rounds each closed one such hole and opened the next. A check that is wrong in states
+// it cannot enumerate is worse than a stated limit, so this is the stated limit.
+// The RUNNING kit copy's own server — the args entry a registration must carry to reach THIS kit.
+export const DEFAULT_SERVER_PATH = fileURLToPath(new URL('./mcp-server.mjs', import.meta.url));
+
+export const STATE = Object.freeze({
+  ABSENT: 'absent',
+  MASKED: 'masked',
+  FOREIGN: 'foreign',
+  UNREADABLE: 'unreadable',
+  MALFORMED: 'malformed',
+  PRESENT: 'present',
+});
+
+const LF = '\n';
+const CRLF = '\r\n';
+const JSON_INDENT = 2;
+
+// The two allow rules a client needs, derived from the server's own name + tool list — never a
+// re-typed pair (a renamed tool would otherwise ship a rule nothing grants).
+export const allowRulesFor = (tools = TOOLS) => tools.map((tool) => `mcp__${SERVER_NAME}__${tool.name}`);
+
+export const buildServerEntry = (serverPath) => ({ type: 'stdio', command: 'node', args: [serverPath] });
+
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// Key-order-independent structural identity: an entry that differs only in key order is the SAME
+// registration, while an extra key, a different command or a different arg is a real difference.
+const stable = (value) => {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value) ?? 'undefined';
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stable(value[k])}`).join(',')}}`;
+};
+
+// The never-committable stat classes (core-evidence's own review-domain rule, re-decided here rather
+// than imported: core-evidence reaches the atomic-write core and this module may not).
+const isMaskStat = (st) => st.isCharacterDevice() || st.isBlockDevice() || st.isFIFO() || st.isSocket();
+
+// lstat FIRST, then read: the classification decides whether an open may happen at all, so a FIFO is
+// never opened and a symlink is never followed.
+const readTarget = (abs, io) => {
+  let st;
+  try {
+    st = lstatNoFollowRead(abs, io.lstat);
+  } catch (err) {
+    return { state: STATE.UNREADABLE, reason: (err && (err.code || err.message)) || 'lstat failed' };
+  }
+  if (st === null) return { state: STATE.ABSENT };
+  if (isMaskStat(st)) return { state: STATE.MASKED, className: describeNonRegular(st) };
+  if (!st.isFile()) return { state: STATE.FOREIGN, className: describeNonRegular(st) };
+  const r = readRegularFileNoFollow(abs, io);
+  if (r.outcome === 'absent') return { state: STATE.ABSENT };
+  if (r.outcome === 'foreign') return { state: STATE.FOREIGN, className: r.className };
+  if (r.outcome !== 'ok') return { state: STATE.UNREADABLE, reason: r.code };
+  return { state: STATE.PRESENT, text: r.content };
+};
+
+const eolOf = (text) => (text.includes(CRLF) ? CRLF : LF);
+
+// A file we cannot parse is MALFORMED with its own reason — never an empty object, which would let a
+// writer clobber a file it never understood.
+const parseJsonText = (text) => {
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch (err) {
+    return { state: STATE.MALFORMED, reason: `not valid JSON (${(err && err.message) || 'parse failed'})` };
+  }
+  if (!isPlainObject(data)) return { state: STATE.MALFORMED, reason: 'the root is not a JSON object' };
+  return { state: STATE.PRESENT, data };
+};
+
+// A MANAGED key of the wrong type is MALFORMED, not "empty". Reading it as an empty container and
+// merging over it DESTROYS whatever it held — the merge-through-clobber `gate-hook.mjs`
+// (assertHooksShape) already refuses for its own `hooks` key. Only the four keys this mode writes are
+// judged; a foreign key of any shape is data, carried over untouched and never inspected.
+const wrongType = (key, expected) => `carrying a "${key}" key that is not ${expected}`;
+
+const NEUTRAL_ENTRY = { hasEntry: false, existing: null, matches: false, differs: false };
+
+// The two decisions over TEXT. Exported because a consumer that already holds the bytes — the
+// uninstaller, which reads every surface through its own injected fs — must answer "is this OUR
+// registration?" by the SAME rule the reader uses, not by a second copy of it.
+export const decideMcpJsonText = (text, entry) => {
+  const parsed = parseJsonText(text);
+  const eol = eolOf(text);
+  if (parsed.state !== STATE.PRESENT) return { ...parsed, eol, ...NEUTRAL_ENTRY };
+  const servers = parsed.data[SERVERS_KEY];
+  if (servers !== undefined && !isPlainObject(servers)) {
+    return { state: STATE.MALFORMED, eol, reason: wrongType(SERVERS_KEY, 'a JSON object'), ...NEUTRAL_ENTRY };
+  }
+  // PRESENCE is hasOwnProperty, never `value !== null`: a key that is THERE is a declaration this
+  // mode may refuse but must never replace — a literal `null` included.
+  const hasEntry = isPlainObject(servers) && Object.prototype.hasOwnProperty.call(servers, SERVER_NAME);
+  const existing = hasEntry ? servers[SERVER_NAME] : null;
+  const matches = hasEntry && stable(existing) === stable(entry);
+  return { ...parsed, eol, hasEntry, existing, matches, differs: hasEntry && !matches };
+};
+
+export const decideSettingsText = (text, allowRules) => {
+  const parsed = parseJsonText(text);
+  const eol = eolOf(text);
+  const neutral = { enabled: false, allowPresent: [], allowMissing: allowRules, complete: false };
+  if (parsed.state !== STATE.PRESENT) return { ...parsed, eol, ...neutral };
+  const malformed = (reason) => ({ state: STATE.MALFORMED, eol, reason, ...neutral });
+  const enabledList = parsed.data[ENABLED_KEY];
+  if (enabledList !== undefined && !Array.isArray(enabledList)) return malformed(wrongType(ENABLED_KEY, 'a JSON array'));
+  const permissions = parsed.data.permissions;
+  if (permissions !== undefined && !isPlainObject(permissions)) return malformed(wrongType('permissions', 'a JSON object'));
+  const allow = isPlainObject(permissions) ? permissions.allow : undefined;
+  if (allow !== undefined && !Array.isArray(allow)) return malformed(wrongType('permissions.allow', 'a JSON array'));
+  const rules = Array.isArray(allow) ? allow : [];
+  const enabled = Array.isArray(enabledList) && enabledList.includes(SERVER_NAME);
+  const allowMissing = allowRules.filter((rule) => !rules.includes(rule));
+  return {
+    ...parsed,
+    eol,
+    enabled,
+    allowPresent: allowRules.filter((rule) => rules.includes(rule)),
+    allowMissing,
+    // "Everything this mode writes is in place" — see the scope note in the header for what that
+    // deliberately does NOT mean.
+    complete: enabled && allowMissing.length === 0,
+  };
+};
+
+// readRegistration(root, io?) → the full registration picture of ONE project. `io.serverPath`
+// overrides the running kit's server path (tests); every fs primitive in `io` is the fs-read-nofollow
+// injection contract. NEVER throws.
+export const readRegistration = (root, io = {}) => {
+  const serverPath = io.serverPath ?? DEFAULT_SERVER_PATH;
+  const entry = buildServerEntry(serverPath);
+  const allowRules = allowRulesFor();
+
+  const mcpAbs = join(root, MCP_JSON_REL);
+  const mcpRead = readTarget(mcpAbs, io);
+  const mcpJson = { rel: MCP_JSON_REL, abs: mcpAbs, eol: LF, ...NEUTRAL_ENTRY, ...mcpRead,
+    ...(mcpRead.state === STATE.PRESENT ? decideMcpJsonText(mcpRead.text, entry) : {}) };
+
+  // The CONTAINER is classified BEFORE the file inside it is read, and the order is load-bearing:
+  // path resolution follows an INTERMEDIATE symlink (O_NOFOLLOW guards the FINAL component only), so
+  // reading first would pull a settings file from outside the work tree into memory — and into a
+  // verdict, and into a rendered merge body — before anything got the chance to refuse it.
+  const claudeDirAbs = join(root, CLAUDE_DIR_REL);
+  const claudeDir = { rel: CLAUDE_DIR_REL, abs: claudeDirAbs, ...classifyDir(claudeDirAbs, io) };
+  const containerUsable = claudeDir.state === STATE.PRESENT || claudeDir.state === STATE.ABSENT;
+
+  // settings.local.json is NOT read at all: this mode never writes it, so counting a rule that lives
+  // only there would report a registration the writer cannot maintain. (Reading it for the deny veto
+  // alone was tried and subtracted — see the scope note in the header.)
+  const settingsAbs = join(root, SETTINGS_REL);
+  const settingsRead = containerUsable
+    ? readTarget(settingsAbs, io)
+    : { state: STATE.UNREADABLE, reason: `${CLAUDE_DIR_REL} is a ${claudeDir.className ?? claudeDir.reason} — refusing to read through it` };
+  const neutralAllow = { enabled: false, allowPresent: [], allowMissing: allowRules, complete: false };
+  const settings = { rel: SETTINGS_REL, abs: settingsAbs, eol: LF, ...neutralAllow, ...settingsRead,
+    ...(settingsRead.state === STATE.PRESENT ? decideSettingsText(settingsRead.text, allowRules) : {}) };
+
+  return {
+    root,
+    serverPath,
+    entry,
+    allowRules,
+    mcpJson,
+    settings,
+    claudeDir,
+    registered: mcpJson.matches && settings.complete,
+  };
+};
+
+// The `.claude/` container: an ABSENT dir is a named state the preflight reports and only `--apply`
+// resolves (creating it here would make a read-only preflight write).
+const classifyDir = (abs, io) => {
+  let st;
+  try {
+    st = lstatNoFollowRead(abs, io.lstat);
+  } catch (err) {
+    return { state: STATE.UNREADABLE, reason: (err && (err.code || err.message)) || 'lstat failed' };
+  }
+  if (st === null) return { state: STATE.ABSENT };
+  if (st.isDirectory()) return { state: STATE.PRESENT };
+  return { state: STATE.FOREIGN, className: describeNonRegular(st) };
+};
+
+// ── the merges (ONE definition, shared by the writer's bodies and the paste-ready fragments) ──
+// Merge-don't-clobber in both: every foreign server, key and allow rule is carried over untouched,
+// and our own entry/rules are added idempotently.
+
+export const mergeMcpJson = (registration) => {
+  const base = isPlainObject(registration.mcpJson.data) ? registration.mcpJson.data : {};
+  const servers = isPlainObject(base[SERVERS_KEY]) ? base[SERVERS_KEY] : {};
+  return { ...base, [SERVERS_KEY]: { ...servers, [SERVER_NAME]: registration.entry } };
+};
+
+export const mergeSettings = (registration) => {
+  const base = isPlainObject(registration.settings.data) ? registration.settings.data : {};
+  const enabled = Array.isArray(base[ENABLED_KEY]) ? base[ENABLED_KEY] : [];
+  const permissions = isPlainObject(base.permissions) ? base.permissions : {};
+  const allow = Array.isArray(permissions.allow) ? permissions.allow : [];
+  return {
+    ...base,
+    [ENABLED_KEY]: enabled.includes(SERVER_NAME) ? enabled : [...enabled, SERVER_NAME],
+    permissions: { ...permissions, allow: [...allow, ...registration.allowRules.filter((rule) => !allow.includes(rule))] },
+  };
+};
+
+export const formatJson = (data, eol) => `${JSON.stringify(data, null, JSON_INDENT).replaceAll(LF, eol)}${eol}`;
+
+// The two hand-apply bodies — the whole output of the MASKED arm.
+//
+// They are deliberately DIFFERENT shapes, because what the kit knows about each file differs. The
+// settings file was OBSERVABLE — and read where present — so its body is a real merge: it already
+// carries every foreign key it had. The masked `.mcp.json` was not observable at all, so a
+// whole-file body would name only our server and, pasted as
+// instructed, would delete every foreign server the mask hid. `mcpEntry` is therefore the ENTRY
+// ALONE, to be merged under `mcpServers` by a human who can see what is actually in that file.
+export const renderFragments = (registration) => ({
+  mcpEntry: formatJson(registration.entry, registration.mcpJson.eol),
+  settings: formatJson(mergeSettings(registration), registration.settings.eol),
+});
+
+// A LIBRARY module the mode doc names by path — so someone can try to run it. A no-op on import;
+// on a direct run it points at the command that acts on what this module only reports.
+refuseDirectRun(import.meta.url);

package/tools/mcp-server.mjs

@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// mcp-server.mjs — the kit's stdio MCP server: the two promptless readers as TYPED tools.
+//
+// WHY THIS EXISTS. Every lane an agent used for a path question or a literal search ended in a STRING
+// handed to a shell, and a string always admits a pipe, a redirect, a quote, an `||`. Here the same two
+// readers (path-inventory.mjs, repo-search.mjs) are reached through named JSON fields: validated against
+// a CLOSED schema, turned into an in-process argv LIST, handed to each reader's exported `main(argv,
+// {cwd})`. No shell, no subprocess, no string — a decoration has no slot; `>`, a backtick, `$(` are bytes.
+// Root = `--root` > env CLAUDE_PROJECT_DIR (Claude Code sets it for a stdio server) > cwd; containment
+// stays the readers' own real-path rule. A client's child, outside any Bash sandbox, read-only,
+// root-contained. Dependency-free, Node >= 22, no side effects on import.
+
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { PassThrough } from 'node:stream';
+import { isDirectRun } from './direct-run.mjs';
+import { JSONRPC_ERRORS, createDispatcher, rpcError, serveStdio } from './mcp-stdio.mjs';
+import {
+  main as inventoryMain,
+  HARD_MAX_CONTENT_BYTES,
+  HARD_MAX_ENTRIES,
+  HARD_MAX_TOTAL_BYTES as INVENTORY_HARD_MAX_TOTAL_BYTES,
+  HARD_MAX_TOTAL_ENTRIES,
+} from './path-inventory.mjs';
+import {
+  main as searchMain,
+  HARD_MAX_TARGETS,
+  HARD_MAX_RESULTS,
+  HARD_MAX_FILE_BYTES,
+  HARD_MAX_TOTAL_BYTES as SEARCH_HARD_MAX_TOTAL_BYTES,
+} from './repo-search.mjs';
+
+export const SERVER_NAME = 'agent-workflow';
+const EXIT_OK = 0;
+const EXIT_FAILED = 1;
+const EXIT_USAGE = 2;
+const ROOT_ENV = 'CLAUDE_PROJECT_DIR';
+const READ_ONLY = Object.freeze({ readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false });
+const INSTRUCTIONS =
+  'Read-only tools over the project root. Prefer them to a shell for a path question (exists / type / size / lines / listing / a small file) and for a literal search: a pattern or path is a JSON field, never a command string.';
+
+const pathList = (description) => ({
+  type: 'array',
+  items: { type: 'string', minLength: 1 },
+  minItems: 1,
+  maxItems: HARD_MAX_TARGETS,
+  description,
+});
+const count = (maximum, description) => ({ type: 'integer', minimum: 0, maximum, description });
+
+// The public definitions — exactly what tools/list returns. The schema a client sees is the schema
+// validateArgs enforces: one object, no second copy to drift.
+export const TOOLS = Object.freeze([
+  Object.freeze({
+    name: 'path_inventory',
+    title: 'Path inventory',
+    description:
+      'Facts about named paths inside the project root, in ONE call: exists, type, bytes, line count (wc -l compatible), a directory listing (one level), and with contents=true the text of a small file. A missing path is a RESULT (absent), never an error. Symlinks are reported by type and never followed; binaries are never decoded.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['paths'],
+      properties: {
+        paths: pathList('Project-relative paths, any number; a trailing "/" asserts a directory.'),
+        contents: { type: 'boolean', description: 'Also return the text of each regular text file.' },
+        maxContentBytes: count(HARD_MAX_CONTENT_BYTES, 'Per-file ceiling for the line count and contents.'),
+        maxEntries: count(HARD_MAX_ENTRIES, 'Per-directory listing ceiling.'),
+        maxTotalBytes: count(INVENTORY_HARD_MAX_TOTAL_BYTES, 'Whole-call byte ceiling.'),
+        maxTotalEntries: count(HARD_MAX_TOTAL_ENTRIES, 'Whole-call listed-entries ceiling.'),
+      },
+    },
+    annotations: READ_ONLY,
+  }),
+  Object.freeze({
+    name: 'repo_search',
+    title: 'Repository search (literal)',
+    description:
+      'LITERAL search (no regex) for a pattern across the project root or the named paths: every hit as file:line with a bounded snippet. The pattern is a plain JSON string, so shell-significant bytes need no quoting. A fired bound is reported as INCOMPLETE with its name, never as an empty result.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      required: ['pattern'],
+      properties: {
+        pattern: { type: 'string', minLength: 1, description: 'The literal bytes to find; multiline allowed.' },
+        paths: pathList('Project-relative search targets (default: the whole root).'),
+        max: count(HARD_MAX_RESULTS, 'Result ceiling.'),
+        maxBytes: count(HARD_MAX_FILE_BYTES, 'Per-file byte ceiling.'),
+        maxTotalBytes: count(SEARCH_HARD_MAX_TOTAL_BYTES, 'Whole-call byte ceiling.'),
+      },
+    },
+    annotations: READ_ONLY,
+  }),
+]);
+
+const numericFlags = (value, pairs) => pairs.flatMap(([key, flag]) => (value[key] === undefined ? [] : [flag, String(value[key])]));
+const pathFlags = (paths = []) => paths.flatMap((p) => ['--path', p]);
+
+// Field → argv, deterministic and ONE flag per field. Kept beside the public definitions by NAME.
+const RUNTIME = Object.freeze({
+  path_inventory: Object.freeze({
+    main: inventoryMain,
+    argv: (v) => [
+      ...pathFlags(v.paths),
+      ...(v.contents === true ? ['--contents'] : []),
+      ...numericFlags(v, [['maxContentBytes', '--max-content-bytes'], ['maxEntries', '--max-entries'], ['maxTotalBytes', '--max-total-bytes'], ['maxTotalEntries', '--max-total-entries']]),
+    ],
+  }),
+  repo_search: Object.freeze({
+    main: searchMain,
+    argv: (v) => ['--pattern', v.pattern, ...pathFlags(v.paths), ...numericFlags(v, [['max', '--max'], ['maxBytes', '--max-bytes'], ['maxTotalBytes', '--max-total-bytes']])],
+  }),
+});
+
+const toolByName = (name) => TOOLS.find((t) => t.name === name);
+const isPlainObject = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+
+// A walker over the schema subset the two tools use — the public schema IS the validator's input. A
+// schema type outside that subset is a fault, never a silent pass; exported so that arm has a test.
+export const checkAgainst = (schema, value, at) => {
+  if (schema.type === 'object') {
+    if (!isPlainObject(value)) return `${at} must be an object`;
+    for (const key of Object.keys(value)) if (!Object.hasOwn(schema.properties, key)) return `${at}: unknown key "${key}"`;
+    for (const key of schema.required ?? []) if (!Object.hasOwn(value, key)) return `${at}: "${key}" is required`;
+    for (const [key, sub] of Object.entries(schema.properties)) {
+      if (!Object.hasOwn(value, key)) continue;
+      const fault = checkAgainst(sub, value[key], `${at}.${key}`);
+      if (fault !== null) return fault;
+    }
+    return null;
+  }
+  if (schema.type === 'string') {
+    if (typeof value !== 'string') return `${at} must be a string`;
+    if (schema.minLength !== undefined && value.length < schema.minLength) return `${at} must not be empty`;
+    // A lone surrogate becomes U+FFFD on the way to the filesystem, so the reader could answer about
+    // a DIFFERENT, existing path — the substitution class the readers refuse; refused here, before argv.
+    if (!value.isWellFormed()) return `${at} must be well-formed Unicode (no lone surrogate)`;
+    return null;
+  }
+  if (schema.type === 'boolean') return typeof value === 'boolean' ? null : `${at} must be a boolean`;
+  if (schema.type === 'integer') {
+    if (!Number.isInteger(value)) return `${at} must be an integer`;
+    if (schema.minimum !== undefined && value < schema.minimum) return `${at} must be >= ${schema.minimum}`;
+    if (schema.maximum !== undefined && value > schema.maximum) return `${at} must be <= ${schema.maximum}`;
+    return null;
+  }
+  if (schema.type === 'array') {
+    if (!Array.isArray(value)) return `${at} must be an array`;
+    if (schema.minItems !== undefined && value.length < schema.minItems) return `${at} must not be empty`;
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) return `${at} holds more than ${schema.maxItems} item(s)`;
+    for (const [i, item] of value.entries()) {
+      const fault = checkAgainst(schema.items, item, `${at}[${i}]`);
+      if (fault !== null) return fault;
+    }
+    return null;
+  }
+  return `${at}: unsupported schema type ${schema.type}`;
+};
+
+export const validateArgs = (name, args) => {
+  const tool = toolByName(name);
+  if (tool === undefined) return { ok: false, message: `Unknown tool: ${name}` };
+  const fault = checkAgainst(tool.inputSchema, args, 'arguments');
+  return fault === null ? { ok: true, value: args } : { ok: false, message: fault };
+};
+
+export const toolArgv = (name, args) => {
+  if (!Object.hasOwn(RUNTIME, name)) throw rpcError(JSONRPC_ERRORS.INVALID_PARAMS, `Unknown tool: ${name}`);
+  return RUNTIME[name].argv(args);
+};
+
+// Reader outcome → tool result. 0 and 3 (INCOMPLETE, the reader names the bound in its own stdout)
+// are answers; 1 (I/O or containment refusal) and 2 (usage) are errors carrying the reader's stderr.
+export const toToolResult = (r) => {
+  const isError = !(r.code === 0 || r.code === 3);
+  const text = isError ? (r.stderr || r.stdout) : r.stdout;
+  return { content: [{ type: 'text', text }], isError };
+};
+
+export const callTool = (name, args, root) => {
+  if (!Object.hasOwn(RUNTIME, name)) throw rpcError(JSONRPC_ERRORS.INVALID_PARAMS, `Unknown tool: ${name}`);
+  const verdict = validateArgs(name, args);
+  if (!verdict.ok) throw rpcError(JSONRPC_ERRORS.INVALID_PARAMS, `${name}: ${verdict.message}`);
+  return toToolResult(RUNTIME[name].main(toolArgv(name, verdict.value), { cwd: root }));
+};
+
+const usage = (message) => Object.assign(new Error(message), { exitCode: EXIT_USAGE });
+
+export const parseArgv = (argv) => {
+  const opts = { root: null, selfCheck: false, help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') opts.help = true;
+    else if (arg === '--self-check') opts.selfCheck = true;
+    else if (arg === '--root') {
+      i += 1;
+      // An EMPTY value is refused: `'' ?? env` keeps the empty string, and resolve(cwd, '') is the cwd —
+      // a silent override of a correct CLAUDE_PROJECT_DIR by whatever directory the client started in.
+      if (argv[i] === undefined || argv[i] === '') throw usage('--root requires a non-empty value');
+      opts.root = argv[i];
+    } else throw usage(`unknown argument: ${arg} (see --help)`);
+  }
+  return opts;
+};
+
+export const resolveRoot = ({ argv = [], env = {}, cwd }) => {
+  const opts = parseArgv(argv);
+  const fromEnv = typeof env[ROOT_ENV] === 'string' && env[ROOT_ENV] !== '' ? env[ROOT_ENV] : null;
+  // The same rule as a tool argument: a lone surrogate would reach the filesystem as U+FFFD and pick
+  // a DIFFERENT existing directory as the root. EVERY string resolve() will see is checked — the flag,
+  // the env value and the cwd a relative candidate resolves against — not only the one selected.
+  for (const [source, value] of [['--root', opts.root], [ROOT_ENV, fromEnv], ['cwd', cwd]]) {
+    if (value === null) continue;
+    if (typeof value !== 'string' || !value.isWellFormed()) throw usage(`${source} must be a well-formed Unicode string (no lone surrogate)`);
+  }
+  const candidate = opts.root ?? fromEnv ?? cwd;
+  let real;
+  try {
+    real = realpathSync(resolve(cwd, candidate));
+  } catch (err) {
+    throw usage(`root does not exist: ${candidate} (${err?.code ?? err?.message ?? err})`);
+  }
+  if (!statSync(real).isDirectory()) throw usage(`root is not a directory: ${candidate}`);
+  return real;
+};
+
+// The kit's package version, informational: an unreadable or versionless package.json degrades to 0.0.0.
+export const readServerVersion = (readFile = readFileSync) => {
+  try {
+    return JSON.parse(readFile(new URL('../package.json', import.meta.url), 'utf8')).version ?? '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+};
+
+export const createServer = ({ root }) =>
+  createDispatcher({
+    serverInfo: { name: SERVER_NAME, version: readServerVersion() },
+    capabilities: { tools: {} },
+    instructions: INSTRUCTIONS,
+    handlers: {
+      'tools/list': () => ({ tools: TOOLS }),
+      'tools/call': (params) => {
+        if (typeof params.name !== 'string') throw rpcError(JSONRPC_ERRORS.INVALID_PARAMS, 'tools/call: "name" must be a string');
+        return callTool(params.name, params.arguments ?? {}, root);
+      },
+    },
+  });
+
+// In-process round trip through the SAME transport and dispatcher a client drives: the installed bytes
+// load, the handshake answers, both tools answer a call rooted here. No process is spawned.
+export const selfCheck = async ({ root }) => {
+  const input = new PassThrough();
+  const lines = [];
+  const done = serveStdio({ input, output: { write: (t) => lines.push(t) }, dispatcher: createServer({ root }) });
+  const requests = [
+    { jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'self-check', version: '0' } } },
+    { jsonrpc: '2.0', method: 'notifications/initialized' },
+    { jsonrpc: '2.0', id: 2, method: 'tools/list' },
+    { jsonrpc: '2.0', id: 3, method: 'tools/call', params: { name: 'path_inventory', arguments: { paths: ['.'] } } },
+    { jsonrpc: '2.0', id: 4, method: 'tools/call', params: { name: 'repo_search', arguments: { pattern: '2>/dev/null', paths: ['.'], max: 1 } } },
+  ];
+  input.end(requests.map((r) => `${JSON.stringify(r)}\n`).join(''));
+  await done;
+  const answers = lines.map((l) => JSON.parse(l));
+  const byId = (id) => answers.find((a) => a.id === id);
+  const checks = [
+    ['initialize answered', byId(1)?.result?.protocolVersion !== undefined],
+    ['tools/list names both tools', JSON.stringify(byId(2)?.result?.tools?.map((t) => t.name)) === JSON.stringify(TOOLS.map((t) => t.name))],
+    ['path_inventory answers', byId(3)?.result?.isError === false],
+    ['repo_search answers a shell-significant pattern', byId(4)?.result?.isError === false],
+  ];
+  const ok = checks.every(([, passed]) => passed);
+  const report = [...checks.map(([label, passed]) => `  ${passed ? 'ok ' : 'FAIL'} ${label}`), `self-check: ${ok ? 'OK' : 'FAILED'} (root ${root})`];
+  return { ok, report };
+};
+
+const HELP = `mcp-server — the kit's stdio MCP server (server name "${SERVER_NAME}").
+
+Tools: ${TOOLS.map((t) => t.name).join(', ')} — the kit's read-only path inventory and literal search,
+reached through typed JSON fields instead of a shell string.
+Usage:
+  node mcp-server.mjs [--root <dir>]      serve JSON-RPC over stdin/stdout until stdin closes
+  node mcp-server.mjs --self-check        in-process handshake + one call per tool, exit 0 on success
+Root = --root > env ${ROOT_ENV} > cwd; every path is contained to it on the REAL path.
+Exit codes: 0 served / self-check passed · 1 self-check failed · 2 usage.`;
+
+export const main = async (argv, deps = {}) => {
+  const out = deps.stdout ?? process.stdout;
+  const err = deps.stderr ?? process.stderr;
+  try {
+    const opts = parseArgv(argv);
+    if (opts.help) {
+      out.write(`${HELP}\n`);
+      return EXIT_OK;
+    }
+    const root = resolveRoot({ argv, env: deps.env ?? process.env, cwd: deps.cwd ?? process.cwd() });
+    if (opts.selfCheck) {
+      const result = await selfCheck({ root });
+      out.write(`${result.report.join('\n')}\n`);
+      return result.ok ? EXIT_OK : EXIT_FAILED;
+    }
+    await serveStdio({ input: deps.stdin ?? process.stdin, output: out, dispatcher: createServer({ root }) });
+    return EXIT_OK;
+  } catch (e) {
+    err.write(`mcp-server: ${e?.message ?? e}\n`);
+    return e?.exitCode ?? EXIT_FAILED;
+  }
+};
+
+if (isDirectRun(import.meta.url)) {
+  main(process.argv.slice(2)).then((code) => {
+    process.exitCode = code;
+  });
+}