jd-intel-mcp 0.1.0

package/README.md

@@ -0,0 +1,119 @@
+# 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.
+
+> **Stop pasting job descriptions into AI assistants. Let your AI fetch them directly.**
+
+---
+
+## 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."
+- "What companies in your index are in the developer tools space?"
+- "Does Figma use Greenhouse or Lever?"
+
+The AI handles the phrasing. The MCP server handles the calls, filters, and normalizes results. No copy-paste.
+
+---
+
+## Install (Claude Desktop)
+
+Add this to your Claude Desktop config file:
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "jd-intel": {
+      "command": "npx",
+      "args": ["-y", "jd-intel-mcp"]
+    }
+  }
+}
+```
+
+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
+
+| Tool | Purpose |
+|------|---------|
+| `fetch_jobs` | Get open roles at a company, with filters for role type, topic, location, and recency |
+| `search_registry` | Find companies by name or sector |
+| `detect_ats` | Identify which ATS platform a company uses |
+
+Plus one Resource: `registry://jd-intel/all`. Full company registry, grouped by ATS, for broad catalog surveys.
+
+---
+
+## Filter design
+
+See the main library [docs/filters.md](../docs/filters.md) for the full rationale. Short version:
+
+- Use `title_filter` for role identity ("product manager", "staff engineer"). Matches title only.
+- Use `filter` for topic or scope ("integrations", "growth"). Matches across title, department, description.
+- They AND together. Use both for "PM roles about integrations".
+- For US queries: `location_includes: ["United States", "US", "Remote - US"]`. Avoid bare "Remote" (matches Remote-EMEA etc.).
+- Short codes like "US", "UK" are safe. They use word-boundary matching to prevent collisions with "Australia", "Auckland", etc.
+
+---
+
+## Local development
+
+```bash
+cd mcp
+npm install
+node server.js
+```
+
+The server prints `jd-intel MCP server running on stdio` and then listens on stdin/stdout. For quick testing, point Claude Desktop at the local path:
+
+```json
+{
+  "mcpServers": {
+    "jd-intel-dev": {
+      "command": "node",
+      "args": ["/absolute/path/to/jd-intel/mcp/server.js"]
+    }
+  }
+}
+```
+
+---
+
+## Response shape
+
+All three tools return a uniform envelope:
+
+```json
+{
+  "status": "success" | "partial" | "error",
+  "data": <tool-specific>,
+  "metadata": {
+    "attempted": [...],
+    "succeeded": [...],
+    "failed": {...},
+    "notes": [...]
+  }
+}
+```
+
+On errors, the envelope adds `"error": { "code", "message" }`. Error codes come from a fixed taxonomy (`company_not_found`, `ats_unreachable`, `invalid_args`, `partial_failure`, `rate_limited`, `no_results`).
+
+---
+
+## License
+
+MIT

package/cli.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+/**
+ * Dispatcher entry point.
+ *
+ * - No args (default, how Claude Desktop invokes us) → start the MCP server
+ * - "install" → set up Claude Desktop config
+ * - "uninstall" → remove from Claude Desktop config
+ * - "help" / "-h" / "--help" → show usage
+ */
+
+const [, , command] = process.argv;
+
+switch (command) {
+  case 'install': {
+    const { install } = await import('./install.js');
+    await install();
+    break;
+  }
+  case 'uninstall': {
+    const { uninstall } = await import('./install.js');
+    await uninstall();
+    break;
+  }
+  case 'help':
+  case '-h':
+  case '--help': {
+    const { printHelp } = await import('./install.js');
+    printHelp();
+    break;
+  }
+  default: {
+    // No command → start the MCP server.
+    // This is the path Claude Desktop invokes via `npx -y jd-intel-mcp`.
+    await import('./server.js');
+  }
+}

package/descriptions.js

