ticketlens 0.22.1 → 0.23.0

package/README.md

@@ -411,7 +411,7 @@ 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"] }`.
+**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"] }` — or run `ticketlens mcp install` in a project to write that entry into its `.mcp.json` for you (creates the file if it doesn't exist, merges in if it does — never touches any other entry already there; `--dry-run` to preview first).
 
 `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.
 
@@ -693,6 +693,8 @@ ticketlens recall "retry backoff"             # Free-text search across all note
 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]
+ticketlens mcp install                        # Register it into the current project's .mcp.json
+ticketlens mcp install --dry-run              # Preview the registration without writing
 
 # ── Stats ──────────────────────────────────────────────────────────────────────
 ticketlens stats                              # Response-time metrics from local history

package/bin/ticketlens.mjs

@@ -724,6 +724,12 @@ switch (command) {
 
   case 'mcp': {
     if (cmdArgs.includes('--help') || cmdArgs.includes('-h')) { printMcpHelp(); break; }
+    if (cmdArgs[0] === 'install') {
+      const { mcpInstall } = await import('../skills/jtb/scripts/lib/mcp-install.mjs');
+      const { written, dryRun, reason } = mcpInstall({ dryRun: cmdArgs.includes('--dry-run') });
+      if (!dryRun && !written && reason) process.exitCode = 1;
+      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');

package/package.json

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

package/scripts/postinstall.mjs

@@ -102,6 +102,7 @@ try {
   } else {
     console.log('  → New here? Run  tl  to launch the guided setup.');
   }
+  console.log('  → Using an MCP-capable AI harness? Run  tl mcp install  in a project to register Recall as native tools.');
   console.log('');
 } catch {
   // Silent on failure — never breaks the install.

package/skills/jtb/SKILL.md

@@ -1,4 +1,4 @@
-<!-- jtb-skill-version: 0.22.1 -->
+<!-- jtb-skill-version: 0.23.0 -->
 ---
 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.

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

@@ -602,6 +602,13 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     '',
     `    ${s.brand('-h')}, ${s.brand('--help')}   Show this help`,
     '',
+    `  ${s.bold('COMMANDS')}`,
+    '',
+    `    ${s.brand('install')}       Register "ticketlens mcp" into the current project's .mcp.json`,
+    '',
+    `  ${s.dim('install is ungated — writes the registration for anyone; the tools it')}`,
+    `  ${s.dim('points at still require Pro at call time, same as note add/recall.')}`,
+    '',
     `  ${s.bold('HARNESS CONFIG')}`,
     '',
     `    ${s.dim('{ "command": "ticketlens", "args": ["mcp"] }')}`,
@@ -609,6 +616,8 @@ export function printMcpHelp({ stream = process.stdout } = {}) {
     `  ${s.bold('EXAMPLES')}`,
     '',
     `    ${s.dim('$')} ticketlens mcp`,
+    `    ${s.dim('$')} ticketlens mcp install`,
+    `    ${s.dim('$')} ticketlens mcp install --dry-run`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');

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

@@ -0,0 +1,92 @@
+/**
+ * Registers `ticketlens mcp` into the current project's `.mcp.json` so the
+ * user doesn't have to hand-write the JSON. Project-scoped only — Claude
+ * Code's MCP config has no global/user-level equivalent (confirmed by
+ * inspecting a real ~/.claude.json: no top-level `mcpServers` key, it's
+ * nested per-project). Never touches ~/.claude.json directly.
+ *
+ * Mirrors hooks-setup.mjs's already-proven safe-merge pattern: malformed
+ * JSON is left untouched (never overwritten), the write is atomic (temp
+ * file + rename — real guarantee on POSIX, still the best available
+ * cross-platform approach on Windows), and every other key in the file is
+ * preserved exactly. Registration itself is never license-gated — same as
+ * `ticketlens mcp`/`note add`/`recall`, which all exist for everyone and
+ * gate only at actual invocation.
+ */
+
+import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { DEFAULT_CONFIG_DIR } from './config.mjs';
+import { isLicensed } from './license.mjs';
+import { createStyler } from './ansi.mjs';
+
+const ENTRY_NAME = 'ticketlens';
+
+function readConfig(configPath) {
+  if (!existsSync(configPath)) return { ok: true, config: {} };
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(configPath, 'utf8'));
+  } catch {
+    return { ok: false, reason: `${configPath} is not valid JSON — left untouched. Fix or remove it, then retry.` };
+  }
+  // Valid JSON whose top level isn't a plain object (array/null/number/string/
+  // boolean) is still valid to parse — `typeof null === 'object'` and arrays
+  // are objects too, so both need an explicit check, not just "did it parse."
+  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+    return { ok: false, reason: `${configPath}'s top level is not a JSON object — left untouched. Fix or remove it, then retry.` };
+  }
+  if (parsed.mcpServers !== undefined && (typeof parsed.mcpServers !== 'object' || parsed.mcpServers === null || Array.isArray(parsed.mcpServers))) {
+    return { ok: false, reason: `${configPath}'s "mcpServers" key is not an object — left untouched. Fix or remove it, then retry.` };
+  }
+  return { ok: true, config: parsed };
+}
+
+/**
+ * @returns {{ written: boolean, dryRun: boolean, path: string, alreadyCorrect?: boolean, reason?: string }}
+ */
+export function mcpInstall({
+  cwd = process.cwd(),
+  isLicensedFn = isLicensed,
+  configDir = DEFAULT_CONFIG_DIR,
+  stream = process.stdout,
+  dryRun = false,
+} = {}) {
+  const configPath = join(cwd, '.mcp.json');
+  const s = createStyler({ isTTY: stream.isTTY });
+
+  const read = readConfig(configPath);
+  if (!read.ok) {
+    stream.write(`  ${s.dim('✗')} ${read.reason}\n`);
+    return { written: false, dryRun, path: configPath, reason: read.reason };
+  }
+
+  const config = read.config;
+  config.mcpServers ??= {};
+  const desired = { command: ENTRY_NAME, args: ['mcp'] };
+  const existing = config.mcpServers[ENTRY_NAME];
+  const alreadyCorrect = existing !== undefined && JSON.stringify(existing) === JSON.stringify(desired);
+  config.mcpServers[ENTRY_NAME] = desired;
+
+  const serialized = JSON.stringify(config, null, 2) + '\n';
+
+  if (dryRun) {
+    stream.write(`  Would write ${configPath}:\n\n${serialized}\n`);
+    return { written: false, dryRun: true, path: configPath, alreadyCorrect };
+  }
+
+  if (alreadyCorrect) {
+    stream.write(`  ${s.dim('✔')} Already registered in ${configPath}\n`);
+  } else {
+    const tmpPath = `${configPath}.${process.pid}.tmp`;
+    writeFileSync(tmpPath, serialized, 'utf8');
+    renameSync(tmpPath, configPath); // atomic on POSIX; best available cross-platform approach on Windows
+    stream.write(`  ${s.brand('✔')} Registered "ticketlens" in ${configPath}\n`);
+  }
+
+  if (!isLicensedFn('pro', configDir)) {
+    stream.write(`  ${s.dim('Note: recall_add/recall_search require a Pro license — see')} ${s.cyan('ticketlens license')}${s.dim('.')}\n`);
+  }
+
+  return { written: !alreadyCorrect, dryRun: false, path: configPath, alreadyCorrect };
+}