Skip to content

Commit b9641b7

Browse files
prPMDevprPMDev
committed
chore(0.8.0): launch polish + correctness fixes
- mcp: fetch_jobs returns the advertised error codes (company_not_found, rate_limited, ats_unreachable) instead of flattening everything to invalid_args - adapters: SmartRecruiters has-probe no longer false-positives (200-empty != exists) - mcp: detect_ats reports the real probe set (ATS_NAMES), not a stale subset - mcpb: jd icon, "JD Intel" display name, accurate/honest access copy + author/support links - docs: hero rewrite, corrected install steps, "seven major ATS", Workable to Next, jd favicon
1 parent bdfc875 commit b9641b7

14 files changed

Lines changed: 255 additions & 77 deletions

File tree

‎README.md‎

Lines changed: 52 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99

1010
> **Stop pasting job descriptions into AI assistants. Let your AI fetch them directly.**
1111
12-
Full text. Clean structure. Across every major ATS. No copy-paste. No context loss.
12+
Full text. Clean structure. Across seven major ATS. No copy-paste. No context loss.
1313

1414
---
1515

@@ -40,9 +40,9 @@ Done.
4040
Because scraping breaks where jd-intel doesn't:
4141

4242
- **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.
43-
- **Structured data, not HTML soup.** Salary, location type, department, and clean markdown, normalized across every ATS.
43+
- **Structured data, not HTML soup.** Salary, location type, department, and clean markdown, normalized across seven ATS.
4444
- **No keys, no browser.** Public APIs only. Runs anywhere your AI does.
45-
- **One schema, every platform.** Greenhouse, Lever, Ashby, SmartRecruiters, TeamTailor, Recruitee, Workday return the same shape.
45+
- **One schema, every platform.** Greenhouse, Lever, Ashby, SmartRecruiters, Teamtailor, Recruitee, Workday return the same shape.
4646

4747
---
4848

@@ -60,34 +60,57 @@ The toolkit fetches. Your AI thinks.
6060

6161
## Install
6262

63-
Works with MCP-aware AI clients: Claude Desktop, Claude Code, Cursor, Windsurf. 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.)
63+
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.)
6464

65-
You'll need [Node.js 18 or newer](https://nodejs.org/). To check: open a terminal and run `node --version`. If it's missing or older, install from nodejs.org first.
65+
### Claude Desktop (one-file install, no terminal)
6666

67-
### For Claude Desktop (one command)
67+
The simplest path. No Node.js, no terminal: Claude Desktop runs the server on its own bundled runtime.
6868

69-
1. **Open a terminal.** It's just a text window. Nothing destructive happens here.
70-
- **macOS:** Spotlight (`⌘ Space`), type "Terminal", hit Enter.
71-
- **Windows:** Start menu, type "PowerShell", hit Enter.
69+
1. **Download** the extension: [jd-intel.mcpb](https://github.com/prPMDev/jd-intel/releases/latest/download/jd-intel.mcpb).
70+
2. In Claude Desktop, open **Settings**, then **Extensions**, then **Advanced settings**, and click **Install Extension**. Pick the file you downloaded.
71+
3. Review the access summary, click **Install**, then start a new chat. The tools appear automatically.
7272

73-
2. **Paste this and hit Enter:**
74-
```bash
75-
npx jd-intel-mcp install
76-
```
73+
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**.
7774

78-
3. **Quit and reopen Claude Desktop.** The tools appear automatically.
75+
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).
7976

80-
Try: *"Find product roles at devtools companies."*
77+
### Other clients (Claude Code, Cursor, Windsurf, VS Code)
8178

82-
If something goes wrong or you'd rather edit the config file directly, see [Manual install](#manual-install-fallback) below.
79+
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/).
8380