@@ -0,0 +1,83 @@
+/**
+ * Tool descriptions — the semantic contract each tool exposes to the AI.
+ *
+ * These strings are loaded into the AI's context on every turn. Every
+ * sentence must earn its place. Dense > long. Target: 200-400 tokens each.
+ *
+ * Updating these strings is a product decision, not a docs task —
+ * 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).
+
+USE WHEN: the user asks about roles at a known company ("Is Stripe hiring?", "What's open at Figma?").
+
+DON'T USE WHEN:
+- User doesn't know the company → read the registry Resource or call search_registry
+- User only asks which ATS a company uses → call detect_ats
+
+ARGUMENT GUIDE:
+
+company: lowercase slug, no spaces (e.g. "stripe", "cockroachlabs"). Hyphens and spaces auto-stripped.
+
+title_filter: JavaScript-compatible regex matched against TITLE ONLY. Case-insensitive by default. Do NOT use inline flags like (?i) (not supported by V8). Use for role identity ("product manager", "staff engineer"). Does NOT match description text. That's the distinction from filter.
+
+filter: JavaScript-compatible regex matched across title + department + description. Case-insensitive by default. Do NOT use inline flags like (?i). Use for topic/scope ("integrations", "growth"). AND'd with title_filter.
+
+posted_within_days: number. "recent" or "new" → 30. "this week" → 7. "today" → 1.
+
+location_includes: array of keywords. Case-insensitive substring match; short codes (US, UK) use word-boundary matching automatically. For US queries prefer ["United States", "US", "Remote - US"]. Avoid bare "Remote". It matches Remote-EMEA, Remote-LatAm.
+
+location_excludes: array. Drop jobs whose location contains any keyword. Use as refinement on top of includes.
+
+limit: default 100. Reduce for high-volume companies.
+
+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
+- rate_limited: upstream 429`;
+
+export const SEARCH_REGISTRY = `Find companies in the indexed registry by name or sector.
+
+USE WHEN: targeted lookups ("Is Stripe in your index?", "Show me fintech companies").
+
+DON'T USE WHEN:
+- User wants a broad survey of the catalog → read the registry://jd-intel/all Resource instead (one fetch vs repeated tool calls)
+- User asks about a specific company's jobs → call fetch_jobs directly
+
+ARGUMENT GUIDE:
+
+query: optional. Substring match (case-insensitive) against company name.
+sector: optional. Match against sector field. Examples: "fintech", "developer tools", "marketing tech".
+
+At least one argument required. Returns companies matching either.
+
+RESPONSE: { status, data: [{ slug, name, sector, ats }], metadata }. Each result includes the ATS platform for that company.
+
+ERROR CODES:
+- invalid_args: both query and sector missing`;
+
+export const DETECT_ATS = `Detect which ATS platform (Greenhouse, Lever, or Ashby) a company uses.
+
+USE WHEN: user asks about the ATS platform explicitly ("What ATS does Stripe use?") or for debugging.
+
+DON'T USE WHEN: you want to fetch jobs. Call fetch_jobs directly (it auto-detects internally).
+
+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.
+
+ERROR CODES:
+- invalid_args: company arg missing
+- partial_failure: some probes failed`;
+
+export const REGISTRY_RESOURCE = `The full jd-intel company registry, grouped by ATS platform.
+
+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: [...] }.`;

package/envelope.js

@@ -0,0 +1,38 @@
+/**
+ * Uniform response envelope for all MCP tools.
+ *
+ * Shape: { status, data, metadata }
+ * status: "success" | "partial" | "error"
+ *
+ * The envelope is serialized as JSON text inside an MCP content block.
+ * Every tool uses this so the AI learns one response pattern that works
+ * across success, partial-failure, and error paths.
+ */
+
+export function success(data, metadata = {}) {
+  return wrap({ status: 'success', data, metadata });
+}
+
+export function partial(data, metadata = {}) {
+  return wrap({ status: 'partial', data, metadata });
+}
+
+export function error(code, message, metadata = {}) {
+  return wrap({
+    status: 'error',
+    data: null,
+    error: { code, message },
+    metadata,
+  });
+}
+
+function wrap(payload) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(payload, null, 2),
+      },
+    ],
+  };
+}

package/errors.js

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+
+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
+};

