# Joblet.ai Claude Connector (v1 — text replies)

A remote MCP server that lets Claude search live joblet.ai jobs. Two read-only tools:

- **`search_jobs`** — search by title/keywords + optional company, location, employment type.
- **`get_job_details`** — full posting (description, responsibilities, requirements, salary, apply link) by job id.

v1 returns plain text/markdown replies. The interactive job-card widget is a later layer.

## Requirements
- Node.js 18+ (tested on 24).
- No API key — joblet.ai's search/detail API is public.

## Install & run
```bash
npm install
npm start            # starts on http://localhost:3000  (MCP at /mcp)
# use another port if 3000 is busy:
PORT=3010 npm start
```

Health check: `GET http://localhost:<port>/health` → `{"status":"ok"}`.

## Test the tools (local, no internet needed)

**Option A — automated script** (lists tools, searches, fetches detail, checks an error):
```bash
MCP_URL="http://localhost:3010/mcp" node test_client.mjs
```

**Option B — MCP Inspector** (interactive UI):
```bash
npx @modelcontextprotocol/inspector
```
In the Inspector: Transport = **Streamable HTTP**, URL = `http://localhost:3010/mcp`, Connect.

## Test inside Claude (end-to-end)
Claude needs a public HTTPS URL. Fastest is a tunnel to your local server:

```bash
# with cloudflared (no account needed):
cloudflared tunnel --url http://localhost:3010
# or with ngrok:
ngrok http 3010
```
Copy the `https://…` URL it prints, then in Claude (paid plan):
Settings → Connectors → Add custom connector → paste `https://<tunnel>/mcp`.

Then ask: *"find manager jobs in India"* — Claude will call `search_jobs`, and
*"tell me more about the first one"* will call `get_job_details`.

## Configuration (env vars)
| Var | Default | Purpose |
|-----|---------|---------|
| `PORT` | `3000` | HTTP port |
| `JOBLET_API_BASE` | `https://joblet.ai/api` | Upstream API base |
| `JOBLET_TIMEOUT_MS` | `8000` | Upstream request timeout |
| `ALLOWED_ORIGINS` | `https://claude.ai,https://claude.com` | Origin allowlist for `/mcp` (localhost + no-Origin clients always allowed) |

## Notes
- **Read-only:** both tools are annotated `readOnlyHint: true`, so Claude runs them without a per-call confirmation.
- **Origin validation** is enforced on `/mcp` (required for the Anthropic directory).
- **Known upstream limitation:** joblet.ai's search does not always filter strictly by
  location server-side, so a location query can include some off-location results. This is
  an API-side issue, not the connector's — flagged for the joblet.ai API team.
- Public-directory submission (OAuth 2.0, privacy policy, logo, test account) is a later phase.