trackly-cli 0.7.2 → 0.7.3

package/README.md

@@ -35,7 +35,7 @@ trackly jobs --function product
 
 ## At a Glance
 
-1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 21 local MCP tools
+1,900+ companies | 128K+ jobs | 40+ ATS types | CLI + MCP | 24 local MCP tools
 
 ## CLI Commands
 
@@ -54,6 +54,9 @@ trackly companies search "fintech"    # Semantic company search
 trackly search "fintech"              # Alias for semantic company search
 trackly stats                         # Show metrics
 trackly status                        # Alias for stats
+trackly preferences                   # Show discovery preferences and experience limits
+trackly preferences experience product=2 strategy=5  # Replace role-specific limits
+trackly preferences experience clear # Turn role-specific experience filtering off
 trackly apply 1234                    # Mark as applied
 trackly save 1234                     # Save a job
 trackly dismiss 1234                  # Dismiss a job
@@ -78,6 +81,8 @@ trackly agent doctor                 # Verify setup, profile, resume, and compat
 
 Add `--json` to any command for JSON output. Use `--api-key <key>` or `--base-url <url>` as one-off global flags when needed.
 
+`trackly preferences --json` returns only `success`, `experienceFilterV2Available`, and `preferences`. The availability flag controls whether this client may edit role-specific limits; it does not claim that feed or alert enforcement is active. Every update checks that flag and the latest preference revision before writing.
+
 ## MCP Server Setup
 
 ### Hosted (Claude co-work, Claude Desktop, ChatGPT)
@@ -160,6 +165,8 @@ Then use natural language in any of these clients:
 | trackly_search_companies | Semantic company search |
 | trackly_list_companies | List all tracked companies |
 | trackly_get_stats | Job tracker metrics and status counts |
+| trackly_get_preferences | Read bounded discovery preferences, edit availability, and save revision |
+| 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) |
@@ -188,9 +195,15 @@ trackly login
 
 Opens your browser for Google sign-in. Tokens are stored locally at `~/.trackly/config.json`.
 
