ticketlens 0.21.12 → 0.22.1

package/README.md

@@ -411,6 +411,8 @@ Every note is scanned before saving — anything shaped like a real secret (API
 
 **Removing a note:** `ticketlens note delete --id="..." [--ticket=KEY]` removes a note from your local vault. Local only — if it was already pushed to a team, teammates who pulled it keep their copy; deleting it there too is a manager action from the Console (Admin > Recall).
 
+**Any MCP-capable AI harness:** `ticketlens mcp` starts a stdio [MCP](https://modelcontextprotocol.io) server exposing `recall_add` and `recall_search` as native tools — any MCP-compatible AI assistant, not just Claude Code, can call them directly instead of constructing a shell command. It's a thin adapter over the exact same code as the CLI commands above — same Pro gate, same secret scan, same local vault, same team sync — nothing is reimplemented. Point your harness's MCP config at it: `{ "command": "ticketlens", "args": ["mcp"] }`.
+
 `note add`'s save confirmation and `recall`'s search results are styled by default in a terminal; add `--plain` to either for bare, pipe-safe output. `recall` always shows each note's file ID (e.g. `[1784135399545-fe01c4.md]`) so you can open it directly (`cat ~/.ticketlens/recall/<PREFIX>/<id>`), or pass `--full` to print the full body content inline instead.
 
 **Gaps** — every `ticketlens PROJ-123` brief also diffs the ticket's own description against its linked tickets (from the depth traversal you already requested) and its own downloaded attachments, looking for requirements mentioned there but missing here. Anything uncovered shows up under a `## Gaps` section, citing exactly where it came from — a linked ticket key or an attachment filename — as evidence, never an instruction to act on. Nothing is saved anywhere; it's recomputed fresh on every fetch. Requires a Pro license, same as Recall. No network call beyond what the brief already made.
@@ -690,6 +692,7 @@ ticketlens recall CNV1-2                      # Search saved notes by ticket key
 ticketlens recall "retry backoff"             # Free-text search across all notes [Pro]
 ticketlens recall sync                        # Retry any notes stuck in the local queue [Team+]
 ticketlens recall settings                    # Show effective retry-queue settings, fetched live [Team+]
+ticketlens mcp                                # Start the MCP stdio server (recall_add/recall_search tools) [Pro]
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history
@@ -771,6 +774,7 @@ ticketlens note delete --id="..."        # Remove a note from your local vault
 ticketlens recall <query|TICKET-KEY>     # Search your saved Recall notes
 ticketlens recall sync                   # Retry any notes stuck in the local queue
 ticketlens recall settings               # Show effective retry-queue settings, fetched live
+ticketlens mcp                           # Start the MCP stdio server (recall_add/recall_search)
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 

package/bin/ticketlens.mjs

@@ -27,7 +27,7 @@ import {
   printComplianceHelp, printLedgerHelp, printPrHelp, printInstallHooksHelp,
   printCollisionsHelp, printStatsHelp,
   printCloudKeysHelp,
-  printNoteHelp, printRecallHelp,
+  printNoteHelp, printRecallHelp, printMcpHelp,
 } from '../skills/jtb/scripts/lib/help.mjs';
 import { runStats } from '../skills/jtb/scripts/lib/run-stats.mjs';
 import { createStyler } from '../skills/jtb/scripts/lib/ansi.mjs';
@@ -722,6 +722,15 @@ switch (command) {
     break;
   }
 
+  case 'mcp': {
+    if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printMcpHelp(); break; }
+    // Long-lived stdio server, not a one-shot command — no .then()-exit-code
+    // pattern; it exits when the client closes stdin (spec's stdio lifecycle).
+    const { runMcpServer } = await import('../skills/jtb/scripts/lib/mcp-server.mjs');
+    await runMcpServer({});
+    break;
+  }
+
   case 'help':
   default: {
     const isInteractive = args.length === 0 && process.stdin.isTTY && process.stdout.isTTY && !process.env.CI;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.21.12",
+  "version": "0.22.1",
   "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.21.0 -->
+<!-- jtb-skill-version: 0.22.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.
@@ -232,6 +232,8 @@ echo "The body text of the note, one or more paragraphs." | \
 
 To search saved notes directly (outside of automatic brief injection): `ticketlens recall "<query>"`.
 
+**Pick exactly one path per capture — never both.** If this harness has TicketLens's MCP server configured (`ticketlens mcp` — `recall_add`/`recall_search` as native tools, see `ticketlens mcp --help`), prefer calling those tools directly over the bash commands above — same license gate, same secret scan, same vault, same team sync, just no shell command to construct. Fall back to the bash form only when the MCP tools aren't available. Calling both for the same insight creates two near-duplicate notes (no dedup exists between the two paths) and, with team sync on, two separate pushes for a manager to review.
+
 ### Quality loop (Pro, in-session only)
 
 Only when `note add` above was dispatched *by you, inside this skill*, and it printed a saved note id (e.g. `Saved note "Retry gotcha" (1784135399545-fe01c4.md)`) — never for a note a user typed directly into a bare shell, which has no Task/Agent tool available. If there's no such tool in your environment, skip this whole section silently: no warning, no degraded fallback, the note is already saved and that's a complete, correct outcome on its own.

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

@@ -126,6 +126,10 @@ export function parseCommand(args) {
     return { command: 'recall', args: args.slice(1) };
   }
 
+  if (first === 'mcp') {
+    return { command: 'mcp', args: args.slice(1) };
+  }
+
   // Anything that looks like a ticket key or any non-flag arg → fetch
   return { command: 'fetch', args };
 }

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

@@ -53,6 +53,7 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('ticketlens')} recall ${s.dim('<query|TICKET-KEY>')}   Search your saved Recall notes  ${s.dim('[Pro]')}`,
     `    ${s.brand('ticketlens')} recall sync                 Retry any notes stuck in the local queue  ${s.dim('[Team+]')}`,
     `    ${s.brand('ticketlens')} recall settings             Show effective retry-queue settings, fetched live  ${s.dim('[Team+]')}`,
+    `    ${s.brand('ticketlens')} mcp                         Start the MCP stdio server for Recall  ${s.dim('[Pro]')}`,
     '',
     `    ${s.brand('ticketlens')} delete ${s.dim('<PROFILE-NAME>')}       Remove a profile`,
     `    ${s.brand('ticketlens')} activate ${s.dim('<KEY>')}              Activate a license key`,
@@ -585,6 +586,34 @@ export function printRecallHelp({ stream = process.stdout } = {}) {
   stream.write(lines.join('\n') + '\n');
 }
 
+export function printMcpHelp({ stream = process.stdout } = {}) {
+  const s = createStyler({ isTTY: stream.isTTY });
+  const lines = [
+    '',
+    `  ${s.bold(s.brand('ticketlens'))} ${s.bold('mcp')}  ${s.dim('[Pro]')}`,
+    '',
+    `  Start an MCP (Model Context Protocol) stdio server exposing Recall as`,
+    `  native tools — ${s.cyan('recall_add')} and ${s.cyan('recall_search')} — for any MCP-compatible AI`,
+    `  harness, not just Claude Code. Thin adapter over the same code as`,
+    `  ${s.cyan('note add')}/${s.cyan('recall')} above: same Pro gate, same secret scan, same local`,
+    `  vault, same team sync. Long-running — exits when the client closes stdin.`,
+    '',
+    `  ${s.bold('OPTIONS')}`,
+    '',
+    `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
+    '',
+    `  ${s.bold('HARNESS CONFIG')}`,
+    '',
+    `    ${s.dim('{ "command": "ticketlens", "args": ["mcp"] }')}`,
+    '',
+    `  ${s.bold('EXAMPLES')}`,
+    '',
+    `    ${s.dim('$')} ticketlens mcp`,
+    '',
+  ];
+  stream.write(lines.join('\n') + '\n');
+}
+
 export function printSwitchHelp({ stream = process.stdout } = {}) {
   const s = createStyler({ isTTY: stream.isTTY });
   const lines = [

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

@@ -0,0 +1,202 @@
+/**
+ * MCP (Model Context Protocol) stdio server — `ticketlens mcp`.
+ *
+ * A pure transport adapter: parses JSON-RPC 2.0 off stdin, translates
+ * `tools/call` arguments into the exact args/dependency shape `runNoteAdd`/
+ * `runRecall` already accept, and captures their human-readable `stream`
+ * output into the JSON-RPC response instead of a real stream. Zero new
+ * validation, licensing, or vault logic — both tools funnel through the
+ * same functions the CLI's `note add`/`recall` commands already use, so
+ * every existing gate (license, secret scan, structural check, retry
+ * queue) applies identically here.
+ *
+ * Per the MCP stdio transport spec, the server MUST NOT write anything to
+ * stdout that isn't a valid MCP message — every wrapped function's output
+ * is captured into a buffer and returned as the tool result, never piped
+ * to the real stdout that also carries the JSON-RPC channel.
+ */
+
+import readline from 'node:readline';
+import { DEFAULT_CONFIG_DIR, getVersion } from './config.mjs';
+import { runNoteAdd } from './note-command.mjs';
+import { runRecall } from './recall-command.mjs';
+
+const PROTOCOL_VERSION = '2025-11-25';
+
+const TOOLS = [
+  {
+    name: 'recall_add',
+    description: 'Save a Recall note — a gotcha, root cause, or non-obvious decision learned this session. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        title: { type: 'string', description: 'Short one-line title.' },
+        ticket: { type: 'string', description: 'Optional ticket key, e.g. PROJ-123.' },
+        tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags.' },
+        body: { type: 'string', description: 'The note body — one or more paragraphs.' },
+      },
+      required: ['title', 'body'],
+    },
+  },
+  {
+    name: 'recall_search',
+    description: 'Search saved Recall notes by free-text query or ticket key. Requires a TicketLens Pro license.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Free-text query or a ticket key like PROJ-123.' },
+      },
+      required: ['query'],
+    },
+  },
+];
+
+function jsonRpcResult(id, result) {
+  return JSON.stringify({ jsonrpc: '2.0', id, result }) + '\n';
+}
+
+function jsonRpcError(id, code, message) {
+  return JSON.stringify({ jsonrpc: '2.0', id, error: { code, message } }) + '\n';
+}
+
+/** Buffers stream.write() calls instead of touching a real stream. */
+function capturingStream() {
+  const parts = [];
+  return {
+    write(s) { parts.push(s); return true; },
+    get text() { return parts.join(''); },
+  };
+}
+
+/**
+ * Builds runNoteAdd's cmdArgs array. Each `--flag=value` MUST stay a single,
+ * discrete array element — runNoteAdd's parseFlag matches per-element via
+ * startsWith/includes, which is only safe as long as this array is never
+ * joined into a string and re-split/re-tokenized. A title/body containing
+ * `--ticket=EVIL-999` stays inert precisely because it's never anything
+ * but one opaque array element.
+ */
+function buildNoteAddArgs({ title, ticket, tags }) {
+  const args = [`--title=${title}`];
+  if (ticket) args.push(`--ticket=${ticket}`);
+  if (Array.isArray(tags) && tags.length > 0) args.push(`--tags=${tags.join(',')}`);
+  return args;
+}
+
+async function callRecallAdd(args, { configDir, runNoteAddFn }) {
+  // runNoteAdd's own `if (!rawTitle)` guard only rejects an empty string —
+  // `--title=${title}` with title===undefined template-stringifies to the
+  // truthy 4-char string "undefined", which would pass that guard and get
+  // persisted as a real note title. Reject before it ever reaches cmdArgs.
+  if (!args.title) {
+    return { isError: true, content: [{ type: 'text', text: 'Missing required argument: title' }] };
+  }
+  const capture = capturingStream();
+  const { written } = await runNoteAddFn(buildNoteAddArgs(args), {
+    configDir,
+    stream: capture,
+    readStdin: async () => args.body ?? '',
+  });
+  const content = [{ type: 'text', text: capture.text }];
+  return written ? { content } : { isError: true, content };
+}
+
+async function callRecallSearch(args, { configDir, runRecallFn }) {
+  const capture = capturingStream();
+  const { ok } = await runRecallFn([args.query ?? ''], {
+    configDir,
+    stream: capture,
+    errorStream: capture,
+  });
+  const content = [{ type: 'text', text: capture.text }];
+  return ok ? { content } : { isError: true, content };
+}
+
+async function handleToolsCall(params, deps) {
+  const { name, arguments: args = {} } = params ?? {};
+  if (name === 'recall_add') return callRecallAdd(args, deps);
+  if (name === 'recall_search') return callRecallSearch(args, deps);
+  return { isError: true, content: [{ type: 'text', text: `Unknown tool: ${name}` }] };
+}
+
+async function handleMessage(raw, { configDir, runNoteAddFn, runRecallFn }) {
+  let msg;
+  try {
+    msg = JSON.parse(raw);
+  } catch {
+    return jsonRpcError(null, -32700, 'Parse error');
+  }
+
+  if (typeof msg !== 'object' || msg === null || Array.isArray(msg)) {
+    return jsonRpcError(null, -32600, 'Invalid Request');
+  }
+
+  const { id, method, params } = msg;
+
+  if (method === 'notifications/initialized') return null; // notification, no response
+
+  if (method === 'initialize') {
+    return jsonRpcResult(id, {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      serverInfo: { name: 'ticketlens', version: getVersion() },
+    });
+  }
+
+  if (method === 'tools/list') {
+    return jsonRpcResult(id, { tools: TOOLS });
+  }
+
+  if (method === 'tools/call') {
+    try {
+      const result = await handleToolsCall(params, { configDir, runNoteAddFn, runRecallFn });
+      return jsonRpcResult(id, result);
+    } catch (err) {
+      return jsonRpcError(id ?? null, -32603, `Internal error: ${err.message}`);
+    }
+  }
+
+  return jsonRpcError(id ?? null, -32601, `Method not found: ${method}`);
+}
+
+/**
+ * Runs the stdio JSON-RPC loop until stdin closes (the client closing
+ * stdin to end the session, per the stdio transport's lifecycle). Each
+ * line is fully processed — awaited — before the next is handled: a
+ * long-lived process (unlike the one-shot CLI) must not let a burst of
+ * rapid messages spawn unbounded concurrent tool calls.
+ */
+export function runMcpServer({
+  configDir = DEFAULT_CONFIG_DIR,
+  stdin = process.stdin,
+  stdout = process.stdout,
+  runNoteAddFn = runNoteAdd,
+  runRecallFn = runRecall,
+} = {}) {
+  // A client can disconnect mid-write (EPIPE) at any time on a long-lived
+  // process — an unhandled 'error' event on either stream would otherwise
+  // throw and crash the whole server via Node's default EventEmitter
+  // behavior. Swallow here; the process ends naturally when stdin closes.
+  stdin.on('error', () => {});
+  stdout.on('error', () => {});
+
+  const rl = readline.createInterface({ input: stdin, terminal: false });
+  let queue = Promise.resolve();
+
+  rl.on('line', (line) => {
+    if (!line.trim()) return;
+    // .catch() here, not left to propagate: an unrejected chain would
+    // otherwise poison every later .then() forever (one bad line kills
+    // all subsequent messages) and leave `queue.then(resolve)` below
+    // never resolving (a dropped rejection isn't a resolution) — the
+    // server would hang on shutdown instead of exiting.
+    queue = queue.then(async () => {
+      const response = await handleMessage(line, { configDir, runNoteAddFn, runRecallFn });
+      if (response) stdout.write(response);
+    }).catch(() => {});
+  });
+
+  return new Promise((resolve) => {
+    rl.on('close', () => { queue.then(resolve); });
+  });
+}

package/skills/jtb/scripts/lib/recall-sync.mjs

@@ -134,7 +134,7 @@ export async function pushNote(note, {
       signal: AbortSignal.timeout(timeoutMs),
     });
   } catch {
-    warn(`  ${yellow('⚠')} Could not sync note to your team (network error) — saved locally only.\n`);
+    warn(`  ${yellow('⚠')} Could not sync note to your team (network error) — saved locally and queued to retry automatically.\n`);
     return { ok: false };
   }