reis-mobile 0.10.0 → 1.0.0

package/bin/reis-mobile.mjs

@@ -3,19 +3,25 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { parseArgs } from 'node:util';
 
+import {
+  debugPayload,
+  detectPayload,
+  doctorPayload,
+  releasePayload,
+  reviewPayload,
+  routePayload,
+  testPayload,
+} from '../core/commands/payloads.mjs';
 import { LANGUAGES, configPath, removeConfig, resolveLanguage, saveLanguage } from '../core/config/language.mjs';
 import { resolveProjectDir } from '../core/config/project.mjs';
-import { collectReviewContext } from '../core/context/context-engine.mjs';
 import { detectStack } from '../core/detection/stack-detector.mjs';
-import { runDoctor } from '../core/diagnostics/doctor.mjs';
 import { runInit } from '../core/install/init.mjs';
+import { serveStdio } from '../core/mcp/server.mjs';
 import { PLUGIN_ROOT } from '../core/paths.mjs';
 import { DEFAULT_TIMEOUT_MS, consult, listProviderModels } from '../core/providers/consult.mjs';
 import { parseProviderList, providerAllowlist, resolveProviders, selectProviders } from '../core/providers/providers.mjs';
 import { loadRegistry, validateRegistry } from '../core/registry/registry.mjs';
-import { releaseContext } from '../core/release/context.mjs';
 import { INTENT_IDS } from '../core/router/intents.mjs';