+Trackly is currently opening new memberships through a limited, invite-based
+rollout. Existing members can keep using OAuth and API keys normally. If a new
+account is not yet eligible, the CLI returns an invitation-specific message
+instead of suggesting repeated login attempts; request a future seat at
+[usetrackly.app/early-access](https://usetrackly.app/early-access).
+
 ### Option 2: API Key
 
-If OAuth doesn't work (firewalls, headless servers, CI), use an API key instead:
+Existing members can use an API key for firewalls, headless servers, or CI:
 
 1. Sign in at [usetrackly.app](https://usetrackly.app)
 2. Go to **Settings → API Keys → Create**
@@ -250,7 +263,7 @@ 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 22 tools for job search, company lookup, application tracking, 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 24 tools for job search, company lookup, discovery preferences, application tracking, profile onboarding, beta evidence, and manual-submit form preparation. Run `trackly mcp` or use `trackly agent setup --client claude`.
 
 **How do I use Claude Code for job hunting?**
 

package/bin/trackly

@@ -5,6 +5,7 @@ const {
   DEFAULT_BASE_URL,
   apiRequest,
   clearConfig,
+  createTracklyAccessError,
   getApiKey,
   getAuthMethod,
   getBaseUrl,
@@ -65,6 +66,7 @@ const COMMAND_FLAGS = {
   search: [],
   stats: [],
   status: [],
+  preferences: [],
   apply: [],
   save: [],
   dismiss: [],
@@ -80,15 +82,32 @@ const COMMAND_FLAGS = {
   agent: ['client', 'window-days', 'target-reviewed-runs'],
 };
 const AUTH_HELP_TEXT = `Not authenticated.
-  Option 1: trackly login                        (Google OAuth)
-  Option 2: trackly config --api-key trk_xxx     (get key at usetrackly.app)
-  Option 3: TRACKLY_API_KEY=trk_xxx trackly ...  (environment variable)`;
+  Existing member: trackly login                 (Google OAuth)
+  Existing API key: trackly config --api-key trk_xxx
+  New member: Trackly is in a limited rollout. Request access at
+              https://usetrackly.app/early-access`;
 const STATUS_LABELS = {
   applied: 'applied',
   saved: 'saved',
   dismissed: 'dismissed',
 };
 const WORK_ARRANGEMENT_VALUES = ['remote', 'hybrid', 'in_person', 'unspecified'];
+const JOB_FUNCTIONS = [
+  'product', 'engineering', 'design', 'data', 'marketing', 'sales', 'partnerships',
+  'finance', 'strategy', 'operations', 'people', 'legal', 'support', 'other',
+];
+
+function loginAccessError(code) {
+  return createTracklyAccessError({ code });
+}
+
+function writeLoginProgress(message) {
+  if (isJSON()) {
+    console.error(message);
+  } else {
+    console.log(message);
+  }
+}
 
 function parseArgs(args) {
   const result = { _: [], command: null };
@@ -225,15 +244,20 @@ function formatMaintenanceForHuman(maintenance) {
 
 function setApiErrorExit(error, fallbackMessage, exitCode = 1) {
   const maintenance = maintenanceOutput(error);
-  if (!maintenance) {
-    setErrorExit(error?.error || error?.message || fallbackMessage, exitCode);
-    return;
-  }
-
-  if (isJSON()) {
+  const accessError = createTracklyAccessError(error, error?.status);
+  if (isJSON() && accessError) {
+    printJson({
+      status: accessError.status,
+      code: accessError.code,
+      message: accessError.message,
+      retryable: accessError.retryable,
+    });
+  } else if (maintenance && isJSON()) {
     printJson(maintenance);
-  } else {
+  } else if (maintenance) {
     outputError(formatMaintenanceForHuman(maintenance));
+  } else {
+    outputError(error?.error || error?.message || fallbackMessage);
   }
   process.exitCode = exitCode;
 }
@@ -252,6 +276,39 @@ function parseJobId(value) {
   return id;
 }
 
+function parseExperienceLimits(values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error('Provide at least one role limit or `clear` (for example, `product=2 strategy=5`).');
+  }
+  if (values.includes('clear')) {
+    if (values.length !== 1) throw new Error('`clear` cannot be combined with role limits.');
+    return {};
+  }
+
+  const limits = {};
+  for (const value of values) {
+    const match = /^([^=]+)=([^=]+)$/.exec(String(value));
+    if (!match) throw new Error(`Invalid limit "${value}". Use role=years (for example, product=2).`);
+    const jobFunction = match[1].trim().toLowerCase();
+    const rawYears = match[2].trim();
+    if (!JOB_FUNCTIONS.includes(jobFunction)) {
+      throw new Error(`Unknown job function "${jobFunction}". Use: ${JOB_FUNCTIONS.join(', ')}.`);
+    }
+    if (Object.prototype.hasOwnProperty.call(limits, jobFunction)) {
+      throw new Error(`Duplicate limit for ${jobFunction}. Provide each job function once.`);
+    }
+    if (!/^\d+$/.test(rawYears)) {
+      throw new Error(`Limit for ${jobFunction} must be an integer from 0 to 60.`);
+    }
+    const years = Number(rawYears);
+    if (!Number.isInteger(years) || years < 0 || years > 60) {
+      throw new Error(`Limit for ${jobFunction} must be an integer from 0 to 60.`);
+    }
+    limits[jobFunction] = years;
+  }
+  return limits;
+}
+
 // Flags deprecated in the API-docs-plan fixup. Still accepted by parseArgs so old
 // scripts don't ERR_NOT_FOUND, but cmdJobs hard-rejects them with a migration hint
 // — silent no-op would be worse than noise (per PR #13 Codex P1 finding).
@@ -321,11 +378,11 @@ function getPublicConfig() {
 
 // -- Commands --
 
-async function cmdLogin() {
+async function cmdLogin({ openUrl = openExternalUrl } = {}) {
   const baseUrl = getBaseUrl();
   const state = crypto.randomBytes(16).toString('hex');
 
-  console.log(color('cyan', 'Opening browser for Google login...'));
+  writeLoginProgress(color('cyan', 'Opening browser for Google login...'));
 
   let activeServer = null;
 
@@ -348,6 +405,21 @@ async function cmdLogin() {
 
           const token = url.searchParams.get('token');
           const refreshToken = url.searchParams.get('refreshToken');
+          const accessError = loginAccessError(url.searchParams.get('error'));
+          if (accessError) {
+            res.writeHead(403, {
+              'Content-Type': 'text/html',
+              'Referrer-Policy': 'no-referrer',
+              'Cache-Control': 'no-store',
+            });
+            res.end('<html><body><h2>Trackly access is limited right now.</h2><p>Return to your terminal for next steps.</p></body></html>');
+            const loginError = new Error(accessError.message);
+            loginError.code = accessError.code;
+            loginError.status = accessError.status;
+            loginError.retryable = accessError.retryable;
+            settle(loginError);
+            return;
+          }
           if (token) {
             const config = loadConfig();
             const hadApiKey = Boolean(config.apiKey);
@@ -382,9 +454,9 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
 </div>
 </body>
 </html>`);
-            console.log(color('green', 'Login successful!'));
+            writeLoginProgress(color('green', 'Login successful!'));
             if (hadApiKey) {
-              console.log('Switched to OAuth. Stored API key cleared.');
+              writeLoginProgress('Switched to OAuth. Stored API key cleared.');
             }
             settle();
           } else {
@@ -405,10 +477,12 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
 
         const finish = () => {
           if (error) {
-            console.log('\nLogin failed. Try API key auth instead:');
-            console.log('  1. Sign in at https://usetrackly.app');
-            console.log('  2. Go to Settings → API Keys → Create');
-            console.log('  3. Run: trackly config --api-key <your-key>');
+            if (!createTracklyAccessError(error, 403)) {
+              writeLoginProgress('\nLogin failed. Existing members can try API key auth:');
+              writeLoginProgress('  1. Sign in at https://usetrackly.app');
+              writeLoginProgress('  2. Go to Settings → API Keys → Create');
+              writeLoginProgress('  3. Run: trackly config --api-key <your-key>');
+            }
             reject(error);
           } else {
             resolve();
@@ -436,10 +510,10 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
           settle(new Error(`OS assigned an out-of-range callback port (${port}); expected 1024-65535.`));
           return;
         }
-        console.log(color('dim', `Callback server on port ${port}`));
+        writeLoginProgress(color('dim', `Callback server on port ${port}`));
         const loginUrl = `${baseUrl}/auth/google/cli?port=${port}&state=${state}`;
-        if (!openExternalUrl(loginUrl)) {
-          console.log(`Open this URL in your browser:\n${loginUrl}`);
+        if (!openUrl(loginUrl)) {
+          writeLoginProgress(`Open this URL in your browser:\n${loginUrl}`);
         }
       });
 
@@ -461,6 +535,7 @@ p{color:#a1a1aa;font-size:15px;line-height:1.5}
   process.on('SIGINT', onSigint);
   try {
     await tryLogin();
+    if (isJSON()) printJson({ success: true, authMethod: 'oauth' });
   } finally {
     process.removeListener('SIGINT', onSigint);
   }
@@ -612,6 +687,119 @@ async function cmdStats() {
   }
 }
 
+function renderPreferences(result) {
+  const user = result?.user || {};
+  const preferences = user.preferences || result?.preferences || {};
+  const limits = preferences.experienceLimitsByJobFunction || {};
+
+  console.log(color('bold', 'Discovery preferences'));
+  const selected = Array.isArray(preferences.wantedJobFunctions)
+    ? preferences.wantedJobFunctions
+    : [];
+  console.log(`  Target roles: ${selected.length > 0 ? selected.join(', ') : 'All roles'}`);
+  console.log(`  Experience limits: ${Object.keys(limits).length > 0 ? 'Configured' : 'Not configured'}`);
+  for (const [jobFunction, years] of Object.entries(limits)) {
+    console.log(`    ${jobFunction}: Up to ${years} year${years === 1 ? '' : 's'} required`);
+  }
+  console.log(color('dim', '  Jobs with no stated minimum remain visible.'));
+  console.log(color('dim', '  This confirms what you saved; it does not show whether Trackly is currently applying the limits.'));
+  if (Number.isSafeInteger(preferences.discoveryPreferenceRevision)) {
+    console.log(color('dim', `  Revision: ${preferences.discoveryPreferenceRevision}`));
+  }
+}
+
+function projectPreferenceResponse(result, experienceFilterV2Available = null) {
+  const user = result?.user || {};
+  return {
+    success: result?.success === true,
+    experienceFilterV2Available: experienceFilterV2Available === null
+      ? user.experienceFilterV2Available === true
+      : experienceFilterV2Available === true,
+    preferences: user.preferences || result?.preferences || {},
+  };
+}
+
+function handlePreferenceConflict(error) {
+  const message = 'Preferences changed on another device. Review `trackly preferences`, then run the update again.';
+  if (isJSON()) {
+    printJson({
+      status: error.status,
+      code: error.error,
+      message,
+      preferences: error.preferences,
+      discoveryPreferenceRevision: error.discoveryPreferenceRevision,
+    });
+  } else {
+    outputError(message);
+  }
+  process.exitCode = 1;
+}
+
+async function cmdPreferences(args) {
+  if (!hasAuth()) failNow(AUTH_HELP_TEXT);
+
+  const subcommand = args._[0];
+  if (subcommand == null || subcommand === 'show') {
+    if (args._.length > (subcommand === 'show' ? 1 : 0)) {
+      failNow('Usage: trackly preferences [show]');
+    }
+    try {
+      const result = await apiRequest('GET', '/api/jobscout/me');
+      if (isJSON()) return printJson(projectPreferenceResponse(result));
+      renderPreferences(result);
+      return;
+    } catch (error) {
+      setApiErrorExit(error, 'Failed to fetch preferences');
+      return;
+    }
+  }
+
+  if (subcommand !== 'experience') {
+    failNow('Unknown preferences subcommand. Use: trackly preferences [show] | trackly preferences experience <role=years...|clear>');
+  }
+
+  let experienceLimitsByJobFunction;
+  try {
+    experienceLimitsByJobFunction = parseExperienceLimits(args._.slice(1));
+  } catch (error) {
+    failNow(error.message);
+  }
+
+  try {
+    // Read immediately before the write and send the authoritative revision.
+    // The backend rejects a stale value with 409 instead of letting this
+    // process overwrite a newer iOS, web, macOS, CLI, or MCP save.
+    const current = await apiRequest('GET', '/api/jobscout/me');
+    if (current?.user?.experienceFilterV2Available !== true) {
+      failNow('Role-specific experience preferences are not available for this account yet. No changes were saved.');
+    }
+    const expectedPreferenceRevision = current?.user?.preferences?.discoveryPreferenceRevision;
+    if (!Number.isSafeInteger(expectedPreferenceRevision) || expectedPreferenceRevision < 0) {
+      failNow('Trackly did not return a valid preference revision. No changes were saved.');
+    }
+
+    const result = await apiRequest('PUT', '/api/jobscout/preferences', {
+      experienceLimitsByJobFunction,
+      experienceFilterVersion: 2,
+      expectedPreferenceRevision,
+    });
+    if (isJSON()) return printJson(projectPreferenceResponse(result, true));
+    console.log(color(
+      'green',
+      Object.keys(experienceLimitsByJobFunction).length > 0
+        ? 'Role-specific experience limits updated.'
+        : 'Role-specific experience filtering turned off.',
+    ));
+    renderPreferences(result);
+  } catch (error) {
+    if (error?.status === 409 && error?.error === 'preference_revision_conflict') {
+      handlePreferenceConflict(error);
+      return;
+    }
+    setApiErrorExit(error, 'Failed to update experience limits');
+  }
+}
+
 const ACTION_TO_COMMAND = { applied: 'apply', saved: 'save', dismissed: 'dismiss' };
 
 // CLI surface accepts applied|saved|dismissed (legacy human-friendly terms).
@@ -1064,6 +1252,8 @@ ${color('bold', 'Commands:')}
   ${color('cyan', 'search <query>')}       Semantic company search
   ${color('cyan', 'stats')}                Show metrics dashboard
   ${color('cyan', 'status')}               Alias for stats
+  ${color('cyan', 'preferences')}          Show discovery preferences
+  ${color('cyan', 'preferences experience')} Replace role limits (role=years; clear turns off)
   ${color('cyan', 'apply <id>')}           Mark job as applied
   ${color('cyan', 'save <id>')}            Save a job
   ${color('cyan', 'dismiss <id>')}         Dismiss a job
@@ -1095,6 +1285,10 @@ ${color('bold', 'Flags:')}
 ${color('bold', 'Filter values:')}
   --function       product, engineering, design, data, marketing, sales, partnerships,
                    finance, strategy, operations, people, legal, support, other (comma-separated)
+  experience limits use the same role values, for example:
+                   trackly preferences experience product=2 strategy=5
+                   When enforcement is active, includes jobs whose stated minimum is up to the limit.
+                   Jobs with no stated minimum remain visible.
   --region         us, non_us, all, or a region tag (europe, canada, remote, ...)
                    Use a comma-separated list of region tags for multiple regions;
                    us/non_us/all cannot be combined.
@@ -1208,6 +1402,9 @@ async function main() {
     case 'status':
       await cmdStats();
       break;
+    case 'preferences':
+      await cmdPreferences(args);
+      break;
     case 'apply':
       await cmdUpdateStatus(args._[0], 'applied');
       break;
@@ -1276,14 +1473,18 @@ if (require.main === module) {
 module.exports = {
   COMMAND_FLAGS,
   UNIVERSAL_FLAGS,
+  cmdLogin,
   formatMaintenanceForHuman,
   getPublicConfig,
   hasJobListFilters,
   levenshtein,
+  loginAccessError,
   main,
   nearestFlag,
   normalizeBaseUrlValue,
   openExternalUrl,
   parseArgs,
+  parseExperienceLimits,
   parseJobId,
+  writeLoginProgress,
 };

package/docs/trackly-tools.md

@@ -65,6 +65,11 @@ trackly config --api-key trk_xxxxxxxxxxxxxxxxxxxx
 
 You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
 
+Existing memberships work across the CLI and local MCP server. New memberships
+are invite-only during the limited rollout; access errors link to
+https://usetrackly.app/early-access instead of recommending repeated OAuth or
+API-key creation attempts.
+
 ### Available Tools
 
 - **trackly_search_jobs** — Search/filter jobs.
@@ -82,6 +87,12 @@ You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
 - **trackly_search_companies** — Semantic company search
 - **trackly_list_companies** — List all tracked companies with job counts
 - **trackly_get_stats** — Job tracker metrics dashboard
+- **trackly_get_preferences** — Read a bounded preference response containing only `success`, `experienceFilterV2Available`, and the authenticated user's discovery `preferences`, including selected roles, saved role-specific limits, and the revision required for a safe update. Availability authorizes editing; it does not report feed or alert enforcement.
+- **trackly_update_experience_limits** — Atomically replace the complete role-specific experience-limit map.
+  - `experienceLimitsByJobFunction`: object whose keys are the 14 canonical job-function values and whose values are integer years from `0` through `60`. An empty object turns this filter off.
+  - `expectedPreferenceRevision`: non-negative safe integer from the latest `trackly_get_preferences` result. A stale revision is rejected; refetch and reconcile with the user rather than retrying blindly.
+  - The tool checks `experienceFilterV2Available` immediately before writing and refuses without a PUT unless it is exactly `true`.
+  - 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)
@@ -114,4 +125,5 @@ REST, refresh, download, CLI, and local/hosted MCP surfaces use canonical `code:
 - "What remote engineering roles are available?"
 - "Show me jobs at Stripe"
 - "Mark job 1234 as applied"
+- "Show my Trackly preferences, then set Product to up to 2 years and Strategy to up to 5 years"
 - "Use Trackly Apply to fill my next saved application and stop before Submit"

package/lib/client.js

@@ -18,6 +18,22 @@ const MAINTENANCE_APPLY_GUIDANCE =
   'Do not blindly retry an Apply mutation. Wait for the advertised maintenance window, ' +
   'refetch the Apply protocol and application profile, then resume the existing agent_browser run. ' +
   'Never create a duplicate run or click Submit.';
+const TRACKLY_ACCESS_GUIDANCE =
+  'Trackly is in a limited rollout. Existing members can sign in; new members need a private invite. ' +
+  'Request access at https://usetrackly.app/early-access.';
+const TRACKLY_ACCESS_PENDING_GUIDANCE =
+  'Your Trackly access request is already pending. No new request is needed.';
+const TRACKLY_ACCESS_UNAVAILABLE_GUIDANCE =
+  'Trackly access could not be verified right now. Please try again.';
+const TRACKLY_ACCESS_CODES = new Set([
+  'INVITATION_REQUIRED',
+  'INVITATION_INVALID',
+  'INVITATION_REDEEMED',
+  'SIGNUP_INTENT_EXPIRED',
+  'ACCESS_BATCH_FULL',
+  'ACCESS_CHECK_UNAVAILABLE',
+  'ALREADY_REQUESTED',
+]);
 
 class TracklyConfigError extends Error {
   constructor(message) {
@@ -243,6 +259,27 @@ function nestedRecord(value) {
   return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
 
+function createTracklyAccessError(json, status) {
+  const record = nestedRecord(json);
+  const code = cleanText(record.code);
+  if (!code || !TRACKLY_ACCESS_CODES.has(code.toUpperCase())) return null;
+  const normalizedCode = code.toUpperCase();
+  const retryable = normalizedCode === 'ACCESS_CHECK_UNAVAILABLE';
+  const message = retryable
+    ? TRACKLY_ACCESS_UNAVAILABLE_GUIDANCE
+    : normalizedCode === 'ALREADY_REQUESTED'
+      ? TRACKLY_ACCESS_PENDING_GUIDANCE
+      : TRACKLY_ACCESS_GUIDANCE;
+  return {
+    ...record,
+    status: status ?? (retryable ? 503 : 403),
+    code: normalizedCode,
+    error: message,
+    message,
+    retryable,
+  };
+}
+
 // REST maintenance responses and hosted MCP JSON-RPC errors intentionally use
 // different envelopes. Collapse both into the same source view so every CLI
 // surface preserves equivalent code/retry/ETA/request context.
@@ -579,6 +616,8 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
             headers: res.headers,
           });
           if (maintenanceError) return reject(maintenanceError);
+          const accessError = createTracklyAccessError(json, res.statusCode);
+          if (accessError) return reject(accessError);
           // 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
@@ -676,6 +715,11 @@ function downloadFile(endpoint, userAgent = null, _isRetry = false) {
             reject(maintenanceError);
             return;
           }
+          const accessError = createTracklyAccessError(body, res.statusCode);
+          if (accessError) {
+            reject(accessError);
+            return;
+          }
           reject({ ...body, status: res.statusCode, message: body.error || `HTTP ${res.statusCode}` });
           return;
         }
@@ -720,6 +764,7 @@ module.exports = {
   TracklyConfigError,
   MAINTENANCE_APPLY_GUIDANCE,
   MAINTENANCE_CODE,
+  TRACKLY_ACCESS_GUIDANCE,
   apiRequest,
   downloadFile,
   clearConfig,
@@ -738,6 +783,7 @@ module.exports = {
   hasAuth,
   loadConfig,
   createMaintenanceError,
+  createTracklyAccessError,
   isMaintenanceError,
   maintenanceOutput,
   normalizeMaintenance,

package/mcp/server.js

@@ -4,14 +4,18 @@ const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { McpError } = require('@modelcontextprotocol/sdk/types.js');
 const { z } = require('zod');
-const { apiRequest, hasAuth, maintenanceOutput } = require('../lib/client');
+const { apiRequest, createTracklyAccessError, hasAuth, maintenanceOutput } = require('../lib/client');
 const { prepareResume, verifyPreparedResume } = require('../lib/agent');
 const { version: PACKAGE_VERSION } = require('../package.json');
 const APPLY_CONTRACT = require('../contracts/trackly-apply-tools.json');
 
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
 const MCP_MAINTENANCE_ERROR_CODE = -32002;
-const AUTH_HINT = 'Run `trackly login` or set TRACKLY_API_KEY. Get a key at https://usetrackly.app (sign in → Settings → API Keys).';
+const MCP_ACCESS_ERROR_CODE = -32003;
+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 APPLY_BROWSER_SURFACES = APPLY_CONTRACT.constants.applyBrowserSurfaces;
 const APPLY_SCENARIO_CODES = APPLY_CONTRACT.constants.applyScenarioCodes;
 const SAFE_OBSERVATION_CODE = /^[a-z0-9][a-z0-9_:-]{0,99}$/;
@@ -60,21 +64,44 @@ const ACTION_TO_STAGE = { applied: 'applied', saved: 'backlog', dismissed: 'disc
 
 function createErrorResult(error, fallbackMessage, extra = {}) {
   const normalizedMaintenance = maintenanceOutput(error);
+  const normalizedAccess = createTracklyAccessError(error, error?.status);
   const payload = normalizedMaintenance
     ? {
         ...normalizedMaintenance,
         error: error?.error || error?.message || fallbackMessage,
         ...extra,
       }
-    : {
-        error: error?.error || error?.message || fallbackMessage,
-        ...extra,
-      };
+    : normalizedAccess
+      ? {
+          error: normalizedAccess.error,
+          message: normalizedAccess.message,
+          status: normalizedAccess.status,
+          code: normalizedAccess.code,
+          retryable: normalizedAccess.retryable,
+          ...extra,
+        }
+      : {
+          error: error?.error || error?.message || fallbackMessage,
+          ...extra,
+        };
 
   if (error?.status) {
     payload.status = error.status;
   }
 
+  if (
+    error?.code === 'experience_filter_v2_unavailable'
+    || error?.code === 'invalid_preference_revision'
+  ) {
+    payload.code = error.code;
+  }
+
+  if (error?.status === 409 && error?.error === 'preference_revision_conflict') {
+    payload.preferences = error.preferences;
+    payload.discoveryPreferenceRevision = error.discoveryPreferenceRevision;
+    payload.hint = 'Preferences changed elsewhere. Refetch with trackly_get_preferences, reconcile with the user, and never retry blindly with the newer revision.';
+  }
+
   if (error?.status === 429 && !payload.hint) {
     payload.hint = 'Daily limit reached (20 natural language queries per day).';
   }
@@ -102,6 +129,25 @@ function throwMcpResourceError(error) {
       normalizedMaintenance,
     );
   }
+  const normalizedAccess = createTracklyAccessError(error, error?.status);
+  if (normalizedAccess) {
+    throw new McpError(
+      MCP_ACCESS_ERROR_CODE,
+      normalizedAccess.message,
+      {
+        status: normalizedAccess.status,
+        code: normalizedAccess.code,
+        retryable: normalizedAccess.retryable,
+      },
+    );
+  }
+  if (error?.status === 401) {
+    throw new McpError(
+      MCP_AUTH_ERROR_CODE,
+      error?.message || 'Not authenticated',
+      { status: 401, hint: AUTH_HINT },
+    );
+  }
   throw error;
 }
 
@@ -126,6 +172,17 @@ function wrapTool(handler, fallbackMessage) {
   };
 }
 
+function projectPreferenceResponse(result, experienceFilterV2Available = null) {
+  const user = result?.user || {};
+  return {
+    success: result?.success === true,
+    experienceFilterV2Available: experienceFilterV2Available === null
+      ? user.experienceFilterV2Available === true
+      : experienceFilterV2Available === true,
+    preferences: user.preferences || result?.preferences || {},
+  };
+}
+
 function createServer() {
   const server = new McpServer({
     name: 'trackly',
@@ -239,6 +296,62 @@ function createServer() {
     }, 'Failed to fetch stats')
   );
 
+  server.tool(
+    'trackly_get_preferences',
+    'Read the authenticated user\'s discovery preferences, including selected and effective job functions, role-specific experience limits and active state, and the discoveryPreferenceRevision required for a safe update.',
+    {},
+    wrapTool(async () => {
+      const result = await apiRequest('GET', '/api/jobscout/me', null, false, false, MCP_USER_AGENT);
+      return projectPreferenceResponse(result);
+    }, 'Failed to fetch preferences')
+  );
+
+  server.tool(
+    'trackly_update_experience_limits',
+    'Atomically replace the complete role-specific experience-limit map. Each value is the highest stated minimum years requirement the user wants for that job function. When Trackly enforcement is active, a job is included when its stated minimum is less than or equal to the limit. Jobs with no stated minimum remain visible. An empty object clears the saved limits. experienceFilterV2Available reports edit capability, not enforcement state. Read discoveryPreferenceRevision with trackly_get_preferences first. If the backend returns a revision conflict, refetch and reconcile with the user; never retry blindly with the newer revision.',
+    {
+      experienceLimitsByJobFunction: z.record(z.enum(JOB_FUNCTIONS), z.number().int().min(0).max(60)).describe(
+        'Complete replacement map from canonical job-function slug to maximum acceptable stated minimum years. Use {} to turn role-specific experience filtering off.'
+      ),
+      expectedPreferenceRevision: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).describe(
+        'The non-negative safe-integer discoveryPreferenceRevision returned by the latest trackly_get_preferences call. A stale revision is rejected instead of overwriting newer choices.'
+      ),
+    },
+    wrapTool(async ({ experienceLimitsByJobFunction, expectedPreferenceRevision }) => {
+      const current = await apiRequest('GET', '/api/jobscout/me', null, false, false, MCP_USER_AGENT);
+      if (current?.user?.experienceFilterV2Available !== true) {
+        throw {
+          status: 403,
+          code: 'experience_filter_v2_unavailable',
+          error: 'Role-specific experience preferences are not available for this account yet. No changes were saved.',
+        };
+      }
+      const currentPreferences = current?.user?.preferences || {};
+      const currentRevision = currentPreferences.discoveryPreferenceRevision;
+      if (!Number.isSafeInteger(currentRevision) || currentRevision < 0) {
+        throw {
+          status: 502,
+          code: 'invalid_preference_revision',
+          error: 'Trackly did not return a valid preference revision. No changes were saved.',
+        };
+      }
+      if (currentRevision !== expectedPreferenceRevision) {
+        throw {
+          status: 409,
+          error: 'preference_revision_conflict',
+          preferences: currentPreferences,
+          discoveryPreferenceRevision: currentRevision,
+        };
+      }
+      const result = await apiRequest('PUT', '/api/jobscout/preferences', {
+        experienceLimitsByJobFunction,
+        experienceFilterVersion: 2,
+        expectedPreferenceRevision,
+      }, false, false, MCP_USER_AGENT);
+      return projectPreferenceResponse(result, true);
+    }, 'Failed to update experience limits')
+  );
+
   server.tool(
     'trackly_update_status',
     'Update a job application status (apply, save, or dismiss).',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trackly-cli",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "mcpName": "io.github.trackly-app/trackly",
   "description": "AI job search CLI + hosted MCP server with OAuth. 128K+ jobs, 1,900+ companies, 40+ ATS. Works with Claude, ChatGPT, Cursor, Windsurf, Codex via hosted streamable-http or local stdio.",
   "bin": {

package/server.json

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