Skip to main content
Glama

Python 3.12 MCP License: MIT Status: Alpha Website

Visit the live CareerBot website

CareerBot

CareerBot is an open‑source Python MCP server for bounded, auditable job‑application preparation and tracking. It helps you:

  • Normalize and rank supplied jobs (manual input, parsed alerts, permitted adapters)

  • Score fit against a private, hash‑verified Master CV using xAI

  • Generate role positioning, tailored LaTeX resumes, and concise cover letters

  • Enforce deterministic ATS and one‑page PDF checks

  • Save immutable application snapshots with SHA‑256 manifests

  • Track prepared/submitted applications locally and (optionally) in Airtable

It’s built for explicit handoffs and review—not unattended job‑board automation.

Features

  • Narrow, typed tools exposed over MCP (stdio or authenticated HTTP)

  • Dry‑run by default; never submits without explicit approval

  • Immutable, verifiable artifacts (PDFs and manifest) for audits

  • Explicit submission policy with hard stops (CAPTCHA, MFA, identity, consent, ambiguous answers, restricted platforms)

  • Optional Airtable tracking via least‑privilege PAT

Related MCP server: resume-coverletter-mcp

Quickstart

Requirements: Python 3.12+, Tectonic (for local LaTeX → PDF), and either uv or pip.

git clone https://github.com/Sai21112000/CareerBot.git
cd CareerBot
# with uv (recommended)
uv sync --extra dev
# or with pip
python -m pip install -e .[dev]

Create local, private files (kept out of git):

cp .env.example .env
cp data/master_resume.tex.example data/master_resume.tex
cp AGENTS.md.example AGENTS.md
chmod 600 .env data/master_resume.tex AGENTS.md

Replace every [VERIFIED ...] marker in data/master_resume.tex. Put any supporting sources under the ignored data/master_cv/ directory. These are the factual boundary for generated claims.

Minimum configuration for model‑backed tools (add to .env):

CAREERBOT_XAI_API_KEY=
CAREERBOT_XAI_MODEL=grok-4.6
# Optional Airtable tracking:
# CAREERBOT_AIRTABLE_PAT=
# CAREERBOT_AIRTABLE_BASE_ID=

Run the MCP server (stdio)

uv run careerbot-mcp
# or, if installed with pip:
careerbot-mcp

The committed .mcp.json in this repo is already wired for stdio with a conservative dry_run profile.

Run the MCP server (authenticated HTTP)

CAREERBOT_MCP_TRANSPORT=streamable-http \
CAREERBOT_MCP_HOST=127.0.0.1 \
CAREERBOT_MCP_PORT=8000 \
CAREERBOT_MCP_AUTH_TOKEN='change-me' \
uv run careerbot-mcp

Point your remote client at https://your-host.example/mcp and use the same bearer token. The bundled static token verifier is for development—use an OAuth/JWT provider in production.

Connect a client (example)

Cursor-style client entry (stdio) looks like:

{
  "mcpServers": {
    "careerbot": {
      "command": "uv",
      "args": ["run", "careerbot-mcp"],
      "env": {
        "CAREERBOT_EXECUTION_PROFILE": "dry_run",
        "CAREERBOT_MAX_JOBS_PER_RUN": "100",
        "CAREERBOT_MAX_APPLICATIONS_PER_RUN": "10",
        "CAREERBOT_MAX_RUN_MINUTES": "30"
      }
    }
  }
}

MCP tools

All tool names and descriptions are taken from the code in mcp_servers/job_agent/server.py.

Tool

Description

consult_career_positioning

Generate a CV‑grounded career strategy for review without saving it.

save_career_strategy

Save an explicitly reviewed strategy and an immutable snapshot.

get_career_strategy

Return the currently approved downstream career strategy.

search_jobs

Normalize, rank, and deduplicate permitted supplied job data.

score_job

Score one job against the verified master resume.

tailor_resume

Tailor the master LaTeX resume and enforce all deterministic rules.

generate_cover_letter

Generate a concise cover letter grounded in the tailored resume.

save_application_snapshot

Compile and atomically save a complete immutable application package.

verify_snapshot

Verify immutable artifact sizes and SHA‑256 hashes.

track_application

Upsert an application in Airtable when configured and in the CSV backup.

submission_hard_stops

Return conditions that always require a manual handoff.

assess_submission

Decide whether an application can use an authorized automatic connector.

Safety model

  • Default profile is dry_run. No shipped command submits to a portal.

  • Human approval gates are required for anything beyond local artifact preparation.

  • Submission hard stops always trigger a manual handoff: CAPTCHA, MFA, identity verification, consent or declaration, ambiguous answers, restricted platforms, and unsupported connectors.

  • Every prepared application snapshot is immutable and auditable: PDFs and metadata are recorded with file sizes and SHA‑256 hashes.

Environment limits (recommended defaults used by .mcp.json):

CAREERBOT_MAX_JOBS_PER_RUN=100
CAREERBOT_MAX_APPLICATIONS_PER_RUN=10
CAREERBOT_MAX_RUN_MINUTES=30

Profiles:

  • dry_run: local inspection and simulation

  • review: prepares artifacts; requires review before any external action

  • auto: reserved for explicitly authorized connectors that have passed supervised qualification