-import { route } from '../core/router/router.mjs';
 import { checkForUpdate, clearUpdateCache } from '../core/update/check.mjs';
 
 const USAGE = `reis-mobile — AI agents for mobile engineering
@@ -34,12 +40,13 @@ Commands:
   release [request...]       Prepare release evidence context (does not build or publish)
   providers                  List the external model providers and what each one needs
   consult [question...]      Ask the configured external providers the same question
+  mcp                        Serve the read-only commands to MCP clients over stdio (Cursor, Claude Code, Codex...)
   agents | skills | stacks   List registered components
   validate                   Validate the plugin's agents, skills and stacks
   update-check               Check npm for a newer reis-mobile release
 
 Options:
-  --dir <path>      Project directory (default: current directory, or "app" in .reis-mobile/config.yaml)
+  --dir <path>      Project directory (default: current directory, or "app" in .reis-mobile/config.yaml); mcp: default for tool calls
   --intent <id>     Force an intent (${INTENT_IDS.join(', ')})
   --base <ref>      review/test: compare <ref>...HEAD instead of the working tree
   --all             doctor: check every tool, not only the relevant ones
@@ -91,6 +98,7 @@ const COMMANDS = {
   release: commandRelease,
   providers: commandProviders,
   consult: commandConsult,
+  mcp: commandMcp,
   agents: (options) => commandList('agents', options),
   skills: (options) => commandList('skills', options),
   stacks: (options) => commandList('stacks', options),
@@ -182,10 +190,9 @@ async function commandLang({ prompt, json }) {
   return 0;
 }
 
-async function commandDetect({ dir, project, json, lang }) {
-  const detection = await detectStack(dir);
-  const language = await resolveLanguage({ flag: lang });
-  if (json) return print({ ...detection, language, projectConfig: project.config?.path ?? null });
+async function commandDetect({ project, json, lang }) {
+  const detection = await detectPayload({ project, lang });
+  if (json) return print(detection);
 
   printProject(project);
 
@@ -195,21 +202,20 @@ async function commandDetect({ dir, project, json, lang }) {
   for (const evidence of detection.evidence) console.log(`  · ${evidence}`);
   const others = detection.candidates.slice(1).map((candidate) => candidate.stack);
   if (others.length) console.log(`Also matches ${others.join(', ')}`);
-  printLanguage(language);
+  printLanguage(detection.language);
   return detection.stack === 'unknown' ? 2 : 0;
 }
 
-async function commandDoctor({ dir, project, all, strict, json, lang }) {
-  const report = await runDoctor({ projectDir: dir, all });
-  const language = await resolveLanguage({ flag: lang });
+async function commandDoctor({ project, all, strict, json, lang }) {
+  const report = await doctorPayload({ project, all, lang });
   if (json) {
-    print({ ...report, language, projectConfig: project.config?.path ?? null });
+    print(report);
   } else {
     console.log('reis-mobile doctor\n');
     printProject(project);
     printDoctorChecks(report);
     console.log(report.warnings ? `${report.warnings} warning(s)` : 'No issues found');
-    printLanguage(language);
+    printLanguage(report.language);
   }
   return strict && report.warnings ? 1 : 0;
 }
@@ -226,30 +232,27 @@ function printDoctorChecks(report) {
 
 const SYMBOLS = { ok: '✓', warning: '✗', info: '-', skipped: '-' };
 
-async function commandRoute({ dir, project, intent, prompt, json, lang }) {
+async function commandRoute({ project, intent, prompt, json, lang }) {
   if (!prompt && !intent) {
     console.error('route needs a prompt or --intent.');
     return 1;
   }
-  const result = await route({ prompt, intent, projectDir: dir });
-  const language = await resolveLanguage({ flag: lang });
-  if (json) return print({ ...summarizeRoute(result), language, projectConfig: project.config?.path ?? null });
+  const result = await routePayload({ project, prompt, intent, lang });
+  if (json) return print(result);
   printProject(project);
   printRoute(result);
-  printLanguage(language);
+  printLanguage(result.language);
   return 0;
 }
 
-async function commandReview({ dir, project, base, prompt, json, lang }) {
-  const result = await route({ prompt, intent: 'review', projectDir: dir });
-  const context = collectReviewContext({ projectDir: dir, base });
-  const language = await resolveLanguage({ flag: lang });
-  if (json) return print({ ...summarizeRoute(result), language, projectConfig: project.config?.path ?? null, context });
+async function commandReview({ project, base, prompt, json, lang }) {
+  const result = await reviewPayload({ project, base, prompt, lang });
+  if (json) return print(result);
 
   printProject(project);
   printRoute(result);
-  printLanguage(language);
-  printContext(context);
+  printLanguage(result.language);
+  printContext(result.context);
   return 0;
 }
 
@@ -264,55 +267,57 @@ function printContext(context) {
  * Routes a failure to the debug agent and skills, and adds the doctor report: most build
  * failures are toolchain mismatches (JDK, Gradle, Xcode, CocoaPods), which the report shows.
  */
-async function commandDebug({ dir, project, prompt, json, lang }) {
-  const result = await route({ prompt, intent: 'debug', projectDir: dir });
-  const doctor = await runDoctor({ projectDir: dir });
-  const language = await resolveLanguage({ flag: lang });
-  if (json) return print({ ...summarizeRoute(result), language, projectConfig: project.config?.path ?? null, doctor });
+async function commandDebug({ project, prompt, json, lang }) {
+  const result = await debugPayload({ project, prompt, lang });
+  if (json) return print(result);
 
   printProject(project);
   printRoute(result);
-  printLanguage(language);
+  printLanguage(result.language);
   console.log('');
-  printDoctorChecks(doctor);
+  printDoctorChecks(result.doctor);
   return 0;
 }
 
 /** Prepare evidence for the test agent; running the selected suite is the agent's job. */
-async function commandTest({ dir, project, base, prompt, json, lang }) {
-  const result = await route({ prompt, intent: 'test', projectDir: dir });
-  const context = collectReviewContext({ projectDir: dir, base });
-  const doctor = await runDoctor({ projectDir: dir });
-  const language = await resolveLanguage({ flag: lang });
-  if (json) return print({ ...summarizeRoute(result), language, projectConfig: project.config?.path ?? null, context, doctor });
+async function commandTest({ project, base, prompt, json, lang }) {
+  const result = await testPayload({ project, base, prompt, lang });
+  if (json) return print(result);
 
   // A test runner needs an explicit working directory even without a monorepo config.
   printProject(project, true);
   printRoute(result);
-  printLanguage(language);
-  printContext(context);
+  printLanguage(result.language);
+  printContext(result.context);
   console.log('\nTest context prepared; no test suites were executed.\n');
-  printDoctorChecks(doctor);
+  printDoctorChecks(result.doctor);
   return 0;
 }
 
 /** Prepare release evidence; the specialist audits it before assigning a verdict. */
-async function commandRelease({ dir, project, prompt, json, lang }) {
-  const result = await route({ prompt, intent: 'release', projectDir: dir });
-  const context = collectReviewContext({ projectDir: dir });
-  const doctor = await runDoctor({ projectDir: dir });
-  const language = await resolveLanguage({ flag: lang });
-  const release = releaseContext(result.detection);
-  if (json) return print({ ...summarizeRoute(result), language, projectConfig: project.config?.path ?? null, context, doctor, release });
+async function commandRelease({ project, prompt, json, lang }) {
+  const result = await releasePayload({ project, prompt, lang });
+  if (json) return print(result);
 
+  const { release } = result;
   printProject(project, true);
   printRoute(result);
-  printLanguage(language);
-  printContext(context);
+  printLanguage(result.language);
+  printContext(result.context);
   console.log(`\nRelease platforms (verify) ${release.platforms.join(', ') || 'unknown'}`);
   for (const reference of release.references) console.log(`  Reference ${reference}`);
   console.log('\nRelease context prepared; readiness has not been evaluated. No builds, tests or uploads were executed.\n');
-  printDoctorChecks(doctor);
+  printDoctorChecks(result.doctor);
+  return 0;
+}
+
+/**
+ * Serves the read-only commands to MCP clients over stdio. Nothing but protocol messages may
+ * reach stdout, so this command prints nothing itself; `--dir` is the default for tool calls.
+ */
+async function commandMcp({ dir }) {
+  const pkg = JSON.parse(await readFile(join(PLUGIN_ROOT, 'package.json'), 'utf8'));
+  await serveStdio({ version: pkg.version, defaultDir: dir });
   return 0;
 }
 
@@ -450,11 +455,6 @@ async function commandValidate({ json }) {
   return errors.length ? 1 : 0;
 }
 
-function summarizeRoute(result) {
-  const component = (item) => item && { name: item.name, description: item.description, path: item.path };
-  return { ...result, agent: component(result.agent), skills: result.skills.map(component) };
-}
-
 function printRoute(result) {
   const confidence = result.intentSource === 'explicit' ? 'explicit' : `confidence ${result.confidence}`;
   console.log(`Intent      ${result.intent ?? '-'} (${confidence})${result.area ? ` · area ${result.area}` : ''}`);

package/commands/debate.md

@@ -1,5 +1,5 @@
 ---
-description: Structured debate between the mobile specialists — each agent defends its perspective, rebuts the others, and lead-mobile decides
+description: Structured debate between the mobile specialists — lead-mobile selects the participants, specialists defend and rebut positions, and lead-mobile returns to decide
 argument-hint: "[--rounds N] [--agents a,b,c] [--external] [--providers a,b] <question>"
 allowed-tools: ["Bash(node:*)", "Bash(mkdir:*)", "Agent", "Read", "Write", "Grep", "Glob"]
 ---
@@ -8,7 +8,7 @@ allowed-tools: ["Bash(node:*)", "Bash(mkdir:*)", "Agent", "Read", "Write", "Grep
 
 Arguments received: `$ARGUMENTS`
 
-Use this command for architecture decisions with real trade-offs, not for routine questions: every debate costs several agents across two rounds. If the question has a single answer that can be verified in the code, answer it directly and tell the user why it was not worth a debate.
+Use this command for mobile decisions with real trade-offs, including architecture, UI/UX, accessibility and release readiness. A debate runs several specialists over the configured rounds; avoid it for routine questions. If the question has a single answer that can be verified in the code, answer it directly and tell the user why it was not worth a debate.
 
 ## 1. Parse the arguments
 
@@ -31,9 +31,11 @@ The JSON carries the stack and the `language` for the whole debate: `en` English
 
 If the question mentions files or directories, resolve the paths and read them now: participants receive the content in the briefing, not the path. If it fails, show the error and stop.
 
-## 3. Pick the participants
+## 3. Lead selects the participants
 
-Choose **three** agents whose priorities genuinely conflict on the question. A debate between roles that agree produces no decision.
+Invoke `Agent(subagent_type: "reis-mobile:lead-mobile", model: "opus")` with `phase: selection`, following the **Debate selection** section of `${CLAUDE_PLUGIN_ROOT}/agents/lead-mobile.md`. Pass the question, detected stack and native targets, language, relevant file contents, flags and the complete candidate/model table below. The lead owns participant selection; the command executes the returned plan and does not independently replace participants.
+
+Ask the lead to choose **three** distinct specialists automatically, with relevant perspectives that can expose the question's trade-offs. Disagreement must come from evidence and competing constraints, not a requirement to invent conflict. Every specialist in the plugin is eligible; the lead itself is the selector and moderator, not a debater.
 
 | Agent | Defends | Model |
 |---|---|---|
@@ -55,19 +57,24 @@ Choose **three** agents whose priorities genuinely conflict on the question. A d
 | `reis-mobile:plugin-native-expert` | Flutter–native boundary, platform channels, lifecycle | `opus` |
 | `reis-mobile:mobile-staff-engineer` | Build, release, migration, cross-platform trade-offs | `opus` |
 | `reis-mobile:mobile-code-reviewer` | Concrete risk in the code that already exists | `sonnet` |
+| `reis-mobile:mobile-ui-ux-designer` | User journeys, visual hierarchy, interaction cost and design consistency | `opus` |
+| `reis-mobile:mobile-accessibility-auditor` | Assistive interaction, readable content, focus and inclusive task completion | `sonnet` |
+| `reis-mobile:mobile-release-engineer` | Artifact provenance, release gates, rollout and production readiness | `opus` |
 
-Pass the `model` from the table on every `Agent` call. It overrides the `model: inherit` the agents declare, and that is what keeps the debate from turning into a monologue: with everyone on the same model, participants inherit the same biases and the same blind spots, and the disagreement stays on the surface of the role. The table pairs model strength with role — `opus` where the question is a long-term trade-off, `sonnet` where it is concrete implementation detail.
+Pass the `model` from the table on each participant's `Agent` call. The lead uses `opus` for both selection and synthesis. Model diversity is a configured perspective check, not proof of independent reasoning or correct conclusions.
 
-Automatic selection must end with **at least two different models** among the participants. If the question leads to three agents on the same model, swap one of them for the most relevant adjacent agent that uses the other model, and tell the user you did so.
+Automatic selection must end with **at least two different models** among the participants. The lead must choose a relevant adjacent specialist using the other model when needed and explain the trade-off. If no relevant mixed-model trio fits the evidence, the lead reports that limitation instead of adding an unrelated role; resolve the scope before launching rounds.
 
 Selection rules:
 
-- The detected stack rules. The `flutter-*` agents only join Flutter projects, `android-*` native Android, `ios-*` native iOS, `rn-*` React Native and `kmp-*` Kotlin Multiplatform. Pick the architect, performance and test specialists of the detected stack first; `mobile-staff-engineer` and `mobile-code-reviewer` fit any stack.
-- Without native code in the project, do not call `plugin-native-expert`.
-- `--agents` overrides the automatic choice, but not the models: each agent keeps the one from the table. Unknown name: warn and stop.
-- `reis-mobile:lead-mobile` never debates — it moderates in step 7, always on `opus`, because synthesizing conflicting positions is the heaviest work in the flow.
+- The detected stack rules. Match `flutter-*` to Flutter, `android-*` to native Android, `ios-*` to native iOS, `rn-*` to React Native and `kmp-*` Kotlin Multiplatform. For architecture questions, consider the stack's architect, performance and test specialists. For design, accessibility or release questions, prioritize the corresponding cross-stack specialists. All `mobile-*` specialists fit any stack; native specialists may join cross-platform projects when the question implicates their native paths.
+- Select `plugin-native-expert` only for Flutter projects with an implicated native bridge or plugin path.
+- `--agents` overrides automatic membership, but not the models. The lead validates the supplied names (with or without the `reis-mobile:` prefix), requires at least two distinct specialists and preserves valid explicit choices. Unknown names, duplicates or the lead as a participant: explain the error and stop before rounds. An explicit same-model selection is allowed; disclose that limitation without substituting participants.
+- `reis-mobile:lead-mobile` never debates: it selects in step 3 and returns to moderate in step 7. Neither lead call launches participants or external providers.
+
+The lead returns a selection plan containing each participant's exact name, model, assigned question, rationale and evidence scope, plus unresolved constraints. Check the returned names/models against the table, uniqueness, explicit membership and the automatic model mix. If invalid, return the validation errors to the lead for correction before starting; do not silently repair its choices. If Agent delegation is unavailable, report that the debate could not run rather than claiming specialists participated.
 
-Before starting, tell the user in one line the stack, the participants with their models and the number of rounds.
+Before starting, tell the user in one line the stack, the lead-selected participants with their models and the number of rounds.
 
 ## 4. Prepare the folder
 
@@ -75,11 +82,11 @@ Before starting, tell the user in one line the stack, the participants with thei
 mkdir -p ".reis-mobile/debates/<NNN-question-slug>/rounds"
 ```
 
