jd-intel-mcp 0.6.0 → 0.8.1

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, Ashby, SmartRecruiters, Teamtailor, Recruitee, and Workday 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.**
 
@@ -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/errors.js

@@ -1,16 +1,9 @@
 /**
  * Error code taxonomy for all MCP tools.
  *
- * Codes are short and stable. Messages are short and factual.
- * The tool description teaches the AI what each code means; errors
- * themselves do not need to be verbose.
+ * The canonical codes now live in the jd-intel library (src/errors.js), so the
+ * library (which throws AtsError with a .code) and the MCP layer share one
+ * source of truth. Re-exported here to keep the existing import path stable.
  */
 
-export const ERROR_CODES = {
-  COMPANY_NOT_FOUND: 'company_not_found',  // Slug not in registry and not detected
-  ATS_UNREACHABLE: 'ats_unreachable',      // Known ATS failed (500, timeout)
-  PARTIAL_FAILURE: 'partial_failure',      // Discovery mode; some adapters failed
-  INVALID_ARGS: 'invalid_args',            // Missing required, wrong type, bad pattern
-  NO_RESULTS: 'no_results',                // Query succeeded, filters returned nothing
-  RATE_LIMITED: 'rate_limited',            // Upstream returned 429
-};
+export { ERROR_CODES } from 'jd-intel';

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "jd-intel-mcp",
-  "version": "0.6.0",
-  "description": "MCP server for jd-intel. Your AI assistant fetches and reasons over full job descriptions, no copy-paste.",
+  "version": "0.8.1",
+  "mcpName": "io.github.prPMDev/jd-intel-mcp",
+  "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,6 +17,7 @@
     "errors.js",
     "descriptions.js",
     "install.js",
+    "version.js",
     "README.md"
   ],
   "scripts": {
@@ -27,7 +29,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "jd-intel": "^0.6.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,11 +10,15 @@
  */
 
 import { z } from 'zod';
-import { fetchJobs, detectAts as libDetectAts, registry } from 'jd-intel';
+import { fetchJobs, detectAts as libDetectAts, registry, ATS_NAMES, AtsError } 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,
@@ -80,20 +84,39 @@ export function registerTools(server, deps = {}) {
         const normalizedSlug = args.company.toLowerCase().replace(/[^a-z0-9]/g, '');
         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: config ? 'workday' : registryAts,
           workday_override: Boolean(config),
+          version: VERSION,
+          registry_source: getRegistrySource(),
         });
       } catch (err) {
         const msg = err.message || 'Unknown error';
-        if (config && /Workday API error/.test(msg)) {
-          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}.`
-          );
+        // AtsError carries a stable .code from the adapter (ats_unreachable /
+        // rate_limited), so we map by code, not by parsing the message.
+        if (err instanceof AtsError) {
+          if (config && err.code === ERROR_CODES.ATS_UNREACHABLE) {
+            // Keep the Workday triple-repair hint.
+            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}.`
+            );
+          }
+          return error(err.code, msg);
         }
+        // Anything else is an arg-validation error from the library.
         return error(ERROR_CODES.INVALID_ARGS, msg);
       }
     }
@@ -128,6 +151,8 @@ export function registerTools(server, deps = {}) {
         count: filtered.length,
         query: args.query || null,
         sector: args.sector || null,
+        version: VERSION,
+        registry_source: getRegistrySource(),
       });
     }
   );
@@ -145,12 +170,12 @@ export function registerTools(server, deps = {}) {
       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],
         });
       }
@@ -159,7 +184,7 @@ export function registerTools(server, deps = {}) {
       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;