# ashby-jobs

Search and browse any company's public [Ashby](https://www.ashbyhq.com/) job board from Claude Code.

Point it at a company's board slug — the `{slug}` in `jobs.ashbyhq.com/{slug}` — and it lists open
roles, surfaces the most recently posted ones, and pulls full details for a single posting.

## Requirements

- [uv](https://docs.astral.sh/uv/)
- Python 3.14+

`uv` must be on your `PATH` before you install the plugin. The MCP server is launched as
`uv run`, so if `uv` is missing the server fails to start and the tools simply never appear —
check `/mcp` if the commands are there but nothing works. Python 3.14 and the dependencies are
fetched by `uv` itself on first launch, which makes that first startup slow.

## Install

Add this repo as a plugin marketplace, then install the plugin:

```
/plugin marketplace add Abhinav-Sriharsha/ashby-jobs-mcp
/plugin install ashby-jobs@ashby-jobs
```

For local development, point the marketplace at your checkout instead:

```
/plugin marketplace add /path/to/ashby-mcp
```

The MCP server starts automatically on install; no manual `.mcp.json` editing needed.

## Commands

Commands are namespaced under the plugin name:

| Command | Arguments | Does |
| --- | --- | --- |
| `/ashby-jobs:list-jobs` | `<job-board> [keyword]` | Lists open roles, optionally filtered by title or department |
| `/ashby-jobs:latest-jobs` | `<job-board> [department] [count]` | Shows the most recently posted roles, newest first |
| `/ashby-jobs:job` | `<job-board> <job-id>` | Full details for one posting |
| `/ashby-jobs:check-company` | `<company>` | Says whether a company is on Ashby at all, and under which slug |
| `/ashby-jobs:add-company` | `<job-board>` | Tracks a company without looking up its jobs |
| `/ashby-jobs:list-companies` | — | Shows every tracked company |
| `/ashby-jobs:remove-company` | `<job-board>` | Stops tracking a company |
| `/ashby-jobs:set-department` | `[keyword, ...]` | Saves the default keywords used when searching and iterating |
| `/ashby-jobs:iterate-list` | `[keyword] [hours]` | Sweeps every tracked company for roles posted in the last 24 hours |

```
/ashby-jobs:latest-jobs ramp Engineering 5
/ashby-jobs:list-jobs ramp backend
/ashby-jobs:job ramp b614563f-3ce6-4dca-b5ba-0e5a6c8bda27
/ashby-jobs:check-company Linear
/ashby-jobs:add-company ramp
/ashby-jobs:set-department engineer, ai, software engineer
/ashby-jobs:iterate-list
```

The two filters do not work the same way. `keyword` matches title and department loosely, so
`backend` works and you can pass a comma-separated list. `department` on `latest-jobs` is an exact
match against the board's own department names, so `Engineering` works but `engineer` returns
nothing — run `list-jobs` first if you are not sure what a board calls its departments.

## Default department

`set-department` saves the keywords that `list_jobs` and `iterate_list` fall back to when you do not
pass your own. Pass several separated by commas — a job matching any one of them counts. They are
matched against title and department, not against exact department names, so broad terms work on
boards that have no such department: `engineer` matches OpenAI's `Forward Deployed Engineering`
roles even though its board has no `Engineering` department.

```
/ashby-jobs:set-department engineer, ai, software engineer
/ashby-jobs:list-jobs openai            # filtered to those keywords
/ashby-jobs:list-jobs openai all        # the whole board anyway
/ashby-jobs:list-jobs openai research   # your keyword wins
/ashby-jobs:set-department              # clears it
```

Keywords match from a **word start**, not anywhere in the string. That is what keeps short ones
usable — plain substring matching turns `ai` into a hit on Ret**ai**l, M**ai**ntenance and Supply
Ch**ai**n, which is 28 junk results out of 66 on OpenAI's board. The end stays open, so prefixes
still work: `engineer` matches `Engineering` and `infra` matches `Infrastructure`.

Because a saved default narrows results silently, both tools return `keyword_source` alongside their
results — `default` when the saved value applied, `argument` when yours did, `override` for `all`,
and `none` when nothing filtered.

## Tools

The same functions are available to Claude directly, so you can just ask in plain language
("what's open at Ramp in engineering?") instead of using a command.

| Tool | Arguments |
| --- | --- |
| `list_jobs` | `job_board_name`, `keyword` (optional) |
| `get_latest_jobs` | `job_board_name`, `department` (optional), `top_k` (default 5) |
| `get_job` | `job_board_name`, `job_id` |
| `check_company` | `company` (slug or plain name) |
| `add_company` | `company` |
| `list_companies` | — |
| `remove_company` | `company` |
| `set_department` | `department` (empty clears it) |
| `iterate_list` | `keyword` (optional), `hours` (default 24) |

`list_jobs` returns the matching jobs together with the board's live totals:

```json
{
  "job_board": "openai",
  "total_open_jobs": 734,
  "matched_jobs": 383,
  "keywords": ["engineer", "ai", "software engineer"],
  "keyword_source": "default",
  "jobs": [ ... ]
}
```

`iterate_list` walks every tracked company. A board that fails to fetch is reported in `errors`
rather than aborting the sweep, so one renamed slug does not cost you the rest of the results.

`check_company` answers from whether the board exists, not from whether it has postings — Ashby
returns `404` for a slug nobody owns and `200` for a real board even when nothing is open. So a
company with an empty board is still a yes, with `open_jobs` of `0`:

```json
{
  "company": "Acme Corp",
  "on_ashby": true,
  "job_board": "acmecorp",
  "board_url": "https://jobs.ashbyhq.com/acmecorp",
  "open_jobs": 12,
  "tried": ["Acme Corp", "acmecorp"]
}
```

It takes a plain company name as well as a slug: the name is retried as a few normalized slugs
(`acmecorp`, `acme-corp`, and legal suffixes dropped), and `job_board` reports whichever one
resolved, which is the slug the other tools want. `tried` lists what was attempted, so a `false`
can be read for what it is — no board found under those names, not proof of absence. When Ashby
cannot be reached, `on_ashby` is `null` rather than `false`, with an `error` explaining why; a
timeout is not evidence that a company is off Ashby.

Each tool also ships an MCP prompt, available as `/mcp__ashby-jobs__<tool_name>` — the same
operations, reachable without the plugin's short commands.

## Tracked companies

Every company you look up with `list_jobs` is recorded in a small SQLite database, along with when
it was first and last queried and how many times. `add_company` adds one up front without fetching
any jobs, `list_companies` shows them, and `remove_company` drops one. Names are normalized to
lowercase, so `Ramp` and `ramp` are one company.

The tracked list is what `iterate_list` sweeps. Removing a company only takes it out of that sweep —
you can still look its jobs up directly, and doing so tracks it again.

The database lives at `~/.ashby-mcp/state.db` — deliberately outside the plugin directory, so
updating or reinstalling the plugin does not discard it. It also holds the default department set by
`set_department`. Delete that file to reset both.

Tracking is best-effort inside `list_jobs`: if the database cannot be written, the job lookup still
returns normally. `add_company` reports its errors, since recording the company is all it does.

## Development

Run the server directly:

```
uv run ashby-mcp
```

It speaks MCP over stdio, so nothing may write to stdout except the protocol itself — a stray
`print()` will corrupt the JSON-RPC stream. Use `stderr` for debugging output.