codebase-onboarder 0.6.0 → 1.0.0

package/server/mcp/server.js

@@ -16,24 +16,20 @@
 //   * A tool that throws is answered with a *result* carrying `isError: true`,
 //     not a JSON-RPC error. That is what puts the message in front of the model
 //     so it can correct itself; a protocol error just fails the turn.
-
 import { toolDefinitions, callTool, findTool } from './tools.js';
 import { ToolError } from './analysis.js';
-
 export const PROTOCOL_VERSION = '2025-06-18';
 export const SERVER_INFO = {
-  name: 'onboarder',
-  version: '1.0.0',
-  title: 'Onboarder',
-  instructions:
-    'Onboarder explains a codebase. Start with onboarder_scan on a repository path; '
-    + 'it returns a written overview, the entry points, the most depended-upon files, and '
-    + 'any dependency cycles. Then use onboarder_tour for a reading order, onboarder_search '
-    + 'to find things by name, onboarder_explain_file for one file, and onboarder_read_file '
-    + 'for raw source. Every tool also takes `path`; omit it to keep working on the last '
-    + 'repository scanned. The repository is read, never written.',
+    name: 'onboarder',
+    version: '1.0.0',
+    title: 'Onboarder',
+    instructions: 'Onboarder explains a codebase. Start with onboarder_scan on a repository path; '
+        + 'it returns a written overview, the entry points, the most depended-upon files, and '
+        + 'any dependency cycles. Then use onboarder_tour for a reading order, onboarder_search '
+        + 'to find things by name, onboarder_explain_file for one file, and onboarder_read_file '
+        + 'for raw source. Every tool also takes `path`; omit it to keep working on the last '
+        + 'repository scanned. The repository is read, never written.',
 };
-
 // JSON-RPC error codes. Only the first two are protocol-level; the rest are
 // conventional in MCP and keep a misbehaving client from parsing a server bug as
 // a server bug it caused.
@@ -41,201 +37,192 @@ const PARSE_ERROR = -32700;
 const INVALID_REQUEST = -32600;
 const METHOD_NOT_FOUND = -32601;
 const INVALID_PARAMS = -32602;
-
 function result(id, value) {
-  return { jsonrpc: '2.0', id, result: value };
+    return { jsonrpc: '2.0', id, result: value };
 }
-
 function failure(id, code, message, data) {
-  const error = { code, message };
-  if (data !== undefined) error.data = data;
-  return { jsonrpc: '2.0', id, error };
+    const error = { code, message };
+    if (data !== undefined)
+        error.data = data;
+    return { jsonrpc: '2.0', id, error };
 }
-
 // A tool error and an internal error are different things. A `ToolError` is a
 // sentence the model can act on — "that path is outside the repo" — so it becomes
 // an isError result with that sentence intact. Anything else is a bug, and saying
 // so plainly beats pretending it was the caller's fault.
 async function callOne(name, args) {
-  const tool = findTool(name);
-  if (!tool) {
-    return {
-      isError: true,
-      content: [{ type: 'text', text: `No tool called "${name}". Call tools/list to see what is available.` }],
-    };
-  }
-  try {
-    const value = await tool.run(args || {});
-    // MCP content is a list of blocks. A tool that returns structured data sends
-    // it as JSON text plus the native `structuredContent` field, which is what
-    // typed clients read; the text block is what everything else falls back to.
-    return {
-      content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
-      structuredContent: value,
-      isError: false,
-    };
-  } catch (err) {
-    if (err instanceof ToolError) {
-      return { isError: true, content: [{ type: 'text', text: err.message }] };
+    const tool = findTool(name);
+    if (!tool) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `No tool called "${name}". Call tools/list to see what is available.` }],
+        };
+    }
+    try {
+        const value = await tool.run(args || {});
+        // MCP content is a list of blocks. A tool that returns structured data sends
+        // it as JSON text plus the native `structuredContent` field, which is what
+        // typed clients read; the text block is what everything else falls back to.
+        return {
+            content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+            structuredContent: value,
+            isError: false,
+        };
+    }
+    catch (err) {
+        if (err instanceof ToolError) {
+            return { isError: true, content: [{ type: 'text', text: err.message }] };
+        }
+        // Unexpected. Report the message, not the stack: the caller is a model on the
+        // other end of a pipe, and a stack trace is noise. The full error is on the
+        // child process's stderr, which is where a human debugging this will look.
+        console.error('[onboarder-mcp] tool failed:', err);
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `The tool failed unexpectedly: ${err?.message || String(err)}` }],
+        };
     }
