Skip to main content
Glama
README.md
# hiringpulse

hiringpulse is a small local bridge to the hosted
Hiring Census MCP server, which reads hiring data
straight from employers' own Greenhouse, Ashby and
Lever boards. Every posting it returns carries the
employer's real publish date and its age in days, so a
role posted this morning looks different from one that
has sat open for two years.

From that raw board data the service answers the
questions a job hunt or a prospect list actually turns
on: is a named company really hiring or has its board
just been left standing, which boards have gone quiet,
which boards are entirely fresh, what moved across a
watch list or the whole market, and what the market
looks like in aggregate this morning. The surface is
read-only: it searches and reports, and it never
submits an application, sends outreach, or contacts
anyone.

The bridge keeps no hiring data of its own. It serves
the upstream server's tool list locally, exactly as
captured from the live endpoint, and forwards each
tool call upstream, returning the result untouched.

## Tools

- `search_jobs` — search open postings across the
  boards. All arguments are optional: `query` (words in
  the job title), `location` (any part of the location
  string), `remote` (only roles flagged remote),
  `department` (function such as Engineering or Sales),
  `technology` (technology named in the posting),
  `max_age_days` (only roles posted within this many
  days), `min_age_days` (only roles older than this many
  days, for hunting stale listings) and `limit` (max
  results, default 25).
- `check_company` — ask whether one company is actually
  hiring. Required: `company`. Returns a board verdict
  (`actively_hiring`, `still_open`, `gone_quiet` or
  `likely_abandoned`) with the newest posting's age, the
  median role age, and counts of reqs open over 90 days
  and over a year.
- `find_quiet_boards` — companies still advertising
  open roles while having posted nothing new in over six
  months. Optional: `limit`.
- `find_fresh_boards` — companies where every currently
  open role was posted in the last 30 days. Optional:
  `limit`.
- `whats_changed` — net movement on a list of companies
  or across the whole record, flagging boards whose
  verdict flipped. All arguments are optional:
  `companies` (names to watch; omit for the whole
  market), `days` (window, default 7) and `limit`.
- `hiring_stats` — market-level numbers measured this
  morning: employers hiring, open roles, roles posted
  in the last 24 hours, roles open over 90 days and over
  a year, boards gone quiet, and the most in-demand
  technologies. Takes no arguments.

## Configuration

- `HIRINGCENSUS_MCP_URL` (optional) — override the
  upstream endpoint. Defaults to
  `https://hiringcensus.com/api/mcp`. (The override hook
  is this rebuild's own labelled reconstruction.)
- `HIRINGCENSUS_API_KEY` (optional) — when set, every
  upstream request carries an
  `Authorization: Bearer <key>` header. When it is not
  set, no key header is sent. (The header name is
  pinned by the original's registry record, which
  declares it optional; the Bearer scheme and this env
  forwarding are labelled reconstructions — the
  original surface was captured keyless, and the
  registry record notes a keyless trial allowance.)

### Forwarding mechanics

On the first tool call the client opens a streamable
HTTP session with the upstream: a JSON-RPC
`initialize` request (protocolVersion `2025-03-26`,
clientInfo name `hiringpulse`), then a
`notifications/initialized` notification, then the
`tools/call` request carrying the caller's arguments
unchanged. When the upstream answers `initialize`
with an `Mcp-Session-Id` header, that value rides on
every later request of the session, which is reused
for the life of the process. Replies may arrive as
plain JSON or as server-sent events; both are read.

Successful upstream results pass through verbatim,
including any `isError` flag the upstream sets.
Failures — a JSON-RPC error, a non-2xx status, an
unreadable response, or a request that cannot be
completed — come back as an `isError` result whose
text starts with `hiringpulse error:` (this rendering
is this rebuild's own labelled reconstruction).

## CLI

Each tool is also a subcommand taking one JSON
argument string:

```bash
npx @reneturcios/hiringpulse search_jobs '{"query":"staff backend engineer","location":"Berlin"}'
npx @reneturcios/hiringpulse check_company '{"company":"Acme"}'
npx @reneturcios/hiringpulse hiring_stats
npx @reneturcios/hiringpulse --version
```

Exit codes: `0` on success, `1` on an `isError`
result, `2` on a usage error.

## MCP server

```bash
npx -y @reneturcios/hiringpulse mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "hiringpulse": {
      "command": "npx",
      "args": ["-y", "@reneturcios/hiringpulse", "mcp"]
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/hiringpulse
docker run --rm ghcr.io/cloudcorprecords/hiringpulse --version
```

The container's default command is `mcp`, so the first
form is a stdio MCP server; any other arguments reach
the CLI normally.

## Development

```bash
npm install
npm run build
npm test
npm run dev
```

The test suite runs entirely against a stubbed
JSON-RPC upstream — no live network calls.

## License

MIT — see `LICENSE`.