trackly-cli 0.14.0 → 0.14.1

package/README.md

@@ -1,6 +1,6 @@
 [![npm](https://img.shields.io/npm/v/trackly-cli.svg)](https://www.npmjs.com/package/trackly-cli)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Node 20+](https://img.shields.io/badge/node-20+-brightgreen.svg)](https://nodejs.org/)
+[![Node 20.20+ or 22.22+](https://img.shields.io/badge/node-20.20%2B%20%7C%2022.22%2B-brightgreen.svg)](https://nodejs.org/)
 [![MCP Server](https://img.shields.io/badge/MCP-Server-blue.svg)](https://modelcontextprotocol.io/)
 
 # trackly-cli
@@ -31,11 +31,11 @@ trackly login
 trackly jobs --function product
 ```
 
-> **Prerequisites:** [Node.js 20+](https://nodejs.org/) (LTS recommended). On macOS with the official `.pkg` installer, global npm installs may require `sudo`.
+> **Prerequisites:** [Node.js 20.20+ or 22.22+](https://nodejs.org/) (LTS recommended). On macOS with the official `.pkg` installer, global npm installs may require `sudo`.
 
 ## At a Glance
 
-3,800+ companies | 170K+ jobs | 40+ ATS types | CLI + MCP | 54 local MCP tools
+3,800+ companies | 170K+ jobs | 40+ ATS types | CLI + MCP | 55 local MCP tools
 
 ## CLI Commands
 
@@ -215,6 +215,7 @@ Then use natural language in any of these clients:
 | trackly_record_application_outcomes | Bulk-record up to 20 leased batch outcomes with per-member conflicts |
 | trackly_prepare_resume | Prepare a private expiring resume file for upload |
 | trackly_verify_prepared_resume | Recheck the confirmed resume immediately before attachment |
+| get_more_tools | Report a missing capability so Trackly can improve its MCP surface |
 
 ## Authentication
 
@@ -280,7 +281,7 @@ trackly config --base-url http://127.0.0.1:3000  # Point at a different backend
 | Job search + filters | Yes | Yes | Yes |
 | Apply/save/dismiss | Yes | Yes | Yes |
 | AI-powered search | Yes (trackly ask) | Yes | Yes |
-| MCP integration | Yes (54 local tools) | -- | -- |
+| MCP integration | Yes (55 local tools) | -- | -- |
 | Browser required | No | Yes | No |
 | Best for | Terminal + AI agents | Visual browsing | Custom integrations |
 
@@ -294,7 +295,18 @@ Install trackly-cli (`npm install -g trackly-cli`), authenticate with `trackly l
 
 **What MCP servers exist for job searching?**
 
-trackly-cli includes a built-in MCP server with 54 tools for job search, company lookup, discovery preferences, application tracking, accessible execution and frozen-batch orchestration, profile onboarding, beta evidence, and manual-submit form preparation. Run `trackly mcp` or use `trackly agent setup --client claude`.
+trackly-cli includes a built-in MCP server with 55 tools: the complete Trackly
+job-search and application set plus `get_more_tools`, which lets agents report
+a missing capability. Run `trackly mcp` or use
+`trackly agent setup --client claude`.
+
+MCP usage analytics are on by default and relay through Trackly so the free
+service can be debugged and improved. They exclude résumé text, profile answers,
+demographic or work-authorization answers, and application notes. Turn off future
+collection with **Share usage analytics** in Account Settings. Operators may also
+disable local MCP instrumentation with `TRACKLY_MCP_ANALYTICS_DISABLED=1` (or
+`TRACKLY_MCP_ANALYTICS_ENABLED=0`); the account setting remains authoritative
+for authenticated backend capture.
 
 **How do I use Claude Code for job hunting?**
 

package/bin/trackly

@@ -4,7 +4,6 @@
 const {
   DEFAULT_BASE_URL,
   apiRequest,
-  clearConfig,
   createTracklyAccessError,
   getApiKey,
   getAuthMethod,
@@ -13,6 +12,7 @@ const {
   hasAuth,
   maintenanceOutput,
   loadConfig,
+  removeCredentials,
   saveConfig,
 } = require('../lib/client');
 const { color, isJSON, outputJobs, outputCompanies, outputStats, outputContacts, outputReferralCampaign, outputNetworkBrief, outputCompanyBrief, outputCompanyWorkspace, outputError } = require('../lib/formatters');
@@ -544,7 +544,7 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
 }
 
 async function cmdLogout() {
-  clearConfig();
+  await removeCredentials({ scope: 'all' });
   console.log(color('green', 'Logged out. Credentials cleared.'));
 }
 
@@ -1055,11 +1055,12 @@ async function cmdConfig(args) {
     failNow('Cannot use --base-url and --clear-base-url together.');
   }
 
-  const config = loadConfig();
+  let config = loadConfig();
   let updated = false;
 
   if (args['clear-api-key']) {
-    delete config.apiKey;
+    await removeCredentials({ scope: 'apiKey' });
+    config = loadConfig();
     updated = true;
     console.log(color('green', 'Stored API key cleared.'));
   }
@@ -1123,8 +1124,10 @@ async function cmdVersion() {
   console.log(VERSION);
 }
 
-async function cmdMcp() {
-  await require('../mcp/server').startMcpServer();
+async function cmdMcp(options = {}) {
+  const mcpServer = options.mcpServer || require('../mcp/server');
+  const server = await mcpServer.startMcpServer(options.startOptions);
+  return mcpServer.installMcpSignalHandlers(server, options.signalOptions);
 }
 
 async function cmdAgent(args) {
@@ -1504,6 +1507,7 @@ if (require.main === module) {
 module.exports = {
   COMMAND_FLAGS,
   UNIVERSAL_FLAGS,
+  cmdMcp,
   cmdLogin,
   formatMaintenanceForHuman,
   getPublicConfig,

package/docs/trackly-tools.md

@@ -72,6 +72,7 @@ API-key creation attempts.
 
 ### Available Tools
 
+- **get_more_tools** — Report what the agent wanted to do when no Trackly tool fit, so Trackly can improve its MCP surface. The tool is always available; report delivery is best-effort and occurs only when usage analytics are enabled.
 - **trackly_search_jobs** — Search/filter jobs.
   - `function` (14 values): `product`, `engineering`, `design`, `data`, `marketing`, `sales`, `partnerships`, `finance`, `strategy`, `operations`, `people`, `legal`, `support`, `other`
   - `locationFilter`: pass ONE of

package/lib/client.js

@@ -10,6 +10,7 @@ const { version: PACKAGE_VERSION } = require('../package.json');
 const DEFAULT_CONFIG_DIR = path.join(os.homedir(), '.trackly');
 const DEFAULT_BASE_URL = 'https://closeai.mba';
 const DEFAULT_HTTP_TIMEOUT_MS = 30000;
+const ANALYTICS_PREFERENCE_SYNC_TIMEOUT_MS = 1500;
 const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
 const MAINTENANCE_CODE = 'maintenance_mode';
 const LEGACY_MAINTENANCE_CODE = 'planned_maintenance';
@@ -106,10 +107,180 @@ function saveConfig(config) {
 }
 
 function clearConfig() {
+  let config = {};
+  try {
+    const loaded = loadConfig();
+    if (loaded && typeof loaded === 'object' && !Array.isArray(loaded)) config = loaded;
+  } catch {
+    // Logout must still remove an invalid or unreadable credential file. The
+    // opt-out can be preserved only when the existing config is recoverable.
+  }
+  // A logout clears credentials and endpoint overrides, but the content-free
+  // analytics opt-out must continue suppressing anonymous MCP lifecycle events.
+  if (config.mcpAnalyticsOptOut === true) {
+    try {
+      saveConfig({ mcpAnalyticsOptOut: true });
+      return;
+    } catch {
+      // Preserving the marker is best-effort. A disk/write failure must never
+      // leave credentials behind, so fall through to unlinking the old file.
+    }
+  }
   const { file } = getConfigPaths();
   try { fs.unlinkSync(file); } catch (e) {}
 }
 
+function isRecord(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+function hasAuthenticationInConfig(config) {
+  return Boolean(
+    (process.env.TRACKLY_API_KEY || '').trim()
+    || (isRecord(config) && (config.apiKey || config.token || config.refreshToken))
+  );
+}
+
+function configAfterCredentialRemoval(config, scope) {
+  const next = isRecord(config) ? { ...config } : {};
+  if (scope === 'all' || scope === 'apiKey') delete next.apiKey;
+  if (scope === 'all' || scope === 'oauth') {
+    delete next.token;
+    delete next.refreshToken;
+  }
+  return next;
+}
+
+async function resolveAnalyticsOptOutBeforeCredentialLoss(
+  request = apiRequest,
+  timeoutMs = ANALYTICS_PREFERENCE_SYNC_TIMEOUT_MS
+) {
+  const controller = new AbortController();
+  let timeout;
+  try {
+    const preference = await Promise.race([
+      Promise.resolve().then(() => request(
+        'GET',
+        '/api/jobscout/analytics-preference',
+        null,
+        false,
+        true,
+        null,
+        null,
+        { signal: controller.signal, timeoutMs }
+      )),
+      new Promise((_, reject) => {
+        timeout = setTimeout(() => {
+          controller.abort();
+          reject(new Error('analytics_preference_sync_timeout'));
+        }, timeoutMs);
+      }),
+    ]);
+    if (typeof preference?.shareUsageAnalytics !== 'boolean') {
+      throw new Error('analytics_preference_invalid');
+    }
+    return preference.shareUsageAnalytics === false;
+  } catch {
+    // Fail closed: if the authoritative preference cannot be read before the
+    // final credential disappears, suppress future anonymous MCP capture.
+    return true;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function synchronizeAnalyticsPreferenceBeforeLogout(
+  request = apiRequest,
+  options = {}
+) {
+  const timeoutMs = options.timeoutMs ?? ANALYTICS_PREFERENCE_SYNC_TIMEOUT_MS;
+  try {
+    if (!hasAuth()) return;
+  } catch {
+    // A corrupt or unreadable config must never prevent logout. clearConfig()
+    // owns the best-effort removal path and will run immediately afterward.
+    return;
+  }
+  const optedOut = await resolveAnalyticsOptOutBeforeCredentialLoss(request, timeoutMs);
+  let config = {};
+  try {
+    const loaded = loadConfig();
+    if (loaded && typeof loaded === 'object' && !Array.isArray(loaded)) config = loaded;
+  } catch {
+    // Environment-provided authentication can still make the preference
+    // request valid when the on-disk config is corrupt. Replace only the
+    // recoverable analytics marker and let clearConfig() remove credentials.
+  }
+  if (optedOut) config.mcpAnalyticsOptOut = true;
+  else delete config.mcpAnalyticsOptOut;
+  try {
+    saveConfig(config);
+  } catch {
+    // Analytics synchronization is best-effort and must never block logout.
+  }
+}
+
+async function removeCredentials({
+  scope = 'all',
+  request = apiRequest,
+  timeoutMs = ANALYTICS_PREFERENCE_SYNC_TIMEOUT_MS,
+  preferenceUnavailable = false,
+} = {}) {
+  let config = {};
+  try {
+    const loaded = loadConfig();
+    if (isRecord(loaded)) config = loaded;
+  } catch {
+    // Corrupt or unreadable config still belongs to the best-effort removal
+    // path below. There is no safe credential state to preserve from it.
+  }
+
+  let next = configAfterCredentialRemoval(config, scope);
+  const removesEphemeralCredential = scope === 'all'
+    && Boolean((process.env.TRACKLY_API_KEY || '').trim());
+  const removesFinalCredential = removesEphemeralCredential
+    || (hasAuthenticationInConfig(config) && !hasAuthenticationInConfig(next));
+
+  if (removesFinalCredential) {
+    const optedOut = preferenceUnavailable
+      ? true
+      : await resolveAnalyticsOptOutBeforeCredentialLoss(request, timeoutMs);
+    if (optedOut) next.mcpAnalyticsOptOut = true;
+    else delete next.mcpAnalyticsOptOut;
+  }
+
+  if (scope === 'all') {
+    // Preserve logout's historical behavior of clearing endpoint overrides and
+    // all future config keys, with only the anonymous opt-out allowed through.
+    if (next.mcpAnalyticsOptOut === true) {
+      try {
+        saveConfig({ mcpAnalyticsOptOut: true });
+        return;
+      } catch {
+        // Credential removal wins over marker preservation on write failure.
+      }
+    }
+    const { file } = getConfigPaths();
+    try { fs.unlinkSync(file); } catch (_) {}
+    return;
+  }
+
+  if (Object.keys(next).length === 0) {
+    const { file } = getConfigPaths();
+    try { fs.unlinkSync(file); } catch (_) {}
+    return;
+  }
+  try {
+    saveConfig(next);
+  } catch (error) {
+    // If the surgical rewrite cannot be persisted, do not leave known-invalid
+    // credentials in the old file. Best-effort unlink is the safer fallback.
+    const { file } = getConfigPaths();
+    try { fs.unlinkSync(file); } catch (_) {}
+    throw error;
+  }
+}
+
 // Surgical alternative to clearConfig() for the refresh-failure path. Deletes ONLY the
 // OAuth credentials (token + refreshToken) while preserving everything else on disk
 // (baseUrl, apiKey, timeout overrides, future keys). A refresh token being invalidated
@@ -488,10 +659,10 @@ async function _doRefresh() {
     // Treat as an invalidated session and purge ONLY the OAuth pair so we don't retry on
     // every subsequent 401. Without this, a backend that signals failure via JSON instead of
     // a 4xx status would leave the user stuck in a doomed-refresh loop forever.
-    // Use clearOAuthTokens() — NOT clearConfig() — so the user's baseUrl, apiKey, and any
-    // other persisted settings survive a token expiry. (Bug caught by Cursor Bugbot on
-    // PR #20 post-review: the earlier clearConfig() call silently wiped baseUrl too.)
-    try { clearOAuthTokens(); } catch (_) {}
+    // Use the centralized OAuth-only removal — NOT clearConfig() — so the user's
+    // baseUrl, apiKey, and other persisted settings survive a token expiry while
+    // final-credential loss still preserves the analytics preference safely.
+    try { await removeCredentials({ scope: 'oauth', preferenceUnavailable: true }); } catch (_) {}
   } catch (e) {
     if (isMaintenanceError(e)) {
       throw e;
@@ -503,7 +674,7 @@ async function _doRefresh() {
     // purge the token. Surgical OAuth-only clear preserves baseUrl + apiKey + timeout overrides.
     const status = e && typeof e.status === 'number' ? e.status : null;
     if (status === 400 || status === 401 || status === 403) {
-      try { clearOAuthTokens(); } catch (_) {}
+      try { await removeCredentials({ scope: 'oauth', preferenceUnavailable: true }); } catch (_) {}
     }
   }
   return null;
@@ -516,7 +687,8 @@ function apiRequest(
   skipAuth = false,
   _isRetry = false,
   userAgent = null,
-  additionalHeaders = null
+  additionalHeaders = null,
+  requestOptions = null
 ) {
   return new Promise((resolve, reject) => {
     let url;
@@ -552,7 +724,15 @@ function apiRequest(
       headers['Idempotency-Key'] = idempotencyEntry[1];
     }
     const authMethod = getAuthMethod();
-    const timeoutMs = getRequestTimeoutMs();
+    const requestedTimeoutMs = Number(requestOptions?.timeoutMs);
+    const timeoutMs = Number.isFinite(requestedTimeoutMs) && requestedTimeoutMs > 0
+      ? Math.min(getRequestTimeoutMs(), requestedTimeoutMs)
+      : getRequestTimeoutMs();
+    const signal = requestOptions?.signal;
+    if (signal?.aborted) {
+      reject(new Error('Trackly request aborted.'));
+      return;
+    }
     const hasSensitivePayload = Boolean(data && typeof data === 'object' && 'refreshToken' in data);
 
     try {
@@ -640,7 +820,8 @@ function apiRequest(
                 false,
                 true,
                 userAgent,
-                additionalHeaders
+                additionalHeaders,
+                requestOptions
               );
               return resolve(retried);
             } catch (e) { return reject(e); }
@@ -671,6 +852,9 @@ function apiRequest(
     req.on('timeout', () => {
       req.destroy(new Error(`Trackly request timed out after ${timeoutMs}ms`));
     });
+    const abortRequest = () => req.destroy(new Error('Trackly request aborted.'));
+    signal?.addEventListener('abort', abortRequest, { once: true });
+    req.on('close', () => signal?.removeEventListener('abort', abortRequest));
     req.on('error', reject);
     if (data) req.write(JSON.stringify(data));
     req.end();
@@ -827,7 +1011,9 @@ module.exports = {
   normalizeMaintenance,
   normalizeEndpoint,
   refreshAccessToken,
+  removeCredentials,
   saveConfig,
+  synchronizeAnalyticsPreferenceBeforeLogout,
   CONFIG_DIR: DEFAULT_CONFIG_DIR,
   CONFIG_FILE: path.join(DEFAULT_CONFIG_DIR, 'config.json'),
 };