trackly-cli 0.18.4 → 0.18.6

package/README.md

@@ -7,7 +7,7 @@
 
 The only job tracking CLI built for AI agents.
 
-Search 170,000+ jobs across Thousands of companies and 40+ ATS types. Track applications, get AI-powered recommendations, and manage your job search -- from the terminal or through Claude, ChatGPT, Cursor, and other MCP-compatible AI agents.
+Search 250K+ jobs across 5,400+ companies and 40+ ATS types. Track applications, get AI-powered recommendations, and manage your job search -- from the terminal or through Claude, ChatGPT, Cursor, and other MCP-compatible AI agents.
 
 ## Two ways to connect
 
@@ -35,7 +35,7 @@ trackly jobs --function product
 
 ## At a Glance
 
-Thousands of companies | Thousands of jobs | 40+ ATS types | CLI + MCP | 58 local MCP tools
+5,400+ companies | 250K+ jobs | 40+ ATS types | CLI + MCP | 58 local + 55 hosted MCP tools
 
 ## CLI Commands
 
@@ -97,6 +97,21 @@ https://mcp.usetrackly.app/api/mcp
 
 Sign in with Google when prompted. [Full visual guide →](https://usetrackly.app/connector)
 
+Claude Code can use the same hosted server over OAuth:
+
+```bash
+claude mcp add --transport http trackly https://mcp.usetrackly.app/api/mcp
+```
+
+OAuth sign-in is the default for every client. An API key is optional and only
+needed for headless clients that cannot complete an interactive sign-in: send
+`Authorization: Bearer trk_...` with a key from **Settings → API Keys**.
+
+Remote connections get 55 hosted tools. They share the search, company, status, and
+Apply tools with the local server and add `trackly_chat`; the 4 local-only
+tools listed below are not available remotely. Hosted setup and tool details
+are at [usetrackly.app/connector](https://usetrackly.app/connector).
+
 ### Local (CLI via stdio, for Cursor / Windsurf / Claude Code)
 
 For agent-assisted form filling on macOS, install the public skill and local MCP together:
@@ -124,7 +139,7 @@ claude mcp add-json --scope user trackly '{"command":"trackly","args":["mcp"]}'
 
 #### Claude Code manual config
 
-Add to `~/.claude/settings.json`:
+Add to a project-scoped `.mcp.json`:
 
 ```json
 {
@@ -160,6 +175,12 @@ Then use natural language in any of these clients:
 
 ## MCP Tools Reference
 
+The local stdio server (`trackly mcp`) registers the 58 tools below. Four are
+local-only because they run their checks on your machine:
+`trackly_diagnose_local_path`, `trackly_lint_application_text`,
+`trackly_validate_apply_resume_upload`, and `trackly_validate_apply_tab_keep_set`.
+The hosted server omits those four and adds `trackly_chat`, for 55 hosted tools.
+
 | Tool | Description |
 |------|-------------|
 | trackly_search_jobs | Search and filter jobs by function, company, region, employment type, work arrangement, visa sponsorship, and status |
@@ -318,7 +339,7 @@ Add trackly as an MCP server in Claude Code. Then ask questions naturally: "Find
 
 **What are the best CLI tools for job search?**
 
-trackly-cli is the first dedicated job tracking CLI. It provides direct terminal access to 170,000+ job postings across Thousands of companies, with filters for job function, location, and work modality. It also integrates with AI agents via the Model Context Protocol (MCP).
+trackly-cli is the first dedicated job tracking CLI. It provides direct terminal access to 250K+ jobs across 5,400+ companies, with filters for job function, location, and work modality. It also integrates with AI agents via the Model Context Protocol (MCP).
 
 ## Security
 

package/contracts/trackly-apply-contract-history.json

@@ -38,5 +38,14 @@
   },
   "3.8.1": {
     "contractSha256": "49028b8a8e1d75a8db6e54dd91001195f8a2e50b1f0ff6554750bd243dde4c6e"
+  },
+  "3.9.0": {
+    "contractSha256": "1d6afc41df1b72ec6eb340df8c080b7dfac2843e9fd6d9d9795d8de6f413559a"
+  },
+  "3.9.1": {
+    "contractSha256": "26dfb900c2782a5437475c06d2e30c718dee4781daa938bc4fa3b6a03a505323"
+  },
+  "3.9.2": {
+    "contractSha256": "d3a82489330d0b0062a1baec8d226b510628accc434731136dca9951ec64c302"
   }
 }

package/contracts/trackly-apply-tools.json

@@ -1,20 +1,21 @@
 {
-  "contractVersion": "3.8.1",
+  "contractVersion": "3.9.2",
   "constants": {
     "applyExecutionProtocolVersion": "trackly-apply-execution/v3",
     "applyAccessKnowledgeOrderingVersion": 3,
     "applyExecutionMaxTarget": 20,
+    "applyAdapterCodes": ["greenhouse:1","ashby:1","lever:1","workday:1","oracle_hcm:1","successfactors:1","icims:1","phenom:1","eightfold:1","jibe:1","avature:1","smartrecruiters:1","workable:1","bamboohr:1","recruitee:1","jobvite:1","teamtailor:1","comeet:1","rippling:1","gem:1","workatastartup:1","jazzhr:1","breezyhr:1","freshteam:1","personio:1","pinpoint:1","zohorecruit:1","gusto:1","hibob:1","paylocity:1","paycor:1","adp:1","linkedin_easy_apply:1","generic_web_form:1"],
     "applyScenarioCodes": ["browser_reclaim", "resume_upload", "resume_parser_recheck", "semantic_boolean_commit", "custom_select_commit", "multi_step_navigation", "free_text_voice", "required_error_sweep", "final_consent", "handoff_reclaim", "critical_contact_integrity", "manual_submit_boundary", "job_identity_match"],
     "applyBrowserSurfaces": ["codex_in_app", "chrome_extension", "claude_in_chrome"],
-    "applyCheckpointActionCodes": ["answer/unknown", "auth/sign_in", "auth/account_creation", "auth/otp", "captcha/before_form", "captcha/at_submit", "artifact/upload_required", "legal/decision_required", "consent/decision_required", "review/manual_submit", "trust/origin_mismatch", "observability/unverifiable_state"],
-    "applyCheckpointContinuationByAction": {"answer/unknown": true, "auth/sign_in": true, "auth/account_creation": true, "auth/otp": true, "captcha/before_form": true, "captcha/at_submit": false, "artifact/upload_required": true, "legal/decision_required": true, "consent/decision_required": true, "review/manual_submit": false, "trust/origin_mismatch": false, "observability/unverifiable_state": false},
-    "applyCheckpointLifecycleByAction": {"answer/unknown": "needs_input", "auth/sign_in": "needs_input", "auth/account_creation": "needs_input", "auth/otp": "needs_input", "captcha/before_form": "needs_input", "captcha/at_submit": "review_ready", "artifact/upload_required": "needs_input", "legal/decision_required": "needs_input", "consent/decision_required": "needs_input", "review/manual_submit": "review_ready", "trust/origin_mismatch": "blocked", "observability/unverifiable_state": "blocked"},
-    "applyCheckpointQuestionPacketByAction": {"answer/unknown": true, "auth/sign_in": false, "auth/account_creation": false, "auth/otp": false, "captcha/before_form": false, "captcha/at_submit": false, "artifact/upload_required": false, "legal/decision_required": true, "consent/decision_required": true, "review/manual_submit": false, "trust/origin_mismatch": false, "observability/unverifiable_state": false},
+    "applyCheckpointActionCodes": ["answer/unknown", "auth/sign_in", "auth/account_creation", "auth/otp", "captcha/before_form", "captcha/at_submit", "artifact/upload_required", "legal/decision_required", "consent/decision_required", "review/manual_submit", "trust/origin_mismatch", "observability/unverifiable_state", "client/upgrade_required"],
+    "applyCheckpointContinuationByAction": {"answer/unknown": true, "auth/sign_in": true, "auth/account_creation": true, "auth/otp": true, "captcha/before_form": true, "captcha/at_submit": false, "artifact/upload_required": true, "legal/decision_required": true, "consent/decision_required": true, "review/manual_submit": false, "trust/origin_mismatch": false, "observability/unverifiable_state": false, "client/upgrade_required": false},
+    "applyCheckpointLifecycleByAction": {"answer/unknown": "needs_input", "auth/sign_in": "needs_input", "auth/account_creation": "needs_input", "auth/otp": "needs_input", "captcha/before_form": "needs_input", "captcha/at_submit": "review_ready", "artifact/upload_required": "needs_input", "legal/decision_required": "needs_input", "consent/decision_required": "needs_input", "review/manual_submit": "review_ready", "trust/origin_mismatch": "blocked", "observability/unverifiable_state": "blocked", "client/upgrade_required": "blocked"},
+    "applyCheckpointQuestionPacketByAction": {"answer/unknown": true, "auth/sign_in": false, "auth/account_creation": false, "auth/otp": false, "captcha/before_form": false, "captcha/at_submit": false, "artifact/upload_required": false, "legal/decision_required": true, "consent/decision_required": true, "review/manual_submit": false, "trust/origin_mismatch": false, "observability/unverifiable_state": false, "client/upgrade_required": false},
     "applyAccessClassifications": ["accessible", "authentication_required", "account_creation_required", "otp_required", "captcha_before_form", "captcha_at_submit", "manual_only", "unknown_unobservable"],
     "applyExecutionDispositionSources": ["live_probe"],
     "applyProbeCleanupPreferences": ["never", "submitted_only", "submitted_and_probe_blockers"],
     "applyExecutionStopReasonCodes": ["user_requested", "target_changed", "session_ended", "execution_restarted", "operator_stop"],
-    "applyBatchConflictCodes": ["state_changed", "lease_unavailable", "idempotency_key_reused", "fixed_batch_not_found", "execution_child_batch", "fixed_batch_not_active", "fixed_batch_revision_changed", "submission_in_progress", "attestation_dependencies_changed", "legacy_fixed_batch_active", "dedicated_recovery_required", "recovery_migration_not_ready", "access_deferment_limit_reached", "access_deferments_active"],
+    "applyBatchConflictCodes": ["state_changed", "client_upgrade_required", "lease_unavailable", "idempotency_key_reused", "fixed_batch_not_found", "execution_child_batch", "fixed_batch_not_active", "fixed_batch_revision_changed", "submission_in_progress", "attestation_dependencies_changed", "legacy_fixed_batch_active", "dedicated_recovery_required", "recovery_migration_not_ready", "access_deferment_limit_reached", "access_deferments_active"],
     "fixedApplyBatchCancelReasonCodes": ["user_requested_restart"],
     "applyCheckpointPacketPhases": ["first_pass", "delta"],
     "applySurfaceBindingReasons": ["initial_binding", "recovery_binding"],

package/lib/client.js

@@ -6,6 +6,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const { version: PACKAGE_VERSION } = require('../package.json');
+const APPLY_CONTRACT = require('../contracts/trackly-apply-tools.json');
 
 const DEFAULT_CONFIG_DIR = path.join(os.homedir(), '.trackly');
 const DEFAULT_BASE_URL = 'https://closeai.mba';
@@ -712,8 +713,15 @@ function apiRequest(
         ? Object.entries(additionalHeaders)
         : [];
       const idempotencyEntry = entries.find(([name]) => name.toLowerCase() === 'idempotency-key');
+      const startEntry = entries.find(([name]) => name.toLowerCase() === 'x-trackly-apply-start-contract');
+      const validStartHeader = startEntry
+        && method === 'POST'
+        && (endpoint === '/api/jobscout/apply/executions'
+          || endpoint === '/api/jobscout/apply/executions/recover')
+        && startEntry[1] === APPLY_CONTRACT.contractVersion;
       if (
-        entries.length !== 1
+        entries.length !== (startEntry ? 2 : 1)
+        || (startEntry && !validStartHeader)
         || !idempotencyEntry
         || typeof idempotencyEntry[1] !== 'string'
         || !/^[\x20-\x7e]{16,200}$/.test(idempotencyEntry[1])
@@ -722,6 +730,7 @@ function apiRequest(
         return;
       }
       headers['Idempotency-Key'] = idempotencyEntry[1];
+      if (startEntry) headers['X-Trackly-Apply-Start-Contract'] = startEntry[1];
     }
     const authMethod = getAuthMethod();
     const requestedTimeoutMs = Number(requestOptions?.timeoutMs);

package/mcp/apply-tools.js

@@ -810,7 +810,12 @@ function registerApplyTools(
       false,
       false,
       MCP_USER_AGENT,
-      idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : undefined,
+      idempotencyKey ? {
+        'Idempotency-Key': idempotencyKey,
+        ...(method === 'POST' && (path === '/api/jobscout/apply/executions'
+          || path === '/api/jobscout/apply/executions/recover')
+          ? { 'X-Trackly-Apply-Start-Contract': APPLY_CONTRACT.contractVersion } : {}),
+      } : undefined,
     )
   );
   const discoveredRecoverableSources = new Map();
@@ -1976,7 +1981,7 @@ function registerApplyTools(
       role: 'user',
       content: {
         type: 'text',
-        text: 'Protocol 3.7.0 reliability gate for new work: require MCP contract 3.8.1 and skill 4.8.0. Consume the exact proposedWave with frozen accessKnowledge before opening any browser; same-key advance replay returns identical member IDs, order, and rationale. When nextAction is access_review, including ordinary OPEN or neutral proposals, display the exact access-review receipt and do not report exhaustion. For a nonempty proposal, obtain explicit approval for the unchanged ordered job IDs and server approval hash before probing. For an all-deferred or recovery-blocked proposal with zero members, show the deferred count and stable job/company/provider deferment IDs, offer clear-deferment only for explicitly returned IDs, stop, or expiry, and never send an empty approval. Defer or clear only through jobId-scoped job, company, or provider tools; provider scope applies across companies until explicitly cleared. Never submit provider names, URLs, or raw chat. After complete local context loss, list bounded recovery candidates, obtain explicit confirmation of the exact set, and recover only that set. An active personal deferment blocks exact recovery until cleared. Treat tab recovery, form-state recovery, and mutation authority as independent. List active handoff receipts for the execution before resolving grouped submission statements; use the named receipt or the sole returned active receipt, classify every member, and claim that receipt before recording outcomes. Validate tab keep sets and resume upload stages locally. Never send raw browser values or click Submit.',
+        text: `Protocol 3.7.0 reliability gate for new work: require MCP contract ${APPLY_CONTRACT.contractVersion} and skill 4.8.0. Consume the exact proposedWave with frozen accessKnowledge before opening any browser; same-key advance replay returns identical member IDs, order, and rationale. When nextAction is access_review, including ordinary OPEN or neutral proposals, display the exact access-review receipt and do not report exhaustion. For a nonempty proposal, obtain explicit approval for the unchanged ordered job IDs and server approval hash before probing. For an all-deferred or recovery-blocked proposal with zero members, show the deferred count and stable job/company/provider deferment IDs, offer clear-deferment only for explicitly returned IDs, stop, or expiry, and never send an empty approval. Defer or clear only through jobId-scoped job, company, or provider tools; provider scope applies across companies until explicitly cleared. Never submit provider names, URLs, or raw chat. After complete local context loss, list bounded recovery candidates, obtain explicit confirmation of the exact set, and recover only that set. An active personal deferment blocks exact recovery until cleared. Treat tab recovery, form-state recovery, and mutation authority as independent. List active handoff receipts for the execution before resolving grouped submission statements; use the named receipt or the sole returned active receipt, classify every member, and claim that receipt before recording outcomes. Validate tab keep sets and resume upload stages locally. Never send raw browser values or click Submit.`,
       },
     }, {
       role: 'user',

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "trackly-cli",
-  "version": "0.18.4",
+  "version": "0.18.6",
   "mcpName": "io.github.trackly-app/trackly",
-  "description": "AI job search CLI + hosted MCP server with OAuth. Thousands of jobs, Thousands of companies, 40+ ATS. Works with Claude, ChatGPT, Cursor, Windsurf, Codex via hosted streamable-http or local stdio.",
+  "description": "AI job search CLI + hosted MCP server with OAuth. 250K+ jobs, 5,400+ companies, 40+ ATS. Works with Claude, ChatGPT, Cursor, Windsurf, Codex via hosted streamable-http or local stdio.",
   "bin": {
     "trackly": "./bin/trackly"
   },
@@ -10,6 +10,7 @@
     "test": "node --test",
     "test:contract-fixture": "node --test test/apply-contract.test.js",
     "test:hosted-contract": "node scripts/verify-hosted-contract.js",
+    "test:candidate-contract": "node scripts/verify-candidate-contract.js",
     "test:review-auth-contract": "node scripts/verify-review-auth-contract.js",
     "test:plugin-submission": "node scripts/verify-plugin-submission.js",
     "security:audit": "node scripts/verify-audit-exceptions.js"

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.trackly-app/trackly",
   "title": "Trackly CLI",
-  "description": "Job search for Claude, ChatGPT, Cursor. Thousands of jobs, Thousands of companies. OAuth or stdio.",
+  "description": "Job search for Claude, ChatGPT, Cursor. 250K+ jobs, 5,400+ companies. OAuth or stdio.",
   "repository": {
     "url": "https://github.com/trackly-app/trackly-cli",
     "source": "github"
@@ -17,12 +17,12 @@
       ]
     }
   ],
-  "version": "0.18.4",
+  "version": "0.18.6",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.18.4",
+      "version": "0.18.6",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {
@@ -48,7 +48,7 @@
       "headers": [
         {
           "name": "Authorization",
-          "description": "Optional Bearer trk_* API key for remote clients that don't support OAuth 2.1 Dynamic Client Registration. Clients that do support DCR can leave this blank \u2014 the server will guide them through an interactive OAuth flow. Create an API key at https://usetrackly.app/settings",
+          "description": "Optional. Leave blank to sign in with OAuth (recommended). For headless clients that cannot complete OAuth, send Bearer trk_... with an API key from https://usetrackly.app/settings",
           "isRequired": false,
           "isSecret": true
         }