trackly-cli 0.22.0 → 0.22.1

package/docs/trackly-tools.md

@@ -73,7 +73,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.
+- **trackly_search_jobs** — Search/filter jobs. A successful page may have `total: null`, `pagination.total: null` and `countStatus: "unavailable"` when its total cannot be computed. The returned jobs remain valid: explain `countGuidance`, use `hasMore` and pagination to continue, and avoid retrying just to obtain a total. Zero is a known count; null is unknown. Genuine page failures remain tool errors.
   - `function` (one value) or `jobFunctions` (nonempty array, OR; use one spelling only). The 14 values are: `product`, `engineering`, `design`, `data`, `marketing`, `sales`, `partnerships`, `finance`, `strategy`, `operations`, `people`, `legal`, `support`, `other`
   - `region`: nonempty array of `us`, `europe`, `latam`, `middle_east`, `asia`, `africa`, `canada`, `oceania`, `remote`, `unknown`, combined with OR. Use instead of `locationFilter`; unlike its legacy list form, this supports US plus other regions.
   - `usStates`: nonempty array of US codes `AL`, `AK`, `AZ`, `AR`, `CA`, `CO`, `CT`, `DC`, `DE`, `FL`, `GA`, `HI`, `ID`, `IL`, `IN`, `IA`, `KS`, `KY`, `LA`, `ME`, `MD`, `MA`, `MI`, `MN`, `MS`, `MO`, `MT`, `NE`, `NV`, `NH`, `NJ`, `NM`, `NY`, `NC`, `ND`, `OH`, `OK`, `OR`, `PA`, `RI`, `SC`, `SD`, `TN`, `TX`, `UT`, `VT`, `VA`, `WA`, `WV`, `WI`, `WY`, `PR`, `REMOTE`.

package/mcp/discovery-capabilities-v1.json

@@ -0,0 +1,131 @@
+{
+  "success": true,
+  "discovery": {
+    "version": 1,
+    "available": false,
+    "activation": "JOBSCOUT_DISCOVERY_V1_ENABLED=true after production query validation",
+    "preferenceWrites": false,
+    "sorts": [
+      "newest",
+      "relevance"
+    ],
+    "modes": {
+      "filters": true,
+      "filters_plus_focus": false,
+      "focus_only": false
+    },
+    "keywords": {
+      "parameter": "search",
+      "fields": [
+        "title",
+        "company",
+        "description",
+        "skills"
+      ],
+      "defaultFields": [
+        "title",
+        "company",
+        "description",
+        "skills"
+      ],
+      "allTerms": true,
+      "quotedPhrases": true,
+      "leadingMinus": true,
+      "maxLength": 500,
+      "maxTerms": 8,
+      "maxTermLength": 80,
+      "matching": "literal_whole_word_case_insensitive_nfkc",
+      "positiveMissingEvidence": "no_match",
+      "negativeMissingEvidence": "not_checked",
+      "descriptionSource": "description_text",
+      "skillsSource": [
+        "structured_jd.requiredSkills",
+        "structured_jd.preferredSkills"
+      ],
+      "companySource": "employer company row or posting organization; aggregator name is not employer evidence",
+      "provider": "postgresql",
+      "semanticExpansion": false,
+      "indexSupport": "validated_same_row_expression_gin_v1",
+      "supportedStrategy": "ascii_anchored_plan_selected_sets_or_exact_regex",
+      "unavailableClasses": [
+        "non_ascii_query",
+        "pure_punctuation"
+      ],
+      "unicodeSourceSafetyCohort": "included_and_rechecked; worst_case_requires_production_benchmark",
+      "performance": "unvalidated_on_azure; readiness_is_not_latency_proof"
+    },
+    "facets": {
+      "jobFunction": {
+        "ids": [
+          "product",
+          "engineering",
+          "design",
+          "data",
+          "marketing",
+          "sales",
+          "partnerships",
+          "finance",
+          "strategy",
+          "operations",
+          "people",
+          "legal",
+          "support",
+          "other"
+        ],
+        "unknown": "include",
+        "source": "job_function"
+      },
+      "industries": {
+        "ids": [
+          "fintech",
+          "healthtech",
+          "ai-ml",
+          "cybersecurity",
+          "ecommerce",
+          "gaming",
+          "devtools",
+          "edtech",
+          "crypto-web3",
+          "robotics",
+          "aerospace",
+          "hr-recruiting",
+          "insurance",
+          "enterprise-saas",
+          "social-media",
+          "media-entertainment",
+          "logistics-supply-chain",
+          "proptech",
+          "legaltech",
+          "biotech-pharma",
+          "climate-cleantech",
+          "hardware-semiconductors",
+          "telecom",
+          "automotive",
+          "food-agriculture",
+          "travel-hospitality",
+          "retail",
+          "marketplace",
+          "consulting-services",
+          "data-analytics",
+          "cloud-infrastructure",
+          "other"
+        ],
+        "unknown": "include",
+        "includeUnknownParameter": "includeUnknownIndustries",
+        "strictSelection": true,
+        "source": "employer company.industry; unresolved aggregator parents are unknown"
+      },
+      "roleSpecializations": {
+        "supported": false,
+        "reason": "No populated canonical taxonomy"
+      },
+      "subindustries": {
+        "supported": false,
+        "reason": "No populated canonical taxonomy"
+      }
+    },
+    "coverage": "unmeasured",
+    "counts": "same_sql_predicate; existing countMode and countCap semantics",
+    "readiness": "disabled"
+  }
+}