-    // Unexpected. Report the message, not the stack: the caller is a model on the
-    // other end of a pipe, and a stack trace is noise. The full error is on the
-    // child process's stderr, which is where a human debugging this will look.
-    console.error('[onboarder-mcp] tool failed:', err);
-    return {
-      isError: true,
-      content: [{ type: 'text', text: `The tool failed unexpectedly: ${err?.message || String(err)}` }],
-    };
-  }
 }
-
 // The dispatcher is exported because the Streamable HTTP transport in `./http.js`
 // needs to answer the same messages without going through a line of stdio. The
 // protocol logic lives in exactly one place; a second transport must not become a
 // second implementation of `tools/list`.
 export { handle };
-
 async function handle(msg) {
-  // A request must name a method and must declare the protocol version. Anything
-  // else is not a request at all, and replying to it would invent an id to answer
-  // under — so this returns nothing and the line is dropped.
-  //
-  // `null` rather than `undefined` is the contract with the loop below: both mean
-  // "say nothing", but only one of them survives being awaited and compared.
-  if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
-    return null;
-  }
-  const { method, id, params } = msg;
-
-  // A notification has no id and expects no answer. Returning `null` is how the
-  // loop knows to stay silent, which matters: replying to a notification is
-  // itself a protocol violation.
-  const isNotification = id === undefined || id === null;
-
-  switch (method) {
-    case 'initialize':
-      return isNotification ? undefined : result(id, {
-        protocolVersion: PROTOCOL_VERSION,
-        capabilities: { tools: { listChanged: false } },
-        serverInfo: SERVER_INFO,
-      });
-
-    // The client's post-handshake ping. Answering it is what tells the client the
-    // handshake completed and the tool loop is live.
-    case 'notifications/initialized':
-      return null;
-
-    case 'ping':
-      return isNotification ? undefined : result(id, {});
-
-    case 'tools/list':
-      return isNotification ? undefined : result(id, { tools: toolDefinitions() });
-
-    case 'tools/call':
-      if (isNotification) return null;
-      if (!params?.name || typeof params.name !== 'string') {
-        return failure(id, INVALID_PARAMS, 'tools/call needs a tool name.');
-      }
-      return result(id, await callOne(params.name, params.arguments));
-
-    // A client asking for resources or prompts is not an error — this server has
-    // none, and saying so is more useful than METHOD_NOT_FOUND. A harness that
-    // probes both at startup gets a clean answer instead of a warning.
-    case 'resources/list':
-      return result(id, { resources: [] });
-
-    case 'prompts/list':
-      return result(id, { prompts: [] });
-
-    case 'resources/templates/list':
-      return result(id, { resourceTemplates: [] });
-
-    default:
-      if (isNotification) return null;
-      return failure(id, METHOD_NOT_FOUND, `No method called "${method}".`);
-  }
+    // A request must name a method and must declare the protocol version. Anything
+    // else is not a request at all, and replying to it would invent an id to answer
+    // under — so this returns nothing and the line is dropped.
+    //
+    // `null` rather than `undefined` is the contract with the loop below: both mean
+    // "say nothing", but only one of them survives being awaited and compared.
+    if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+        return null;
+    }
+    const { method, id, params } = msg;
+    // A notification has no id and expects no answer. Returning `null` is how the
+    // loop knows to stay silent, which matters: replying to a notification is
+    // itself a protocol violation.
+    const isNotification = id === undefined || id === null;
+    switch (method) {
+        case 'initialize':
+            return isNotification ? undefined : result(id, {
+                protocolVersion: PROTOCOL_VERSION,
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: SERVER_INFO,
+            });
+        // The client's post-handshake ping. Answering it is what tells the client the
+        // handshake completed and the tool loop is live.
+        case 'notifications/initialized':
+            return null;
+        case 'ping':
+            return isNotification ? undefined : result(id, {});
+        case 'tools/list':
+            return isNotification ? undefined : result(id, { tools: toolDefinitions() });
+        case 'tools/call':
+            if (isNotification)
+                return null;
+            if (!params?.name || typeof params.name !== 'string') {
+                return failure(id, INVALID_PARAMS, 'tools/call needs a tool name.');
+            }
+            return result(id, await callOne(params.name, params.arguments));
+        // A client asking for resources or prompts is not an error — this server has
+        // none, and saying so is more useful than METHOD_NOT_FOUND. A harness that
+        // probes both at startup gets a clean answer instead of a warning.
+        case 'resources/list':
+            return result(id, { resources: [] });
+        case 'prompts/list':
+            return result(id, { prompts: [] });
+        case 'resources/templates/list':
+            return result(id, { resourceTemplates: [] });
+        default:
+            if (isNotification)
+                return null;
+            return failure(id, METHOD_NOT_FOUND, `No method called "${method}".`);
+    }
 }
