trackly-cli 0.21.2 → 0.22.0

package/README.md

@@ -210,7 +210,7 @@ The hosted server omits those four and adds `trackly_chat`, for 55 hosted tools.
 | Tool | Description |
 |------|-------------|
 | trackly_search_jobs | Search by roles, regions, states/provinces, internship level, favorites, recency, annual USD salary floor, sponsorship, work arrangement, and pipeline status |
-| trackly_get_job | Get full details for a specific job |
+| trackly_get_job | Get details by Trackly ID, with availability and retry guidance |
 | trackly_search_companies | Semantic company search |
 | trackly_list_companies | List all tracked companies |
 | trackly_get_stats | Job tracker metrics and status counts |
@@ -218,7 +218,7 @@ The hosted server omits those four and adds `trackly_chat`, for 55 hosted tools.
 | trackly_update_experience_limits | Atomically replace role-specific limits on a job's stated minimum years |
 | trackly_update_status | Mark jobs as applied, saved, or dismissed |
 | trackly_ask | Natural language job search (20/day) |
-| trackly_get_job_brief | Get network brief for a job (company signal, top contact, actions) |
+| trackly_get_job_brief | Get a network brief, with availability and retry guidance |
 | trackly_contacts_at_company | Search contacts at a specific company |
 | trackly_get_company_workspace | Full company workspace (jobs, contacts, hiring managers, campaigns) |
 | trackly_request_company | Request a company be added to Trackly (rate-limited to 5 pending) |

package/docs/solutions/integration-issues/job-lookups-need-availability-and-retry-guidance.md

@@ -0,0 +1,44 @@
+---
+title: Job lookups need availability and retry guidance
+date: 2026-10-20
+category: integration-issues
+module: MCP job lookups
+problem_type: integration_issue
+severity: medium
+symptoms:
+  - Expected missing postings appear as tool exceptions
+  - Agents repeat unavailable job lookups without a useful next action
+root_cause: missing_error_handling
+resolution_type: code_fix
+applies_when:
+  - Changing job detail or brief MCP response handling
+tags: [mcp, jobs, availability, errors, retry]
+---
+
+A generic HTTP error wrapper cannot decide whether a 404 means an unavailable
+posting or a broken route. Normalize only the job endpoint's recognized missing
+envelopes (including their explicit failure flag) and availability flags. Preserve unrelated 404s and genuine
+service failures as errors. An absent flag is unknown, never evidence of closure.
+
+Keep this decision inside the job tools. Generic HTTP clients and Apply mutations
+have different error and retry contracts. Return ordinary structured results for
+expected unavailability, with a fixed explanation, retryable=false and another
+search as the next step. Closed briefs retain allowed context while omitting obsolete recommended motions and application actions.
+For real errors, expose a closed category and bounded retry guidance that honors longer valid API delays and HTTP Retry-After headers, while
+retaining the original failure only for the existing content-free telemetry path.
+
+Test through a real MCP client and local HTTP fixture, including recognized job
+404s, unrelated route 404s, closed/unknown availability, auth, rate limits and
+server failures. Check actual network-request counts and diagnostic events;
+expected unavailable results must not emit exceptions. Validate numeric internal
+IDs before HTTP, and keep SDK validation failures separate from endpoint errors.
+
+Sanitized stack coordinates alone do not identify a backend response or rejected
+argument. Reproduce emitted source using the exact build options and version,
+and distinguish the throw-site proof from synthetic input examples. Never report
+a fixture's invalid ID as the recovered cause of a historical incident.
+
+Carry Retry-After metadata through the HTTP client without adding retries. Parse
+only positive safe integer seconds or a standard HTTP date, choose the longer
+body/header delay, and preserve it when applying transient access guidance. Test
+these failure branches; healthy responses never exercise them.

package/docs/trackly-tools.md

@@ -100,7 +100,7 @@ API-key creation attempts.
 Example: `{"jobFunctions":["finance","partnerships"],"region":["us","europe"],"sponsorship":"exclude_no","postedWithinDays":7,"limit":20}`.
 The local package and hosted service have separate release lifecycles. Refresh the client's tool discovery after upgrading or reconnecting and use only parameters its current schema advertises.
 
-- **trackly_get_job** — Get full job details by ID
+- **trackly_get_job** — Get full job details by positive numeric Trackly ID from search or the saved queue. Employer requisition IDs and URLs are not accepted.
 - **trackly_search_companies** — Semantic company search
 - **trackly_list_companies** — List all tracked companies with job counts
 - **trackly_get_stats** — Job tracker metrics dashboard
@@ -112,7 +112,11 @@ The local package and hosted service have separate release lifecycles. Refresh t
   - When server-side enforcement is active, a job remains visible when its stated minimum is less than or equal to that role's limit. Jobs with no stated minimum remain visible.
 - **trackly_update_status** — Mark a job as applied, saved, or dismissed
 - **trackly_ask** — Natural language job search (20/day limit)
-- **trackly_get_job_brief** — Get network brief for a job (company signal, top contact, actions)
+- **trackly_get_job_brief** — Get network brief for a positive numeric Trackly job ID (company signal, top contact, actions).
+
+Both job tools return JSON text and matching `structuredContent`. A recognized missing or removed posting, or an explicitly inactive posting, returns `availability: "unavailable"`, a reason, `retryable: false`, and a `nextStep` directing the agent to search for current openings. This is a normal tool result. Closed briefs retain their allowed stored company and role context, but omit stale recommended motions and application actions. A missing availability flag means unknown, not closed; detecting closed briefs requires a backend that supplies that flag.
+
+Actual failures retain `isError: true`, HTTP status when available, a closed `category`, `retryable`, `maxRetries`, and a next step. Categories are `authentication`, `authorization`, `validation`, `not_found`, `conflict`, `rate_limit`, `timeout`, `server`, `network`, `maintenance`, `access`, or `unknown`. Transient read failures permit one retry after `retryAfterSeconds`, honoring the longer valid API body or HTTP `Retry-After` delay (seconds or HTTP date); the tools add no automatic retry loop. The `nextStep.message` always explains what to do; `nextStep.tool` is present when a corresponding MCP tool exists. Authentication and invalid-input failures require a corrected request first. A route or unrelated dependency 404 remains an error. Invalid argument shapes are rejected by MCP schema validation before any API call; correct the arguments before retrying.
 - **trackly_contacts_at_company** — Search contacts at a specific company
 - **trackly_get_company_workspace** — Get full company workspace (jobs, contacts, hiring managers, campaigns)
 - **trackly_request_company** — Request that a company be added to Trackly's tracked companies. Rate-limited to 5 pending requests per user. Parameters: `companyName` (required), `companyUrl` (optional), `notes` (optional).

package/lib/client.js

@@ -843,15 +843,17 @@ function apiRequest(
             headers: res.headers,
           });
           if (maintenanceError) return reject(maintenanceError);
+          const retryHeader = res.headers?.['retry-after'];
+          const retryMetadata = typeof retryHeader === 'string' ? { retryAfterHeader: retryHeader } : {};
           const accessError = createTracklyAccessError(json, res.statusCode);
-          if (accessError) return reject(accessError);
+          if (accessError) return reject({ ...accessError, ...retryMetadata });
           // Spread `json` FIRST so the HTTP statusCode always wins. A backend that returns
           // `{"status": "error"}` in the body would otherwise clobber the numeric status with
           // a string, breaking downstream branches like `typeof e.status === 'number'` in
           // refreshAccessToken — which would silently skip the 400/401/403 token-clear and
           // leave dead refresh tokens on disk. (Cursor Bugbot finding #5 on PR #20.)
           const record = json && typeof json === 'object' ? json : {};
-          reject({ ...record, status: res.statusCode });
+          reject({ ...record, status: res.statusCode, ...retryMetadata });
         } else {
           resolve(json);
         }

package/lib/job-result.js