package/install.js

@@ -0,0 +1,142 @@
+/**
+ * One-command installer for jd-intel-mcp in Claude Desktop.
+ *
+ * Usage: npx jd-intel-mcp install
+ *
+ * What it does:
+ *   1. Detects the user's OS
+ *   2. Locates Claude Desktop's config file
+ *   3. Reads existing config (preserves other MCP servers)
+ *   4. Adds or updates the jd-intel entry
+ *   5. Writes back as valid JSON
+ *   6. Prints next steps
+ *
+ * Prevents the "paste a snippet into existing config and break JSON" error
+ * that hand-editing reliably produces.
+ */
+
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir, platform } from 'node:os';
+
+const PACKAGE_NAME = 'jd-intel-mcp';
+const SERVER_KEY = 'jd-intel';
+
+function configPathFor(os) {
+  const home = homedir();
+  switch (os) {
+    case 'darwin':
+      return join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    case 'win32':
+      return join(process.env.APPDATA || join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+    case 'linux':
+      return join(home, '.config', 'Claude', 'claude_desktop_config.json');
+    default:
+      return null;
+  }
+}
+
+export async function install() {
+  const os = platform();
+  const configPath = configPathFor(os);
+
+  if (!configPath) {
+    console.error(`Unsupported platform: ${os}. Supported: macOS, Windows, Linux.`);
+    process.exit(1);
+  }
+
+  console.log(`Installing ${PACKAGE_NAME} in Claude Desktop config.`);
+  console.log(`Config file: ${configPath}\n`);
+
+  let config = {};
+  let existed = false;
+
+  if (existsSync(configPath)) {
+    existed = true;
+    const raw = await readFile(configPath, 'utf-8');
+    try {
+      config = JSON.parse(raw);
+    } catch (err) {
+      console.error('Your existing Claude Desktop config is not valid JSON.');
+      console.error(`Fix it manually first, or back it up and run this again.`);
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  } else {
+    // Make sure the parent directory exists before writing
+    await mkdir(dirname(configPath), { recursive: true });
+    console.log('Config file did not exist — creating it.\n');
+  }
+
+  if (!config.mcpServers || typeof config.mcpServers !== 'object') {
+    config.mcpServers = {};
+  }
+
+  const alreadyInstalled = Boolean(config.mcpServers[SERVER_KEY]);
+
+  config.mcpServers[SERVER_KEY] = {
+    command: 'npx',
+    args: ['-y', PACKAGE_NAME],
+  };
+
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+
+  console.log(
+    alreadyInstalled
+      ? `Updated existing ${SERVER_KEY} entry.`
+      : `Added ${SERVER_KEY} to mcpServers.`
+  );
+
+  const otherServers = Object.keys(config.mcpServers).filter((k) => k !== SERVER_KEY);
+  if (otherServers.length > 0) {
+    console.log(`Preserved other MCP servers: ${otherServers.join(', ')}`);
+  }
+
+  console.log('\nNext steps:');
+  console.log('  1. Fully quit Claude Desktop (system tray → Quit on Windows, ⌘Q on macOS)');
+  console.log('  2. Reopen Claude Desktop');
+  console.log('  3. Start a new chat — jd-intel tools will be available');
+  console.log('\nTry: "What fintech companies are in your jd-intel?"\n');
+}
+
+export async function uninstall() {
+  const os = platform();
+  const configPath = configPathFor(os);
+
+  if (!configPath || !existsSync(configPath)) {
+    console.log('No Claude Desktop config found. Nothing to uninstall.');
+    return;
+  }
+
+  const raw = await readFile(configPath, 'utf-8');
+  let config;
+  try {
+    config = JSON.parse(raw);
+  } catch {
+    console.error('Existing config is not valid JSON. Leaving it alone.');
+    process.exit(1);
+  }
+
+  if (!config.mcpServers || !config.mcpServers[SERVER_KEY]) {
+    console.log(`${SERVER_KEY} is not installed. Nothing to do.`);
+    return;
+  }
+
+  delete config.mcpServers[SERVER_KEY];
+  await writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+
+  console.log(`Removed ${SERVER_KEY} from Claude Desktop config.`);
+  console.log('Restart Claude Desktop to complete the uninstall.');
+}
+
+export function printHelp() {
+  console.log(`jd-intel-mcp — MCP server for searching jobs across ATS platforms
+
+Usage:
+  npx jd-intel-mcp            Start the MCP server (invoked by Claude Desktop)
+  npx jd-intel-mcp install    Configure Claude Desktop to use this server
+  npx jd-intel-mcp uninstall  Remove this server from Claude Desktop config
+  npx jd-intel-mcp help       Show this help message
+`);
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "jd-intel-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for jd-intel. Your AI assistant fetches and reasons over full job descriptions, no copy-paste.",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "jd-intel-mcp": "./cli.js"
+  },
+  "files": [
+    "cli.js",
+    "server.js",
+    "tools.js",
+    "resources.js",
+    "envelope.js",
+    "errors.js",
+    "descriptions.js",
+    "install.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"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "jd-intel": "^0.1.0",
+    "zod": "^3.23.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "jd",
+    "job-description",
+    "jobs",
+    "ats",
+    "claude",
+    "greenhouse",
+    "lever",
+    "ashby"
+  ],
+  "author": "Prashant R",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/prPMDev/jd-intel.git",
+    "directory": "mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/prPMDev/jd-intel/issues"
+  },
+  "homepage": "https://github.com/prPMDev/jd-intel#readme",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/resources.js

@@ -0,0 +1,40 @@
+/**
+ * Register Resources on the MCP server.
+ *
+ * The registry is exposed as a Resource for broad catalog surveys.
+ * Tools (search_registry) handle directed queries; the Resource
+ * covers the "tell me about the whole index" intent without needing
+ * repeated tool calls.
+ *
+ * Resources are lazy-loaded — the AI only fetches when it decides
+ * it needs the full catalog. One fetch per session for broad reasoning.
+ */
+
+import { registry } from 'jd-intel';
+
+const { load: loadRegistry } = registry;
+import { REGISTRY_RESOURCE } from './descriptions.js';
+
+export function registerResources(server) {
+  server.registerResource(
+    'registry',
+    'registry://jd-intel/all',
+    {
+      title: 'jd-intel company registry',
+      description: REGISTRY_RESOURCE,
+      mimeType: 'application/json',
+    },
+    async (uri) => {
+      const all = await loadRegistry();
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: 'application/json',
+            text: JSON.stringify(all, null, 2),
+          },
+        ],
+      };
+    }
+  );
+}

