trackly-cli 0.1.3 → 0.1.5

package/docs/trackly-tools.md

@@ -1,6 +1,27 @@
 ## Trackly Job Tracker (MCP)
 
-Trackly MCP server provides job search and tracking tools. Add to your Claude Code settings:
+Trackly MCP server provides job search and tracking tools. Start it with:
+
+```bash
+trackly mcp
+```
+
+### Claude Code
+
+```json
+{
+  "mcpServers": {
+    "trackly": {
+      "command": "trackly",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
 
 ```json
 {
@@ -13,6 +34,22 @@ Trackly MCP server provides job search and tracking tools. Add to your Claude Co
 }
 ```
 
+### Authentication
+
+Use either interactive OAuth:
+
+```bash
+trackly login
+```
+
+Or an API key:
+
+```bash
+trackly config --api-key trk_xxxxxxxxxxxxxxxxxxxx
+```
+
+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, location, modality, keywords

package/lib/client.js

@@ -5,33 +5,70 @@ const http = require('http');
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const { version: PACKAGE_VERSION } = require('../package.json');
 
-const CONFIG_DIR = path.join(os.homedir(), '.trackly');
-const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const DEFAULT_CONFIG_DIR = path.join(os.homedir(), '.trackly');
 const DEFAULT_BASE_URL = 'https://closeai.mba';
+const DEFAULT_HTTP_TIMEOUT_MS = 30000;
+const LOCAL_HOSTNAMES = new Set(['localhost', '127.0.0.1', '::1']);
+
+class TracklyConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'TracklyConfigError';
+  }
+}
+
+function getConfigPaths() {
+  const dir = process.env.TRACKLY_CONFIG_DIR || DEFAULT_CONFIG_DIR;
+  return {
+    dir,
+    file: path.join(dir, 'config.json'),
+  };
+}
 
 function loadConfig() {
+  const { file } = getConfigPaths();
   try {
-    if (fs.existsSync(CONFIG_FILE)) {
-      return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    if (fs.existsSync(file)) {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
     }
-  } catch (e) {}
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new TracklyConfigError(`Trackly config is invalid JSON. Fix or delete ${file}.`);
+    }
+    throw error;
+  }
   return {};
 }
 
-function saveConfig(config) {
-  if (!fs.existsSync(CONFIG_DIR)) {
-    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+function ensureConfigDir() {
+  const { dir } = getConfigPaths();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   }
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(dir, 0o700); } catch (e) {}
+  return dir;
+}
+
+function saveConfig(config) {
+  ensureConfigDir();
+  const { file } = getConfigPaths();
+  fs.writeFileSync(file, JSON.stringify(config, null, 2), { mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch (e) {}
 }
 
 function clearConfig() {
-  try { fs.unlinkSync(CONFIG_FILE); } catch (e) {}
+  const { file } = getConfigPaths();
+  try { fs.unlinkSync(file); } catch (e) {}
 }
 
 function getBaseUrl() {
-  return loadConfig().baseUrl || DEFAULT_BASE_URL;
+  return process.env.TRACKLY_BASE_URL || loadConfig().baseUrl || DEFAULT_BASE_URL;
+}
+
+function getApiKey() {
+  return process.env.TRACKLY_API_KEY || loadConfig().apiKey || null;
 }
 
 function getToken() {
@@ -42,15 +79,88 @@ function getRefreshToken() {
   return loadConfig().refreshToken || null;
 }
 
+function getAuthMethod() {
+  if (getApiKey()) return 'apiKey';
+  if (getToken()) return 'token';
+  return null;
+}
+
+function hasAuth() {
+  return Boolean(getAuthMethod());
+}
+
+function getAuthHeader(skipAuth = false) {
+  if (skipAuth) return null;
+
+  const apiKey = getApiKey();
+  if (apiKey) return `Bearer ${apiKey}`;
+
+  const token = getToken();
+  if (token) return `Bearer ${token}`;
+
+  return null;
+}
+
+function normalizeEndpoint(endpoint, baseUrl = getBaseUrl()) {
+  const base = new URL(baseUrl);
+  const url = new URL(endpoint, base);
+
+  if (url.origin !== base.origin) {
+    throw new Error(
+      `Refusing to send Trackly requests to a different origin (${url.origin}). ` +
+      'Configure TRACKLY_BASE_URL or use `trackly config --base-url <url>` instead.'
+    );
+  }
+
+  return url;
+}
+
+function isLocalHttpUrl(url) {
+  return url.protocol === 'http:' && LOCAL_HOSTNAMES.has(url.hostname);
+}
+
+function ensureSecureUrl(url, reason = 'credentials') {
+  if (url.protocol === 'https:' || isLocalHttpUrl(url)) {
+    return;
+  }
+
+  throw new Error(
+    `Refusing to send ${reason} over insecure connection (${url.origin}). Use HTTPS or localhost.`
+  );
+}
+
+function getRequestTimeoutMs() {
+  const configuredValue = process.env.TRACKLY_HTTP_TIMEOUT_MS || loadConfig().timeoutMs;
+  const timeoutMs = Number(configuredValue);
+
+  if (Number.isFinite(timeoutMs) && timeoutMs > 0) {
+    return timeoutMs;
+  }
+
+  return DEFAULT_HTTP_TIMEOUT_MS;
+}
+
+function getRequestHeaders(skipAuth = false, userAgent = null) {
+  const headers = {
+    'Content-Type': 'application/json',
+    'Accept': 'application/json',
+    'User-Agent': userAgent || `trackly-cli/${PACKAGE_VERSION}`,
+  };
+
+  const authHeader = getAuthHeader(skipAuth);
+  if (authHeader) {
+    headers['Authorization'] = authHeader;
+  }
+
+  return headers;
+}
+
 async function refreshAccessToken() {
   const rt = getRefreshToken();
   if (!rt) return null;
-  const baseUrl = getBaseUrl();
-  if (!baseUrl.startsWith('https://') && !baseUrl.startsWith('http://localhost')) {
-    console.error('Warning: Refusing to send refresh token over insecure connection');
-    return null;
-  }
+
   try {
+    ensureSecureUrl(normalizeEndpoint('/api/auth/refresh'), 'refresh tokens');
     const result = await apiRequest('POST', '/api/auth/refresh', { refreshToken: rt }, true);
     if (result.success && result.token) {
       const config = loadConfig();
@@ -65,20 +175,28 @@ async function refreshAccessToken() {
 
 function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry = false, userAgent = null) {
   return new Promise((resolve, reject) => {
-    const baseUrl = getBaseUrl();
-    const url = new URL(endpoint, baseUrl);
+    let url;
+    try {
+      url = normalizeEndpoint(endpoint);
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
     const isHttps = url.protocol === 'https:';
     const lib = isHttps ? https : http;
+    const headers = getRequestHeaders(skipAuth, userAgent);
+    const authMethod = getAuthMethod();
+    const timeoutMs = getRequestTimeoutMs();
+    const hasSensitivePayload = Boolean(data && typeof data === 'object' && 'refreshToken' in data);
 
-    const headers = {
-      'Content-Type': 'application/json',
-      'Accept': 'application/json',
-      'User-Agent': userAgent || 'trackly-cli/0.1.3',
-    };
-
-    if (!skipAuth) {
-      const token = getToken();
-      if (token) headers['Authorization'] = `Bearer ${token}`;
+    try {
+      if (headers['Authorization'] || hasSensitivePayload) {
+        ensureSecureUrl(url, hasSensitivePayload ? 'refresh tokens' : 'credentials');
+      }
+    } catch (error) {
+      reject(error);
+      return;
     }
 
     const options = {
@@ -87,6 +205,7 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
       path: url.pathname + url.search,
       method,
       headers,
+      timeout: timeoutMs,
     };
 
     const req = lib.request(options, (res) => {
@@ -94,9 +213,9 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
       res.on('data', chunk => body += chunk);
       res.on('end', async () => {
         let json;
-        try { json = JSON.parse(body); } catch { json = { raw: body }; }
+        try { json = body ? JSON.parse(body) : {}; } catch { json = { raw: body }; }
 
-        if (res.statusCode === 401 && !skipAuth && !_isRetry) {
+        if (res.statusCode === 401 && !skipAuth && authMethod === 'token' && !_isRetry) {
           // Try token refresh (once only)
           const newToken = await refreshAccessToken();
           if (newToken) {
@@ -115,10 +234,35 @@ function apiRequest(method, endpoint, data = null, skipAuth = false, _isRetry =
       });
     });
 
+    req.on('timeout', () => {
+      req.destroy(new Error(`Trackly request timed out after ${timeoutMs}ms`));
+    });
     req.on('error', reject);
     if (data) req.write(JSON.stringify(data));
     req.end();
   });
 }
 
-module.exports = { loadConfig, saveConfig, clearConfig, apiRequest, getToken, CONFIG_DIR, CONFIG_FILE };
+module.exports = {
+  DEFAULT_BASE_URL,
+  DEFAULT_CONFIG_DIR,
+  DEFAULT_HTTP_TIMEOUT_MS,
+  TracklyConfigError,
+  apiRequest,
+  clearConfig,
+  ensureSecureUrl,
+  getApiKey,
+  getAuthHeader,
+  getAuthMethod,
+  getBaseUrl,
+  getConfigPaths,
+  getRequestHeaders,
+  getRequestTimeoutMs,
+  getToken,
+  hasAuth,
+  loadConfig,
+  normalizeEndpoint,
+  saveConfig,
+  CONFIG_DIR: DEFAULT_CONFIG_DIR,
+  CONFIG_FILE: path.join(DEFAULT_CONFIG_DIR, 'config.json'),
+};

package/mcp/server.js

@@ -3,163 +3,190 @@
 const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { z } = require('zod');
-const { apiRequest, getToken } = require('../lib/client');
-
-const MCP_USER_AGENT = 'trackly-mcp/0.1.3';
-
-const server = new McpServer({
-  name: 'trackly',
-  version: '0.1.3',
-});
-
-// Tool: Search/filter jobs
-server.tool(
-  'trackly_search_jobs',
-  'Search and filter job postings. Returns matching jobs with title, company, location, modality.',
-  {
-    function: z.enum(['product_management','engineering','design','data_science','marketing','sales','finance','operations','legal','hr','other']).optional().describe('Job function filter: product_management, engineering, design, data_science, marketing, sales, finance, operations, legal, hr, other'),
-    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'),
-    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'),
-  },
-  async (params) => {
-    const qs = new URLSearchParams();
-    for (const [k, v] of Object.entries(params)) {
-      if (v !== undefined && v !== null) qs.set(k, String(v));
-    }
-    try {
-      const result = await apiRequest('GET', `/api/jobscout/jobs?${qs.toString()}`, null, false, false, MCP_USER_AGENT);
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    } catch (e) {
-      return { content: [{ type: 'text', text: JSON.stringify({ error: e.error || e.message }) }], isError: true };
-    }
-  }
-);
-
-// Tool: Get job detail
-server.tool(
-  'trackly_get_job',
-  'Get full details for a specific job posting including description.',
-  {
-    id: z.number().describe('Job posting ID'),
-  },
-  async ({ id }) => {
-    try {
-      const result = await apiRequest('GET', `/api/jobscout/jobs/${id}`, null, false, false, MCP_USER_AGENT);
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    } catch (e) {
-      return { content: [{ type: 'text', text: JSON.stringify({ error: e.error || e.message }) }], isError: true };
-    }
-  }
-);
-
-// Tool: Search companies
-server.tool(
-  'trackly_search_companies',
-  'Semantic search for companies by name, domain, or keywords.',
-  {
-    query: z.string().max(500).describe('Search query'),
-    limit: z.number().max(50).optional().describe('Max results (default 10)'),
-  },
-  async ({ query, limit }) => {
-    const qs = new URLSearchParams({ q: query });
-    if (limit) qs.set('limit', String(limit));
-    try {
-      const result = await apiRequest('GET', `/api/jobscout/companies/search?${qs.toString()}`, null, false, false, MCP_USER_AGENT);
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    } catch (e) {
-      return { content: [{ type: 'text', text: JSON.stringify({ error: e.error || e.message }) }], isError: true };
-    }
-  }
-);
-
-// Tool: List companies
-server.tool(
-  'trackly_list_companies',
-  'List all tracked companies with their active job counts.',
-  {
-    limit: z.number().max(50).optional().describe('Max results'),
-    offset: z.number().min(0).optional().describe('Pagination offset'),
-  },
-  async ({ limit, offset }) => {
-    const qs = new URLSearchParams();
-    if (limit) qs.set('limit', String(limit));
-    if (offset) qs.set('offset', String(offset));
-    try {
-      const result = await apiRequest('GET', `/api/jobscout/companies?${qs.toString()}`, null, false, false, MCP_USER_AGENT);
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    } catch (e) {
-      return { content: [{ type: 'text', text: JSON.stringify({ error: e.error || e.message }) }], isError: true };
-    }
+const { apiRequest, hasAuth } = require('../lib/client');
+const { version: PACKAGE_VERSION } = require('../package.json');
+
+const MCP_USER_AGENT = `trackly-mcp/${PACKAGE_VERSION}`;
+const AUTH_HINT = 'Run `trackly login` or configure an API key with `trackly config --api-key <key>`.';
+
+function createErrorResult(error, fallbackMessage, extra = {}) {
+  const payload = {
+    error: error?.error || error?.message || fallbackMessage,
+    ...extra,
+  };
+
+  if (error?.status) {
+    payload.status = error.status;
   }
-);
-
-// Tool: Get stats
-server.tool(
-  'trackly_get_stats',
-  'Get job tracker metrics: total jobs, companies, application status counts.',
-  {},
-  async () => {
-    try {
-      const result = await apiRequest('GET', '/api/jobscout/me', null, false, false, MCP_USER_AGENT);
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    } catch (e) {
-      return { content: [{ type: 'text', text: JSON.stringify({ error: e.error || e.message }) }], isError: true };
-    }
+
+  if (error?.status === 429 && !payload.hint) {
+    payload.hint = 'Daily limit reached (20 natural language queries per day).';
   }
-);
-
-// Tool: Update job status
-server.tool(
-  'trackly_update_status',
-  'Update a job application status (apply, save, or dismiss).',
-  {
-    id: z.number().describe('Job posting ID'),
-    action: z.enum(['applied', 'saved', 'dismissed']).describe('Status action'),
-  },
-  async ({ id, action }) => {
+
+  return {
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    isError: true,
+  };
+}
+
+function createAuthErrorResult() {
+  return createErrorResult(
+    { message: 'Not authenticated', status: 401 },
+    'Not authenticated',
+    { hint: AUTH_HINT }
+  );
+}
+
+function wrapTool(handler, fallbackMessage) {
+  return async (params) => {
     try {
-      const result = await apiRequest('POST', '/api/jobscout-tracker/status', { jobId: id, action }, false, false, MCP_USER_AGENT);
-      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
-    } catch (e) {
-      return { content: [{ type: 'text', text: JSON.stringify({ error: e.error || e.message }) }], isError: true };
+      if (!hasAuth()) {
+        return createAuthErrorResult();
+      }
+
+      const result = await handler(params);
+      return {
+        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+      };
+    } catch (error) {
+      return createErrorResult(
+        error,
+        fallbackMessage,
+        error?.status === 401 ? { hint: AUTH_HINT } : {}
+      );
     }
-  }
-);
-
-// Tool: Natural language search
-server.tool(
-  'trackly_ask',
-  'Natural language job search. Describe what you are looking for and the AI parses it into structured filters. Limited to 20 queries per day.',
-  {
-    query: z.string().max(500).describe('Natural language search query, e.g. "PM jobs at fintech companies in SF"'),
-  },
-  async ({ query }) => {
-    try {
+  };
+}
+
+function createServer() {
+  const server = new McpServer({
+    name: 'trackly',
+    version: PACKAGE_VERSION,
+  });
+
+  server.tool(
+    'trackly_search_jobs',
+    'Search and filter job postings. Returns matching jobs with title, company, location, modality.',
+    {
+      function: z.enum(['product_management', 'engineering', 'design', 'data_science', 'marketing', 'sales', 'finance', 'operations', 'legal', 'hr', 'other']).optional().describe('Job function filter: product_management, engineering, design, data_science, marketing, sales, finance, operations, legal, hr, other'),
+      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'),
+      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'),
+    },
+    wrapTool(async (params) => {
+      const qs = new URLSearchParams();
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== undefined && value !== null) qs.set(key, String(value));
+      }
+      return apiRequest('GET', `/api/jobscout/jobs?${qs.toString()}`, null, false, false, MCP_USER_AGENT);
+    }, 'Failed to search jobs')
+  );
+
+  server.tool(
+    'trackly_get_job',
+    'Get full details for a specific job posting including description.',
+    {
+      id: z.number().describe('Job posting ID'),
+    },
+    wrapTool(async ({ id }) => {
+      return apiRequest('GET', `/api/jobscout/jobs/${id}`, null, false, false, MCP_USER_AGENT);
+    }, 'Failed to fetch job')
+  );
+
+  server.tool(
+    'trackly_search_companies',
+    'Semantic search for companies by name, domain, or keywords.',
+    {
+      query: z.string().max(500).describe('Search query'),
+      limit: z.number().max(50).optional().describe('Max results (default 10)'),
+    },
+    wrapTool(async ({ query, limit }) => {
+      const qs = new URLSearchParams({ q: query });
+      if (limit) qs.set('limit', String(limit));
+      return apiRequest('GET', `/api/jobscout/companies/search?${qs.toString()}`, null, false, false, MCP_USER_AGENT);
+    }, 'Failed to search companies')
+  );
+
+  server.tool(
+    'trackly_list_companies',
+    'List all tracked companies with their active job counts.',
+    {
+      limit: z.number().max(50).optional().describe('Max results'),
+      offset: z.number().min(0).optional().describe('Pagination offset'),
+    },
+    wrapTool(async ({ limit, offset }) => {
+      const qs = new URLSearchParams();
+      if (limit) qs.set('limit', String(limit));
+      if (offset !== undefined) qs.set('offset', String(offset));
+      return apiRequest('GET', `/api/jobscout/companies?${qs.toString()}`, null, false, false, MCP_USER_AGENT);
+    }, 'Failed to list companies')
+  );
+
+  server.tool(
+    'trackly_get_stats',
+    'Get job tracker metrics: total jobs, companies, application status counts.',
+    {},
+    wrapTool(async () => {
+      return apiRequest('GET', '/api/jobscout/me', null, false, false, MCP_USER_AGENT);
+    }, 'Failed to fetch stats')
+  );
+
+  server.tool(
+    'trackly_update_status',
+    'Update a job application status (apply, save, or dismiss).',
+    {
+      id: z.number().describe('Job posting ID'),
+      action: z.enum(['applied', 'saved', 'dismissed']).describe('Status action'),
+    },
+    wrapTool(async ({ id, action }) => {
+      return apiRequest('POST', '/api/jobscout-tracker/status', { jobId: id, action }, false, false, MCP_USER_AGENT);
+    }, 'Failed to update job status')
+  );
+
+  server.tool(
+    'trackly_ask',
+    'Natural language job search. Describe what you are looking for and the AI parses it into structured filters. Limited to 20 queries per day.',
+    {
+      query: z.string().max(500).describe('Natural language search query, e.g. "PM jobs at fintech companies in SF"'),
+    },
+    wrapTool(async ({ query }) => {
       const askResult = await apiRequest('GET', `/api/jobscout/ask?q=${encodeURIComponent(query)}`, null, false, false, MCP_USER_AGENT);
-      // Auto-fetch jobs with parsed filters
-      if (askResult.jobsUrl && askResult.jobsUrl.startsWith('/api/')) {
+      if (askResult.jobsUrl) {
         const jobsResult = await apiRequest('GET', askResult.jobsUrl, null, false, false, MCP_USER_AGENT);
-        return { content: [{ type: 'text', text: JSON.stringify({ ...askResult, jobs: jobsResult.jobs || jobsResult.data || [] }, null, 2) }] };
+        return {
+          ...askResult,
+          jobs: jobsResult.jobs || jobsResult.data || [],
+        };
       }
-      return { content: [{ type: 'text', text: JSON.stringify(askResult, null, 2) }] };
-    } catch (e) {
-      return { content: [{ type: 'text', text: JSON.stringify({ error: e.error || e.message }) }], isError: true };
-    }
-  }
-);
+      return askResult;
+    }, 'Failed to process natural language query')
+  );
+
+  return server;
+}
 
-// Start server
-async function main() {
+async function startMcpServer() {
+  const server = createServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
+  return server;
+}
+
+if (require.main === module) {
+  startMcpServer().catch((error) => {
+    console.error('MCP server error:', error);
+    process.exit(1);
+  });
 }
 
-main().catch((e) => {
-  console.error('MCP server error:', e);
-  process.exit(1);
-});
+module.exports = {
+  AUTH_HINT,
+  createAuthErrorResult,
+  createErrorResult,
+  createServer,
+  startMcpServer,
+};