# HireFrog MCP 🐸

Connect your AI assistant to your HireFrog job search.

Search jobs, understand why opportunities match your background, save jobs
to your HireFrog queue, and continue your application workflow at
[HireFrog](https://hirefrog.co).

## What this is

HireFrog MCP is a small, public [Model Context Protocol](https://modelcontextprotocol.io)
server that gives an MCP-compatible AI client (Claude, and any other client
that speaks Streamable HTTP MCP) a narrow, authenticated window into your
own HireFrog account — the same account and data you already use at
[hirefrog.co](https://hirefrog.co).

It is a thin adapter, not a second copy of HireFrog. Every tool call reads
or writes through the same authenticated backend the HireFrog web app uses
(Supabase Postgres protected by Row Level Security, and HireFrog's existing
authenticated `roleflow-ai` service for the one tool that needs AI). No
matching logic, resume-generation logic, or database access lives in this
repository.

## What it can do (V1)

| Tool | What it does |
|---|---|
| `search_jobs` | Search jobs already in your HireFrog queue by keyword, location, remote status, and how recently they were posted |
| `get_job` | Get full details for one job, with a link back to HireFrog |
| `analyze_job_fit` | Explain how well a job matches your HireFrog profile — match score, strengths, gaps |
| `save_job` | Save a job into your HireFrog queue |
| `list_my_jobs` | List your HireFrog job queue, optionally filtered by status |
| `get_my_profile_summary` | A curated summary of what HireFrog knows about your background and preferences |

Every response includes a link back to `hirefrog.co` so you can pick up the
workflow there.

## What it intentionally does not do

This is a deliberately lightweight V1 — an on-ramp to HireFrog, not a
replacement for it. It does **not**: generate a tailored resume, generate a
cover letter or application answers, submit applications, edit your master
resume or profile, touch billing/subscriptions, or run bulk/automated
actions. Where one of these would be useful, a tool response links you to
the right place in HireFrog to finish the job. See
[`docs/FUTURE_TOOLS.md`](docs/FUTURE_TOOLS.md) for what's technically ready
to build on this later, and why it isn't in V1 yet.

It also never runs a *new* HireFrog search against job boards — `search_jobs`
searches jobs HireFrog has already found for you. Run a new search at
[hirefrog.co/app/search](https://hirefrog.co/app/search).

## Architecture

See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the full request path
and module layout. In short:

```
MCP client → this server (Streamable HTTP, stateless)
           → Supabase (same Postgres + Row Level Security + Auth
              HireFrog's own web app uses), scoped to your own token
           → HireFrog's existing roleflow-ai Edge Function for AI analysis
```

This server never holds a database credential, an AI provider key, or a
Stripe/TheirStack key — it only ever acts as *you*, using the same
authorization rules the web app already enforces.

## Authentication

Every tool call requires `Authorization: Bearer <token>`, where the token is
resolved to your HireFrog identity by verifying it against Supabase Auth —
the exact same check every HireFrog Edge Function performs. No tool ever
accepts a user/account/profile id as an argument; identity comes only from
this token.

**Current limitation:** HireFrog doesn't yet have a dedicated long-lived API
token for this. For now, the token is your HireFrog session's Supabase
access token, which expires after about an hour. Until a proper token
(OAuth or a HireFrog-issued personal access token) ships, you'll need to
refresh it periodically — see [`docs/SECURITY.md`](docs/SECURITY.md) for
detail and the reasoning.

## Local development

```bash
git clone https://github.com/HireFrog/hirefrog-mcp.git
cd hirefrog-mcp
npm install
cp .env.example .env   # fill in HIREFROG_SUPABASE_URL / HIREFROG_SUPABASE_ANON_KEY
npm run dev             # starts on http://127.0.0.1:3000
```

Then verify it's up:

```bash
curl http://127.0.0.1:3000/health
```

Before opening a PR, run everything CI runs:

```bash
npm run lint
npm run typecheck
npm test
npm run build
```

## Connecting an MCP client

Point any MCP client that supports the Streamable HTTP transport at:

```
http://127.0.0.1:3000/mcp     (local)
https://mcp.hirefrog.co/mcp   (hosted, once deployed — see below)
```

with header `Authorization: Bearer <your HireFrog access token>`. Exact
configuration is client-specific — consult your client's docs for how it
adds a custom remote MCP server with a bearer token. This README doesn't
claim compatibility with any specific client beyond what the MCP
Streamable HTTP spec requires.

## Deployment

This server has no state of its own and is a normal Node HTTP service — a
`Dockerfile` is included. It's designed to eventually run at
`https://mcp.hirefrog.co/mcp`, but no hosting/DNS for that exists yet; this
repo doesn't assume it does. To run it yourself:

```bash
docker build -t hirefrog-mcp .
docker run -p 3000:3000 --env-file .env hirefrog-mcp
```

In production, set `NODE_ENV=production`, use a real `HIREFROG_SUPABASE_URL`,
and if binding to `0.0.0.0` behind a reverse proxy, set `MCP_ALLOWED_HOSTS`
(see `.env.example` and `docs/SECURITY.md`).

## Security

See [`docs/SECURITY.md`](docs/SECURITY.md) for the full threat model. In
short: no tool ever accepts a user/account id from the client, every
request rides HireFrog's own Row Level Security via your own token, the one
AI-backed tool goes through HireFrog's existing metered/authenticated
service (this server can't bypass your usage limits even if it wanted to),
and no secret or full bearer token is ever logged or returned in a
response.

Found a real vulnerability? Please report it privately rather than filing a
public issue — see contact info on [hirefrog.co](https://hirefrog.co).

## Contributing

Issues and PRs are welcome. Since this repo intentionally stays a thin
adapter, changes that would move HireFrog business logic, matching/scoring
algorithms, or database access into this repository will be redirected back
toward exposing a small endpoint on HireFrog's own backend instead — see
`docs/ARCHITECTURE.md` for why. Please run `npm run lint && npm run
typecheck && npm test && npm run build` before opening a PR.

## Links

- HireFrog: [hirefrog.co](https://hirefrog.co) — don't have an account yet?
  [Sign up](https://hirefrog.co/signup) to get the full HireFrog experience
  this server is a doorway into.
- HireFrog on GitHub: [github.com/HireFrog](https://github.com/HireFrog)

## License

MIT — see [`LICENSE`](LICENSE).