🚀 JobJourney Claude Plugin

A production-ready MCP server for JobJourney with AI job-search tools, local job discovery, and scheduled scraping from Claude.

![npm version](https://www.npmjs.com/package/jobjourney-claude-plugin) ![License: AGPL-3.0](LICENSE) ![Commercial License](COMMERCIAL.md) !Node !Protocol ![GitHub stars](https://github.com/Rorogogogo/jobjourney-claude-plugin)

---

✨ What It Does

🤖 AI job-search workflows for resume fit scoring, cover letters, CV generation, interview prep, and career chat
🗂️ Application tracking with saved jobs, notes, status changes, starring, search, and dashboard analytics
🔍 Local job discovery with a canonical discovery engine that stores results in local SQLite
🌐 Mixed scraping strategy: LinkedIn uses direct HTTP guest scraping, while blocked sites like SEEK use Playwright
🏢 ATS expansion for supported providers like Greenhouse and Lever after discovery
⏰ Scheduled discovery through the background agent and MCP tools
💾 Local storage for jobs, runs, schedules, and discovery reports in ~/.jobjourney/jobs.db

---

📸 Demo

Use it naturally from Claude:

"Use discover_jobs with keyword full stack, location Sydney, sources linkedin and seek, pages 1."

"Use search_jobs and show me the latest LinkedIn roles in Sydney."

"Use schedule_discovery to run every day at 9am for backend jobs in Melbourne."

"Evaluate how well my resume matches this job and draft a cover letter."

If you want product screenshots or GIFs later, this is the right place to add them.

---

📦 Installation

Option A: Claude Code

claude mcp add jobjourney \
  -e JOBJOURNEY_API_URL=https://server.jobjourney.me \
  -e JOBJOURNEY_API_KEY=jj_your_api_key_here \
  -e TRANSPORT=stdio \
  -- npx -y jobjourney-claude-plugin@latest

Option B: Claude Desktop

Add this to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "jobjourney": {
      "command": "npx",
      "args": ["-y", "jobjourney-claude-plugin@latest"],
      "env": {
        "JOBJOURNEY_API_URL": "https://server.jobjourney.me",
        "JOBJOURNEY_API_KEY": "jj_your_api_key_here",
        "TRANSPORT": "stdio"
      }
    }
  }
}

Playwright prerequisite

For local browser-backed sources like SEEK, install a browser once:

npx playwright install chromium

---

🚀 Quick Start

1. Connect the plugin

claude mcp add jobjourney \
  -e JOBJOURNEY_API_URL=https://server.jobjourney.me \
  -e JOBJOURNEY_API_KEY=jj_your_api_key_here \
  -e TRANSPORT=stdio \
  -- npx -y jobjourney-claude-plugin@latest

2. Log in to browser-backed sites when needed

From Claude:

Use login_jobsite with site "seek"

3. Run discovery

From Claude:

Use discover_jobs with keyword "full stack", location "Sydney", sources ["linkedin", "seek"], pages 1

4. Query the stored results

Use search_jobs with source "linkedin" and limit 5

5. Schedule it

Use schedule_discovery with keyword "full stack", location "Sydney", time "09:00", sources ["linkedin", "seek"]

---

🔍 Source Support

| Source | Status | Transport | Notes | |---|---|---|---| | linkedin | Active | HTTP guest scraping | Primary supported LinkedIn path | | seek | Active | Playwright | Local browser session support | | indeed | Planned | Playwright | Not implemented yet | | jora | Planned | Playwright | Not implemented yet |

| ATS | Support | |---|---| | greenhouse | Detect + expand | | lever | Detect + expand | | workday | Detect only | | smartrecruiters | Detect only | | ashby | Detect only |

---

🧠 How Local Discovery Works

The local discovery engine lives under src/discovery and uses one canonical job model across all sources.

Fetch guest search results
Fetch guest job detail HTML for each posting
Extract description, metadata, and external apply URL
Detect ATS from the external URL
Expand supported ATS companies

SEEK

Launch Playwright
Use the browser-backed source flow
Normalize results into the same canonical job schema

Storage

Local runs are stored in:

jobs DB: ~/.jobjourney/jobs.db
agent heartbeat: ~/.jobjourney/agent-heartbeat.json

The database stores:

discovered jobs
scrape/discovery runs
schedules

---

🛠 Key Tools

This MCP exposes a broad JobJourney toolset. For local discovery, these are the most important ones:

| Tool | What it does | |---|---| | discover_jobs | Run the canonical multi-source discovery engine and store results locally | | search_jobs | Query jobs already stored in local SQLite | | schedule_discovery | Schedule recurring local discovery runs | | get_latest_discovery_report | Show the latest discovery batch summary | | scrape_jobs | Legacy one-off local scrape path | | login_jobsite | Save browser login state for supported sites | | check_login_status | Confirm browser login state |

And the broader platform also includes:

job tracking
AI fit evaluation
cover letter and CV generation
mock interviews
dashboard analytics
coffee chat networking
profile and document management

---

🏗 Architecture

src/
  index.ts                # FastMCP server entrypoint
  tools/                  # MCP tool registration
  discovery/              # Canonical local discovery engine
    core/                 # orchestration and job types
    sources/              # linkedin guest, seek browser, planned sources
    ats/                  # ATS detection and supported crawlers
    analysis/             # salary, tech stack, PR, experience enrichment
    fallback/             # optional company career-page probing
    storage/              # discovery persistence adapters
    parity/               # TS vs Python parity harness
  scraper/                # legacy browser scraper layer, being phased down
  storage/sqlite/         # SQLite repos and migrations
  agent/                  # background scheduling agent
  config/                 # path and runtime config

Built with FastMCP, TypeScript, Zod, Playwright, and SQLite.

---

⚙️ Environment Variables

| Variable | Description | Default | |---|---|---| | JOBJOURNEY_API_URL | JobJourney backend base URL | https://server.jobjourney.me | | JOBJOURNEY_API_KEY | API key for backend-authenticated features | - | | TRANSPORT | MCP transport: stdio or httpStream | stdio | | PORT | HTTP port when TRANSPORT=httpStream | 8080 |

---

🧪 Development

git clone https://github.com/Rorogogogo/jobjourney-claude-plugin.git
cd jobjourney-claude-plugin
npm install
npx playwright install chromium
npm run build
npm test
npm run typecheck

Useful local commands:

npm run start
npm run agent
npm run parity:discovery
npm run parity:live-smoke

---

🤝 Contributing

Contributions are welcome. Useful contribution areas right now:

tightening the canonical src/discovery architecture
implementing indeed and jora
improving live parity coverage
reducing remaining legacy surface in src/scraper

Standard flow:

git checkout -b feature/my-change
npm test
npm run typecheck
git commit -m "feat: my change"

---

🔗 Links

---

📄 License

License

This project is dual-licensed:

🆓 AGPL-3.0 — free for personal use, open-source forks, and projects themselves open-sourced under a compatible license. See LICENSE.
💼 Commercial license — required for closed-source products, proprietary internal tools, or paid / hosted services where AGPL-3.0's copyleft and network-use obligations don't fit. See COMMERCIAL.md.

Do I need a commercial license?

| Use case | License | |---|---| | Personal use / running locally | AGPL-3.0 (free) | | Forking and publishing under AGPL-3.0 | AGPL-3.0 (free) | | Bundling into a closed-source product | Commercial | | Hosting a modified version as a SaaS without publishing source | Commercial | | Internal company tool not open-sourced | Commercial |

For a commercial license, contact Robert Wang at xwang.robert@gmail.com — see COMMERCIAL.md for what to include in your request.

jobjourney-claude-plugin