package/mcp/discovery-capabilities.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const { isDeepStrictEqual } = require('node:util');
+
+let preparedReadyEnvelope;
+
+/**
+ * Preparatory parser only: no transport, registration or production activation.
+ * The local opt-in defaults off and does not read capability data when off.
+ * A ready response proves contract compatibility, never production performance.
+ * Any contract drift requires a new reviewed fixture rather than inferred support.
+ */
+function parseDiscoveryCapabilities(response, { enabled = false } = {}) {
+  if (enabled !== true) return null;
+
+  if (!preparedReadyEnvelope) {
+    // Frozen API contract; test fixtures bind its exact bytes to the reviewed source.
+    preparedReadyEnvelope = structuredClone(require('./discovery-capabilities-v1.json'));
+    preparedReadyEnvelope.discovery.available = true;
+    preparedReadyEnvelope.discovery.readiness = 'ready';
+  }
+
+  if (!isDeepStrictEqual(response, preparedReadyEnvelope)) return null;
+  return structuredClone(preparedReadyEnvelope.discovery);
+}
+
+module.exports = { parseDiscoveryCapabilities };

package/mcp/server.js

@@ -285,7 +285,7 @@ function createServer() {
 
   server.registerTool(
     'trackly_search_jobs',
-    { description: 'Search and filter job postings. Returns one matching page with title, company, location, structured fields and backend pagination. Use jobFunctions for multiple roles, region for multiple regions, and usStates/caProvinces for geographic detail. Work arrangement is independent from geography and employment type. Unknown sponsorship and non-comparable salary data stay visible with exclude_no and salaryFloorUsd. Never invent industry, specialization, exclusion or literal-search controls; ask when sponsorship intent is ambiguous.',
+    { description: 'Search and filter job postings. Returns one matching page with title, company, location, structured fields and backend pagination. Use jobFunctions for multiple roles, region for multiple regions, and usStates/caProvinces for geographic detail. Work arrangement is independent from geography and employment type. Unknown sponsorship and non-comparable salary data stay visible with exclude_no and salaryFloorUsd. Never invent industry, specialization, exclusion or literal-search controls; ask when sponsorship intent is ambiguous. If the total is unavailable, returned matching jobs remain valid. Explain countGuidance and use hasMore/pagination; do not retry just for totals.',
     inputSchema: z.object({
       function: z.enum(JOB_FUNCTIONS).optional().describe('Job function filter. One of: ' + JOB_FUNCTIONS.join(', ')),
       jobFunctions: z.array(z.enum(JOB_FUNCTIONS)).min(1).max(14).optional().describe('Multiple job functions, combined with OR. Use instead of function. Omit both to request all 14 functions.'),

package/npm-shrinkwrap.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "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.22.0",
+  "version": "0.22.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.22.0",
+      "version": "0.22.1",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {