# WaaS MCP

MCP server for [Work at a Startup](https://www.workatastartup.com) — YC's job board (**WaaS**). Search jobs, read listings, inspect what each application needs, and submit with dry-run safety by default.

> `waas.com` is a parked domain. This targets **workatastartup.com**.

## Quick start

**Requirements:** Node.js 20+, a [Work at a Startup](https://www.workatastartup.com) / YC account (for applying).

```bash
git clone https://github.com/Thespaceblade/waas-mcp.git
cd waas-mcp
./scripts/install.sh
```

`install.sh` installs dependencies, builds, downloads the Playwright browser, and prints an MCP config snippet for your machine.

**Sign in once** (opens a browser window):

```bash
npm run login
```

Reload MCP in Cursor (or restart Claude Desktop), then ask your assistant:

> Search WaaS for remote engineering jobs and inspect one at random.

## Cursor / Claude MCP config

Merge into `~/.cursor/mcp.json` (or Claude Desktop config). Use the **absolute path** where you cloned the repo:

```json
{
  "mcpServers": {
    "waas": {
      "command": "node",
      "args": ["/path/to/waas-mcp/dist/index.js"]
    }
  }
}
```

See [`mcp.json.example`](mcp.json.example). Session is stored at `~/.waas-mcp/storage-state.json` after `npm run login`.

### Claude Desktop (.mcpb)

One-click bundle (build from a clone):

```bash
npm run pack:mcpb
```

Install `waas-mcp.mcpb` via Claude Desktop → Settings → Extensions. Then run `npm run login` from the extension folder once (see Claude's extension install path).

## What it does

| Step | Tool |
|------|------|
| Check weekly cap | `waas_application_quota` — 10 in-app applications/week (Monday reset); also on `waas_search` / `waas_inspect_application` as `weeklyQuota` |
| `waas_search` | `waas_search` — role, remote, visa, keywords, etc. (`job_type` tightened client-side when WaaS returns mixed results) |
| Read job | `waas_get_job` |
| Read company | `waas_get_company` |
| Inspect apply form | `waas_inspect_application` — `applicationType`, `fields[]`, external links |
| Submit | `waas_submit_application` — answer map, **`dry_run=true` default** |
| Track | `waas_list_applied` |
| Check login | `waas_auth_status` |

### Application types (`waas_inspect_application`)

| Type | Meaning |
|------|---------|
| `custom_questions` | Resume URL, multiple choice, text questions — **includes required `message` field (50+ chars)** |
| `in_app_message` | Default "message the founder" textarea |
| `external` | Greenhouse, email, etc. — **won't auto-submit** |
| `already_applied` | Skip |
| `weekly_limit_reached` | 10/week cap hit — **won't auto-submit** (`applyBlocked: true`) |
| `needs_login` | Run `npm run login` |

### Weekly application cap

Work at a Startup limits **10 in-app applications per calendar week** (week starts Monday). When the cap is reached, the Apply modal is blocked or shows a limit message.

The MCP tracks usage by counting your candidate messages in `GET /api/conversations` since Monday (re-applies to existing company threads count separately). It also merges `~/.waas-mcp/applied.json` when a recent MCP submit is not yet in the API. Check `countNote` on quota responses. WaaS's server-side cap may still differ slightly — keep a 1–2 application buffer.

## Example workflow

```
waas_application_quota {}
waas_search { "role": "eng", "remote": true, "limit": 10 }
waas_inspect_application { "job_id": "99221" }
waas_submit_application {
  "job_id": "99221",
  "answers": { "question_1981": "Your drafted answer..." },
  "dry_run": true
}
```

Only set `dry_run: false` after you explicitly approve.

## Manual install

If you prefer not to use `install.sh`:

```bash
npm install          # runs build + Playwright chromium via lifecycle scripts
npm run login
```

## Upgrade

```bash
cd waas-mcp && git pull && npm install
```

Reload MCP in Cursor after updating.

### Claude Desktop (.mcpb)

Claude **does not auto-update** installed extensions. After a new release:

1. Download `waas-mcp.mcpb` from [Releases](https://github.com/Thespaceblade/waas-mcp/releases)
2. Claude → Settings → Extensions → remove old WaaS extension
3. Install the new `.mcpb` (drag & drop or file picker)
4. **Quit Claude completely** (Cmd+Q) and reopen — MCP servers only restart on app launch

Or point Claude at a git clone via `claude_desktop_config.json` (same snippet as Cursor) to pick up `git pull` + `npm run build` without reinstalling the bundle.

| Command | Purpose |
|---------|---------|
| `npm start` | Run MCP server (stdio) |
| `npm run login` | One-time YC / WaaS sign-in |
| `npm test` | Unit tests |
| `npm run test:live` | Live smoke test against workatastartup.com |
| `npm run pack:mcpb` | Build Claude Desktop `.mcpb` bundle |

## Credits

Parsing adapted from [workatastartup-mcp](https://github.com/moutasem-isentemiz/workatastartup-mcp) (MIT).

## License

MIT — see [LICENSE](LICENSE).