@@ -0,0 +1,109 @@
+'use strict';
+
+const NEXT_SEARCH = {
+  tool: 'trackly_search_jobs',
+  message: 'Search for current openings or use another ID from search or your saved queue. Do not retry this job ID.',
+};
+
+function storedBrief(brief) {
+  const { recommendedMotion, nextActions, actions, ...stored } = brief;
+  return stored;
+}
+
+function unavailableJob(jobId, reason, result = {}) {
+  return {
+    ...(result.job ? { job: result.job }
+      : result.brief ? { brief: storedBrief(result.brief) } : storedBrief(result)),
+    success: true,
+    availability: 'unavailable',
+    reason,
+    jobId,
+    message: 'This job is no longer available.',
+    retryable: false,
+    maxRetries: 0,
+    nextStep: { ...NEXT_SEARCH },
+    // Stored context remains useful; stale networking recommendations do not.
+  };
+}
+
+function normalizeJobResult(result, jobId) {
+  const posting = result?.job || result?.brief || result;
+  // isActive is authoritative. Some older projections collapse unknown into
+  // active=false, so never let that legacy flag override an explicit unknown.
+  const active = posting && Object.hasOwn(posting, 'isActive') ? posting.isActive : posting?.active;
+  return active === false
+    ? unavailableJob(jobId, 'closed', result)
+    : result;
+}
+
+function unavailableJobFromError(error, jobId) {
+  if (error?.status !== 404 && error?.status !== 410) return null;
+  const code = error.code || error.error;
+  const reason = code === 'job_not_found' ? 'not_found'
+    : code === 'job_removed' ? 'removed'
+      : code === 'job_closed' ? 'closed' : null;
+  if (reason) return unavailableJob(jobId, reason);
+  // These are the two existing job-endpoint envelopes. A missing route, brief
+  // dependency or unrelated resource must remain an error even at HTTP 404.
+  if (error.status === 404 && error.success === false && (
+    error.error === 'Job not found' || error.error === `Job ${jobId} not found`
+  )) return unavailableJob(jobId, 'not_found');
+  return null;
+}
+
+function retryDelayFromHeader(value) {
+  if (typeof value !== 'string') return 0;
+  const text = value.trim();
+  let seconds = 0;
+  if (/^\d+$/.test(text)) seconds = Number(text);
+  else if (/^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(text)) {
+    seconds = Math.ceil((Date.parse(text) - Date.now()) / 1000);
+  }
+  return Number.isSafeInteger(seconds) && seconds > 0 ? seconds : 0;
+}
+
+function jobFailureGuidance(error) {
+  const status = error?.status;
+  let category = 'unknown';
+  if (Number.isInteger(status)) {
+    if (status === 401) category = 'authentication';
+    else if (status === 403) category = 'authorization';
+    else if ([400, 413, 422].includes(status)) category = 'validation';
+    else if ([404, 410].includes(status)) category = 'not_found';
+    else if (status === 408) category = 'timeout';
+    else if (status === 409) category = 'conflict';
+    else if (status === 429) category = 'rate_limit';
+    else if (status >= 500 && status <= 599) category = 'server';
+  } else if (error?.code === 'ETIMEDOUT' || /timed out/i.test(error?.message || '')) {
+    category = 'timeout';
+  } else if (['ECONNRESET', 'ECONNREFUSED', 'ENOTFOUND', 'EAI_AGAIN', 'EPIPE'].includes(error?.code)) {
+    category = 'network';
+  }
+  const retryable = ['rate_limit', 'timeout', 'server', 'network'].includes(category);
+  const declaredDelay = error?.retryAfterSeconds;
+  const retryAfterSeconds = Math.max(category === 'rate_limit' ? 60 : 5,
+    retryDelayFromHeader(error?.retryAfterHeader),
+    Number.isSafeInteger(declaredDelay) && declaredDelay > 0 ? declaredDelay : 0);
+  const messages = {
+    authentication: 'Sign in again with trackly login or refresh the configured credential before trying again. Do not retry unchanged credentials.',
+    authorization: 'Check account access before trying again. Repeating the same request will not grant access.',
+    validation: 'Use the positive numeric Trackly job ID returned by search or your saved queue, then correct the request. Do not retry unchanged arguments.',
+    not_found: 'The requested route or a brief dependency was not found. Search for a current posting or report the tool failure. Do not retry unchanged.',
+    conflict: 'Refresh the job state and resolve the conflict before trying again. Do not retry unchanged.',
+    rate_limit: 'Wait for the rate limit to reset before retrying this read once. Do not retry in a loop.',
+    timeout: 'The read timed out. Wait briefly, then retry once. If it still fails, stop and try later.',
+    server: 'Trackly could not complete this read. Wait briefly, then retry once. If it still fails, stop and try later.',
+    network: 'Check the connection, then retry this read once. If it still fails, stop and try later.',
+    unknown: 'The failure could not be classified. Check the request or report the tool failure. Do not retry unchanged.',
+  };
+  return {
+    category,
+    retryable,
+    maxRetries: retryable ? 1 : 0,
+    ...(retryable ? { retryAfterSeconds } : {}),
+    error: 'Unable to retrieve this job right now.',
+    nextStep: { message: messages[category] },
+  };
+}
+
+module.exports = { normalizeJobResult, unavailableJobFromError, jobFailureGuidance };

package/mcp/server.js

@@ -9,6 +9,7 @@ const { version: PACKAGE_VERSION } = require('../package.json');
 const APPLY_CONTRACT = require('../contracts/trackly-apply-tools.json');
 const { registerApplyTools } = require('./apply-tools');
 const { configureMcpAnalytics, shutdownMcpAnalytics } = require('./analytics');
+const { normalizeJobResult, unavailableJobFromError, jobFailureGuidance } = require('../lib/job-result');
 
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
 const MCP_SHUTDOWN_TIMEOUT_MS = 2_000;
@@ -219,18 +220,38 @@ function throwMcpResourceError(error) {
   throw error;
 }
 
