trackly-cli 0.14.0 → 0.14.1

package/mcp/apply-tools.js

@@ -284,6 +284,7 @@ function registerApplyTools(
       idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined,
     )
   );
+  const discoveredRecoverableSources = new Map();
   const discoveredHandoffBindings = new Map();
   const discoveredHandoffIdsByExecution = new Map();
   server.tool(
@@ -418,9 +419,19 @@ function registerApplyTools(
     'trackly_list_recoverable_apply_executions',
     'List bounded, value-free exact-member recovery candidates after local context loss. Show the stable job identities to the user and obtain explicit confirmation before recovery; never infer or substitute candidates.',
     {},
-    wrapTool(async () => recoverableExecutionsResponseSchema.parse(await applyControlRequest(
-      'GET', '/api/jobscout/apply/executions/recoverable',
-    )), 'Failed to list recoverable apply executions')
+    wrapTool(async () => {
+      const response = recoverableExecutionsResponseSchema.parse(await applyControlRequest(
+        'GET', '/api/jobscout/apply/executions/recoverable',
+      ));
+      discoveredRecoverableSources.clear();
+      for (const source of response.sources) {
+        discoveredRecoverableSources.set(source.sourceExecutionId, {
+          sourceSnapshotHash: source.sourceSnapshotHash,
+          candidateIds: new Set(source.candidates.map(({ candidateId }) => candidateId)),
+        });
+      }
+      return response;
+    }, 'Failed to list recoverable apply executions')
   );
 
   server.tool(
@@ -436,13 +447,23 @@ function registerApplyTools(
       explicitExactSetConfirmation: z.literal(true),
       idempotencyKey: z.string().min(16).max(200).regex(SAFE_IDEMPOTENCY_KEY),
     },
-    wrapTool(async ({ idempotencyKey, ...input }) => validateExactRecoveryResponse(
-      input,
-      exactRecoveryResponseSchema.parse(await applyControlRequest('POST', '/api/jobscout/apply/executions/recover', {
-        mode: 'recover_exact_members',
-        ...input,
-      }, idempotencyKey)),
-    ), 'Failed to recover exact apply members')
+    wrapTool(async ({ idempotencyKey, ...input }) => {
+      const source = discoveredRecoverableSources.get(input.sourceExecutionId);
+      if (
+        !source
+        || source.sourceSnapshotHash !== input.sourceSnapshotHash
+        || input.candidateIds.some((candidateId) => !source.candidateIds.has(candidateId))
+      ) {
+        throw new Error('Exact recovery must use one source and candidate set from the latest discovery response.');
+      }
+      return validateExactRecoveryResponse(
+        input,
+        exactRecoveryResponseSchema.parse(await applyControlRequest('POST', '/api/jobscout/apply/executions/recover', {
+          mode: 'recover_exact_members',
+          ...input,
+        }, idempotencyKey)),
+      );
+    }, 'Failed to recover exact apply members')
   );
 
   server.tool(

package/mcp/server.js

@@ -7,6 +7,7 @@ const { z } = require('zod');
 const { apiRequest, createTracklyAccessError, hasAuth, maintenanceOutput } = require('../lib/client');
 const { version: PACKAGE_VERSION } = require('../package.json');
 const { registerApplyTools } = require('./apply-tools');
+const { configureMcpAnalytics, shutdownMcpAnalytics } = require('./analytics');
 
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
 const MCP_MAINTENANCE_ERROR_CODE = -32002;
@@ -15,6 +16,8 @@ const MCP_AUTH_ERROR_CODE = -32004;
 const AUTH_HINT =
   'Existing members: run `trackly login` or set TRACKLY_API_KEY. ' +
   'New members need a private invite during the limited rollout; request access at https://usetrackly.app/early-access.';
+const MCP_ANALYTICS_CONTEXT_DESCRIPTION =
+  'Briefly explain why this tool helps the current job-search goal. Never include resume text, profile answers, demographic or work-authorization answers, application notes, credentials, or secrets.';
 
 // Mirrors `granola-followup-app/src/services/region-classifier.ts:8` REGION_TAGS.
 // Keep in sync when the backend enum changes.
@@ -48,6 +51,22 @@ const JOB_MODALITIES = ['full_time', 'internship', 'all'];
 // workArrangements query contract and job_postings constraint.
 const WORK_ARRANGEMENTS = ['remote', 'hybrid', 'in_person', 'unspecified'];
 
+const MCP_MISSING_CAPABILITY_VALUES = [
+  'search', 'inspect', 'compare', 'rank', 'recommend', 'track', 'update', 'apply',
+  'submit', 'export', 'notify', 'schedule', 'integrate', 'authenticate', 'debug', 'other',
+];
+const MCP_MISSING_ACTION_VALUES = [
+  'find', 'read', 'compare', 'rank', 'create', 'update', 'delete', 'submit',
+  'export', 'notify', 'schedule', 'connect', 'debug', 'other',
+];
+const MCP_MISSING_RESOURCE_VALUES = [
+  'job', 'company', 'application', 'contact', 'profile', 'resume', 'preference',
+  'analytics', 'account', 'tool', 'other',
+];
+const MCP_MISSING_DESTINATION_VALUES = [
+  'trackly', 'external_site', 'file', 'email', 'calendar', 'crm', 'browser', 'other',
+];
+
 // `sort` enum matches backend handler at `jobscout.ts:3053` — NOT the pre-fix
 // `newest|oldest|company` (backend rejects oldest/company with HTTP 400).
 const SORT_VALUES = ['newest', 'match'];
@@ -169,7 +188,7 @@ function throwMcpResourceError(error) {
 }
 
 function wrapTool(handler, fallbackMessage) {
-  return async (params) => {
+  return async (params, extra) => {
     try {
       if (!hasAuth()) {
         return createAuthErrorResult();
@@ -180,6 +199,11 @@ function wrapTool(handler, fallbackMessage) {
         content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
       };
     } catch (error) {
+      if (extra && typeof extra === 'object') {
+        extra.__mcp_analytics_error = error instanceof Error
+          ? error
+          : new Error(error?.message || fallbackMessage, { cause: error });
+      }
       return createErrorResult(
         error,
         fallbackMessage,
@@ -485,28 +509,119 @@ function createServer() {
     mcpUserAgent: MCP_USER_AGENT,
     throwMcpResourceError,
   });
+
+  server.tool(
+    'get_more_tools',
+    'Report a capability Trackly does not currently provide. Use structured categories; context is optional and is classified but never stored as raw text.',
+    {
+      requestedCapability: z.enum(MCP_MISSING_CAPABILITY_VALUES).optional(),
+      requestedAction: z.enum(MCP_MISSING_ACTION_VALUES).optional(),
+      requestedResource: z.enum(MCP_MISSING_RESOURCE_VALUES).optional(),
+      requestedDestination: z.enum(MCP_MISSING_DESTINATION_VALUES).optional(),
+      context: z.string().optional().describe(MCP_ANALYTICS_CONTEXT_DESCRIPTION),
+    },
+    async () => ({
+      content: [{
+        type: 'text',
+        text: JSON.stringify({ accepted: true, delivery: 'best_effort' }),
+      }],
+    }),
+  );
+
   return server;
 }
 
-async function startMcpServer() {
+// Keep `createServer` a deterministic catalog factory for embedders and
+// contract verification. Analytics belongs at the executable startup boundary,
+// after every source tool has been registered.
+function configureServerAnalytics(server, options = {}) {
+  if (typeof options.configureAnalytics === 'function') {
+    return options.configureAnalytics(server, options.analytics);
+  }
+  return configureMcpAnalytics(server, options.analytics);
+}
+
+async function startMcpServer(options = {}) {
   const server = createServer();
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  configureServerAnalytics(server, options);
+  const transport = options.transport || new StdioServerTransport();
+  const shutdownAnalytics = options.shutdownAnalytics || shutdownMcpAnalytics;
+  const previousOnClose = server.server.onclose;
+  const beginAnalyticsShutdown = () => {
+    try {
+      Promise.resolve(shutdownAnalytics(server)).catch(() => {});
+    } catch {
+      // Analytics teardown must not affect transport teardown.
+    }
+  };
+  server.server.onclose = () => {
+    try {
+      previousOnClose?.();
+    } catch {
+      // Preserve fail-open behavior if an instrumentation callback misbehaves.
+    }
+    beginAnalyticsShutdown();
+  };
+
+  try {
+    await server.connect(transport);
+  } catch (error) {
+    try {
+      await shutdownAnalytics(server);
+    } catch {
+      // Preserve the original transport failure.
+    }
+    throw error;
+  }
   return server;
 }
 
+function installMcpSignalHandlers(server, options = {}) {
+  const signalTarget = options.signalTarget || process;
+  const exit = options.exit || ((code) => process.exit(code));
+  const shutdownAnalytics = options.shutdownAnalytics || shutdownMcpAnalytics;
+  let terminating = false;
+  const handlers = new Map();
+  const cleanup = () => {
+    for (const [signal, handler] of handlers) {
+      signalTarget.removeListener(signal, handler);
+    }
+    handlers.clear();
+  };
+  for (const [signal, exitCode] of [['SIGINT', 130], ['SIGTERM', 143]]) {
+    const handler = () => {
+      if (terminating) return;
+      terminating = true;
+      void Promise.resolve()
+        .then(() => shutdownAnalytics(server))
+        .catch(() => {})
+        .finally(() => {
+          cleanup();
+          exit(exitCode);
+        });
+    };
+    handlers.set(signal, handler);
+    signalTarget.on(signal, handler);
+  }
+  return cleanup;
+}
+
 if (require.main === module) {
-  startMcpServer().catch((error) => {
-    console.error('MCP server error:', error);
-    process.exit(1);
-  });
+  startMcpServer()
+    .then((server) => installMcpSignalHandlers(server))
+    .catch((error) => {
+      console.error('MCP server error:', error);
+      process.exit(1);
+    });
 }
 
 module.exports = {
   AUTH_HINT,
   createAuthErrorResult,
   createErrorResult,
+  configureServerAnalytics,
   createServer,
+  installMcpSignalHandlers,
   startMcpServer,
   throwMcpResourceError,
 };

package/npm-shrinkwrap.json

@@ -1,18 +1,20 @@
 {
   "name": "trackly-cli",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "trackly-cli",
-      "version": "0.14.0",
+      "version": "0.14.1",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.30.0",
+        "@posthog/mcp": "0.11.0",
         "fast-uri": "3.1.5",
         "hono": "4.13.0",
         "ip-address": "10.4.0",
+        "posthog-node": "5.48.1",
         "zod": "^3.23.0"
       },
       "bin": {
@@ -23,7 +25,7 @@
         "acorn": "8.18.0"
       },
       "engines": {
-        "node": ">=20"
+        "node": "^20.20.0 || >=22.22.0"
       }
     },
     "node_modules/@babel/helper-string-parser": {
@@ -128,6 +130,37 @@
         }
       }
     },
+    "node_modules/@posthog/core": {
+      "version": "1.46.9",
+      "resolved": "https://registry.npmjs.org/@posthog/core/-/core-1.46.9.tgz",
+      "integrity": "sha512-EXO6y5ih+jBkTCpUCuYgQmajuDZuvy6vMvflkub6pLQyi0GPlCPWVSvZZkOeQw9e2MxoD5GteeGCt9R8+UJ/yQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@posthog/types": "^1.402.2"
+      }
+    },
+    "node_modules/@posthog/mcp": {
+      "version": "0.11.0",
+      "resolved": "https://registry.npmjs.org/@posthog/mcp/-/mcp-0.11.0.tgz",
+      "integrity": "sha512-wxvIvx2/MuXqDH9Zy99hqop6Hyhymn8aoh7e7wYOH3AUdeohZhom2W8E2UDgBO63eR/vm8QGH/fidyA6H+KNyA==",
+      "license": "MIT",
+      "dependencies": {
+        "@posthog/core": "^1.46.9"
+      },
+      "engines": {
+        "node": "^20.20.0 || >=22.22.0"
+      },
+      "peerDependencies": {
+        "@modelcontextprotocol/sdk": ">=1.26.0",
+        "posthog-node": "^5.0.0"
+      }
+    },
+    "node_modules/@posthog/types": {
+      "version": "1.402.2",
+      "resolved": "https://registry.npmjs.org/@posthog/types/-/types-1.402.2.tgz",
+      "integrity": "sha512-ZZTiS4dLwF4/D0YTzS3gGSLFnhuNOY5yu4d9VGS9trGe5GW6FjIXo20p18K5BPW2RZSYSld8sdnSAY3AUXleUQ==",
+      "license": "MIT"
+    },
     "node_modules/accepts": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz",
@@ -909,6 +942,26 @@
         "node": ">=16.20.0"
       }
     },
+    "node_modules/posthog-node": {
+      "version": "5.48.1",
+      "resolved": "https://registry.npmjs.org/posthog-node/-/posthog-node-5.48.1.tgz",
+      "integrity": "sha512-BxLX2SqGEQhPqCPTalpyo0RRv1NMbf7UaN7q9d/ED77ksD6XOmE7ko2vIKO8F0zPL1NtKxIi+DYXap9lvR0RaA==",
+      "license": "MIT",
+      "dependencies": {
+        "@posthog/core": "^1.46.9"
+      },
+      "engines": {
+        "node": "^20.20.0 || >=22.22.0"
+      },
+      "peerDependencies": {
+        "rxjs": "^7.0.0"
+      },
+      "peerDependenciesMeta": {
+        "rxjs": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/proxy-addr": {
       "version": "2.0.7",
       "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "mcpName": "io.github.trackly-app/trackly",
   "description": "AI job search CLI + hosted MCP server with OAuth. 170K+ jobs, 3,800+ companies, 40+ ATS. Works with Claude, ChatGPT, Cursor, Windsurf, Codex via hosted streamable-http or local stdio.",
   "bin": {
@@ -63,13 +63,15 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
+    "@posthog/mcp": "0.11.0",
     "fast-uri": "3.1.5",
     "hono": "4.13.0",
     "ip-address": "10.4.0",
+    "posthog-node": "5.48.1",
     "zod": "^3.23.0"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^20.20.0 || >=22.22.0"
   },
   "overrides": {
     "@hono/node-server": "2.0.12",

package/server.json

@@ -17,12 +17,12 @@
       ]
     }
   ],
-  "version": "0.14.0",
+  "version": "0.14.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.14.0",
+      "version": "0.14.1",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {