Metadata-Version: 2.5
Name: applywise
Version: 0.1.0
Summary: Modular, parallel, token-frugal MCP server for discovering and applying to jobs, with local-first LLM routing.
Project-URL: Homepage, https://github.com/tanmayagrawal21/job-apply-mcp
Project-URL: Repository, https://github.com/tanmayagrawal21/job-apply-mcp
Project-URL: Documentation, https://github.com/tanmayagrawal21/job-apply-mcp/tree/main/docs
Project-URL: Issues, https://github.com/tanmayagrawal21/job-apply-mcp/issues
Project-URL: Changelog, https://github.com/tanmayagrawal21/job-apply-mcp/blob/main/CHANGELOG.md
License-Expression: MIT
License-File: LICENSE
Keywords: applywise,automation,job-application,jobs,local-llm,mcp,model-context-protocol,ollama
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<2,>=1.2
Requires-Dist: pydantic<3,>=2.7
Provides-Extra: agent
Requires-Dist: browser-use>=0.3; extra == 'agent'
Requires-Dist: playwright<2,>=1.45; extra == 'agent'
Provides-Extra: browser
Requires-Dist: playwright<2,>=1.45; extra == 'browser'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: hf
Requires-Dist: transformers<5,>=4.44; extra == 'hf'
Provides-Extra: jobspy
Requires-Dist: python-jobspy>=1.1; extra == 'jobspy'
Provides-Extra: keyring
Requires-Dist: keyring<26,>=25; extra == 'keyring'
Provides-Extra: litellm
Requires-Dist: litellm>=1.83.0; extra == 'litellm'
Provides-Extra: mlx
Requires-Dist: mlx-lm>=0.18; extra == 'mlx'
Provides-Extra: resume
Requires-Dist: pypdf>=4; extra == 'resume'
Provides-Extra: tune
Requires-Dist: mlx-lm>=0.18; extra == 'tune'
Description-Content-Type: text/markdown

# job-apply-mcp (ApplyWise)

<!-- mcp-name: io.github.tanmayagrawal21/applywise -->

An MCP server that finds jobs and fills applications for you, and stops before anything irreversible. It is
**modular** (pluggable platforms, LLM providers, browser drivers), **parallel**, **token-frugal** (compact,
paginated output) and **local-first** (routine form fields go to Ollama, LM Studio or MLX on your machine; only
hard prose escalates). Works with any MCP client on macOS, Linux and Windows.

> [!WARNING]
> **Alpha.** Field results from the first live dogfooding run (one user, one night, ~330 discovered postings):
> search, ranking, dedupe and planning work end to end, and the browser driver now fills and verifies
> complete Greenhouse and Lever forms, but **no application has yet been submitted unattended**. Most
> Greenhouse boards are reCAPTCHA-protected, so the tool fills the form and hands the final click to you
> (`handoff`), which is the intended behaviour. Free-text questions need `writing.reviewer = "router"` (local strict
> review) to go out without you. Expect rough edges; every irreversible step is gated, logged and
> never retried when the outcome is uncertain.

## Install as a Claude Code plugin

The repository is also a Claude Code plugin marketplace. The `applywise` plugin starts the MCP server for you
(pinned to a reviewed version) and adds a skill that tells Claude how to use the tools safely:

```bash
claude plugin marketplace add tanmayagrawal21/job-apply-mcp
claude plugin install applywise@applywise
```

Then run `init` and `doctor` from the quickstart below in your own terminal, and check `/mcp` for
`plugin:applywise:applywise`. The same safety model applies: dry run by default, a human approves every real
submit, and visible CAPTCHAs always come back to you; logins, codes and account creation stay with you unless
you open a consent window yourself (safety model, items 7 and 8). To update, run
`claude plugin update applywise@applywise`. How releases and the version pin work: [docs/release.md](docs/release.md).

## 5-minute quickstart

