ticketlens 0.38.20 → 0.38.22

package/README.md

@@ -529,11 +529,12 @@ A one-line summary footer is also appended automatically to `ticketlens triage`
 ### Doctor
 
 ```bash
-ticketlens doctor                        # Diagnose profile/license/connectivity/cache/queue problems
-ticketlens doctor --fix                  # Attempt safe automatic fixes (license revalidation, corrupt cache cleanup, queue flush)
+ticketlens doctor                        # Diagnose profile/license/connectivity/cache/MCP-registration/queue problems
+ticketlens doctor --fix                  # Attempt safe automatic fixes (license revalidation, corrupt cache cleanup, MCP registration, queue flush)
 ticketlens doctor --profile=acme         # Scope checks to a single profile
 ticketlens doctor --format=json          # JSON output for scripting/piping
 ticketlens doctor --format=json | jq '.ok'
+ticketlens doctor --mcp                  # Also check the MCP server handshake (spawns a subprocess)
 ```
 
 Runs five checks — profile configuration, license freshness, tracker connectivity, attachment cache health, and the Recall sync queue — and reports pass/fail with an actionable hint per failure, instead of a raw stack trace. Free tier, fully unrestricted; no license required.
@@ -817,10 +818,11 @@ ticketlens stats --days=14                   # Extend lookback window (Pro, max
 ticketlens stats --format=json               # JSON output for scripting
 
 # ── Doctor ────────────────────────────────────────────────────────────────────
-ticketlens doctor                             # Diagnose profile/license/connectivity/cache/queue problems
+ticketlens doctor                             # Diagnose profile/license/connectivity/cache/MCP-registration/queue problems
 ticketlens doctor --fix                       # Attempt safe automatic fixes
 ticketlens doctor --profile=acme             # Scope checks to a single profile
 ticketlens doctor --format=json               # JSON output for scripting/piping
+ticketlens doctor --mcp                       # Also check the MCP server handshake (spawns a subprocess)
 
 # ── Compliance ────────────────────────────────────────────────────────────────
 ticketlens compliance <TICKET-KEY>            # Check ticket requirements against local diff [Pro/Free 3/mo]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.38.20",
+  "version": "0.38.22",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.34.0 -->
+<!-- jtb-skill-version: 0.34.1 -->
 ---
 name: jtb
 description: Fetch a Jira ticket's full context (description, comments, linked issues, code references) and assemble a structured TicketBrief for implementation planning. Use when user types /jtb, mentions a Jira ticket key, or wants to plan work from a Jira ticket.
@@ -314,16 +314,17 @@ Requires a Pro license — on Free, all seven no-op with an upgrade hint on stde
 
 ## Doctor — diagnose local/tracker problems (Free)
 
-`ticketlens doctor` runs five fixed checks — profile configuration, license freshness, tracker connectivity, attachment cache health, and the Recall sync queue — and returns a pass/fail report with an actionable hint per failure, instead of a raw stack trace. Free tier, fully unrestricted; nothing here is gated.
+`ticketlens doctor` runs six fixed checks by default — profile configuration, license freshness, tracker connectivity, attachment cache health, MCP registration, and the Recall sync queue — and returns a pass/fail report with an actionable hint per failure, instead of a raw stack trace. Pass `--mcp` to also run a seventh, opt-in check: a real MCP server handshake (spawns `ticketlens mcp`, confirms it answers the JSON-RPC `initialize` request). Free tier, fully unrestricted; nothing here is gated.
 
 ```bash
-ticketlens doctor                    # run all checks
-ticketlens doctor --fix              # attempt safe automatic fixes (license revalidation, corrupt cache cleanup, queue flush)
+ticketlens doctor                    # run the six default checks
+ticketlens doctor --fix              # attempt safe automatic fixes (license revalidation, corrupt cache cleanup, MCP registration, queue flush)
 ticketlens doctor --profile=acme     # scope checks to a single profile
 ticketlens doctor --format=json      # structured output for scripting/piping
+ticketlens doctor --mcp              # also check the MCP server handshake (spawns a subprocess)
 ```
 
-If this harness has TicketLens's MCP server configured (a tool named `doctor` — often shown as `mcp__ticketlens__doctor` — visible in your tool list), prefer it over the bash form: it always requests the JSON report internally and returns it as the tool's text content, so you get a structured result to reason over directly instead of parsing CLI stdout. It accepts the same `fix`/`profile` options as the CLI flags above.
+If this harness has TicketLens's MCP server configured (a tool named `doctor` — often shown as `mcp__ticketlens__doctor` — visible in your tool list), prefer it over the bash form: it always requests the JSON report internally and returns it as the tool's text content, so you get a structured result to reason over directly instead of parsing CLI stdout. It accepts the same `fix`/`profile` options as the CLI flags above (the `--mcp` handshake check is CLI-only — deliberately not exposed as an MCP tool option, since a successful MCP tool call already proves the handshake works).
 
 A report with `ok: false` is a successful tool call describing failures, not a tool error — read the `checks[]` array for what's failing and act on each entry's `hint`, don't treat the call itself as having failed.
 

package/skills/jtb/scripts/lib/banner.mjs

@@ -10,8 +10,8 @@ import { getVersion } from './config.mjs';
 const ANSI_RE = /\x1b\[[0-9;]*m/g;
 const visibleLength = (str) => str.replace(ANSI_RE, '').length;
 
-const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
-const SPINNER_INTERVAL = 80;
+export const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export const SPINNER_INTERVAL = 80;
 
 
 function buildBox(lines, { s, borderColor = 'cyan' }) {

package/skills/jtb/scripts/lib/doctor-checks.mjs

@@ -12,6 +12,8 @@
  * before any public (CLI plain/JSON or MCP) output.
  */
 
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { resolveProfile, loadCredentials, loadProfiles } from './profile-resolver.mjs';
 import { checkLicense, GRACE_DAYS } from './license.mjs';
@@ -21,6 +23,8 @@ import { testConnections } from './connection-tester.mjs';
 import { formatSize } from './attachment-downloader.mjs';
 import { getCacheEntries, filterEntriesByProfile } from './cache-manager.mjs';
 import { readQueue } from './recall-queue.mjs';
+import { readMcpConfig, ENTRY_NAME, DESIRED_MCP_ENTRY } from './mcp-install.mjs';
+import { testMcpHandshake, DEFAULT_HANDSHAKE_TIMEOUT_MS } from './mcp-handshake-checker.mjs';
 
 const NOOP_STREAM = { write: () => true };
 
@@ -217,3 +221,83 @@ export function checkRecallQueue({
     fixable: true,
   };
 }
+
+export function checkMcpRegistration({
+  cwd = process.cwd(),
+  existsSyncFn = existsSync,
+  readMcpConfigFn = readMcpConfig,
+} = {}) {
+  const configPath = join(cwd, '.mcp.json');
+  const read = readMcpConfigFn(configPath);
+
+  if (!read.ok) {
+    return {
+      id: 'mcp-registration', label: 'MCP registration', ok: false,
+      message: read.reason, hint: null, fixable: false,
+    };
+  }
+
+  const existing = read.config.mcpServers?.[ENTRY_NAME];
+  const registered = existing !== undefined && JSON.stringify(existing) === JSON.stringify(DESIRED_MCP_ENTRY);
+
+  if (registered) {
+    return {
+      id: 'mcp-registration', label: 'MCP registration', ok: true,
+      message: '"ticketlens" is registered in .mcp.json with the correct command and args.',
+      hint: null, fixable: false,
+    };
+  }
+
+  if (!existsSyncFn(configPath)) {
+    return {
+      id: 'mcp-registration', label: 'MCP registration', ok: false,
+      message: 'No .mcp.json file found in the current directory.',
+      hint: 'Run `ticketlens mcp install` to create it and register "ticketlens".',
+      fixable: true,
+    };
+  }
+
+  return {
+    id: 'mcp-registration', label: 'MCP registration', ok: false,
+    message: '"ticketlens" is not registered in .mcp.json.',
+    hint: 'Run `ticketlens mcp install` to register it.',
+    fixable: true,
+  };
+}
+
+// 'timeout' is handled separately below (its message embeds the actual
+// timeoutMs), so it has no entry here.
+const MCP_HANDSHAKE_MESSAGES = {
+  'spawn-error': 'Could not start "ticketlens mcp" — command not found or failed to launch.',
+  'invalid-response': '"ticketlens mcp" responded, but not with a valid initialize result.',
+};
+
+const MCP_HANDSHAKE_HINTS = {
+  'spawn-error': 'Confirm `ticketlens` is installed and on PATH, then run `ticketlens doctor --mcp` again.',
+  'timeout': 'Run `ticketlens doctor --mcp` again — if it keeps timing out, check for a hung `ticketlens mcp` process.',
+  'invalid-response': 'Run `ticketlens --version` to check the installed build; reinstall if the response looks corrupted.',
+};
+
+export async function checkMcpHandshake({
+  timeoutMs = DEFAULT_HANDSHAKE_TIMEOUT_MS,
+  testMcpHandshakeFn = testMcpHandshake,
+} = {}) {
+  const result = await testMcpHandshakeFn({ timeoutMs });
+
+  if (result.ok) {
+    return {
+      id: 'mcp-handshake', label: 'MCP server handshake', ok: true,
+      message: `MCP server handshake succeeded, protocol version ${result.protocolVersion}.`,
+      hint: null, fixable: false,
+    };
+  }
+
+  const message = result.reason === 'timeout'
+    ? `No response from "ticketlens mcp" within ${timeoutMs}ms.`
+    : MCP_HANDSHAKE_MESSAGES[result.reason] ?? 'MCP server handshake failed.';
+
+  return {
+    id: 'mcp-handshake', label: 'MCP server handshake', ok: false,
+    message, hint: MCP_HANDSHAKE_HINTS[result.reason] ?? null, fixable: false,
+  };
+}

package/skills/jtb/scripts/lib/doctor-command.mjs

@@ -8,43 +8,59 @@ import fs from 'node:fs';
 import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { handleUnknownFlags } from './arg-validator.mjs';
 import { createStyler } from './ansi.mjs';
+import { SPINNER_FRAMES, SPINNER_INTERVAL } from './banner.mjs';
 import {
   checkProfileConfig, checkLicenseFreshness, checkConnectivity,
-  checkCacheHealth, checkRecallQueue,
+  checkCacheHealth, checkRecallQueue, checkMcpRegistration, checkMcpHandshake,
 } from './doctor-checks.mjs';
 import { revalidateLicense } from './license.mjs';
 import { flushQueue } from './recall-queue.mjs';
 import { readCliToken } from './cli-auth.mjs';
+import { mcpInstall } from './mcp-install.mjs';
 
-const KNOWN_FLAGS = ['--format=', '--fix', '--profile=', '--help', '-h'];
+const KNOWN_FLAGS = ['--format=', '--fix', '--profile=', '--mcp', '--help', '-h'];
+const NOOP_STREAM = { write: () => true };
 
-const lowerFirst = (str) => str.charAt(0).toLowerCase() + str.slice(1);
+// A leading run of 2+ capitals is an acronym (e.g. "MCP registration") and
+// must not be partially lowercased — only a genuine single leading capital
+// (e.g. "Profile configuration") gets folded to start a sentence mid-line.
+const lowerFirst = (str) => (/^[A-Z]{2,}/.test(str) ? str : str.charAt(0).toLowerCase() + str.slice(1));
 
-function renderPlain(checks, { fixed, skipped, stream }) {
-  const s = createStyler({ isTTY: stream.isTTY });
-  stream.write('\n');
-  for (const check of checks) {
-    const icon = check.ok ? s.green('✔') : s.red('✖');
-    stream.write(`  ${icon} ${check.label}: ${check.message}\n`);
-    if (!check.ok && check.hint) {
-      for (const line of check.hint.split('\n')) stream.write(`      ${s.dim(line)}\n`);
-    }
+function renderCheckRow(check, s) {
+  const icon = check.ok ? s.green('✔') : s.red('✖');
+  let text = `  ${icon} ${check.label}: ${check.message}\n`;
+  if (!check.ok && check.hint) {
+    for (const line of check.hint.split('\n')) text += `      ${s.dim(line)}\n`;
   }
+  return text;
+}
+
+function renderTrailer({ fixed, skipped }, s) {
+  let text = '';
   if (fixed.length > 0) {
-    stream.write(`\n  ${s.green('Fixed:')} ${fixed.join(', ')}\n`);
+    text += `\n  ${s.green('Fixed:')} ${fixed.join(', ')}\n`;
   }
   if (skipped.length > 0) {
-    stream.write(`\n  ${s.yellow('Skipped:')}\n`);
-    for (const sk of skipped) stream.write(`    ${sk.id}: ${sk.reason}\n`);
+    text += `\n  ${s.yellow('Skipped:')}\n`;
+    for (const sk of skipped) text += `    ${sk.id}: ${sk.reason}\n`;
   }
+  return text;
+}
+
+function renderPlain(checks, { fixed, skipped, stream }) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  stream.write('\n');
+  for (const check of checks) stream.write(renderCheckRow(check, s));
+  stream.write(renderTrailer({ fixed, skipped }, s));
   stream.write('\n');
 }
 
 async function applyFixes(rawResults, {
-  configDir, profileName, format, stream,
+  configDir, profileName, cwd, format, stream,
   revalidateLicenseFn, checkLicenseFreshnessFn,
   unlinkFn, checkCacheHealthFn,
   flushQueueFn, checkRecallQueueFn, readCliTokenFn,
+  mcpInstallFn, checkMcpRegistrationFn,
 }) {
   const fixed = [];
   const skipped = [];
@@ -81,6 +97,14 @@ async function applyFixes(rawResults, {
     }
   }
 
+  if (byId['mcp-registration'] && !byId['mcp-registration'].ok && byId['mcp-registration'].fixable) {
+    if (format === 'plain') stream.write('Registering ticketlens as an MCP server...\n');
+    mcpInstallFn({ cwd, stream: NOOP_STREAM, dryRun: false });
+    const recheck = checkMcpRegistrationFn({ cwd });
+    byId['mcp-registration'] = recheck;
+    if (recheck.ok) fixed.push('mcp-registration');
+  }
+
   return { results: Object.values(byId), fixed, skipped };
 }
 
@@ -94,10 +118,13 @@ export async function runDoctor(args, {
   checkConnectivityFn = checkConnectivity,
   checkCacheHealthFn = checkCacheHealth,
   checkRecallQueueFn = checkRecallQueue,
+  checkMcpRegistrationFn = checkMcpRegistration,
+  checkMcpHandshakeFn = checkMcpHandshake,
   revalidateLicenseFn = revalidateLicense,
   unlinkFn = (p) => fs.unlinkSync(p),
   flushQueueFn = flushQueue,
   readCliTokenFn = readCliToken,
+  mcpInstallFn = mcpInstall,
 } = {}) {
   const validated = await handleUnknownFlags(args, KNOWN_FLAGS, { stream });
   if (validated === null) return { ok: false };
@@ -112,6 +139,7 @@ export async function runDoctor(args, {
   const profileArg = validated.find(a => a.startsWith('--profile='));
   const profileName = profileArg ? profileArg.split('=')[1] : null;
   const shouldFix = validated.includes('--fix');
+  const shouldCheckMcpHandshake = validated.includes('--mcp');
 
   const checkList = [
     { label: 'Profile configuration', run: () => checkProfileConfigFn({ configDir, profileName, cwd }) },
@@ -119,17 +147,57 @@ export async function runDoctor(args, {
     { label: 'Tracker connectivity', run: () => checkConnectivityFn({ configDir, profileName, cwd }) },
     { label: 'Attachment cache', run: () => checkCacheHealthFn({ configDir, profileName }) },
     { label: 'Recall sync queue', run: () => checkRecallQueueFn({ configDir }) },
+    { label: 'MCP registration', run: () => checkMcpRegistrationFn({ cwd }) },
+    ...(shouldCheckMcpHandshake ? [{ label: 'MCP server handshake', run: () => checkMcpHandshakeFn({}) }] : []),
   ];
 
   const showProgress = format === 'plain' && stream.isTTY;
-  const s = createStyler({ isTTY: stream.isTTY });
+  const loaderStyler = createStyler({ isTTY: stream.isTTY });
+  const outStyler = createStyler({ isTTY: out.isTTY });
   const rawResults = [];
-  for (const { label, run } of checkList) {
-    if (showProgress) stream.write(`  ${s.dim(`○ Checking ${lowerFirst(label)}…`)}\n`);
-    try {
-      rawResults.push(await run());
-    } finally {
-      if (showProgress) stream.write('\x1b[A\r\x1b[2K');
+
+  const writeSpinnerLine = (label, frame) => {
+    stream.write(`  ${loaderStyler.brand(SPINNER_FRAMES[frame])} ${loaderStyler.dim(`Checking ${lowerFirst(label)}…`)}\n`);
+  };
+
+  // Ctrl+C during a slow check (e.g. tracker connectivity) must not leave the
+  // user's real terminal cursor permanently hidden — Node's default SIGINT
+  // handling terminates before pending finally blocks on an in-flight await
+  // run, so this needs its own listener. Same pattern as init-wizard.mjs.
+  const onSigint = () => { stream.write('\x1b[?25h'); process.exit(130); };
+  if (showProgress) {
+    out.write('\n');
+    stream.write('\x1b[?25l'); // hide cursor for the whole check-running phase
+    process.on('SIGINT', onSigint);
+  }
+  try {
+    for (const { label, run } of checkList) {
+      let frame = 0;
+      let timer;
+      if (showProgress) {
+        writeSpinnerLine(label, frame);
+        timer = setInterval(() => {
+          frame = (frame + 1) % SPINNER_FRAMES.length;
+          stream.write('\x1b[A\r\x1b[2K');
+          writeSpinnerLine(label, frame);
+        }, SPINNER_INTERVAL);
+      }
+      let result;
+      try {
+        result = await run();
+      } finally {
+        if (showProgress) {
+          clearInterval(timer);
+          stream.write('\x1b[A\r\x1b[2K');
+        }
+      }
+      rawResults.push(result);
+      if (showProgress) out.write(renderCheckRow(result, outStyler));
+    }
+  } finally {
+    if (showProgress) {
+      stream.write('\x1b[?25h'); // restore cursor
+      process.removeListener('SIGINT', onSigint);
     }
   }
 
@@ -138,10 +206,11 @@ export async function runDoctor(args, {
   let finalResults = rawResults;
   if (shouldFix) {
     const applied = await applyFixes(rawResults, {
-      configDir, profileName, format, stream,
+      configDir, profileName, cwd, format, stream,
       revalidateLicenseFn, checkLicenseFreshnessFn,
       unlinkFn, checkCacheHealthFn,
       flushQueueFn, checkRecallQueueFn, readCliTokenFn,
+      mcpInstallFn, checkMcpRegistrationFn,
     });
     finalResults = applied.results;
     fixed = applied.fixed;
@@ -156,6 +225,15 @@ export async function runDoctor(args, {
     return { ok };
   }
 
-  renderPlain(checks, { fixed, skipped, stream: out });
+  if (showProgress) {
+    // Rows already streamed to `out` progressively during the check loop
+    // (each check's raw, first-observed state — a later `--fix` never
+    // rewrites an already-shown row; the trailing Fixed:/Skipped: block
+    // below is the sole signal of what got repaired).
+    out.write(renderTrailer({ fixed, skipped }, outStyler));
+    out.write('\n');
+  } else {
+    renderPlain(checks, { fixed, skipped, stream: out });
+  }
   return { ok };
 }

package/skills/jtb/scripts/lib/help.mjs

@@ -1230,18 +1230,21 @@ export function printDoctorHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [
     '',
-    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('doctor')} ${s.dim('[--fix] [--format=plain|json] [--profile=NAME]')}`,
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('doctor')} ${s.dim('[--fix] [--format=plain|json] [--profile=NAME] [--mcp]')}`,
     '',
     `  Diagnose common TicketLens problems: profile configuration, license`,
-    `  freshness, tracker connectivity, attachment cache health, and the Recall`,
-    `  sync queue. Free tier, fully unrestricted.`,
+    `  freshness, tracker connectivity, attachment cache health, MCP`,
+    `  registration, and the Recall sync queue. Pass --mcp to also check the`,
+    `  MCP server handshake. Free tier, fully unrestricted.`,
     '',
     `  ${s.bold('OPTIONS')}`,
     '',
     `    ${s.brand('--fix')}              Attempt safe, non-destructive repairs for failing checks`,
+    `                       ${s.dim('(rows show pre-fix status; see the Fixed: summary for what was repaired)')}`,
     `    ${s.brand('--format')}=${s.dim('plain')}    Human-readable output  ${s.dim('(default)')}`,
     `    ${s.brand('--format')}=${s.dim('json')}     JSON output for scripting/piping`,
     `    ${s.brand('--profile')}=${s.dim('NAME')}    Scope profile/connectivity/cache checks to one profile`,
+    `    ${s.brand('--mcp')}              Also run the MCP server handshake check (spawns a subprocess)`,
     `    ${s.brand('-h')}, ${s.brand('--help')}         Show this help`,
     '',
     `  ${s.bold('EXAMPLES')}`,
@@ -1250,6 +1253,7 @@ export function printDoctorHelp({ stream = process.stdout } = {}) {
     `    ${s.dim('$')} ticketlens doctor --fix`,
     `    ${s.dim('$')} ticketlens doctor --profile=work`,
     `    ${s.dim('$')} ticketlens doctor --format=json`,
+    `    ${s.dim('$')} ticketlens doctor --mcp`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');

package/skills/jtb/scripts/lib/mcp-handshake-checker.mjs

@@ -0,0 +1,82 @@
+/**
+ * Spawns `ticketlens mcp` as a child process and speaks one round of the
+ * MCP stdio JSON-RPC handshake to it — the same `initialize` request an AI
+ * harness sends per the MCP stdio transport spec (see mcp-server.mjs's own
+ * `initialize` handler). Pure diagnostic probe: the child is always killed
+ * before this resolves, on every path (success, timeout, or error) — never
+ * left running.
+ */
+
+import { spawn } from 'node:child_process';
+
+export const DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+const PROTOCOL_VERSION = '2025-11-25';
+
+/**
+ * @returns {Promise<{ok: boolean, reason?: 'spawn-error'|'timeout'|'invalid-response', error?: Error, protocolVersion?: string}>}
+ */
+export function testMcpHandshake({
+  spawnFn = spawn,
+  timeoutMs = DEFAULT_HANDSHAKE_TIMEOUT_MS,
+} = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let buffer = '';
+    let child;
+
+    const settle = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      try { child?.kill(); } catch { /* already exited */ }
+      resolve(value);
+    };
+
+    const timer = setTimeout(() => settle({ ok: false, reason: 'timeout' }), timeoutMs);
+
+    try {
+      child = spawnFn('ticketlens', ['mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
+    } catch (error) {
+      settle({ ok: false, reason: 'spawn-error', error });
+      return;
+    }
+
+    child.on('error', (error) => settle({ ok: false, reason: 'spawn-error', error }));
+    // A write can fail asynchronously (e.g. EPIPE if the child already died) —
+    // an unhandled 'error' on a Writable stream crashes the process. The
+    // child's own 'error'/'exit' already attributes the real failure reason;
+    // this only needs to stop the crash, not settle a second time.
+    child.stdin.on('error', () => {});
+
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk.toString();
+      const newlineIdx = buffer.indexOf('\n');
+      if (newlineIdx === -1) return;
+      const line = buffer.slice(0, newlineIdx);
+      let msg;
+      try {
+        msg = JSON.parse(line);
+      } catch {
+        settle({ ok: false, reason: 'invalid-response' });
+        return;
+      }
+      if (msg?.id === 1 && msg.result?.protocolVersion) {
+        settle({ ok: true, protocolVersion: msg.result.protocolVersion });
+      } else {
+        settle({ ok: false, reason: 'invalid-response' });
+      }
+    });
+
+    const request = JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: 'ticketlens-doctor', version: '1.0' },
+      },
+    }) + '\n';
+    child.stdin.write(request);
+  });
+}

package/skills/jtb/scripts/lib/mcp-install.mjs

@@ -20,9 +20,10 @@ import { DEFAULT_CONFIG_DIR } from './config.mjs';
 import { isLicensed } from './license.mjs';
 import { createStyler } from './ansi.mjs';
 
-const ENTRY_NAME = 'ticketlens';
+export const ENTRY_NAME = 'ticketlens';
+export const DESIRED_MCP_ENTRY = { command: ENTRY_NAME, args: ['mcp'] };
 
-function readConfig(configPath) {
+export function readMcpConfig(configPath) {
   if (!existsSync(configPath)) return { ok: true, config: {} };
   let parsed;
   try {
@@ -55,7 +56,7 @@ export function mcpInstall({
   const configPath = join(cwd, '.mcp.json');
   const s = createStyler({ isTTY: stream.isTTY });
 
-  const read = readConfig(configPath);
+  const read = readMcpConfig(configPath);
   if (!read.ok) {
     stream.write(`  ${s.dim('✗')} ${read.reason}\n`);
     return { written: false, dryRun, path: configPath, reason: read.reason };
@@ -63,7 +64,7 @@ export function mcpInstall({
 
   const config = read.config;
   config.mcpServers ??= {};
-  const desired = { command: ENTRY_NAME, args: ['mcp'] };
+  const desired = DESIRED_MCP_ENTRY;
   const existing = config.mcpServers[ENTRY_NAME];
   const alreadyCorrect = existing !== undefined && JSON.stringify(existing) === JSON.stringify(desired);
   config.mcpServers[ENTRY_NAME] = desired;

package/skills/jtb/scripts/lib/mcp-server.mjs

@@ -31,7 +31,7 @@ const PROTOCOL_VERSION = '2025-11-25';
 const TOOLS = [
   {
     name: 'doctor',
-    description: 'Diagnose common TicketLens problems: profile configuration, license freshness, tracker connectivity, attachment cache health, and the Recall sync queue. Always returns structured JSON. Free tier, fully unrestricted — including fix.',
+    description: 'Diagnose common TicketLens problems: profile configuration, license freshness, tracker connectivity, attachment cache health, MCP registration, and the Recall sync queue. Always returns structured JSON. Free tier, fully unrestricted — including fix.',
     inputSchema: {
       type: 'object',
       properties: {