-function wrapTool(handler, fallbackMessage) {
+function wrapTool(handler, fallbackMessage, jobIdKey) {
   return async (params, extra) => {
+    const successResult = (value) => ({
+      content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+      ...(jobIdKey ? { structuredContent: value } : {}),
+    });
+    const failureResult = (error) => {
+      const result = createErrorResult(error, fallbackMessage, error?.status === 401 ? { hint: AUTH_HINT } : {});
+      if (!jobIdKey) return result;
+      const payload = JSON.parse(result.content[0].text);
+      const guidance = jobFailureGuidance(error);
+      if (payload.code === 'maintenance_mode' || createTracklyAccessError(error, error?.status)) {
+        guidance.category = payload.code === 'maintenance_mode' ? 'maintenance' : 'access';
+        guidance.error = payload.error;
+        guidance.retryable = payload.retryable;
+        guidance.maxRetries = payload.retryable ? 1 : 0;
+        if (!payload.retryable) delete guidance.retryAfterSeconds;
+        guidance.nextStep = { message: payload.guidance || payload.message || payload.error };
+      }
+      if (error?.status === 429) delete payload.hint;
+      return { ...result, ...successResult({ ...payload, ...guidance }) };
+    };
     try {
       if (!hasAuth()) {
-        return createAuthErrorResult();
+        return jobIdKey ? failureResult({ message: 'Not authenticated', status: 401 }) : createAuthErrorResult();
       }
 
       const result = await handler(params);
-      return {
-        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-      };
+      return successResult(jobIdKey ? normalizeJobResult(result, params[jobIdKey]) : result);
     } catch (error) {
+      const unavailable = jobIdKey && unavailableJobFromError(error, params[jobIdKey]);
+      if (unavailable) return successResult(unavailable);
       if (extra && typeof extra === 'object') {
         const statusPrefix = Number.isInteger(error?.status) ? `HTTP ${error.status}: ` : '';
         extra.__mcp_analytics_error = error instanceof Error
@@ -240,11 +261,7 @@ function wrapTool(handler, fallbackMessage) {
             { cause: error },
           );
       }
-      return createErrorResult(
-        error,
-        fallbackMessage,
-        error?.status === 401 ? { hint: AUTH_HINT } : {}
-      );
+      return failureResult(error);
     }
   };
 }
@@ -370,13 +387,13 @@ function createServer() {
 
   server.tool(
     'trackly_get_job',
-    'Get full details for a specific job posting including description.',
+    'Get full details for a Trackly job ID returned by search or your saved queue. Missing or closed postings return availability=unavailable with retryable=false and a next step; do not retry that ID. Failures include a category and retry guidance.',
     {
-      id: z.number().describe('Job posting ID'),
+      id: z.number().int().positive().safe().describe('Positive numeric Trackly job ID from trackly_search_jobs or your saved queue, not an employer requisition ID or URL. Correct invalid arguments before retrying.'),
     },
     wrapTool(async ({ id }) => {
       return apiRequest('GET', `/api/jobscout/jobs/${id}`, null, false, false, MCP_USER_AGENT);
-    }, 'Failed to fetch job')
+    }, 'Failed to fetch job', 'id')
   );
 
   server.tool(
@@ -532,13 +549,13 @@ function createServer() {
 
   server.tool(
     'trackly_get_job_brief',
-    'Get a network brief for a specific job. Returns company signal, recommended motion, top contact, and suggested actions.',
+    'Get a network brief for a Trackly job ID, including company signal, recommended motion, top contact and suggested actions. Missing or closed postings return availability=unavailable with retryable=false; search for another opening. Failures include a category and retry guidance.',
     {
-      jobId: z.number().describe('Job posting ID'),
+      jobId: z.number().int().positive().safe().describe('Positive numeric Trackly job ID from trackly_search_jobs or your saved queue, not an employer requisition ID or URL. Correct invalid arguments before retrying.'),
     },
     wrapTool(async ({ jobId }) => {
       return apiRequest('GET', `/api/jobscout/jobs/${jobId}/network-brief`, null, false, false, MCP_USER_AGENT);
-    }, 'Failed to fetch network brief')
+    }, 'Failed to fetch network brief', 'jobId')
   );
 
   server.tool(

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "trackly-cli",
-  "version": "0.21.2",
+  "version": "0.22.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "trackly-cli",
-      "version": "0.21.2",
+      "version": "0.22.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "1.32.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.21.2",
+  "version": "0.22.0",
   "mcpName": "io.github.trackly-app/trackly",
   "description": "Search 250K+ jobs across 5,400+ companies with the Trackly CLI and MCP server for Claude, ChatGPT, Codex and Cursor. Filter by role, location, salary and sponsorship; track jobs and prepare applications.",
   "bin": {

package/server.json

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