84-
### For Cursor and Windsurf
81+
**Claude Code**
82+
```bash
83+
claude mcp add jd-intel -- npx -y jd-intel-mcp
84+
```
85+
86+
**Cursor** (Settings, then Tools & MCP, then New MCP Server, or edit `~/.cursor/mcp.json`):
87+
```json
88+
{
89+
"mcpServers": {
90+
"jd-intel": { "command": "npx", "args": ["-y", "jd-intel-mcp"] }
91+
}
92+
}
93+
```
94+
95+
**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.
96+
97+
**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`:
98+
```json
99+
{
100+
"servers": {
101+
"jd-intel": { "type": "stdio", "command": "npx", "args": ["-y", "jd-intel-mcp"] }
102+
}
103+
}
104+
```
105+
106+
### Confirm it's working
85107

86-
These clients have their own MCP setup flows. Follow their docs:
87-
- Cursor: [docs.cursor.com](https://docs.cursor.com)
88-
- Windsurf: [docs.windsurf.com](https://docs.windsurf.com)
108+
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."*
89109

90-
Use this server config: `command: "npx"`, `args: ["-y", "jd-intel-mcp"]`.
110+
**Tools not appearing?**
111+
- Fully quit and reopen the client (quit, do not just close the window). Claude Desktop: system tray then Quit (Windows), or ⌘Q (macOS).
112+
- For npx clients (Claude Code, Cursor, Windsurf, VS Code), run `npx clear-npx-cache`, then restart.
113+
- Confirm `node --version` is 18 or newer for the npx paths. The one-click `.mcpb` does not need Node.
91114

92115
### For developers
93116

@@ -133,21 +156,11 @@ Restart Claude Desktop.
133156

134157
### Updating
135158

136-
`npx -y jd-intel-mcp` auto-updates within ~24 hours via npm's cache. To force an update immediately:
137-
138-
```bash
139-
npx clear-npx-cache
140-
```
141-
142-
Then quit and reopen Claude Desktop.
159+
- **Claude Desktop extension (`.mcpb`):** install a newer `.mcpb` over the current one, or manage it in Settings, then Extensions. Remove and reinstall to reset.
160+
- **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 client.
161+
- **Library or CLI:** `npm install jd-intel@latest` (force latest) or `npm update jd-intel` (respect semver).
143162

144-
If you installed the library or CLI directly:
145-
146-
```bash
147-
npm install jd-intel@latest # force latest
148-
# or
149-
npm update jd-intel # respect semver
150-
```
163+
The company registry refreshes on its own: jd-intel fetches the current list at startup and falls back to the bundled copy offline, so new companies show up without reinstalling.
151164

152165
---
153166

@@ -208,7 +221,7 @@ No custom parsing per company.
208221
| Ashby | Shipped | Growing fast with startups |
209222
| Lever | Shipped | Common at mid-stage companies |
210223
| SmartRecruiters | Shipped | Enterprise and mid-market |
211-
| TeamTailor | Shipped | European startups and scale-ups |
224+
| Teamtailor | Shipped | European startups and scale-ups |
212225
| Recruitee | Shipped | Dutch / EU SMBs and scale-ups |
213226
| Workday | Shipped | Large enterprises (registry-keyed) |
214227
| Personio | Planned | German / EU mid-market |
@@ -236,17 +249,17 @@ All filters AND together. Deep dive on patterns and gotchas: [docs/filters.md](d
236249

237250
**Shipped**
238251
- Library, CLI, and MCP server (three surfaces of one toolkit)
239-
- Greenhouse, Ashby, Lever, SmartRecruiters, TeamTailor, Recruitee, Workday adapters
252+
- Greenhouse, Ashby, Lever, SmartRecruiters, Teamtailor, Recruitee, Workday adapters
240253
- Title, topic, location, and date filters
241254
- Salary extraction from JD text
242-
- Verified company registry (160+ companies)
255+
- Verified company registry (300+ companies)
243256

244257
**Next**
245258
- Personio adapter (German / EU mid-market)
259+
- Workable adapter (widget API; broad SMB coverage)
246260
- Anthropic MCP marketplace submission
247261

248262
**Planned**
249-
- Workable adapter (parked — needs SPA shortcode resolution)
250263
- Temporal tracking (when roles open, close, reopen)
251264
- Change detection
252265
- Resume-aware fit scoring

‎docs/favicon.svg‎

Lines changed: 3 additions & 2 deletions
Loading

‎docs/icon.png‎

12.2 KB
Loading

‎docs/icon.svg‎

Lines changed: 5 additions & 0 deletions
Loading

‎docs/index.html‎

Lines changed: 27 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -52,8 +52,8 @@
5252
<h1 class="visually-hidden">jd-intel</h1>
5353
<div class="masthead-headline">
5454
<div class="masthead-intro-text">
55-
<p class="hook">Ever wished you could ask your AI?</p>
56-
<p class="hero-tagline"><strong>jd-intel makes that possible.</strong> Your AI gets live access to real job postings across every major hiring platform. Full text, structured, ready to compare.</p>
55+
<p class="hook">Search job posting data from inside your AI. No more copy pasting of job descriptions.</p>
56+
<p class="hero-tagline"><strong>jd-intel</strong> gives your AI live access to real openings across seven major hiring platforms. Full text, structured, ready to compare.</p>
5757
</div>
5858
<div class="masthead-right">
5959
<p class="badges">
@@ -142,16 +142,16 @@ <h3 class="how-block-heading">How it works</h3>
142142
<section id="install" class="install" aria-labelledby="install-heading">
143143
<h2 id="install-heading">Install</h2>
144144

145-
<p>Works with MCP-aware AI clients: Claude Desktop, Claude Code, Cursor, Windsurf.</p>
145+
<p>Works with any MCP-aware AI client. Claude Desktop gets a one-click install. Every other client uses a small config, shown below.</p>
146146

147-
<h3>Add to Claude Desktop (one click)</h3>
148-
<p>No terminal, no Node.js. Claude Desktop runs it for you.</p>
147+
<h3>Add to Claude Desktop (no terminal)</h3>
148+
<p>No terminal, no Node.js. Claude Desktop runs it for you. One-click install is a Claude Desktop feature; other clients use the config further down.</p>
149149
<ol class="install-steps">
150150
<li><a href="https://github.com/prPMDev/jd-intel/releases/latest/download/jd-intel.mcpb" rel="noopener">Download the jd-intel extension</a> (a <code>.mcpb</code> file).</li>
151-
<li>Double-click it, or open Claude Desktop, go to Settings, then Extensions, and choose Install.</li>
152-
<li>Start a new chat. The tools appear automatically.</li>
151+
<li>In Claude Desktop, open <strong>Settings</strong>, then <strong>Extensions</strong>, then <strong>Advanced settings</strong>, and click <strong>Install Extension</strong>. Pick the file you downloaded.</li>
152+
<li>Review the access summary, click <strong>Install</strong>, then start a new chat. The tools appear automatically.</li>
153153
</ol>
154-
<p class="install-note">The extension is open source and unsigned. If your system or Claude Desktop warns about that, choose Install anyway.</p>
154+
<p class="install-note">Shortcuts: you can also drag the <code>.mcpb</code> onto the Settings window, or double-click it when your system opens <code>.mcpb</code> files with Claude Desktop. The extension is open source and unsigned, so Claude Desktop shows an "unverified" notice. Choose <strong>Install Anyway</strong>.</p>
155155

156156
<h3>Claude Desktop (command line)</h3>
157157
<p>Prefer the terminal, or on an older Claude Desktop? You'll need <a href="https://nodejs.org" rel="noopener">Node.js</a> 18 or newer first (check with <code>node --version</code>).</p>
@@ -163,8 +163,18 @@ <h3>Claude Desktop (command line)</h3>
163163
<li>Quit and reopen Claude Desktop. The tools appear automatically.</li>
164164
</ol>
165165

166-
<h3>Cursor and Windsurf</h3>
167-
<p>These clients have their own MCP setup flow. Add a server with <code>command: "npx"</code> and <code>args: ["-y", "jd-intel-mcp"]</code>. See <a href="https://docs.cursor.com" rel="noopener">docs.cursor.com</a> and <a href="https://docs.windsurf.com" rel="noopener">docs.windsurf.com</a>.</p>
166+
<h3>Other clients (Claude Code, Cursor, Windsurf, VS Code)</h3>
167+
<p>One-click <code>.mcpb</code> install is a Claude Desktop feature. These clients run the same server, defined as <code>command: "npx"</code>, <code>args: ["-y", "jd-intel-mcp"]</code>, and need Node.js 18+. Only the wrapper differs:</p>
168+
<ul class="config-paths">
169+
<li><strong>Claude Code:</strong> run <code>claude mcp add jd-intel -- npx -y jd-intel-mcp</code>.</li>
170+
<li><strong>Cursor:</strong> add it under <code>mcpServers</code> in <code>~/.cursor/mcp.json</code> (or Settings, Tools &amp; MCP). See <a href="https://docs.cursor.com" rel="noopener">docs.cursor.com</a>.</li>
171+
<li><strong>Windsurf:</strong> add it under <code>mcpServers</code> via Settings, Tools, Add Server. See <a href="https://docs.windsurf.com" rel="noopener">docs.windsurf.com</a>.</li>
172+
<li><strong>VS Code (Copilot agent):</strong> add it under <code>servers</code> with <code>"type": "stdio"</code> in <code>.vscode/mcp.json</code>.</li>
173+
</ul>
174+
175+
<h3>Confirm it's working</h3>
176+
<p>Start a new chat and ask: <em>"What fintech companies are in your jd-intel registry?"</em> If it lists companies, you're set.</p>
177+
<p class="install-note"><strong>Tools not appearing?</strong> Fully quit and reopen the client (quit, do not just close the window). For npx clients, run <code>npx clear-npx-cache</code> and restart, and check that <code>node --version</code> is 18 or newer. The one-click <code>.mcpb</code> needs no Node.</p>
168178

169179
<h3>Manual config (fallback)</h3>
170180
<p>If the one-command install fails, edit Claude Desktop's config file directly:</p>
@@ -182,6 +192,10 @@ <h3>Manual config (fallback)</h3>
182192
}</code></pre>
183193
<p>Restart Claude Desktop after editing.</p>
184194

195+
<h3>Updating</h3>
196+
<p>The one-click <code>.mcpb</code> is built for convenience, and the trade-off is updates. A self-installed extension does not auto-update, so to move to a newer version, <a href="https://github.com/prPMDev/jd-intel/releases/latest/download/jd-intel.mcpb" rel="noopener">download the latest <code>.mcpb</code></a> and install it over the current one. If an update misbehaves, remove the old extension under Settings, then Extensions, and reinstall.</p>
197+
<p>The <code>npx</code> path updates on its own: each restart runs the published version from npm. To always pull the newest, pin <code>jd-intel-mcp@latest</code> in your config.</p>
198+
185199
<h3>Developer (CLI / library)</h3>
186200
<pre><code>npm install jd-intel</code></pre>
187201
<p>Library API and CLI usage in the <a href="https://github.com/prPMDev/jd-intel#for-developers" rel="noopener">README</a>.</p>
@@ -197,11 +211,11 @@ <h3>Today</h3>
197211
<li>Ashby</li>
198212
<li>Lever</li>
199213
<li>SmartRecruiters</li>
200-
<li>TeamTailor</li>
214+
<li>Teamtailor</li>
201215
<li>Recruitee</li>
202216
<li>Workday</li>
203217
</ul>
204-
<p class="coverage-meta">160+ verified companies in the registry.</p>
218+
<p class="coverage-meta">300+ verified companies in the registry.</p>
205219
</div>
206220
<div>
207221
<h3>Next</h3>
@@ -222,7 +236,7 @@ <h3>Next</h3>
222236
<a href="https://github.com/prPMDev/jd-intel" rel="noopener">GitHub</a> ·
223237
<a href="https://www.npmjs.com/package/jd-intel-mcp" rel="noopener">npm</a>
224238
</p>
225-
<p class="copyright">&copy; <span id="year"></span> Prashant Rana. MIT licensed.</p>
239+
<p class="copyright">&copy; <span id="year"></span> Prashant R. MIT licensed.</p>
226240
</footer>
227241
</main>
228242

‎mcp/README.md‎

Lines changed: 25 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# jd-intel-mcp
22

3-
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.
3+
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.
44

55
> **Stop pasting job descriptions into AI assistants. Let your AI fetch them directly.**
66
@@ -17,9 +17,31 @@ The AI handles the phrasing. The MCP server handles the calls, filters, and norm
1717

1818
---
1919

20-
## Install (Claude Desktop)
20+
## Install
2121

22-
Add this to your Claude Desktop config file:
22+
### Claude Desktop (one-file install, no terminal)
23+
24+
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.
25+
26+
Prefer the terminal? Install [Node.js 18+](https://nodejs.org/), then run:
27+
28+
```bash
29+
npx jd-intel-mcp install
30+
```
31+
32+
This locates the Claude Desktop config, adds the entry alongside any existing servers, and writes back valid JSON. Quit and reopen Claude Desktop.
33+
34+
### Other clients (Claude Code, Cursor, Windsurf, VS Code)
35+
36+
The same server runs via `npx` (needs Node.js 18+):
37+
38+
- **Claude Code:** `claude mcp add jd-intel -- npx -y jd-intel-mcp`
39+
- **Cursor / Windsurf:** add under `mcpServers` (`command: "npx"`, `args: ["-y", "jd-intel-mcp"]`) in the client's MCP config.
40+
- **VS Code (Copilot agent):** add under `servers` with `"type": "stdio"` in `.vscode/mcp.json`.
41+
42+
### Manual config (fallback)
43+
44+
Edit Claude Desktop's config file directly:
2345

2446
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
2547
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
@@ -37,13 +59,6 @@ Add this to your Claude Desktop config file:
3759

3860
Restart Claude Desktop. The tools appear automatically.
3961

40-
**One-command install (avoids hand-editing the config):**
41-
```bash
42-
npx jd-intel-mcp install
43-
```
44-
45-
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.
46-
4762
---
4863

4964
## Tools exposed

‎mcp/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "jd-intel-mcp",
33
"version": "0.8.0",
4-
"description": "MCP server for jd-intel. Your AI assistant fetches and reasons over full job descriptions, no copy-paste.",
4+
"description": "MCP server for jd-intel. Your AI assistant fetches and reads full job descriptions across seven ATS platforms, no copy-paste.",
55
"type": "module",
66
"main": "server.js",
77
"bin": {

0 commit comments

Comments
 (0)