jd-intel-mcp 0.5.0 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # jd-intel-mcp
 
-MCP server for [jd-intel](https://github.com/prPMDev/jd-intel). Lets any AI assistant (Claude Desktop, Cursor, Windsurf) search open job listings across Greenhouse, Lever, and Ashby through natural conversation.
+MCP server for [jd-intel](https://github.com/prPMDev/jd-intel). Lets any AI assistant (Claude Desktop, Claude Code, Cursor, Windsurf, VS Code) search open job listings across Greenhouse, Lever, Ashby, SmartRecruiters, Teamtailor, Recruitee, and Workday through natural conversation.
 
 > **Stop pasting job descriptions into AI assistants. Let your AI fetch them directly.**
 
@@ -9,7 +9,7 @@ MCP server for [jd-intel](https://github.com/prPMDev/jd-intel). Lets any AI assi
 ## What you can ask
 
 - "Is Stripe hiring PMs in the US?"
-- "Find remote engineering roles at fintech companies, posted in the last two weeks, then draft a cover letter for the best match."
+- "Find remote engineering roles at fintech companies, posted in the last two weeks, then rank them by fit for a senior backend profile."
 - "What companies in your index are in the developer tools space?"
 - "Does Figma use Greenhouse or Lever?"
 
@@ -17,9 +17,31 @@ The AI handles the phrasing. The MCP server handles the calls, filters, and norm
 
 ---
 
-## Install (Claude Desktop)
+## Install
 
-Add this to your Claude Desktop config file:
+### Claude Desktop (one-file install, no terminal)
+
+Download [jd-intel.mcpb](https://github.com/prPMDev/jd-intel/releases/latest/download/jd-intel.mcpb), then in Claude Desktop open **Settings**, then **Extensions**, then **Advanced settings**, and click **Install Extension**. Pick the file, review the access summary, click **Install**, and start a new chat. No Node.js needed (Claude Desktop runs it on its own bundled runtime). It's open source and unsigned, so choose **Install Anyway** if prompted.
+
+Prefer the terminal? Install [Node.js 18+](https://nodejs.org/), then run:
+
+```bash
+npx jd-intel-mcp install
+```
+
+This locates the Claude Desktop config, adds the entry alongside any existing servers, and writes back valid JSON. Quit and reopen Claude Desktop.
+
+### Other clients (Claude Code, Cursor, Windsurf, VS Code)
+
+The same server runs via `npx` (needs Node.js 18+):
+
+- **Claude Code:** `claude mcp add jd-intel -- npx -y jd-intel-mcp`
+- **Cursor / Windsurf:** add under `mcpServers` (`command: "npx"`, `args: ["-y", "jd-intel-mcp"]`) in the client's MCP config.
+- **VS Code (Copilot agent):** add under `servers` with `"type": "stdio"` in `.vscode/mcp.json`.
+
+### Manual config (fallback)
+
+Edit Claude Desktop's config file directly:
 
 **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
 **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
@@ -37,13 +59,6 @@ Add this to your Claude Desktop config file:
 
 Restart Claude Desktop. The tools appear automatically.
 
-**One-command install (avoids hand-editing the config):**
-```bash
-npx jd-intel-mcp install
-```
-
-This detects your OS, locates the Claude Desktop config, adds the entry alongside any existing servers, and writes back valid JSON. Prevents the "paste-a-snippet-into-existing-config" hand-editing error.
-
 ---
 
 ## Tools exposed

package/descriptions.js

@@ -8,7 +8,7 @@
  * the AI's behavior changes immediately when descriptions change.
  */
 
-export const FETCH_JOBS = `Fetch open job postings from a specific company's ATS (Greenhouse, Lever, or Ashby).
+export const FETCH_JOBS = `Fetch open job postings from a specific company's ATS (Greenhouse, Lever, Ashby, SmartRecruiters, Teamtailor, Recruitee, Workday).
 
 USE WHEN: the user asks about roles at a known company ("Is Stripe hiring?", "What's open at Figma?").
 
@@ -32,12 +32,14 @@ location_excludes: array. Drop jobs whose location contains any keyword. Use as
 
 limit: default 100. Reduce for high-volume companies.
 
+workday: optional { tenant, env, site }. Use ONLY for a Workday company not in the registry when the user gives a careers URL. Derive from https://{tenant}.{env}.myworkdayjobs.com/{site}: tenant is the first label, env is the part like wd108, site is the path segment. Overrides the registry for that fetch. Never guess or fabricate these values; use only what the user supplied or what is literally in the careers URL. Omit this argument entirely if you do not have a real URL.
+
 RESPONSE: { status, data: [jobs], metadata: { attempted, succeeded, failed, notes } }. Check status first. "partial" means some adapters failed. Tell the user results may be incomplete.
 
 ERROR CODES:
 - company_not_found: slug not in registry, not detected
-- ats_unreachable: known ATS failed
-- invalid_args: missing/malformed args
+- ats_unreachable: known ATS failed, or a supplied workday {tenant,env,site} was rejected by Workday
+- invalid_args: missing/malformed args, including an incomplete workday triple
 - rate_limited: upstream 429`;
 
 export const SEARCH_REGISTRY = `Find companies in the indexed registry by name or sector.
@@ -60,7 +62,7 @@ RESPONSE: { status, data: [{ slug, name, sector, ats }], metadata }. Each result
 ERROR CODES:
 - invalid_args: both query and sector missing`;
 
-export const DETECT_ATS = `Detect which ATS platform (Greenhouse, Lever, or Ashby) a company uses.
+export const DETECT_ATS = `Detect which ATS platform (Greenhouse, Lever, Ashby, SmartRecruiters, Teamtailor, Recruitee) a company uses by probing. Workday is registry-only and never returned here; find Workday-hosted companies via search_registry or fetch_jobs (which auto-detects from the registry).
 
 USE WHEN: user asks about the ATS platform explicitly ("What ATS does Stripe use?") or for debugging.
 
@@ -70,7 +72,7 @@ ARGUMENT GUIDE:
 
 company: company name or slug. Hyphens and spaces stripped automatically ("Cockroach Labs" → "cockroachlabs").
 
-RESPONSE: { status, data: "greenhouse" | "lever" | "ashby" | null, metadata }. data === null means no supported ATS hosts this company. "partial" status means some probes failed. Result may be incomplete.
+RESPONSE: { status, data: "greenhouse" | "lever" | "ashby" | "smartrecruiters" | "teamtailor" | "recruitee" | null, metadata }. data === null means none of the probeable ATS host this company (Workday is registry-only and never detected here). "partial" status means some probes failed. Result may be incomplete.
 
 ERROR CODES:
 - invalid_args: company arg missing
@@ -80,4 +82,4 @@ export const REGISTRY_RESOURCE = `The full jd-intel company registry, grouped by
 
 Use for broad surveys ("what fintech companies are indexed?", "tell me about the catalog"). Fetched once per session, then cached. Cheaper than repeated search_registry calls for multi-query reasoning.
 
-Shape: { greenhouse: [{slug, name, sector}], lever: [...], ashby: [...] }.`;
+Shape: { greenhouse: [{slug, name, sector}], lever: [...], ashby: [...], smartrecruiters: [...], teamtailor: [...], recruitee: [...], workday: [...] }.`;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "jd-intel-mcp",
-  "version": "0.5.0",
-  "description": "MCP server for jd-intel. Your AI assistant fetches and reasons over full job descriptions, no copy-paste.",
+  "version": "0.8.0",
+  "description": "MCP server for jd-intel. Your AI assistant fetches and reads full job descriptions across seven ATS platforms, no copy-paste.",
   "type": "module",
   "main": "server.js",
   "bin": {
@@ -16,17 +16,19 @@
     "errors.js",
     "descriptions.js",
     "install.js",
+    "version.js",
     "README.md"
   ],
   "scripts": {
     "start": "node server.js",
     "dev": "node --watch server.js",
     "install:local": "node cli.js install",
-    "uninstall:local": "node cli.js uninstall"
+    "uninstall:local": "node cli.js uninstall",
+    "test": "node --test test/*.test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "jd-intel": "^0.5.0",
+    "jd-intel": "^0.8.0",
     "zod": "^3.23.0"
   },
   "keywords": [

package/server.js

@@ -23,11 +23,23 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 
 import { registerTools } from './tools.js';
 import { registerResources } from './resources.js';
+import { VERSION } from './version.js';
 
 async function main() {
+  // Claude Desktop runs this on its OWN bundled Node, not the user's system
+  // Node. Log which version that is (read it in Claude Desktop's MCP logs),
+  // and fail loudly with a human message instead of a cryptic SDK crash if
+  // the runtime is too old.
+  const nodeMajor = Number(process.versions.node.split('.')[0]);
+  console.error(`[jd-intel] runtime check: Node ${process.version} on ${process.platform}/${process.arch}`);
+  if (nodeMajor < 18) {
+    console.error(`[jd-intel] Needs Node 18 or newer, but this runtime is ${process.version}. If you installed via Claude Desktop, update Claude Desktop to the latest version and try again.`);
+    process.exit(1);
+  }
+
   const server = new McpServer({
     name: 'jd-intel',
-    version: '0.1.0',
+    version: VERSION,
   });
 
   registerTools(server);
@@ -37,7 +49,7 @@ async function main() {
   await server.connect(transport);
 
   // Log to stderr so stdout stays clean for MCP protocol traffic
-  console.error('jd-intel MCP server running on stdio');
+  console.error(`jd-intel MCP server ${VERSION} running on stdio`);
 }
 
 main().catch((err) => {

package/tools.js

@@ -10,18 +10,25 @@
  */
 
 import { z } from 'zod';
-import { fetchJobs, detectAts as libDetectAts, registry } from 'jd-intel';
+import { fetchJobs, detectAts as libDetectAts, registry, ATS_NAMES } from 'jd-intel';
 
 const { search: searchRegistry, findAtsBySlug } = registry;
+// Tolerate an older jd-intel that predates getSource. The bundle always
+// vendors a matching version; this only guards a skewed local/global install.
+const getRegistrySource = registry.getSource || (() => 'unknown');
 import { success, partial, error } from './envelope.js';
 import { ERROR_CODES } from './errors.js';
+import { VERSION } from './version.js';
 import {
   FETCH_JOBS,
   SEARCH_REGISTRY,
   DETECT_ATS,
 } from './descriptions.js';
 
-export function registerTools(server) {
+export function registerTools(server, deps = {}) {
+  const _fetchJobs = deps.fetchJobs || fetchJobs;
+  const _findAtsBySlug = deps.findAtsBySlug || findAtsBySlug;
+
   server.registerTool(
     'fetch_jobs',
     {
@@ -35,12 +42,37 @@ export function registerTools(server) {
         location_includes: z.array(z.string()).optional().describe('Keep jobs whose location contains any keyword'),
         location_excludes: z.array(z.string()).optional().describe('Drop jobs whose location contains any keyword'),
         limit: z.number().int().positive().optional().describe('Cap results (default 100)'),
+        workday: z
+          .object({
+            tenant: z.string().trim().min(1).describe('Workday tenant, the first URL label, e.g. "expedia"'),
+            env: z.string().trim().min(1).describe('Workday env/datacenter, e.g. "wd108", "wd5"'),
+            site: z.string().trim().min(1).describe('Workday career-site path, e.g. "search", "Cisco_Careers"'),
+          })
+          .strict()
+          .optional()
+          .describe('Override the registry for a Workday board not indexed. Derive all three from the careers URL https://{tenant}.{env}.myworkdayjobs.com/{site}. Never guess these.'),
       },
     },
     async (args) => {
+      let ats;
+      let config;
+      if (args.workday) {
+        const { tenant, env, site } = args.workday;
+        if (!tenant?.trim() || !env?.trim() || !site?.trim()) {
+          return error(
+            ERROR_CODES.INVALID_ARGS,
+            'workday requires all three of {tenant, env, site}. Read them from the careers URL https://{tenant}.{env}.myworkdayjobs.com/{site}.'
+          );
+        }
+        ats = 'workday';
+        config = { tenant, env, site };
+      }
+
       try {
-        const jobs = await fetchJobs({
+        const jobs = await _fetchJobs({
           company: args.company,
+          ats,
+          config,
           titleFilter: args.title_filter,
           filter: args.filter,
           postedWithinDays: args.posted_within_days,
@@ -50,15 +82,46 @@ export function registerTools(server) {
         });
 
         const normalizedSlug = args.company.toLowerCase().replace(/[^a-z0-9]/g, '');
-        const registryAts = await findAtsBySlug(normalizedSlug);
+        const registryAts = await _findAtsBySlug(normalizedSlug);
+
+        // Discovery miss: not in the registry and no board returned anything.
+        // Guard on !config so a valid Workday override that returns 0 jobs is not
+        // mislabeled; a registry hit with 0 open roles stays a success([]).
+        if (!config && registryAts === null && jobs.length === 0) {
+          return error(
+            ERROR_CODES.COMPANY_NOT_FOUND,
+            `No board found for "${args.company}" on any supported ATS. Check the slug, or pass an explicit workday {tenant,env,site} for a Workday board.`
+          );
+        }
 
         return success(jobs, {
           count: jobs.length,
           registry_hit: registryAts !== null,
-          ats: registryAts,
+          ats: config ? 'workday' : registryAts,
+          workday_override: Boolean(config),
+          version: VERSION,
+          registry_source: getRegistrySource(),
         });
       } catch (err) {
-        return error(ERROR_CODES.INVALID_ARGS, err.message || 'Unknown error');
+        const msg = err.message || 'Unknown error';
+        // Map the library error to the advertised taxonomy. Order matters: a rate
+        // limit surfaces as "...API error...: 429", so the 429 check must run
+        // before the generic /API error/ check. This string-matches the adapters'
+        // message wording (the contained trade-off vs typed errors in the library).
+        if (config && /Workday API error/.test(msg)) {
+          // Keep the Workday triple-repair hint even on a 429.
+          return error(
+            ERROR_CODES.ATS_UNREACHABLE,
+            `Workday rejected ${config.tenant}/${config.env}/${config.site}: ${msg}. Verify the triple against the careers URL https://{tenant}.{env}.myworkdayjobs.com/{site}.`
+          );
+        }
+        if (/:\s*429\b/.test(msg)) {
+          return error(ERROR_CODES.RATE_LIMITED, msg);
+        }
+        if (/API error/.test(msg)) {
+          return error(ERROR_CODES.ATS_UNREACHABLE, msg);
+        }
+        return error(ERROR_CODES.INVALID_ARGS, msg);
       }
     }
   );
@@ -92,6 +155,8 @@ export function registerTools(server) {
         count: filtered.length,
         query: args.query || null,
         sector: args.sector || null,
+        version: VERSION,
+        registry_source: getRegistrySource(),
       });
     }
   );
@@ -109,12 +174,12 @@ export function registerTools(server) {
       const results = await libDetectAts(args.company);
 
       if (results.length === 0) {
-        return success(null, { attempted: ['greenhouse', 'lever', 'ashby'], succeeded: [] });
+        return success(null, { attempted: ATS_NAMES, succeeded: [] });
       }
 
       if (results.length === 1) {
         return success(results[0].ats, {
-          attempted: ['greenhouse', 'lever', 'ashby'],
+          attempted: ATS_NAMES,
           succeeded: [results[0].ats],
         });
       }
@@ -123,7 +188,7 @@ export function registerTools(server) {
       return partial(
         results[0].ats,
         {
-          attempted: ['greenhouse', 'lever', 'ashby'],
+          attempted: ATS_NAMES,
           succeeded: results.map((r) => r.ats),
           notes: [`Company found on multiple platforms: ${results.map((r) => r.ats).join(', ')}. Returning first match.`],
         }

package/version.js

@@ -0,0 +1,12 @@
+/**
+ * Single source of the server version.
+ *
+ * Read from package.json via createRequire — works on every Node 18+ with no
+ * import-attribute version concerns (Claude Desktop's bundled Node version is
+ * not known ahead of time). server.js reports this to the MCP host; tools.js
+ * surfaces it in response metadata so the AI can tell the user what's running.
+ */
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+export const VERSION = require('./package.json').version;