jd-intel

# jd-intel

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node.js 18+](https://img.shields.io/badge/node-18%2B-green.svg)](https://nodejs.org)
[![npm](https://img.shields.io/npm/v/jd-intel.svg)](https://www.npmjs.com/package/jd-intel)
[![jd-intel downloads](https://badgen.net/npm/dt/jd-intel?label=jd-intel)](https://www.npmjs.com/package/jd-intel)
[![jd-intel-mcp downloads](https://badgen.net/npm/dt/jd-intel-mcp?label=jd-intel-mcp)](https://www.npmjs.com/package/jd-intel-mcp)
[![GitHub stars](https://img.shields.io/github/stars/prPMDev/jd-intel.svg?style=flat)](https://github.com/prPMDev/jd-intel/stargazers)

> **Stop pasting job descriptions into AI assistants. Let your AI fetch them directly.**

Full text. Clean structure. Across seven major ATS. No copy-paste. No context loss.

---

## Why this exists

Your AI assistant already knows a lot about you. Your resume is in its memory. Your target roles, your past projects, your background. Ready to help the moment you feed it a job description.

So you copy-paste.

A JD from one company. Another from the next. A half-dozen more from your target list. Half have broken HTML. Salary info dies in translation. Links get stripped. And for every role, the dance starts over.

You could wait for the job boards to ship their own MCPs. They'll get there eventually. On their timeline. Filtered through their priorities, not yours. Tied to their query abstractions.

jd-intel skips that wait. Raw JDs, fetched directly by your AI, on your terms. One level below the curated layer.

Try asking your AI:

> "Find AI/ML engineering jobs posted this week."
> "What product designer roles are open at fintechs right now?"
> "Pull the staff PM roles posted in the last 7 days."

Done.

---

## Why not just scrape?

Because scraping breaks where jd-intel doesn't:

- **Full JDs when browsing fails.** SPA-rendered boards, slow loads, auth walls, and geo-restrictions block a browser. They don't block a public API call.
- **Structured data, not HTML soup.** Salary, location type, department, and clean markdown, normalized across seven ATS.
- **No keys, no browser.** Public APIs only. Runs anywhere your AI does.
- **One schema, every platform.** Greenhouse, Lever, Ashby, SmartRecruiters, Teamtailor, Recruitee, Workday return the same shape.

---

## What you can do with it

- Look up open roles at any company directly from your AI, no copy-paste
- Tailor your resume across ten roles in one conversation
- Rank openings by fit with your background
- Scan a whole sector: "Pull open roles at fintech companies posted this week"
- Research teams by reading their JDs in bulk

The toolkit fetches. Your AI thinks.

---

## Install

Works with MCP-aware AI clients: Claude Desktop, Claude Code, Cursor, Windsurf, VS Code. ChatGPT, Gemini, and other non-MCP clients don't support this yet. They use different tool-calling systems. (We wish they did. The protocol works the same way regardless of which AI you talk to.)

Everything runs locally on your machine. That also means desktop only: mobile apps can't run a local MCP server, so jd-intel isn't available on phones or tablets.

### Claude Desktop (one-file install, no terminal)

The simplest path. No Node.js, no terminal: Claude Desktop runs the server on its own bundled runtime.

1. **Download** the extension: [jd-intel.mcpb](https://github.com/prPMDev/jd-intel/releases/latest/download/jd-intel.mcpb).
2. In Claude Desktop, open **Settings**, then **Extensions**, then **Advanced settings**, and click **Install Extension**. Pick the file you downloaded.
3. Review the access summary, click **Install**, then start a new chat. The tools appear automatically.

Shortcuts: drag the `.mcpb` onto the Settings window, or double-click it when your system opens `.mcpb` files with Claude Desktop. The extension is open source and unsigned, so Claude Desktop shows an "unverified" notice. Choose **Install Anyway**.

Prefer the terminal, or on an older Claude Desktop? Install [Node.js 18+](https://nodejs.org/), run `npx jd-intel-mcp install`, then reopen Claude Desktop. Or edit the config file directly, see [Manual install](#manual-install-fallback).

### Other clients (Claude Code, Cursor, Windsurf, VS Code)

One-file `.mcpb` install is a Claude Desktop feature; these clients run the same server via `npx` and need [Node.js 18+](https://nodejs.org/).

**Claude Code**
```bash
claude mcp add jd-intel -- npx -y jd-intel-mcp
```

**Cursor** (Settings, then Tools & MCP, then New MCP Server, or edit `~/.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "jd-intel": { "command": "npx", "args": ["-y", "jd-intel-mcp"] }
  }
}
```

**Windsurf** (Settings, then Tools, then Windsurf Settings, then Add Server, or View Raw Config to edit `mcp_config.json`). Use the same `mcpServers` block as Cursor, then press refresh.

**VS Code** (Copilot agent mode): run the **MCP: Add Server** command, or create `.vscode/mcp.json`. The key is `servers` and the type is `stdio`:
```json
{
  "servers": {
    "jd-intel": { "type": "stdio", "command": "npx", "args": ["-y", "jd-intel-mcp"] }
  }
}
```

### Confirm it's working

Start a new chat and ask: **"What fintech companies are in your jd-intel registry?"** If it lists companies, you're set. Then try the real thing: *"Find senior PM roles open right now that I'd be a fit for."*

**Tools not appearing?**
- Fully quit and reopen the client (quit, do not just close the window). Claude Desktop: system tray then Quit (Windows), or ⌘Q (macOS).
- For npx clients (Claude Code, Cursor, Windsurf, VS Code), run `npx clear-npx-cache`, then restart.
- Confirm `node --version` is 18 or newer for the npx paths. The one-click `.mcpb` does not need Node.

### For developers

```bash
npm install jd-intel
```

```js
import { fetchJobs } from 'jd-intel';

const jobs = await fetchJobs({
  company: '<your-target-company>',
  titleFilter: 'designer',
  postedWithinDays: 14,
  limit: 50,
});
```

Results come back newest first by `postedAt`, undated last (`order: 'board'` keeps the ATS's own order). `fetchJobs` returns the page as an array. `fetchJobsDetailed` returns the same page plus `total_matched`, the number of matches before `offset` and `limit`, so you can tell a small board from a cut and page through the rest:

```js
import { fetchJobsDetailed } from 'jd-intel';

const { jobs, total_matched } = await fetchJobsDetailed({
  company: '<your-target-company>',
  titleFilter: 'engineer',
  limit: 20,
  offset: 20, // second page
});
```

The same result says how the company was resolved and which boards answered:

- `match`: `registry` (a known company, one adapter call), `probe` (not in the registry, every adapter asked) or `workday_override` (an explicit Workday config).
- `company`: `{ key, name }` from the registry row on a registry match, null otherwise.
- `boards`: one entry per board that answered, `{ ats, slug, name, site, board_url, org_name, org_url, jobs_found, matched, selected, scan }`. `jobs_found` counts the rows the board listed before any filter. Workday and SmartRecruiters filter their list before fetching details, so for them it is the list count, not the rows that came back (a lower bound when the list scan caps). `matched` is the rows left after filters and before `offset` and `limit`, so a board whose rows were all cut from the page still shows up. `board_url` is built from the slug. `org_name` and `org_url` are null until the adapters read them from the board itself; nothing is filled in from the slug. A `probe` match is a slug match, not a confirmed identity: open `board_url` before treating the jobs as that company's.
- `failed`: adapters that threw during discovery, `{ ats, slug, name, code, message }`, with `code` either `rate_limited` or `ats_unreachable`. When no board answered and a check failed, `fetchJobs` throws that error instead of returning `[]`, so an outage never reads as "not found".
- `total_before_filters`: the sum of `jobs_found`. Zero matches with a positive `total_before_filters` means the company is hiring and nothing passed the filters, on every ATS.

`detectAtsDetailed(company)` returns `{ boards, failed }`: registry rows first (`source: 'registry'`, never probed), then every live probe that answered (`source: 'probe'`), in platform order; `failed` lists the probes that could not be checked, with the same codes. `detectAts` keeps returning `[{ ats, slug }]`.

A call the library cannot make throws `ArgumentError` (`code: 'invalid_args'`): no company, an unknown `ats`, or a `titleFilter` or `filter` that does not compile as a regex. It is thrown before any request goes out.

CLI usage: `npx jd-intel fetch <company-slug> --title-filter "engineer" --posted-within-days 14`. Full filter reference [below](#filters-quick-reference).

Each ATS request gives the server 10 seconds to start responding. A 429, a 5xx or a network error is retried up to three attempts with backoff (1s, 2s), honoring `Retry-After` when the ATS sends one, and at most 4 requests run at a time per host. A failure that outlasts the retries throws an `AtsError` whose `code` is `rate_limited` or `ats_unreachable`.

Node.js 18+. No API keys. No configuration.

### Manual install (fallback)

If `npx jd-intel-mcp install` fails, edit the config directly.

**Config file location:**
- **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.

### Updating

- **Claude Desktop extension (`.mcpb`):** install a newer `.mcpb` over the current one, or manage it in Settings, then Extensions. Remove and reinstall to reset.
- **npx clients (Claude Code, Cursor, Windsurf, VS Code):** `npx -y jd-intel-mcp` picks up new versions from npm's cache (within ~24h). Force it now with `npx clear-npx-cache`, then restart the clie