Claude Works

An MCP server that turns a perpetual, fit-first job-application pipeline into typed, honest tools an LLM agent can call.

What it is

Claude Works is a Model Context Protocol server built on FastMCP. It exposes a working, autonomous job-application loop (discovery sweeps, fit scoring, a verified resume builder, a fill-and-park submission planner, and an application ledger) as a small set of typed tools.

The point is not to wrap a chatbot around a job board. The point is to put the policy where it cannot drift: in code. An agent calling these tools cannot quietly inflate a fit score, claim a resume passed gates it never ran, or report a submission that did not happen. The honesty lives in the modules, not in a system prompt that the next conversation might forget.

The core (everything except the FastMCP wiring) imports with the standard library only. That keeps the domain logic fast to test, easy to read, and reusable outside the MCP runtime.

Related MCP server: decroche-mcp

Architecture

The system is a five-stage pipeline. Each stage is a frozen or plain @dataclass defined in models.py, and each crosses the MCP boundary as a JSON-serializable dict:

SearchAngle  ->  Job  ->  Score  ->  Resume  ->  Application

• SearchAngle is one reusable search lens (FDE, IoT, Overemployed, and so on). It biases discovery and scoring toward a lane without changing the rules.

• Job is a single discovered role, normalized across every source. Its role_key (ATS plus org slug plus job id, parsed from the apply URL) is the canonical identity used for de-duplication. De-dup is by role, never by company, so the same company with a different role is allowed.

• Score is the fit-rubric verdict for a job: a value from 0 to 10, a pursue boolean, one reason line per signal, and a hard_cap field set when a disqualifying signal applies.

• Resume is a built artifact plus the verdicts of a four-gate verification pipeline (one-page render, style lint, anti-fabrication verify, and an agent claim-trace check).

• Application is one row in the durable ledger.

Module layout:

Because __init__.py imports only models, import claude_works never requires the MCP runtime, and the unit tests run against the pure core with no network and no third-party dependencies.

Tools

Every tool returns JSON-serializable structures so results flow straight back into the model.

Install

git clone https://github.com/andrewaws26/claude-works.git
cd claude-works
pip install -e ".[dev]"

Run the test suite (pure core, no network):

pytest

Quickstart

Start the server over stdio:

python -m claude_works

Register it with Claude Desktop or Claude Code by adding it to your MCP server config:

{
  "mcpServers": {
    "claude-works": {
      "command": "python",
      "args": ["-m", "claude_works"],
      "env": {
        "JOBSEARCH_APPLY_EMAIL": "you@example.com",
        "JOBSEARCH_APPLY_LOCATION": "City, ST",
        "JOBSEARCH_COMP_FLOOR": "120000",
        "JOBSEARCH_PURSUE_THRESHOLD": "7.0"
      }
    }
  }
}

Configuration

All configuration is environment driven. Nothing sensitive is stored in the repo.

Design principles

Honesty is enforced in the modules, not the prompt. Three concrete mechanisms:

1. Score hard caps. An over-level title (Director, Principal, Staff, and the like), a required-skill gap, a non-US-only role, an excluded domain (defense, surveillance, and so on), or an active interview track caps the score and forces pursue=False. The agent cannot score its way past a disqualifier.

2. Gate findings, not claims. The resume tools return the actual results of the lint and anti-fabrication gates with the specific findings attached. A resume is reported as passing only when every automated gate ran and passed.

3. Fill-and-park plans, not faked submits. submit_application returns a deterministic plan (the ATS, the action, the field values, the honest screening answers, and the one human step left when parked). It never drives a browser and never reports a submission that did not happen. The real outcome is recorded afterward through record_application.

Typed dataclass boundaries. Every value that crosses a tool boundary is one of the five core dataclasses with an explicit to_dict. The schema is the contract, and the contract is the same whether a record was written by this server or by the underlying loop.

Zero-dependency, testable core. The domain logic depends on nothing but the standard library. The included tests cover the slug and role-key normalization, the dataclass round-trips, the de-dup-by-role behavior, the scoring hard caps, and the submission planner, all without touching the network.

License

MIT. See LICENSE.