hiringpulse
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`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues