Metadata-Version: 2.4
Name: searchsteward-mcp
Version: 0.3.2
Summary: MCP server for SearchSteward — search job matches, read score breakdowns, log applications, and pull negotiation prep from any MCP client.
Project-URL: Homepage, https://searchsteward.com
Project-URL: Repository, https://github.com/SearchSteward/searchsteward-mcp
Project-URL: Issues, https://github.com/SearchSteward/searchsteward-mcp/issues
Author: SearchSteward
License: MIT
License-File: LICENSE
Keywords: claude,job-search,mcp,searchsteward
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<2,>=1.2
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# searchsteward-mcp

An [MCP](https://modelcontextprotocol.io) server that connects [SearchSteward](https://searchsteward.com) to Claude Desktop, Claude Code, and any other MCP client. Search your job matches, read score breakdowns, log applications, and pull negotiation prep — from inside Claude.

**Any SearchSteward account can use it — free or paid.** You mint an API key from any plan and it applies *your plan's own limits*, exactly as the web app does: free keys reach the search, tracking, and triage tools; **Radar** unlocks the negotiation playbook and the full-depth match feed. Your key hits the paywall in precisely the same place your account does. (See [Free vs paid](#free-vs-paid) below.)

---

## 1. Get an API key

In SearchSteward: **Settings → Connect to Claude → Create API key**. The key (`ss_pat_…`) is shown **once** — copy it immediately. You can revoke it any time from the same screen; revocation takes effect immediately.

## 2. Add it to your MCP client

### Claude Code

```bash
claude mcp add searchsteward uvx searchsteward-mcp -e SEARCHSTEWARD_API_KEY=ss_pat_...
```

Verify it connected:

```bash
claude mcp list
# searchsteward: uvx searchsteward-mcp - ✓ Connected
```

> **Why command-first, `-e` last?** Claude Code's `-e/--env` flag is variadic — if it comes *before* the command it swallows `uvx searchsteward-mcp` as extra env values. The Anthropic docs show an `-e KEY=val -- uvx …` form, but the `--` separator is stripped by **Windows PowerShell** before it reaches the CLI, which reintroduces the same problem. Putting the command first and `-e` last works on PowerShell, cmd, and bash alike.

### Claude Desktop

Add to `claude_desktop_config.json` (**Settings → Developer → Edit Config**):

```json
{
  "mcpServers": {
    "searchsteward": {
      "command": "uvx",
      "args": ["searchsteward-mcp"],
      "env": { "SEARCHSTEWARD_API_KEY": "ss_pat_..." }
    }
  }
}
```

Restart Claude Desktop after saving.

## 3. Use it

Start a **new** session (MCP servers load at session start) and ask, e.g.:

- *"Search my SearchSteward matches"*
- *"Show me the score breakdown for match 12345"*
- *"Log an application for match 12345"*
- *"Give me a negotiation playbook for application 42"*

---

## Tools

19 tools in five groups.

**Discover & analyze**
| Tool | What it does |
|------|--------------|
| `search_matches` | Search your job matches (score-ranked; each row carries a `score`). Page size capped at 25. |
| `check_new_matches` | Pull the new 90%+ matches discovered in the last N hours (default 48). Scans the top page only — see the tool's own note. |
| `get_job` | Full detail for one match — score breakdown, ghost-listing signal, description. |
| `get_resume` | Your résumé text, so Claude can reason about fit and tailor it natively. |

**Track**
| Tool | What it does |
|------|--------------|
| `list_applications` | List your tracked applications. |
| `get_application` | Full detail for one application (status, notes, dates + offer if present). |
| `log_application` | Mark a **feed** job as applied (promotes a match to a tracked application). |
| `track_external_application` | Track a job you applied to **elsewhere** (LinkedIn, a recruiter, a company site) — it doesn't need to be in your feed. |
| `update_application` | Change an application's status and/or add a note. |

**Triage**
| Tool | What it does |
|------|--------------|
| `save_match` | Save a feed job to watch later (no application yet). |
| `dismiss_match` | Hide a match (with a reason) — sharpens future scoring. |
| `restore_match` | Undo a dismiss. |

**Prep & negotiate**
| Tool | What it does |
|------|--------------|
| `list_questions` | Your interview/application question bank. |
| `save_question` | Save a drafted answer back to the bank. |
| `get_offer` | Offer/compensation details for an application. |
| `get_negotiation_playbook` | SearchSteward's offer-negotiation playbook (**Radar**; runs an LLM job). |

**Audit match quality**
| Tool | What it does |
|------|--------------|
| `review_candidates` | Review whether the scorer ranked right — reaches the whole corpus, including roles it never surfaced for you. |
| `submit_match_verdict` | Record ground truth on one job (`should_surface` / `should_not_surface` / `unsure`). Distinct from `dismiss_match`. |
| `review_summary` | Count of the verdicts you've submitted, by verdict. |

<a name="free-vs-paid"></a>
### Free vs paid

A key uses **your plan's limits — identical to the web app**; a free account mints a working key. What each tier reaches:

| | Free | Radar (paid) |
|---|---|---|
| Search, read, résumé (`search_matches`, `get_job`, `get_resume`) | ✅ | ✅ |
| Track & triage (`log_application`, `save_match`, `dismiss_match`, …) | ✅ | ✅ |
| Question bank & match-quality review | ✅ | ✅ |
| `check_new_matches` (manual pull) | ✅ | ✅ |
| Full match-feed depth (beyond the free cap) | capped + upgrade hint | ✅ full |
| `get_negotiation_playbook` | ❌ 402 | ✅ |

Your key hits the paywall in exactly the place your account does. Radar's *push* alerts (an email the moment a new 90%+ match appears) remain a subscription feature — `check_new_matches` is the manual, on-demand equivalent.

## Configuration

| Env var | Required | Default |
|---------|----------|---------|
| `SEARCHSTEWARD_API_KEY` | yes | — |
| `SEARCHSTEWARD_API_BASE` | no | `https://searchsteward.com` |

`SEARCHSTEWARD_API_BASE` must be HTTPS (localhost is exempt for local development) — the server refuses to start otherwise, since the key would otherwise travel in cleartext.

---

## Troubleshooting

**`error: missing required argument 'commandOrUrl'`** — the variadic `-e` ate your command, or PowerShell stripped a `--`. Use the command-first form above (`claude mcp add searchsteward uvx searchsteward-mcp -e KEY=…`).

**`Invalid input` from `claude mcp add-json`** — your Claude Code version wants a `type` field. Prefer the plain `claude mcp add` command-first form above instead.

**Tool returns a 401 / "Invalid or revoked API key"** — the key was revoked or mistyped. Mint a fresh key in Settings.

**Tool returns a 402 / "entitlement_denied"** — that capability is Radar-only (e.g. the negotiation playbook, or feed depth beyond the free cap). Your key uses your plan's limits, the same as the web app.

**Tool returns a 403 / "This endpoint is not available to API keys"** — expected: API keys can only reach the tools above, nothing else.

**Don't paste keys into a shell command line** — `-e` values land in your shell history. If you must, revoke and re-mint afterward.

---

## Notes

- Job descriptions returned by `get_job` are untrusted web content — treat them as data, not instructions.
- `log_application` and `update_application` write to your account; everything else is read-only.

## Development

```bash
pip install -e ".[test]"
pytest
```

Issues and contributions: [github.com/SearchSteward/searchsteward-mcp](https://github.com/SearchSteward/searchsteward-mcp).