-
 // One line in, one line out. A message that will not parse gets a parse error
 // with `id: null`, which is what the spec requires — the client cannot know which
 // request the bad line belonged to.
 function parseLine(line) {
-  try {
-    const msg = JSON.parse(line);
-    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {
-      return { bad: failure(null, INVALID_REQUEST, 'A message must be a JSON-RPC object.') };
+    try {
+        const msg = JSON.parse(line);
+        if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {
+            return { bad: failure(null, INVALID_REQUEST, 'A message must be a JSON-RPC object.') };
+        }
+        return { msg };
+    }
+    catch (err) {
+        return { bad: failure(null, PARSE_ERROR, `Could not parse the message: ${err.message}`) };
     }
-    return { msg };
-  } catch (err) {
-    return { bad: failure(null, PARSE_ERROR, `Could not parse the message: ${err.message}`) };
-  }
 }
-
 /**
  * Run the server until stdin closes. `input` and `output` are parameters so tests
  * can drive a whole session through in-memory streams.
  */
-export function serveMcp({ input = process.stdin, output = process.stdout } = {}) {
-  let buffer = '';
-  // Messages are handled strictly in order, but not awaited inline: a long scan
-  // must not block the event loop from reading the next line, or a client that
-  // pipelines would sit with a full buffer. The promise chain is what preserves
-  // the ordering while letting reads continue.
-  let chain = Promise.resolve();
-  let closed = false;
-
-  const send = (message) => {
-    if (closed) return;
-    output.write(JSON.stringify(message) + '\n');
-  };
-
-  const enqueue = (line) => {
-    chain = chain.then(async () => {
-      const { msg, bad } = parseLine(line);
-      if (bad) { send(bad); return; }
-      const response = await handle(msg);
-      if (response) send(response);
-    }).catch((err) => {
-      // `handle` already turns tool failures into results. Reaching here means
-      // something threw outside that, so the only honest move is to log it and
-      // keep serving — a dead server helps nobody recover.
-      console.error('[onboarder-mcp] dispatch failed:', err);
+export function serveMcp({ input = process.stdin, output = process.stdout, dispatch = handle } = {}) {
+    let buffer = '';
+    // Messages are handled strictly in order, but not awaited inline: a long scan
+    // must not block the event loop from reading the next line, or a client that
+    // pipelines would sit with a full buffer. The promise chain is what preserves
+    // the ordering while letting reads continue.
+    let chain = Promise.resolve();
+    let closed = false;
+    const send = (message) => {
+        if (closed)
+            return;
+        output.write(JSON.stringify(message) + '\n');
+    };
+    const enqueue = (line) => {
+        chain = chain.then(async () => {
+            const { msg, bad } = parseLine(line);
+            if (bad) {
+                send(bad);
+                return;
+            }
+            const response = await dispatch(msg);
+            if (response)
+                send(response);
+        }).catch((err) => {
+            // `handle` already turns tool failures into results. Reaching here means
+            // something threw outside that, so the only honest move is to log it and
+            // keep serving — a dead server helps nobody recover.
+            console.error('[onboarder-mcp] dispatch failed:', err);
+        });
+    };
+    input.setEncoding?.('utf8');
+    input.on('data', (chunk) => {
+        buffer += chunk;
+        let nl;
+        // A partial line at the end of a chunk stays in the buffer for the next one.
+        while ((nl = buffer.indexOf('\n')) !== -1) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (line)
+                enqueue(line);
+        }
     });
-  };
-
-  input.setEncoding?.('utf8');
-  input.on('data', (chunk) => {
-    buffer += chunk;
-    let nl;
-    // A partial line at the end of a chunk stays in the buffer for the next one.
-    while ((nl = buffer.indexOf('\n')) !== -1) {
-      const line = buffer.slice(0, nl).trim();
-      buffer = buffer.slice(nl + 1);
-      if (line) enqueue(line);
-    }
-  });
-
-  input.on('end', () => {
-    // A last line without a trailing newline is still a message. Dropping it
-    // would lose the final request of a session — which is often the only one.
-    const line = buffer.trim();
-    buffer = '';
-    if (line) enqueue(line);
-    // Let the queue finish before the process exits, so a reply written just
-    // after stdin closed still reaches the client.
-    chain.finally(() => {
-      if (output === process.stdout) process.exitCode = 0;
+    input.on('end', () => {
+        // A last line without a trailing newline is still a message. Dropping it
+        // would lose the final request of a session — which is often the only one.
+        const line = buffer.trim();
+        buffer = '';
+        if (line)
+            enqueue(line);
+        // Let the queue finish before the process exits, so a reply written just
+        // after stdin closed still reaches the client.
+        chain.finally(() => {
+            if (output === process.stdout)
+                process.exitCode = 0;
+        });
+    });
+    input.on('error', (err) => {
+        console.error('[onboarder-mcp] stdin error:', err);
     });
-  });
-
-  input.on('error', (err) => {
-    console.error('[onboarder-mcp] stdin error:', err);
-  });
-
-  return {
-    stop() { closed = true; },
-    // Awaiting the queue is how a test knows every reply has been written, and
-    // how a shutdown can drain in-flight work instead of cutting it off.
-    settled() { return chain; },
-  };
+    return {
+        stop() { closed = true; },
+        // Awaiting the queue is how a test knows every reply has been written, and
+        // how a shutdown can drain in-flight work instead of cutting it off.
+        settled() { return chain; },
+    };
 }
+//# sourceMappingURL=server.js.map

package/server/mcp/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../src/server/mcp/server.ts"],"names":[],"mappings":"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","sourcesContent":["// The MCP server: JSON-RPC 2.0 over stdio, one JSON object per line.\n//\n// Why no SDK: the project has no dependencies, and `package.json` says so. MCP's\n// stdio transport is a framing convention (one line-delimited JSON-RPC message\n// per message, on the child's stdin/stdout), not a wire protocol with magic — so\n// implementing it directly is a few dozen lines and keeps the promise that this\n// repo installs with nothing. If the SDK ever becomes worth it, this file is the\n// only thing that changes; `tools.js` and `analysis.js` know nothing about JSON.\n//\n// The rules that matter for correctness:\n//   * stdout belongs to the protocol. Anything else printed there corrupts the\n//     stream, so the logger is redirected to stderr for the lifetime of the\n//     child (see `runner.js`).\n//   * Requests are answered in order. MCP clients pipeline, and answering a\n//     `tools/call` out of order makes some clients discard the later result.\n//   * A tool that throws is answered with a *result* carrying `isError: true`,\n//     not a JSON-RPC error. That is what puts the message in front of the model\n//     so it can correct itself; a protocol error just fails the turn.\n\nimport { toolDefinitions, callTool, findTool } from './tools.js';\nimport { ToolError } from './analysis.js';\n\nexport const PROTOCOL_VERSION = '2025-06-18';\nexport const SERVER_INFO = {\n  name: 'onboarder',\n  version: '1.0.0',\n  title: 'Onboarder',\n  instructions:\n    'Onboarder explains a codebase. Start with onboarder_scan on a repository path; '\n    + 'it returns a written overview, the entry points, the most depended-upon files, and '\n    + 'any dependency cycles. Then use onboarder_tour for a reading order, onboarder_search '\n    + 'to find things by name, onboarder_explain_file for one file, and onboarder_read_file '\n    + 'for raw source. Every tool also takes `path`; omit it to keep working on the last '\n    + 'repository scanned. The repository is read, never written.',\n};\n\n// JSON-RPC error codes. Only the first two are protocol-level; the rest are\n// conventional in MCP and keep a misbehaving client from parsing a server bug as\n// a server bug it caused.\nconst PARSE_ERROR = -32700;\nconst INVALID_REQUEST = -32600;\nconst METHOD_NOT_FOUND = -32601;\nconst INVALID_PARAMS = -32602;\n\nfunction result(id, value) {\n  return { jsonrpc: '2.0', id, result: value };\n}\n\nfunction failure(id, code, message, data?: unknown) {\n  const error: { code: number; message: string; data?: unknown } = { code, message };\n  if (data !== undefined) error.data = data;\n  return { jsonrpc: '2.0', id, error };\n}\n\n// A tool error and an internal error are different things. A `ToolError` is a\n// sentence the model can act on — \"that path is outside the repo\" — so it becomes\n// an isError result with that sentence intact. Anything else is a bug, and saying\n// so plainly beats pretending it was the caller's fault.\nasync function callOne(name, args) {\n  const tool = findTool(name);\n  if (!tool) {\n    return {\n      isError: true,\n      content: [{ type: 'text', text: `No tool called \"${name}\". Call tools/list to see what is available.` }],\n    };\n  }\n  try {\n    const value = await tool.run(args || {});\n    // MCP content is a list of blocks. A tool that returns structured data sends\n    // it as JSON text plus the native `structuredContent` field, which is what\n    // typed clients read; the text block is what everything else falls back to.\n    return {\n      content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],\n      structuredContent: value,\n      isError: false,\n    };\n  } catch (err) {\n    if (err instanceof ToolError) {\n      return { isError: true, content: [{ type: 'text', text: err.message }] };\n    }\n    // Unexpected. Report the message, not the stack: the caller is a model on the\n    // other end of a pipe, and a stack trace is noise. The full error is on the\n    // child process's stderr, which is where a human debugging this will look.\n    console.error('[onboarder-mcp] tool failed:', err);\n    return {\n      isError: true,\n      content: [{ type: 'text', text: `The tool failed unexpectedly: ${err?.message || String(err)}` }],\n    };\n  }\n}\n\n// The dispatcher is exported because the Streamable HTTP transport in `./http.js`\n// needs to answer the same messages without going through a line of stdio. The\n// protocol logic lives in exactly one place; a second transport must not become a\n// second implementation of `tools/list`.\nexport { handle };\n\nasync function handle(msg) {\n  // A request must name a method and must declare the protocol version. Anything\n  // else is not a request at all, and replying to it would invent an id to answer\n  // under — so this returns nothing and the line is dropped.\n  //\n  // `null` rather than `undefined` is the contract with the loop below: both mean\n  // \"say nothing\", but only one of them survives being awaited and compared.\n  if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {\n    return null;\n  }\n  const { method, id, params } = msg;\n\n  // A notification has no id and expects no answer. Returning `null` is how the\n  // loop knows to stay silent, which matters: replying to a notification is\n  // itself a protocol violation.\n  const isNotification = id === undefined || id === null;\n\n  switch (method) {\n    case 'initialize':\n      return isNotification ? undefined : result(id, {\n        protocolVersion: PROTOCOL_VERSION,\n        capabilities: { tools: { listChanged: false } },\n        serverInfo: SERVER_INFO,\n      });\n\n    // The client's post-handshake ping. Answering it is what tells the client the\n    // handshake completed and the tool loop is live.\n    case 'notifications/initialized':\n      return null;\n\n    case 'ping':\n      return isNotification ? undefined : result(id, {});\n\n    case 'tools/list':\n      return isNotification ? undefined : result(id, { tools: toolDefinitions() });\n\n    case 'tools/call':\n      if (isNotification) return null;\n      if (!params?.name || typeof params.name !== 'string') {\n        return failure(id, INVALID_PARAMS, 'tools/call needs a tool name.');\n      }\n      return result(id, await callOne(params.name, params.arguments));\n\n    // A client asking for resources or prompts is not an error — this server has\n    // none, and saying so is more useful than METHOD_NOT_FOUND. A harness that\n    // probes both at startup gets a clean answer instead of a warning.\n    case 'resources/list':\n      return result(id, { resources: [] });\n\n    case 'prompts/list':\n      return result(id, { prompts: [] });\n\n    case 'resources/templates/list':\n      return result(id, { resourceTemplates: [] });\n\n    default:\n      if (isNotification) return null;\n      return failure(id, METHOD_NOT_FOUND, `No method called \"${method}\".`);\n  }\n}\n\n// One line in, one line out. A message that will not parse gets a parse error\n// with `id: null`, which is what the spec requires — the client cannot know which\n// request the bad line belonged to.\nfunction parseLine(line) {\n  try {\n    const msg = JSON.parse(line);\n    if (!msg || typeof msg !== 'object' || Array.isArray(msg)) {\n      return { bad: failure(null, INVALID_REQUEST, 'A message must be a JSON-RPC object.') };\n    }\n    return { msg };\n  } catch (err) {\n    return { bad: failure(null, PARSE_ERROR, `Could not parse the message: ${err.message}`) };\n  }\n}\n\n/**\n * Run the server until stdin closes. `input` and `output` are parameters so tests\n * can drive a whole session through in-memory streams.\n */\nexport function serveMcp({ input = process.stdin, output = process.stdout, dispatch = handle }: Record<string, any> = {}) {\n  let buffer = '';\n  // Messages are handled strictly in order, but not awaited inline: a long scan\n  // must not block the event loop from reading the next line, or a client that\n  // pipelines would sit with a full buffer. The promise chain is what preserves\n  // the ordering while letting reads continue.\n  let chain = Promise.resolve();\n  let closed = false;\n\n  const send = (message) => {\n    if (closed) return;\n    output.write(JSON.stringify(message) + '\\n');\n  };\n\n  const enqueue = (line) => {\n    chain = chain.then(async () => {\n      const { msg, bad } = parseLine(line);\n      if (bad) { send(bad); return; }\n      const response = await dispatch(msg);\n      if (response) send(response);\n    }).catch((err) => {\n      // `handle` already turns tool failures into results. Reaching here means\n      // something threw outside that, so the only honest move is to log it and\n      // keep serving — a dead server helps nobody recover.\n      console.error('[onboarder-mcp] dispatch failed:', err);\n    });\n  };\n\n  input.setEncoding?.('utf8');\n  input.on('data', (chunk) => {\n    buffer += chunk;\n    let nl;\n    // A partial line at the end of a chunk stays in the buffer for the next one.\n    while ((nl = buffer.indexOf('\\n')) !== -1) {\n      const line = buffer.slice(0, nl).trim();\n      buffer = buffer.slice(nl + 1);\n      if (line) enqueue(line);\n    }\n  });\n\n  input.on('end', () => {\n    // A last line without a trailing newline is still a message. Dropping it\n    // would lose the final request of a session — which is often the only one.\n    const line = buffer.trim();\n    buffer = '';\n    if (line) enqueue(line);\n    // Let the queue finish before the process exits, so a reply written just\n    // after stdin closed still reaches the client.\n    chain.finally(() => {\n      if (output === process.stdout) process.exitCode = 0;\n    });\n  });\n\n  input.on('error', (err) => {\n    console.error('[onboarder-mcp] stdin error:', err);\n  });\n\n  return {\n    stop() { closed = true; },\n    // Awaiting the queue is how a test knows every reply has been written, and\n    // how a shutdown can drain in-flight work instead of cutting it off.\n    settled() { return chain; },\n  };\n}\n"]}

package/server/mcp/standalone.d.ts

@@ -0,0 +1 @@
+export {};

package/server/mcp/standalone.js

@@ -11,9 +11,7 @@
 // would look like a server bug rather than a logging bug. Redirecting is better
 // than trusting: the guard costs one comparison per write and cannot be forgotten
 // by a future contributor three files deep.
-
 import { serveMcp, SERVER_INFO } from './server.js';
-
 // stdout is a shared pipe with two kinds of writer: the protocol, which must be
 // the only thing a client ever sees, and everything else — a stray `console.log`
 // in a shared analyzer, a logger — which would be read as a malformed frame and
@@ -25,18 +23,18 @@ import { serveMcp, SERVER_INFO } from './server.js';
 // on being the first thing to run.
 const realStdoutWrite = process.stdout.write.bind(process.stdout);
 const protocolStream = { write: (chunk) => realStdoutWrite(chunk) };
-
 process.stdout.write = function toStderr(chunk, encoding, callback) {
-  process.stderr.write(chunk);
-  if (typeof encoding === 'function') encoding();
-  else if (typeof callback === 'function') callback();
-  return true;
+    process.stderr.write(chunk);
+    if (typeof encoding === 'function')
+        encoding();
+    else if (typeof callback === 'function')
+        callback();
+    return true;
 };
-
 // Diagnostics are opt-in: a client reading stdout is reading a protocol stream
 // and nothing else, so anything else has to be asked for.
 if (process.env.ONBOARDER_MCP_LOG === '1') {
-  console.error(`[onboarder-mcp] ${SERVER_INFO.name} ${SERVER_INFO.version} starting on stdio`);
+    console.error(`[onboarder-mcp] ${SERVER_INFO.name} ${SERVER_INFO.version} starting on stdio`);
 }
-
 serveMcp({ output: protocolStream });
+//# sourceMappingURL=standalone.js.map

package/server/mcp/standalone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"standalone.js","sourceRoot":"","sources":["../../src/server/mcp/standalone.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,kFAAkF;AAClF,+EAA+E;AAC/E,6EAA6E;AAC7E,+CAA+C;AAC/C,EAAE;AACF,8EAA8E;AAC9E,iFAAiF;AACjF,6EAA6E;AAC7E,gFAAgF;AAChF,kFAAkF;AAClF,4CAA4C;AAE5C,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEpD,gFAAgF;AAChF,iFAAiF;AACjF,gFAAgF;AAChF,8CAA8C;AAC9C,EAAE;AACF,kFAAkF;AAClF,8EAA8E;AAC9E,kFAAkF;AAClF,mCAAmC;AACnC,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAClE,MAAM,cAAc,GAAG,EAAE,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;AAEpE,OAAO,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS,QAAQ,CAAC,KAA0B,EAAE,QAAmD,EAAE,QAAgC;IACxJ,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5B,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,QAAQ,EAAE,CAAC;SAC1C,IAAI,OAAO,QAAQ,KAAK,UAAU;QAAE,QAAQ,EAAE,CAAC;IACpD,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF,+EAA+E;AAC/E,0DAA0D;AAC1D,IAAI,OAAO,CAAC,GAAG,CAAC,iBAAiB,KAAK,GAAG,EAAE,CAAC;IAC1C,OAAO,CAAC,KAAK,CAAC,mBAAmB,WAAW,CAAC,IAAI,IAAI,WAAW,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAChG,CAAC;AAED,QAAQ,CAAC,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC,CAAC","sourcesContent":["// The MCP server as its own process: `node server/mcp/standalone.js`.\n//\n// This is the command an agent harness is configured with. It is a separate entry\n// point rather than a flag on the web server because the two have incompatible\n// requirements for stdout — the web server logs to it, the MCP server speaks\n// JSON-RPC over it and must own it completely.\n//\n// It also guards stdout for the lifetime of the process. Anything that writes\n// there — a `console.log` from a shared analyzer, a logger the tools reach for —\n// would be read by the client as a malformed protocol frame, and the failure\n// would look like a server bug rather than a logging bug. Redirecting is better\n// than trusting: the guard costs one comparison per write and cannot be forgotten\n// by a future contributor three files deep.\n\nimport { serveMcp, SERVER_INFO } from './server.js';\n\n// stdout is a shared pipe with two kinds of writer: the protocol, which must be\n// the only thing a client ever sees, and everything else — a stray `console.log`\n// in a shared analyzer, a logger — which would be read as a malformed frame and\n// make the server look broken when it is not.\n//\n// Rather than hoping nothing else writes, this builds the protocol's writer first\n// and hands it to `serveMcp`, then points `process.stdout.write` at stderr. A\n// later `console.log` cannot corrupt the stream, and the protocol does not depend\n// on being the first thing to run.\nconst realStdoutWrite = process.stdout.write.bind(process.stdout);\nconst protocolStream = { write: (chunk) => realStdoutWrite(chunk) };\n\nprocess.stdout.write = function toStderr(chunk: string | Uint8Array, encoding?: BufferEncoding | ((err?: Error) => void), callback?: (err?: Error) => void) {\n  process.stderr.write(chunk);\n  if (typeof encoding === 'function') encoding();\n  else if (typeof callback === 'function') callback();\n  return true;\n};\n\n// Diagnostics are opt-in: a client reading stdout is reading a protocol stream\n// and nothing else, so anything else has to be asked for.\nif (process.env.ONBOARDER_MCP_LOG === '1') {\n  console.error(`[onboarder-mcp] ${SERVER_INFO.name} ${SERVER_INFO.version} starting on stdio`);\n}\n\nserveMcp({ output: protocolStream });\n"]}