Project structure

  • src/job_agent/ — typed domain models, CLI, scoring, strategy, validation, tracking, policy

  • mcp_servers/job_agent/ — FastMCP composition root and the 12 MCP tools

  • .agent/ — optional agent definitions, skills, and bounded workflow runbooks

  • docs/ — static website served by GitHub Pages

  • examples/ — fictional job inputs and command examples

  • data/ — public templates and integration schemas; private runtime files are ignored

  • workspaces/ — per‑platform instructions; active queues and logs are ignored

  • tests/ — offline unit and integration‑contract tests

Development and tests

# install with dev extras
uv sync --extra dev
# or: python -m pip install -e .[dev]

# run tests and static checks
python -m pytest
ruff check .
mypy src/job_agent mcp_servers

Website publishing

The project site is a static website in docs/ and is published with GitHub Pages:

  • Settings → Pages → Build and deployment → Source = Deploy from a branch

  • Branch: main, Folder: /docs

Screenshots

These are generated by the taste‑skill inspector at 1440px and 390px.

Website preview — desktop

Website preview — mobile

Credits

Pictures used on the site are openly licensed and credited in‑page:

  • “Olympia Simplex” by Sammlung der Medien und Wissenschaft, CC BY 4.0, via Wikimedia Commons.

  • “Typewriter-12 hg” by Hannes Grobe, CC BY-SA 4.0, via Wikimedia Commons.

  • “Cover for ‘Coleccion de Cartas Amorosas Cuaderno No. 6’, a young woman writing a letter at a desk” by José Guadalupe Posada / Antonio Vanegas Arroyo, CC0, via Wikimedia Commons.

  • “Writing a Letter of Resignation” by CIPHR Connect, CC BY 2.0, via Wikimedia Commons.

License

CareerBot is released under the MIT License.

Available Tools

12 tools
assess_submissionAssess SubmissionC

Decide whether an application can use an authorized automatic connector.

Inputs: source_url (required), mfa_required, captcha_present, ambiguous_questions, +2 more. Returns: object

consult_career_positioningConsult Career PositioningA

Generate a CV-grounded career strategy for review without saving it.

Inputs: market_context. Returns: object

generate_cover_letterGenerate Cover LetterB

Generate a concise cover letter grounded in the tailored resume.

Inputs: job (required), tailored_resume_text (required). Returns: object

get_career_strategyGet Career StrategyA

Return the currently approved downstream career strategy.

Inputs: no named parameters. Returns: result

save_application_snapshotSave Application SnapshotC

Compile and atomically save a complete immutable application package.

Inputs: job (required), changes (required), resume_tex (required), cover_letter (required), +5 more. Returns: object

save_career_strategySave Career StrategyC

Save an explicitly reviewed strategy and an immutable snapshot.

Inputs: strategy (required). Returns: object

score_jobScore JobB

Score one job against the verified master resume.

Inputs: role (required), company (required), description (required), job_url, +2 more. Returns: object

search_jobsSearch JobsC

Normalize, rank, and deduplicate permitted supplied job data.

Inputs: query (required), limit, manual_jobs, email_alerts. Returns: result

submission_hard_stopsSubmission Hard StopsA

Return conditions that always require a manual handoff.

Inputs: no named parameters. Returns: result

tailor_resumeTailor ResumeC

Tailor the master LaTeX resume and enforce all deterministic rules.

Inputs: job (required). Returns: object

track_applicationTrack ApplicationC

Upsert an application in Airtable when configured and in the CSV backup.

Inputs: record (required). Returns: object

verify_snapshotVerify SnapshotB

Verify immutable artifact sizes and SHA-256 hashes.

Inputs: snapshot_path (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools map cleanly to distinct actions: strategy lifecycle, resume/cover letter generation, snapshot verification, and tracking are all clearly separated. The only mild ambiguity is between search_jobs/score_job and submission_hard_stops/assess_submission, where the evaluation and approval responsibilities are adjacent.

    Naming Consistency4/5

    Nearly all tools follow a verb_noun snake_case pattern such as save_career_strategy, tailor_resume, and verify_snapshot. The outlier is submission_hard_stops, which is a noun phrase rather than a verb-led action, creating a small but noticeable inconsistency.

    Tool Count5/5

    Twelve tools is well-scoped for a career-application pipeline covering strategy, job matching, resume/cover letter production, snapshot verification, tracking, and submission assessment. Each tool addresses a distinct stage or artifact, so the count feels purposeful rather than bloated.

    Completeness4/5

    The core lifecycle is well covered: strategy approval, job scoring, resume tailoring, cover letter generation, application snapshot creation and verification, tracking, and submission assessment. Minor gaps exist around retrieving past application snapshots and actually executing a submission, though the design may intentionally stop at assessment and manual handoff.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables LLM clients to analyse job postings, tailor resumes from an evidence-labelled profile, validate every claim against that profile, and track applications, all through deterministic MCP tools.
      7
      Apache 2.0
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables Claude Web users to manage their job application workflow by storing profile and resume data, analyzing job descriptions, preparing applications, and tracking progress — all with manual submission and no platform automation.
      1
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to discover postings from watched company boards ranked by keyword fit, tailor and fact-check resumes against a source-cited profile, render ATS-readable PDFs, submit applications through the user's own browser, and track replies and follow-ups. All ranking, claim checking and email classification run as plain code, so LLM tokens are spent only on writing.
      1
      Apache 2.0