-`NNN` is sequential within `.reis-mobile/debates/`. Write `context.md` in the folder with the question, the stack, the language, the participants, the flags and the context read in step 2.
+`NNN` is sequential within `.reis-mobile/debates/`. Write `context.md` in the folder with the question, the stack, the language, the participants, the flags, the lead's selection plan with its rationale and the context read in step 2.
 
 ## 5. Round 1 — blind positions
 
-Launch the participants **in parallel**, each with `Agent(subagent_type: "<agent>", model: "<model from the table>", run_in_background: true)`, in a single tool block. Nobody sees anyone else's position in this round: that is what keeps the first to answer from anchoring the rest.
+Launch the participants **in parallel**, each with `Agent(subagent_type: "<agent>", model: "<model from the table>", run_in_background: true)`, in a single tool block. Pass each specialist its assigned question and evidence scope from the lead's plan. Instruct every participant to return analysis only, without editing app code or launching subagents. Nobody sees anyone else's position in this round: that is what keeps the first to answer from anchoring the rest.
 
 Each briefing, self-contained:
 
@@ -140,7 +147,7 @@ Rebutting the generic thesis does not count: every rebuttal cites a concrete cla
 
 ## 7. Synthesis
 
-Invoke `reis-mobile:lead-mobile` with all rounds, following the **Debate moderation** section of `${CLAUDE_PLUGIN_ROOT}/agents/lead-mobile.md`. It resolves the disagreements and produces the action plan.
+Invoke `Agent(subagent_type: "reis-mobile:lead-mobile", model: "opus")` again with `phase: synthesis`, the selection plan, original context, all completed rounds and any missing/failed participant statuses, following the **Debate moderation** section of `${CLAUDE_PLUGIN_ROOT}/agents/lead-mobile.md`. It reads the rounds, verifies decisive evidence, resolves the disagreements and delivers the decision with an ordered action plan. This call does not select new participants or start additional rounds.
 
 Before accepting the synthesis, confirm any decisive claim in the code yourself: participants do not verify each other. Write the result to `.reis-mobile/debates/<id>/synthesis.md`.
 

