mcp

# JobMojito MCP Server

## Welcome

[JobMojito](https://jobmojito.com) is an AI interview platform for hiring teams:
**let AI interview every candidate — you make the call.** Lifelike avatar and
voice agents run structured, multilingual interviews at any scale, score them in
real time, and hand recruiters the transcripts, summaries and reports they need
to make the actual decision. Everything the platform produces is decision
support for a qualified human reviewer — never the hiring decision itself.

What the platform offers:

- **AI avatar & voice interviews** — real-time conversational interviews with
  configurable avatars, generated from a job description or built from your own
  question set, with a fully branded candidate experience.
- **Scoring, transcripts & reports** — consistent structured assessment with
  real-time scoring, plus shareable interview reports for the hiring team.
- **Candidate management & invitations** — register candidates in bulk, send
  each one a personal interview link, grant extra attempts, track results.
- **Role-play & coaching personas** — avatars that play a defined role, for
  screening scenarios or candidate practice on the coaching portal.
- **Knowledge base** — upload company documents so interviews and evaluations
  reflect your organisation's context.
- **Workspaces & analytics** — merchants and sub-merchants, credit usage, and
  hiring analytics across positions.

Around the product: the admin console at [app.jobmojito.com](https://app.jobmojito.com),
developer/API docs at [developer.jobmojito.com](https://developer.jobmojito.com),
the help center at [help.jobmojito.com](https://help.jobmojito.com), and the
hosted MCP endpoint this repo powers at `https://mcp.jobmojito.com/mcp`.

This repository is the MCP server that puts all of that into AI assistants like
Claude and ChatGPT.

---

An [MCP](https://modelcontextprotocol.io) server for the **JobMojito API**, built
with [FastMCP](https://gofastmcp.com) and designed to deploy on
[Prefect Horizon](https://horizon.prefect.io) (the MCP platform from the FastMCP
team — `app.prefect.cloud` → Horizon).

It exposes:

- **25 API tools** auto-generated from JobMojito's live OpenAPI spec (interviews
  and role-play personas, the coaching catalogue, candidates and results,
  knowledge base, merchant lists/analytics). All endpoints — including the `GET`
  lists — are surfaced as tools with clean, curated names, each with a title and
  read-only/destructive annotations.
- **2 documentation tools** (`search_documentation`, `get_documentation`) that read
  the developer docs and help center **live** — docs stay single-source on their
  existing platforms; nothing is copied into this repo.
- **Supabase OAuth** so end users can log in directly from Claude, ChatGPT, etc.
  The signed-in user's Supabase JWT is forwarded to the JobMojito API on every call.

---

## How it fits together

```
MCP client (Claude / ChatGPT)
        │  OAuth login (Supabase OAuth Server, DCR)
        ▼
JobMojito MCP server (this repo, on Horizon)
        │  forwards the user's Supabase JWT
        ▼
JobMojito API  (https://cool.jobmojito.com/functions/v1)
```

| Concern            | Approach |
|--------------------|----------|
| API → tools        | `FastMCP.from_openapi(...)`, all routes mapped to **Tools**, curated names via injected `operationId`s |
| Spec freshness     | Fetched **live at startup**; a runtime cache + committed snapshot are fallbacks |
| Auth               | `SupabaseProvider` (Remote OAuth); per-request JWT forwarding to the upstream API |
| Docs               | Built-in tools reading `developer.jobmojito.com/llms.txt` + `.md` and the `help.jobmojito.com` (Featurebase) help center |

### Files

| File | Purpose |
|------|---------|
| `server.py` | Entry point — builds and exposes `mcp` (point Horizon at `server.py:mcp`) |
| `config.py` | Environment-driven settings |
| `openapi_loader.py` | Live fetch + cache/snapshot fallback + operationId injection |
| `naming.py` | Curated tool names, titles, hints and annotations per endpoint |
| `upstream.py` | httpx client that forwards the user's Supabase JWT to the API |
| `middleware.py` | Call logging, upstream-error rewriting, result-size guard, annotation backfill |
| `merchants.py` | Merchant picker (MCP App UI) + `list_my_merchants` text fallback |
| `docs_tools.py` | `search_documentation` / `get_documentation` |
| `featurebase.py` | Featurebase REST client (help-center articles) |
| `mintlify.py` | Mintlify developer-docs MCP proxy + client-credentials auth |
| `tests/` | `test_smoke.py` (inventory, schema relaxation, docs) + `test_listing_readiness.py` (directory contract) |
| `docs/` | Developer docs: architecture, development, deployment |
| `scripts/update_snapshot.py` | Refresh the committed fallback spec |
| `scripts/try_docs.py` | Local smoke test for the documentation tools |
| `data/openapi.snapshot.json` | Offline fallback spec (regenerate from your machine) |
| `lazy_auth.py` | Unauthenticated capability discovery + `scope=` on the 401 challenge |
| `wellknown.py` | `/healthz`, OpenAI domain challenge, Smithery server card |
| `server.json` | Official MCP Registry entry |
| `.github/workflows/publish-registry.yml` | Publishes `server.json` to the MCP Registry when a push to `main` changes `server.py:SERVER_VERSION` (or via manual dispatch) |

---

## Local development & testing (macOS)

```bash
# 1. Set up a virtualenv and install deps
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 2. Configure secrets in .env (auto-loaded; gitignored)
cp .env.example .env        # then fill in your keys/credentials

# 3. Static check — see exactly what Horizon will deploy
fastmcp inspect server.py:mcp

# 4. Run the unit tests (offline; uses the snapshot fallback)
ENABLE_AUTH=false pytest -q --asyncio-mode=auto

# 5. Smoke-test the docs tools live (Featurebase + Mintlify federation)
ENABLE_AUTH=false python scripts/try_docs.py "how do I create an interview"

# 6. Run the server and connect a client
ENABLE_AUTH=false python server.py        # → http://localhost:8000/mcp
#   then, in another terminal, open the MCP Inspector:
npx @modelcontextprotocol/inspector
#   transport: "Streamable HTTP", URL: http://localhost:8000/mcp
```

Testing notes:

- **Docs tools** (`search_documentation`, and the mounted Mintlify
  `search_*_developer_*` / `query_docs_filesystem_*`) work with `ENABLE_AUTH=false`
  — no Supabase login needed. `scripts/try_docs.py` is the fastest check.
- **API tools** (`create_interview`, `list_candidates`, …) call the real
  JobMojito API and need a Supabase user token. For local testing, set
  `JOBMOJITO_DEV_BEARER_TOKEN` in `.env` to a valid Supabase access token; it's
  forwarded when `ENABLE_AUTH=false`. (Never set this in production — there the
  token comes from the user's OAuth session.)
- **Full OAuth locally** is rarely needed; if you want it, run with
  `ENABLE_AUTH=true`, set `BASE_URL=http://localhost:8000`, and connect a client
  that supports OAuth (it will bounce you through Supabase).

> **Refresh the fallback snapshot** from a network that can reach the API:
> `python scripts/update_snapshot.py` (the committed snapshot in this repo is a
> thin structural fallback; this replaces it with the full live spec).

---

## Supabase OAuth setup

This server uses Supabase's **OAuth Server** feature (which supports Dynamic
Client Registration, so MCP clients self-register). The MCP server is the OAuth
**resource server** — it validates tokens; Supabase issues them.

**Project:** `https://momsbvnltsydezmoesqt.supabase.co`
`SupabaseProvider` derives every endpoint from this project URL:

| Endpoint | URL |
|----------|-----|
| Authorize | `…/auth/v1/oauth/authorize` |
| Token | `…/auth/v1/oauth/token` |
| JWKS | `…/auth/v1/.well-known/jwks.json` |
| OIDC discovery | `…/auth/v1/.well-known/openid-configuration` |

Steps:

1. **Supabase Dashboard → Authentication → OAuth Server**
   - Enable the **OAuth Server** and **Allow Dynamic OAuth Apps**
   - **Site URL:** `https://app.jobmojito.com`
   - **Authorization Path:** `/oauth/consent`
2. Env: `SUPABASE_PROJECT_URL=https://momsbvnltsydezmoesqt.supabase.co`,
   `BASE_URL=https://mcp.jobmojito.com` (public base, no `/mcp`),
   `SUPABASE_JWT_ALGORITHM=ES256` (switch to `RS256` if your JWKS shows RSA keys).
3. If the JobMojito Edge Functions require an `apikey` header, set `SUPABASE_ANON_KEY`.

**Consent is handled by Supabase / your app, not this server.** Because the Site
URL is `app.jobmojito.com`, Supabase serves the approve/deny screen at
`https://app.jobmojito.com/oauth/consent`, where the user already has a Supabase
session. This MCP server is only the OAuth resource server — it does not serve a
consent page. `SITE_URL` and `OAUTH_CONSENT_PATH` are informational and should
match your Supabase OAuth Server settings.

> Token note: `SupabaseProvider` cannot validate token *audience* (Supabase Auth
> doesn't implement RFC 8707 resource indicators yet). This is expected and
> logged at startup.

---

## Authentication model

**Every tool *call* requires the user to be signed in via Supabase OAuth** —
including `search_documentation` and `get_documentation`. Keep `ENABLE_AUTH=true`;
the signed-in user's token is forwarded to the JobMojito API so calls respect that
user's permissions.

The one deliberate exception is **capability discovery**: with `ENABLE_LAZY_AUTH`
(default `true`), `initialize`, `ping` and the `*/list` methods answer without a
token so directory crawlers can render the tool list. No data is reachable that
way — every `tools/call`, resource read and prompt still needs a verified JWT.

## Deploy to Prefect Horizon

1. Push this repo to GitHub.
2. At [horizon.prefect.io](https://horizon.prefect.io), sign in with GitHub and
   select this repo.
3. Configure:
   - **Entrypoint:** `server.py:mcp`
   - **Dependencies:** auto-detected from `requirements.txt`
   - **Horizon Authenticati