You need [uv](https://docs.astral.sh/uv/getting-started/installation/) (or pipx). No clone required.

```bash
# 1. Create config.toml, profile.toml, controls.toml (asks a few questions; --yes to skip them)
uvx --from git+https://github.com/tanmayagrawal21/job-apply-mcp job-apply-mcp init

# 2. Put your real details in the profile it printed the path of, then check everything
uvx --from git+https://github.com/tanmayagrawal21/job-apply-mcp job-apply-mcp doctor

# 3. Add the printed snippet to your MCP client (guides for ten clients: docs/clients/)
claude mcp add --transport stdio job-apply -- uvx --from git+https://github.com/tanmayagrawal21/job-apply-mcp job-apply-mcp
```

Then ask your assistant: "search jobs at greenhouse:examplecorp for data roles, plan the best one, and do a dry run."
Everything is a dry run until you set `dry_run = false`.

Install alternatives: `pipx install git+https://github.com/tanmayagrawal21/job-apply-mcp` (then the command is just
`job-apply-mcp`), or `pip install` into a virtualenv. After the first PyPI release, `uvx applywise` (the PyPI distribution is
`applywise`; the `job-apply-mcp` command stays as an alias).
Optional extras: `[browser]` (Playwright), `[agent]`, `[jobspy]`, `[mlx]`, `[hf]`, `[litellm]`, `[keyring]`.

## Features

| Area | What you get |
|---|---|
| Discovery | Parallel search over Greenhouse, Lever, Ashby, SmartRecruiters, Workday and JobSpy boards, paginated |
| Policy gates | Skip by sponsorship, citizenship, clearance, experience, graduation window, salary floor, employer patterns |
| Runs | `run_applications` / `job-apply-mcp run`: links you pass, job links you emailed yourself (read-only mail) and discovery in one run, a run report and feedback applied to the next run |
| Applying | Platform API where possible, browser driver otherwise, generic LLM-assisted adapter for other sites |
| Local LLM routing | Complexity-scored tiers (small/medium/large/narrative), fallbacks, optional cloud, your MCP client as last resort |
| Profile builder | Collects the questions your profile could not answer, ranks them, and asks **you** (`profile_questions`, `answer_profile_question`, `job-apply-mcp profile ask`); the model never supplies an answer |
| Authorization | Per-country facts (`[authorization]` for your `home_country`, `[authorization.<CC>]` for others); no default country, and unknown countries stay unresolved |
| Writing | Cover letters and answers with style rules, banned phrases and gap-avoidance checks |
| Provenance | Every generated text is recorded and can be verified or edited by you |
| Dedupe | Store of applications plus optional confirmation-email ingest so you never apply twice |
| Control layer | Quotas, mode switch, attestation and recipient guards, prose lint, prompt-injection screen |
| Transports | stdio (default) and streamable HTTP with bearer token |
| Operations | `init`, `doctor`, Dockerfile, CI on Linux/macOS/Windows |

### Run statuses

Every posting in a `run_applications` / `run_report` result has exactly one status, with a `why` where useful
(ADR-0049):

| Status | Meaning |
|---|---|
| `submitted` | Live submit sent; a confirmation may follow |
| `confirmed` | Reconciliation confirmed the submission |
| `dry_run_ok` | Dry run complete: a live run would submit it (see `live_preview` for quotas) |
| `needs_human` | You must act; `why` says what (unresolved fields, review gate, awaiting approval, verification code) |
| `quota_blocked` | A daily, per-platform or per-run quota refused the live submit; nothing was sent |
| `skipped` | Not attempted; `why` says why (policy, duplicate, prose not approved yet, `max_applications` reached) |
| `unsupported_site` | No enabled adapter handles the host |
| `unknown` | Outcome unclear (for example a roadblock after the click); verify by hand |
| `failed` | An error |

`max_applications` (a whole number >= 1) caps the eligible postings a run handles (ready to submit, or needing you),
the same in dry and live mode; skipped and unsupported postings do not count. A dry run also returns
`live_preview` with what the current live quotas would allow. Live submits also count against the daily (25 per
rolling 24 h), per-platform (10) and per-run (10) limits; a user config can lower or raise them.

## Safety model

1. **Dry-run by default.** `dry_run = true` unless you change it; `init` always writes it.
2. **Approval tokens.** `plan_application` returns a token bound to a hash of the exact answers. A real submit
   needs that token, so what you reviewed is what is sent (`apply.auto_approve` turns this off; do not).
3. **Control layer.** Independent checks run before every side effect: daily and per-run quotas, single-submit
   guard, recipient deny-list, prose lint, page-text injection screen, `apply_enabled` kill switch. Add your own
   rules in `controls.toml`.
4. **Hard stops.** Visible CAPTCHA challenges and attestation checkboxes matching `policy.stop_phrases` (for
   example "no AI used") always return `needs_human`. They are not configurable away. Verification codes are
   entered only when the USER types them, confirms a granted prefill (ADR-0026/0027), or consented to unattended
   runs from a terminal (item 8). Account creation is off by default; it needs `accounts.auto_create = true` in your
   own user config file AND an open credentials consent window (ADR-0046).
5. **No invented facts.** Answers come from your profile or are marked; unresolved required fields stop the run.
   **Autonomy level (ADR-0052).** `[answers] autonomy` in your own user config decides what the agent may assume
   when you are not available: `strict` (default: every unresolved field waits for you), `safe_default` (decline
   contact/marketing permission, the configured "how did you hear" default, "decline to self-identify"), or `infer`
   (also skill/experience questions about a tool or technology, answered from your resume: Yes only when it
   clearly says so, otherwise No; willingness, availability, location and terms questions are never inferred).
   Authorization/visa/identity, background and other screening, accommodation, recording, attestations, legal
   agreements and employment terms, salary without a policy, start date and location facts are never assumed. Every assumed answer is labelled (`assumed`, plan, evidence, run report); after
   `promote_after` (3) assumptions of one question you are asked once and your answer is reused. A project file or
   env var can only make the level stricter. `init` asks which level to use; `control_status` shows it.
6. **Privacy.** Profile and secrets stay on your machine, are never committed, and API keys are read only from
   the environment. See [SECURITY.md](SECURITY.md).
7. **Credentials never reach the model.** ATS logins live in the OS keychain (`job-apply-mcp vault add <host>
   --username U`, password prompted without echo). The browser fills them straight into the page; MCP exposes only
   `vault_status` (hosts, never secrets). At most 2 sign-in attempts per host per run; a lockout or wrong password
   stops that host (ADR-0046).
8. **Consent window (optional, ADR-0048).** `job-apply-mcp consent --for 24h` (or `--per-run`, `--max N`,
   `--scopes ...`) is typed once, in a terminal, per period you choose. Inside the window submissions are approved
   automatically (logged with the consent id), a page whose only bot check is an invisible widget is submitted
   with one click, and an emailed code is read from the newest message of the expected sender and entered once.
   Unattended codes stay off until `verification.trusted_authserv_ids` lists your own mail server's
   Authentication-Results id (user config only), so a spoofed sender cannot supply a code.
   You review the results afterwards (`list_applications`). `consent --revoke` ends it; `consent_status` (MCP) is
   read-only and no tool can create one.
9. **Owner-only questions (ADR-0050).** Contact, messaging and marketing permissions (SMS, WhatsApp, calls, email,
   job alerts, talent community) are never answered Yes; only your own `optin:<channel>` answer applies, and only
   to a single, plain permission question. Otherwise they stay with you, or are declined (labelled `assumed`) at
   `answers.autonomy = "safe_default"` or `"infer"` (item 5). Authorization and sponsorship come only from
   structured per-country facts.

## Transports

```bash
job-apply-mcp                                                  # stdio (what clients launch)
job-apply-mcp --transport http --host 127.0.0.1 --port 8765   # http://127.0.0.1:8765/mcp
JOB_APPLY_MCP_TOKEN=... job-apply-mcp --transport http --host 0.0.0.0   # non-local: token required
```

HTTP binds loopback by default; any other address refuses to start without `JOB_APPLY_MCP_TOKEN`
(`Authorization: Bearer ...`). Use a TLS reverse proxy for network access. A [Dockerfile](Dockerfile) is included
(no browser by default; `--build-arg BROWSER=1` adds Playwright and Chromium).

## Documentation

- [Client setup guides](docs/clients/README.md): Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Zed,
  Codex CLI, Gemini CLI, Continue, generic JSON
- [Tool reference](docs/tools.md) and [configuration reference](docs/configuration.md) (generated)
- [FAQ](docs/faq.md), [CHANGELOG](CHANGELOG.md), [design decisions](docs/adr/), [CONTRIBUTING](CONTRIBUTING.md)

## Development

```bash
git clone https://github.com/tanmayagrawal21/job-apply-mcp && cd job-apply-mcp
uv sync --extra dev
uv run ruff check . && uv run pytest -q      # offline; live tests need JAM_LIVE=1
uv run python scripts/gen_config_docs.py     # after changing config.py
```

Privacy scan: `python scripts/privacy_scan.py --terms ~/.config/job-apply-mcp/privacy_terms.txt`. Owner-accepted
findings go in `~/.config/job-apply-mcp/privacy_allow.txt` (outside the repo, `--allow FILE`); see ADR-0051.
The committed `.privacy-allow` holds only fully anchored regexes for fictional fixtures and the public project
identity in manifests (ADR-0042); never add private terms or fingerprints to it.

MIT licensed. Contributions welcome under the [Code of Conduct](CODE_OF_CONDUCT.md).