package/core/commands/payloads.mjs

@@ -0,0 +1,63 @@
+import { resolveLanguage } from '../config/language.mjs';
+import { collectReviewContext } from '../context/context-engine.mjs';
+import { detectStack } from '../detection/stack-detector.mjs';
+import { runDoctor } from '../diagnostics/doctor.mjs';
+import { releaseContext } from '../release/context.mjs';
+import { route } from '../router/router.mjs';
+
+// The `--json` output of the read-only commands. The CLI prints it and the MCP server returns
+// it, so both surfaces describe a project the same way. `project` is resolveProjectDir's result.
+
+export async function detectPayload({ project, lang }) {
+  const detection = await detectStack(project.projectDir);
+  return { ...detection, ...(await common(project, lang)) };
+}
+
+export async function doctorPayload({ project, all, lang }) {
+  const report = await runDoctor({ projectDir: project.projectDir, all });
+  return { ...report, ...(await common(project, lang)) };
+}
+
+export async function routePayload({ project, prompt, intent, lang }) {
+  const result = await route({ prompt, intent, projectDir: project.projectDir });
+  return { ...summarizeRoute(result), ...(await common(project, lang)) };
+}
+
+export async function reviewPayload({ project, base, prompt, lang }) {
+  const result = await route({ prompt, intent: 'review', projectDir: project.projectDir });
+  const context = collectReviewContext({ projectDir: project.projectDir, base });
+  return { ...summarizeRoute(result), ...(await common(project, lang)), context };
+}
+
+/** Most build failures are toolchain mismatches, so the doctor report travels with the route. */
+export async function debugPayload({ project, prompt, lang }) {
+  const result = await route({ prompt, intent: 'debug', projectDir: project.projectDir });
+  const doctor = await runDoctor({ projectDir: project.projectDir });
+  return { ...summarizeRoute(result), ...(await common(project, lang)), doctor };
+}
+
+/** Evidence for the test agent; running the selected suite is the agent's job. */
+export async function testPayload({ project, base, prompt, lang }) {
+  const result = await route({ prompt, intent: 'test', projectDir: project.projectDir });
+  const context = collectReviewContext({ projectDir: project.projectDir, base });
+  const doctor = await runDoctor({ projectDir: project.projectDir });
+  return { ...summarizeRoute(result), ...(await common(project, lang)), context, doctor };
+}
+
+/** Release evidence; the specialist audits it before assigning a verdict. */
+export async function releasePayload({ project, prompt, lang }) {
+  const result = await route({ prompt, intent: 'release', projectDir: project.projectDir });
+  const context = collectReviewContext({ projectDir: project.projectDir });
+  const doctor = await runDoctor({ projectDir: project.projectDir });
+  const release = releaseContext(result.detection);
+  return { ...summarizeRoute(result), ...(await common(project, lang)), context, doctor, release };
+}
+
+async function common(project, lang) {
+  return { language: await resolveLanguage({ flag: lang }), projectConfig: project.config?.path ?? null };
+}
+
+function summarizeRoute(result) {
+  const component = (item) => item && { name: item.name, description: item.description, path: item.path };
+  return { ...result, agent: component(result.agent), skills: result.skills.map(component) };
+}

package/core/mcp/server.mjs

@@ -0,0 +1,188 @@
+import { once } from 'node:events';
+import { createInterface } from 'node:readline';
+
+import { callTool, hasTool, listTools } from './tools.mjs';
+
+// A dual-era MCP server. Modern clients (2026-07-28) send the protocol version and their
+// capabilities in every request's `_meta` and may probe with `server/discover`; legacy clients
+// (2025-11-25 and earlier) open with an `initialize` handshake. Both are served on one process.
+export const MODERN_VERSIONS = ['2026-07-28'];
+export const LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+const SUPPORTED_VERSIONS = [...MODERN_VERSIONS, ...LEGACY_VERSIONS];
+
+const META_VERSION = 'io.modelcontextprotocol/protocolVersion';
+const META_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities';
+const META_SERVER_INFO = 'io.modelcontextprotocol/serverInfo';
+
+export const ERROR_CODES = {
+  parse: -32700,
+  invalidRequest: -32600,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internal: -32603,
+  unsupportedVersion: -32022,
+};
+
+const CAPABILITIES = { tools: {} };
+
+const INSTRUCTIONS =
+  'reis-mobile prepares context for Flutter, native Android, native iOS, React Native/Expo and Kotlin Multiplatform apps. ' +
+  'Call reis_mobile_route, or reis_mobile_review, reis_mobile_debug, reis_mobile_test or reis_mobile_release for those tasks, ' +
+  'with the app directory as "dir". Then read the returned agent and skill files with reis_mobile_read_instructions and follow them; ' +
+  'open only the references that match the stack and the task. Every tool is read-only and offline: none edits the project, ' +
+  'builds, runs tests or calls a network service.';
+
+class RpcError extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/**
+ * Handles one decoded JSON-RPC message and resolves to the response, or to null for a
+ * notification. It never rejects: every failure becomes a JSON-RPC error or a tool error.
+ */
+export function createMcpServer({ version, defaultDir = process.cwd() }) {
+  const serverInfo = { name: 'reis-mobile', title: 'reis-mobile', version };
+  // Set by `initialize`: from then on, requests without `_meta` follow that legacy revision.
+  let legacyVersion = null;
+
+  async function handle(message) {
+    if (typeof message !== 'object' || message === null || Array.isArray(message)) {
+      return failure(null, new RpcError(ERROR_CODES.invalidRequest, 'Expected one JSON-RPC 2.0 message object; batches are not supported.'));
+    }
+    const isRequest = Object.hasOwn(message, 'id');
+    if (message.jsonrpc !== '2.0' || typeof message.method !== 'string') {
+      return isRequest ? failure(requestId(message.id), new RpcError(ERROR_CODES.invalidRequest, 'Expected a JSON-RPC 2.0 request with a method.')) : null;
+    }
+    // notifications/initialized needs no reply; cancellation is handled by the transport.
+    if (!isRequest) return null;
+
+    const { id, method, params } = message;
+    if (requestId(id) === null) return failure(null, new RpcError(ERROR_CODES.invalidRequest, 'The request id must be a string or a number.'));
+    try {
+      if (params !== undefined && (typeof params !== 'object' || params === null || Array.isArray(params))) {
+        throw new RpcError(ERROR_CODES.invalidParams, 'params must be an object.');
+      }
+      if (method === 'initialize') return success(id, initialize(params ?? {}));
+
+      const modern = isModernRequest(method, params);
+      const result = await dispatch(method, params ?? {}, modern);
+      return success(id, modern ? { resultType: 'complete', ...result, _meta: { [META_SERVER_INFO]: serverInfo } } : result);
+    } catch (error) {
+      return failure(id, error instanceof RpcError ? error : new RpcError(ERROR_CODES.internal, `Internal error: ${error.message}`));
+    }
+  }
+
+  function initialize(params) {
+    const requested = params.protocolVersion;
+    legacyVersion = LEGACY_VERSIONS.includes(requested) ? requested : LEGACY_VERSIONS[0];
+    return { protocolVersion: legacyVersion, capabilities: CAPABILITIES, serverInfo, instructions: INSTRUCTIONS };
+  }
+
+  /** A request is modern when it carries a protocol version in `_meta`; legacy once initialized. */
+  function isModernRequest(method, params) {
+    const meta = params?._meta;
+    const requested = meta?.[META_VERSION];
+    if (requested !== undefined) {
+      if (!MODERN_VERSIONS.includes(requested)) {
+        throw new RpcError(ERROR_CODES.unsupportedVersion, 'Unsupported protocol version', { supported: SUPPORTED_VERSIONS, requested });
+      }
+      const capabilities = meta[META_CAPABILITIES];
+      if (typeof capabilities !== 'object' || capabilities === null || Array.isArray(capabilities)) {
+        throw new RpcError(ERROR_CODES.invalidParams, `Missing _meta["${META_CAPABILITIES}"]: every ${requested} request carries the client capabilities.`);
+      }
+      return true;
+    }
+    if (legacyVersion || method === 'ping') return false;
+    throw new RpcError(
+      ERROR_CODES.invalidParams,
+      `Missing _meta["${META_VERSION}"]. Send initialize first (protocol ${LEGACY_VERSIONS[0]} and earlier) or include the per-request _meta of ${MODERN_VERSIONS[0]}.`,
+      { supported: SUPPORTED_VERSIONS },
+    );
+  }
+
+  async function dispatch(method, params, modern) {
+    switch (method) {
+      case 'server/discover':
+        if (!modern) break;
+        return { supportedVersions: MODERN_VERSIONS, capabilities: CAPABILITIES, instructions: INSTRUCTIONS };
+      case 'ping':
+        return {};
+      case 'tools/list':
+        return { tools: listTools() };
+      case 'tools/call': {
+        const { name, arguments: args } = params;
+        if (typeof name !== 'string' || !hasTool(name)) throw new RpcError(ERROR_CODES.invalidParams, `Unknown tool: ${name}`);
+        if (args !== undefined && (typeof args !== 'object' || args === null || Array.isArray(args))) {
+          throw new RpcError(ERROR_CODES.invalidParams, 'tools/call arguments must be an object.');
+        }
+        return callTool(name, args ?? {}, { defaultDir });
+      }
+    }
+    throw new RpcError(ERROR_CODES.methodNotFound, `Method not found: ${method}`);
+  }
+
+  return { handle };
+}
+
+/**
+ * Serves newline-delimited JSON-RPC over stdio until the input closes. Only protocol messages
+ * are written to `output`; a cancelled request gets no reply, as the transport requires.
+ */
+export async function serveStdio({ version, defaultDir, input = process.stdin, output = process.stdout }) {
+  const server = createMcpServer({ version, defaultDir });
+  const inFlight = new Set();
+  const cancelled = new Set();
+  const pending = new Set();
+  const lines = createInterface({ input, crlfDelay: Infinity });
+
+  const write = (message) => {
+    if (!output.writableEnded && !output.destroyed) output.write(`${JSON.stringify(message)}\n`);
+  };
+  // The client closing its end mid-reply is a shutdown, not a crash.
+  output.on('error', () => lines.close());
+
+  lines.on('line', (line) => {
+    if (!line.trim()) return;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      write(failure(null, new RpcError(ERROR_CODES.parse, 'Parse error: each line must be one JSON-RPC message.')));
+      return;
+    }
+    if (message?.method === 'notifications/cancelled') {
+      const target = message.params?.requestId;
+      if (inFlight.has(target)) cancelled.add(target);
+      return;
+    }
+
+    const id = Object.hasOwn(message ?? {}, 'id') ? message.id : undefined;
+    if (id !== undefined) inFlight.add(id);
+    const task = server.handle(message).then((response) => {
+      inFlight.delete(id);
+      if (cancelled.delete(id) || !response) return;
+      write(response);
+    });
+    pending.add(task);
+    task.finally(() => pending.delete(task));
+  });
+
+  await once(lines, 'close');
+  await Promise.allSettled([...pending]);
+}
+
+function requestId(id) {
+  return typeof id === 'string' || typeof id === 'number' ? id : null;
+}
+
+function success(id, result) {
+  return { jsonrpc: '2.0', id, result };
+}
+
+function failure(id, error) {
+  return { jsonrpc: '2.0', id, error: { code: error.code, message: error.message, ...(error.data !== undefined && { data: error.data }) } };
+}