trackly-cli 0.1.12 → 0.2.1

package/README.md

@@ -7,9 +7,23 @@
 
 The only job tracking CLI built for AI agents.
 
-Search 128,000+ jobs across 1,900+ companies and 40+ ATS types. Track applications, get AI-powered recommendations, and manage your job search -- from the terminal or through Claude Code, Cursor, and other MCP-compatible AI agents.
+Search 128,000+ jobs across 1,900+ 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.
 
-## Quick Start
+## Two ways to connect
+
+### 🚀 Option 1: One-click in Claude co-work, Claude Desktop, ChatGPT (no install)
+
+Use Trackly directly inside your AI — zero config:
+
+1. Open Settings → Connectors → **Add custom connector**
+2. URL: `https://mcp.usetrackly.app/api/mcp`
+3. Click **Add** → sign in with Google → done
+
+**[Full setup guide with screenshots →](https://usetrackly.app/connect)**
+
+Works in: Claude co-work (web), Claude Desktop, ChatGPT Connectors, and any MCP client that supports remote/streamable-http connectors.
+
+### 💻 Option 2: CLI install (for Cursor, Windsurf, or terminal use)
 
 ```bash
 npm install -g trackly-cli    # may need: sudo npm install -g trackly-cli
@@ -27,8 +41,10 @@ trackly jobs --function product
 
 ```bash
 trackly jobs                          # List jobs
-trackly jobs --modality remote        # Filter remote jobs
-trackly jobs --function product        # Filter by function
+trackly jobs --remote                 # Filter remote jobs (sets usStates=REMOTE)
+trackly jobs --region us              # Filter by region (us, non_us, all, or a region tag: europe, canada, remote, ...)
+trackly jobs --job-type internship    # Filter by employment type (full_time, internship, all)
+trackly jobs --function product       # Filter by function
 trackly jobs --company 243            # Filter by company ID
 trackly job 1234                      # Get job details
 trackly jobs 1234                     # Alias for job details
@@ -60,7 +76,19 @@ Add `--json` to any command for JSON output. Use `--api-key <key>` or `--base-ur
 
 ## MCP Server Setup
 
-### One-liner (recommended)
+### Hosted (Claude co-work, Claude Desktop, ChatGPT)
+
+No install. In your AI tool, open **Settings → Connectors → Add custom connector** and enter:
+
+```text
+https://mcp.usetrackly.app/api/mcp
+```
+
+Sign in with Google when prompted. [Full visual guide →](https://usetrackly.app/connect)
+
+### Local (CLI via stdio, for Cursor / Windsurf / Claude Code)
+
+#### Claude Code one-liner
 
 ```bash
 claude mcp add --scope user trackly -- trackly mcp
@@ -72,7 +100,7 @@ Or equivalently:
 claude mcp add-json --scope user trackly '{"command":"trackly","args":["mcp"]}'
 ```
 
-### Claude Code manual config
+#### Claude Code manual config
 
 Add to `~/.claude/settings.json`:
 
@@ -87,9 +115,9 @@ Add to `~/.claude/settings.json`:
 }
 ```
 
-### Cursor
+#### Cursor / Windsurf
 
-Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
+Add to `.cursor/mcp.json` or `~/.cursor/mcp.json` (same schema works for Windsurf):
 
 ```json
 {
@@ -102,7 +130,7 @@ Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
 }
 ```
 
-Then use natural language in Claude Code or Cursor:
+Then use natural language in any of these clients:
 
 - "Find me PM jobs at fintech companies"
 - "What remote engineering roles are available?"

package/bin/trackly

@@ -19,17 +19,17 @@ const crypto = require('crypto');
 const { spawnSync } = require('child_process');
 const { version: VERSION } = require('../package.json');
 
-const BOOLEAN_FLAGS = new Set(['help', 'h', 'json', 'version', 'v', 'clear-api-key', 'clear-base-url', 'refresh']);
+const BOOLEAN_FLAGS = new Set(['help', 'h', 'json', 'version', 'v', 'clear-api-key', 'clear-base-url', 'refresh', 'remote']);
 const VALUE_FLAGS = new Set([
   'api-key',
   'base-url',
   'function',
+  'job-type',
   'keywords',
   'limit',
-  'location',
-  'modality',
   'name',
   'offset',
+  'region',
   'search',
   'sort',
   'status',
@@ -128,9 +128,21 @@ function parseJobId(value) {
   return id;
 }
 
+// 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).
+const DEPRECATED_JOB_FLAGS = Object.freeze({
+  location: '--location was removed. Use --region <tag> (us, non_us, all, or a region tag like europe, canada, remote). See `trackly --help` for accepted values.',
+  modality: '--modality was removed. Use --job-type <full_time|internship|all> for employment type, and/or --remote / --region remote for work-location.',
+});
+
 function hasJobListFilters(args) {
-  return ['function', 'keywords', 'limit', 'location', 'modality', 'offset', 'sort', 'status']
-    .some((key) => args[key] !== undefined);
+  // Include deprecated flags so `trackly jobs 42 --location us` routes to cmdJobs
+  // (which then raises the migration error) instead of cmdJob(42) silently ignoring
+  // the filter. See PR #13 Cursor Bugbot finding.
+  const deprecated = Object.keys(DEPRECATED_JOB_FLAGS);
+  const active = ['function', 'company', 'keywords', 'limit', 'region', 'job-type', 'remote', 'offset', 'sort', 'status'];
+  return [...active, ...deprecated].some((key) => args[key] !== undefined);
 }
 
 function openExternalUrl(url) {
@@ -350,11 +362,25 @@ async function cmdWhoami() {
 async function cmdJobs(args) {
   if (!hasAuth()) failNow(AUTH_HELP_TEXT);
 
+  // Reject deprecated flags with migration hints instead of silently ignoring them
+  // (scripts from older releases would otherwise appear to succeed while returning
+  // an unfiltered feed — misleading and hard to debug).
+  for (const [flag, hint] of Object.entries(DEPRECATED_JOB_FLAGS)) {
+    if (args[flag] !== undefined) failNow(hint);
+  }
+
+  // --remote is a shorthand that conflicts with --region (they both control location).
+  // Help text documents them as alternatives; enforce it explicitly here.
+  if (args.remote && args.region) {
+    failNow('--remote cannot be combined with --region. Use one or the other (e.g. --region remote).');
+  }
+
   const params = new URLSearchParams();
   if (args.function) params.set('jobFunction', args.function);
   if (args.company) params.set('companyId', args.company);
-  if (args.location) params.set('location', args.location);
-  if (args.modality) params.set('modality', args.modality);
+  if (args.region) params.set('locationFilter', args.region);
+  if (args['job-type']) params.set('jobModality', args['job-type']);
+  if (args.remote) params.set('usStates', 'REMOTE');
   if (args.status) params.set('status', args.status);
   if (args.sort) params.set('sort', args.sort);
   if (args.limit) params.set('limit', args.limit);
@@ -384,16 +410,15 @@ async function cmdJob(args) {
 
     const job = result.job || result;
     console.log(color('bold', job.title));
-    console.log(`Company: ${color('blue', job.company_name)}`);
+    console.log(`Company: ${color('blue', job.companyName || (job.company && job.company.name) || '')}`);
     if (job.location) console.log(`Location: ${job.location}`);
-    if (job.modality) console.log(`Modality: ${color('cyan', job.modality)}`);
-    if (job.url) console.log(`URL: ${color('dim', job.url)}`);
-    if (job.posted_at) console.log(`Posted: ${job.posted_at}`);
-    if (job.description_text) {
+    if (job.jobUrl) console.log(`URL: ${color('dim', job.jobUrl)}`);
+    if (job.postedAt) console.log(`Posted: ${job.postedAt}`);
+    if (typeof job.description === 'string' && job.description.length > 0) {
       console.log();
       console.log(color('bold', 'Description:'));
-      console.log(job.description_text.slice(0, 1000));
-      if (job.description_text.length > 1000) console.log(color('dim', '... (truncated)'));
+      console.log(job.description.slice(0, 1000));
+      if (job.description.length > 1000) console.log(color('dim', '... (truncated)'));
     }
   } catch (e) {
     setErrorExit(e.error || e.message || 'Failed to fetch job');
@@ -700,7 +725,7 @@ ${color('bold', 'Commands:')}
   ${color('cyan', 'login')}                Authenticate via Google OAuth
   ${color('cyan', 'logout')}               Clear credentials
   ${color('cyan', 'whoami')}               Show current user
-  ${color('cyan', 'jobs')}                 List jobs (--function, --company <id>, --location, --modality, --status, --sort, --limit, --offset, --keywords)
+  ${color('cyan', 'jobs')}                 List jobs (--function, --company <id>, --region <tag>, --job-type <type>, --remote, --status, --sort, --limit, --offset, --keywords)
   ${color('cyan', 'job <id>')}             Get full job detail
   ${color('cyan', 'jobs <id>')}            Alias for job <id>
   ${color('cyan', 'companies')}            List companies
@@ -732,6 +757,18 @@ ${color('bold', 'Flags:')}
   --version             Show version
   --help                Show this help
 
+${color('bold', 'Filter values:')}
+  --function       product, engineering, design, data, marketing, sales, partnerships,
+                   finance, strategy, operations, people, legal, support, other (comma-separated)
+  --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.
+  --job-type       full_time, internship, all  (employment type, not work-location)
+  --remote         Flag (no value). Filters for remote jobs (equivalent to usStates=REMOTE).
+  --status         new, applying, applied_confirmed, check_later, not_interested, all
+                   (filters by YOUR application pipeline state)
+  --sort           newest, oldest, company
+
 ${color('bold', 'MCP Setup:')}
   Claude Code: claude mcp add --scope user trackly -- trackly mcp
   Cursor: add {"command":"trackly","args":["mcp"]} to .cursor/mcp.json

package/docs/trackly-tools.md

@@ -1,12 +1,27 @@
 ## Trackly Job Tracker (MCP)
 
-Trackly MCP server provides job search and tracking tools. Start it with:
+Trackly MCP server provides job search and tracking tools. Two ways to connect:
+
+### Claude co-work, Claude Desktop, ChatGPT (hosted, no install)
+
+In your AI tool, open **Settings → Connectors → Add custom connector**:
+
+- URL: `https://mcp.usetrackly.app/api/mcp`
+- Leave any optional OAuth fields empty — **Client ID**, **Client Secret**, **Authorization URL**, **Token URL** — Trackly uses OAuth 2.1 Dynamic Client Registration and will register the client automatically
+- If the client UI uses different labels or requires you to continue past an OAuth section, keep those fields blank and proceed to sign in. Do not invent client credentials or endpoint URLs.
+
+Sign in with Google when prompted. [Visual guide →](https://usetrackly.app/connect)
+
+### Cursor, Windsurf, Claude Code (CLI via stdio)
+
+Install and start the stdio server:
 
 ```bash
+npm install -g trackly-cli
 trackly mcp
 ```
 
-### Claude Code
+#### Claude Code
 
 ```json
 {
@@ -19,9 +34,9 @@ trackly mcp
 }
 ```
 
-### Cursor
+#### Cursor / Windsurf
 
-Add to `.cursor/mcp.json`:
+Add to `.cursor/mcp.json` (same schema for Windsurf):
 
 ```json
 {
@@ -52,7 +67,16 @@ You can also pass `TRACKLY_API_KEY` as an environment variable for one-off runs.
 
 ### Available Tools
 
-- **trackly_search_jobs** — Search/filter jobs by function, company, location, modality, keywords. Function values: `product`, `engineering`, `design`, `data`, `marketing`, `sales`, `finance`, `operations`, `legal`, `people`, `strategy`, `support`, `other`
+- **trackly_search_jobs** — Search/filter jobs.
+  - `function` (14 values): `product`, `engineering`, `design`, `data`, `marketing`, `sales`, `partnerships`, `finance`, `strategy`, `operations`, `people`, `legal`, `support`, `other`
+  - `locationFilter`: pass ONE of
+    - a single scalar: `us`, `non_us`, `all`, or a region tag (`europe`, `latam`, `middle_east`, `asia`, `africa`, `canada`, `oceania`, `remote`, `unknown`), OR
+    - an array of region tags for multi-region (e.g. `["europe", "canada"]`). The array form excludes `us` — combining `us` with other tags in an array causes the backend to silently drop the others. To get "not US" use the scalar `non_us` alone.
+  - `jobModality`: `full_time`, `internship`, `all` — employment type, NOT work-location style. For remote/hybrid/onsite filtering, use the `remote` boolean or `locationFilter: "remote"`; hybrid and onsite are not exposed as filters.
+  - `remote` (boolean): filter to remote jobs only. Maps to `usStates=REMOTE`.
+  - `status`: your application pipeline state. Values: `new`, `applying`, `applied_confirmed`, `check_later`, `not_interested`, `all`.
+  - `sort`: `newest`, `oldest`, `company`.
+  - `keywords`, `companyId`, `limit`, `offset`.
 - **trackly_get_job** — Get full job details by ID
 - **trackly_search_companies** — Semantic company search
 - **trackly_list_companies** — List all tracked companies with job counts

package/lib/formatters.js

@@ -39,14 +39,14 @@ function outputJobs(jobs) {
     return;
   }
   for (const job of jobs) {
-    const modality = job.modality ? color('cyan', `[${job.modality}]`) : '';
     const location = job.location ? color('dim', job.location) : '';
-    console.log(`${color('bold', job.title)} ${modality}`);
-    console.log(`  ${color('blue', job.company_name)} | ${location}`);
+    const companyName = job.companyName || (job.company && job.company.name) || '';
+    console.log(`${color('bold', job.title)}`);
+    console.log(`  ${color('blue', companyName)} | ${location}`);
     const fundingLine = formatFundingLine(job.company);
     if (fundingLine) console.log(`  ${color('magenta', fundingLine)}`);
-    console.log(`  ID: ${color('dim', job.id)} | Posted: ${color('dim', job.posted_at || job.first_seen_at || 'unknown')}`);
-    if (job.url) console.log(`  ${color('dim', job.url)}`);
+    console.log(`  ID: ${color('dim', job.id)} | Posted: ${color('dim', job.postedAt || job.firstSeenAt || 'unknown')}`);
+    if (job.jobUrl) console.log(`  ${color('dim', job.jobUrl)}`);
     console.log();
   }
 }
@@ -58,7 +58,7 @@ function outputCompanies(companies) {
     return;
   }
   for (const co of companies) {
-    const count = co.active_jobs_count || co.job_count || 0;
+    const count = co.totalJobCount || 0;
     console.log(`${color('bold', co.name)} — ${color('cyan', count + ' jobs')}`);
     if (co.domain) console.log(`  ${color('dim', co.domain)}`);
     console.log();

package/mcp/server.js

@@ -9,6 +9,33 @@ const { version: PACKAGE_VERSION } = require('../package.json');
 const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
 const AUTH_HINT = 'Run `trackly login` or set TRACKLY_API_KEY. Get a key at https://usetrackly.app (sign in → Settings → API Keys).';
 
+// Mirrors `granola-followup-app/src/services/region-classifier.ts:8` REGION_TAGS.
+// Keep in sync when the backend enum changes.
+const REGION_TAGS = [
+  'us', 'europe', 'latam', 'middle_east', 'asia', 'africa', 'canada', 'oceania', 'remote', 'unknown',
+];
+
+// REGION_TAGS values that are safe to combine in a comma-list with other tags.
+// `us` is excluded because combining it with other tags (e.g. ['us', 'europe']) is a trap:
+// the backend parser at granola-followup-app/src/routes/jobscout-filter-utils.ts:73-90
+// supports `us` ONLY as a single-value scalar; in a comma-list it behaves identically to
+// the scalar branch and any non-us members are ignored. Callers who want 'us + europe' should
+// use the scalar `all` or two separate calls. Callers who want 'not us' should use `non_us`.
+const REGION_TAGS_ARRAY_SAFE = REGION_TAGS.filter((t) => t !== 'us');
+
+// `jobFunction` enum matches `granola-followup-app/src/routes/jobscout-filter-utils.ts:17-21`
+// (ALL_JOB_FUNCTIONS). 14 canonical values.
+const JOB_FUNCTIONS = [
+  'product', 'engineering', 'design', 'data', 'marketing', 'sales', 'partnerships',
+  'finance', 'strategy', 'operations', 'people', 'legal', 'support', 'other',
+];
+
+// `status` enum matches the backend allowlist at `jobscout.ts:2949`.
+const STATUS_VALUES = ['new', 'applying', 'applied_confirmed', 'check_later', 'not_interested', 'all'];
+
+// `jobModality` enum matches `jobscout.ts:2870-2875`. Employment type, NOT work-location.
+const JOB_MODALITIES = ['full_time', 'internship', 'all'];
+
 function createErrorResult(error, fallbackMessage, extra = {}) {
   const payload = {
     error: error?.error || error?.message || fallbackMessage,
@@ -66,31 +93,46 @@ function createServer() {
 
   server.tool(
     'trackly_search_jobs',
-    'Search and filter job postings. Returns matching jobs with title, company, location, modality. Use companyId to filter jobs at a specific company (get companyId from trackly_search_companies first).',
+    'Search and filter job postings. Returns matching jobs with title, company, location, and structured fields. Use companyId to filter jobs at a specific company (get companyId from trackly_search_companies first). Pass `remote: true` for remote-only jobs.',
     {
-      function: z.enum(['product', 'engineering', 'design', 'data', 'marketing', 'sales', 'finance', 'operations', 'legal', 'people', 'strategy', 'support', 'other']).optional().describe('Job function filter (matches DB column). Common: product, engineering, design, data, marketing, sales, operations, other'),
+      function: z.enum(JOB_FUNCTIONS).optional().describe('Job function filter. One of: ' + JOB_FUNCTIONS.join(', ')),
       companyId: z.number().optional().describe('Filter jobs by company ID (get from trackly_search_companies)'),
-      location: z.string().optional().describe('Location filter (city or state)'),
-      modality: z.enum(['remote', 'hybrid', 'onsite']).optional().describe('Work modality: remote, hybrid, onsite'),
-      status: z.enum(['new', 'saved', 'applied', 'dismissed']).optional().describe('Application status: new, saved, applied, dismissed'),
+      locationFilter: z.union([
+        z.enum(['us', 'non_us', 'all']),
+        z.enum(REGION_TAGS),
+        z.array(z.enum(REGION_TAGS_ARRAY_SAFE)).min(1),
+      ]).optional().describe(
+        "Region tag filter. Pass ONE of: (a) a single scalar from 'us', 'non_us', 'all', or a REGION_TAGS value ('europe', 'latam', 'middle_east', 'asia', 'africa', 'canada', 'oceania', 'remote', 'unknown'); or (b) an array of region tags for multi-region (e.g. ['europe', 'canada']). The array form excludes 'us' — combining 'us' with other tags causes the backend to silently drop the others. For 'not US' use the scalar 'non_us' alone."
+      ),
+      jobModality: z.enum(JOB_MODALITIES).optional().describe(
+        "Employment type (NOT work-location style). full_time = full-time roles, internship = internships, all = both. For remote filtering, use the `remote` boolean or locationFilter='remote'. Hybrid and onsite are not exposed as filters."
+      ),
+      remote: z.boolean().optional().describe('Filter to remote jobs only (maps to usStates=REMOTE).'),
+      status: z.enum(STATUS_VALUES).optional().describe(
+        'Filter by YOUR application pipeline state. Not a generic job-posting status. Values: ' + STATUS_VALUES.join(', ')
+      ),
       sort: z.enum(['newest', 'oldest', 'company']).optional().describe('Sort order: newest, oldest, company'),
       limit: z.number().max(50).optional().describe('Max results (default 20, max 50)'),
       offset: z.number().min(0).optional().describe('Pagination offset'),
-      keywords: z.string().max(500).optional().describe('Keyword search in title/description'),
+      keywords: z.string().max(500).optional().describe('Keyword search in title, company, or description'),
     },
     wrapTool(async (params) => {
-      // Map MCP param names to backend query param names
-      const paramMap = {
-        function: 'jobFunction',
-        keywords: 'search',
-      };
       const qs = new URLSearchParams();
-      for (const [key, value] of Object.entries(params)) {
-        if (value !== undefined && value !== null) {
-          const backendKey = paramMap[key] || key;
-          qs.set(backendKey, String(value));
-        }
+      if (params.function !== undefined) qs.set('jobFunction', params.function);
+      if (params.companyId !== undefined) qs.set('companyId', String(params.companyId));
+      if (params.locationFilter !== undefined) {
+        const value = Array.isArray(params.locationFilter)
+          ? params.locationFilter.join(',')
+          : params.locationFilter;
+        qs.set('locationFilter', value);
       }
+      if (params.jobModality !== undefined) qs.set('jobModality', params.jobModality);
+      if (params.remote === true) qs.set('usStates', 'REMOTE');
+      if (params.status !== undefined) qs.set('status', params.status);
+      if (params.sort !== undefined) qs.set('sort', params.sort);
+      if (params.limit !== undefined) qs.set('limit', String(params.limit));
+      if (params.offset !== undefined) qs.set('offset', String(params.offset));
+      if (params.keywords !== undefined) qs.set('search', params.keywords);
       return apiRequest('GET', `/api/jobscout/jobs?${qs.toString()}`, null, false, false, MCP_USER_AGENT);
     }, 'Failed to search jobs')
   );

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "trackly-cli",
-  "version": "0.1.12",
+  "version": "0.2.1",
   "mcpName": "io.github.kevinastuhuaman/trackly",
-  "description": "CLI + MCP server for job tracking — search, apply, and manage applications from terminal or AI agents",
+  "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": {
     "trackly": "./bin/trackly"
   },
@@ -25,8 +25,16 @@
     "mcp",
     "mcp-server",
     "model-context-protocol",
-    "cli",
+    "oauth",
+    "claude",
     "claude-code",
+    "claude-cowork",
+    "claude-connector",
+    "chatgpt",
+    "chatgpt-connector",
+    "cursor",
+    "windsurf",
+    "cli",
     "ai-agent",
     "ai-tools",
     "job-search",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.kevinastuhuaman/trackly",
   "title": "Trackly CLI",
-  "description": "Job search and application tracking for AI agents. Search 128K+ jobs across 1,900+ companies and 40+ ATS types. Filter by role, location, visa sponsorship. Natural language queries. Works with Claude Code, Cursor, Windsurf, and any MCP client.",
+  "description": "AI job search for Claude, ChatGPT, Cursor. 128K+ jobs, 1,900+ companies. OAuth or stdio.",
   "repository": {
     "url": "https://github.com/kevinastuhuaman/trackly-cli",
     "source": "github"
@@ -12,15 +12,17 @@
     {
       "src": "https://usetrackly.app/favicon-512x512.png?v=5",
       "mimeType": "image/png",
-      "sizes": ["512x512"]
+      "sizes": [
+        "512x512"
+      ]
     }
   ],
-  "version": "0.1.12",
+  "version": "0.2.1",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "trackly-cli",
-      "version": "0.1.12",
+      "version": "0.2.1",
       "runtimeHint": "npx",
       "runtimeArguments": [
         {
@@ -46,8 +48,8 @@
       "headers": [
         {
           "name": "Authorization",
-          "description": "Bearer API key (trk_*). Create one at https://usetrackly.app/settings",
-          "isRequired": true,
+          "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",
+          "isRequired": false,
           "isSecret": true
         }
       ]