package/server.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+/**
+ * jd-intel MCP server — entry point.
+ *
+ * Exposes fetch_jobs, search_registry, and detect_ats as MCP tools,
+ * plus the full company registry as a Resource, over stdio transport.
+ *
+ * Run locally:   node mcp/server.js
+ * Via Claude Desktop config:
+ *   {
+ *     "mcpServers": {
+ *       "jd-intel": {
+ *         "command": "npx",
+ *         "args": ["-y", "jd-intel-mcp"]
+ *       }
+ *     }
+ *   }
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { registerTools } from './tools.js';
+import { registerResources } from './resources.js';
+
+async function main() {
+  const server = new McpServer({
+    name: 'jd-intel',
+    version: '0.1.0',
+  });
+
+  registerTools(server);
+  registerResources(server);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  // Log to stderr so stdout stays clean for MCP protocol traffic
+  console.error('jd-intel MCP server running on stdio');
+}
+
+main().catch((err) => {
+  console.error('Fatal error starting jd-intel MCP:', err);
+  process.exit(1);
+});

package/tools.js

@@ -0,0 +1,133 @@
+/**
+ * Register all three tools on the MCP server.
+ *
+ * Each handler:
+ *   1. Validates args (Zod handles most of this)
+ *   2. Calls the jd-intel library
+ *   3. Wraps the result in the uniform envelope
+ *
+ * Handlers stay thin — library does the work, MCP layer shapes the response.
+ */
+
+import { z } from 'zod';
+import { fetchJobs, detectAts as libDetectAts, registry } from 'jd-intel';
+
+const { search: searchRegistry, findAtsBySlug } = registry;
+import { success, partial, error } from './envelope.js';
+import { ERROR_CODES } from './errors.js';
+import {
+  FETCH_JOBS,
+  SEARCH_REGISTRY,
+  DETECT_ATS,
+} from './descriptions.js';
+
+export function registerTools(server) {
+  server.registerTool(
+    'fetch_jobs',
+    {
+      title: 'Fetch jobs from a company ATS',
+      description: FETCH_JOBS,
+      inputSchema: {
+        company: z.string().describe('Company slug or name (e.g. "stripe")'),
+        title_filter: z.string().optional().describe('Regex matched against title only — role identity'),
+        filter: z.string().optional().describe('Regex matched across title, department, description — topic/scope'),
+        posted_within_days: z.number().int().positive().optional().describe('Only jobs posted within N days'),
+        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)'),
+      },
+    },
+    async (args) => {
+      try {
+        const jobs = await fetchJobs({
+          company: args.company,
+          titleFilter: args.title_filter,
+          filter: args.filter,
+          postedWithinDays: args.posted_within_days,
+          locationIncludes: args.location_includes,
+          locationExcludes: args.location_excludes,
+          limit: args.limit,
+        });
+
+        const normalizedSlug = args.company.toLowerCase().replace(/[^a-z0-9]/g, '');
+        const registryAts = await findAtsBySlug(normalizedSlug);
+
+        return success(jobs, {
+          count: jobs.length,
+          registry_hit: registryAts !== null,
+          ats: registryAts,
+        });
+      } catch (err) {
+        return error(ERROR_CODES.INVALID_ARGS, err.message || 'Unknown error');
+      }
+    }
+  );
+
+  server.registerTool(
+    'search_registry',
+    {
+      title: 'Search the company registry',
+      description: SEARCH_REGISTRY,
+      inputSchema: {
+        query: z.string().optional().describe('Substring match against company name'),
+        sector: z.string().optional().describe('Match against sector (e.g. "fintech", "developer tools")'),
+      },
+    },
+    async (args) => {
+      if (!args.query && !args.sector) {
+        return error(ERROR_CODES.INVALID_ARGS, 'Provide query or sector');
+      }
+
+      // searchRegistry searches both name and sector via a single query string.
+      // We combine args into a single search string, preferring query if both given.
+      const searchTerm = args.query || args.sector;
+      const results = await searchRegistry(searchTerm);
+
+      // If sector was specified, further filter by sector match
+      const filtered = args.sector
+        ? results.filter((r) => (r.sector || '').toLowerCase().includes(args.sector.toLowerCase()))
+        : results;
+
+      return success(filtered, {
+        count: filtered.length,
+        query: args.query || null,
+        sector: args.sector || null,
+      });
+    }
+  );
+
+  server.registerTool(
+    'detect_ats',
+    {
+      title: 'Detect which ATS a company uses',
+      description: DETECT_ATS,
+      inputSchema: {
+        company: z.string().describe('Company name or slug'),
+      },
+    },
+    async (args) => {
+      const results = await libDetectAts(args.company);
+
+      if (results.length === 0) {
+        return success(null, { attempted: ['greenhouse', 'lever', 'ashby'], succeeded: [] });
+      }
+
+      if (results.length === 1) {
+        return success(results[0].ats, {
+          attempted: ['greenhouse', 'lever', 'ashby'],
+          succeeded: [results[0].ats],
+        });
+      }
+
+      // Multiple matches — rare but possible if a company is registered on more than one ATS
+      return partial(
+        results[0].ats,
+        {
+          attempted: ['greenhouse', 'lever', 'ashby'],
+          succeeded: results.map((r) => r.ats),
+          notes: [`Company found on multiple platforms: ${results.map((r) => r.ats).join(', ')}. Returning first match.`],
+        }
+      );
+    }
+  );
+}