jobjourney-claude-plugin 3.1.1

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "jobjourney",
+  "description": "Track job applications, get AI resume evaluations, generate cover letters, prep for interviews, and manage coffee chat networking — all through Claude Code.",
+  "version": "3.1.0",
+  "author": "JobJourney",
+  "homepage": "https://jobjourney.me",
+  "repository": "https://github.com/Rorogogogo/jobjourney-claude-plugin",
+  "mcp": {
+    "config_path": "../.mcp.json"
+  }
+}

package/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "jobjourney": {
+      "type": "http",
+      "url": "https://server.jobjourney.me/mcp",
+      "headers": {
+        "X-API-Key": "${JOBJOURNEY_API_KEY}"
+      }
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 JobJourney
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,333 @@
+# 🚀 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://img.shields.io/npm/v/jobjourney-claude-plugin)](https://www.npmjs.com/package/jobjourney-claude-plugin)
+![License](https://img.shields.io/badge/license-MIT-blue.svg)
+![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)
+![Protocol](https://img.shields.io/badge/protocol-MCP-7c3aed)
+[![GitHub stars](https://img.shields.io/github/stars/Rorogogogo/jobjourney-claude-plugin?style=social)](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.
+
+---
+
+## 🧭 Remote Vs Local
+
+This project has two distinct usage modes.
+
+| Mode | Best for | Includes |
+|---|---|---|
+| **Remote MCP** | Fastest setup, cloud-backed JobJourney tools | Job tracking, AI tools, documents, networking, profile, analytics |
+| **Local plugin / stdio** | Full local scraping and scheduled discovery | Everything above, plus `discover_jobs`, `search_jobs`, `schedule_discovery`, `login_jobsite`, local SQLite |
+
+Important:
+
+- **Local scraping requires the local plugin**, not just the hosted MCP endpoint.
+- **LinkedIn discovery** uses direct HTTP guest scraping.
+- **SEEK discovery** uses Playwright and local browser session support.
+
+---
+
+## 📦 Installation
+
+### Option A: Remote MCP
+
+Use this if you want the hosted JobJourney tools with the least setup.
+
+```bash
+claude mcp add jobjourney -t url -h "X-API-Key: jj_your_api_key_here" https://server.jobjourney.me/mcp
+```
+
+Or add it manually to `~/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "jobjourney": {
+      "type": "url",
+      "url": "https://server.jobjourney.me/mcp",
+      "headers": {
+        "X-API-Key": "jj_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Option B: Local stdio plugin
+
+Use this if you want local discovery, Playwright-backed scraping, scheduling, and SQLite storage.
+
+```bash
+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
+```
+
+If you prefer Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "jobjourney": {
+      "command": "npx",
+      "args": ["-y", "jobjourney-claude-plugin"],
+      "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:
+
+```bash
+npx playwright install chromium
+```
+
+---
+
+## 🚀 Quick Start
+
+### 1. Connect the plugin
+
+```bash
+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
+```
+
+### 2. Log in to browser-backed sites when needed
+
+From Claude:
+
+```text
+Use login_jobsite with site "seek"
+```
+
+### 3. Run discovery
+
+From Claude:
+
+```text
+Use discover_jobs with keyword "full stack", location "Sydney", sources ["linkedin", "seek"], pages 1
+```
+
+### 4. Query the stored results
+
+```text
+Use search_jobs with source "linkedin" and limit 5
+```
+
+### 5. Schedule it
+
+```text
+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.
+
+### LinkedIn
+
+1. Fetch guest search results
+2. Fetch guest job detail HTML for each posting
+3. Extract description, metadata, and external apply URL
+4. Detect ATS from the external URL
+5. Expand supported ATS companies
+
+### SEEK
+
+1. Launch Playwright
+2. Use the browser-backed source flow
+3. 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
+
+```text
+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
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+git checkout -b feature/my-change
+npm test
+npm run typecheck
+git commit -m "feat: my change"
+```
+
+---
+
+## 🔗 Links
+
+- [Website](https://jobjourney.me)
+- [npm package](https://www.npmjs.com/package/jobjourney-claude-plugin)
+- [GitHub repository](https://github.com/Rorogogogo/jobjourney-claude-plugin)
+- [Issues](https://github.com/Rorogogogo/jobjourney-claude-plugin/issues)
+
+---
+
+## 📄 License
+
+[MIT](LICENSE) © JobJourney

package/dist/agent/heartbeat.d.ts

@@ -0,0 +1,11 @@
+export interface HeartbeatData {
+    pid: number;
+    updatedAt: string;
+}
+export declare function writeHeartbeat(homeDir?: string): void;
+export declare function readHeartbeat(homeDir?: string): HeartbeatData | null;
+export declare function isAgentHealthy(options?: {
+    homeDir?: string;
+    maxAgeMs?: number;
+    now?: string;
+}): boolean;

package/dist/agent/heartbeat.js

@@ -0,0 +1,31 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { getJobJourneyPaths } from "../config/paths.js";
+export function writeHeartbeat(homeDir) {
+    const paths = getJobJourneyPaths(homeDir);
+    mkdirSync(path.dirname(paths.heartbeatPath), { recursive: true });
+    const data = {
+        pid: process.pid,
+        updatedAt: new Date().toISOString(),
+    };
+    writeFileSync(paths.heartbeatPath, JSON.stringify(data, null, 2));
+}
+export function readHeartbeat(homeDir) {
+    const paths = getJobJourneyPaths(homeDir);
+    try {
+        const raw = readFileSync(paths.heartbeatPath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function isAgentHealthy(options) {
+    const maxAge = options?.maxAgeMs ?? 60_000;
+    const now = options?.now ? new Date(options.now).getTime() : Date.now();
+    const heartbeat = readHeartbeat(options?.homeDir);
+    if (!heartbeat)
+        return false;
+    const updatedAt = new Date(heartbeat.updatedAt).getTime();
+    return now - updatedAt < maxAge;
+}

package/dist/agent/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent/index.js

@@ -0,0 +1,43 @@
+import { AgentScheduler } from "./scheduler.js";
+import { writeHeartbeat } from "./heartbeat.js";
+const RECONCILE_INTERVAL_MS = 30_000;
+const HEARTBEAT_INTERVAL_MS = 15_000;
+async function main() {
+    console.log("[agent] starting jobjourney-agent");
+    const homeDir = process.env.JOBJOURNEY_HOME;
+    const scheduler = new AgentScheduler();
+    // Initial reconciliation
+    scheduler.reconcile();
+    writeHeartbeat(homeDir);
+    // Periodic reconciliation
+    setInterval(() => {
+        try {
+            scheduler.reconcile();
+        }
+        catch (error) {
+            console.error("[agent] reconciliation error:", error);
+        }
+    }, RECONCILE_INTERVAL_MS);
+    // Periodic heartbeat
+    setInterval(() => {
+        try {
+            writeHeartbeat(homeDir);
+        }
+        catch (error) {
+            console.error("[agent] heartbeat error:", error);
+        }
+    }, HEARTBEAT_INTERVAL_MS);
+    // Handle graceful shutdown
+    const shutdown = () => {
+        console.log("[agent] shutting down");
+        scheduler.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    console.log("[agent] running, reconcile every", RECONCILE_INTERVAL_MS / 1000, "s");
+}
+main().catch((error) => {
+    console.error("[agent] fatal:", error);
+    process.exit(1);
+});

package/dist/agent/process.d.ts

@@ -0,0 +1 @@
+export declare function ensureAgentRunning(homeDir?: string): boolean;

package/dist/agent/process.js

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { isAgentHealthy } from "./heartbeat.js";
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+export function ensureAgentRunning(homeDir) {
+    if (isAgentHealthy({ homeDir })) {
+        return false; // already running
+    }
+    const agentEntry = path.resolve(__dirname, "index.js");
+    const child = spawn(process.execPath, [agentEntry], {
+        detached: true,
+        stdio: "ignore",
+        env: {
+            ...process.env,
+            ...(homeDir ? { JOBJOURNEY_HOME: homeDir } : {}),
+        },
+    });
+    child.unref();
+    return true; // spawned
+}

package/dist/agent/scheduler.d.ts

@@ -0,0 +1,20 @@
+import { runScrape } from "../scraper/core/run-scrape.js";
+import { runDiscovery } from "../discovery/core/run-discovery.js";
+interface AgentSchedulerDeps {
+    runScrape?: typeof runScrape;
+    runDiscovery?: typeof runDiscovery;
+}
+export declare class AgentScheduler {
+    private tasks;
+    private dbPath?;
+    private readonly runScrapeImpl;
+    private readonly runDiscoveryImpl;
+    constructor(dbPath?: string, deps?: AgentSchedulerDeps);
+    private readonly discoveryLogger;
+    reconcile(): void;
+    private runScheduledJob;
+    runScheduledJobForTest(id: number, keyword: string, location: string, source: string, runMode: string, sources: string | null): Promise<void>;
+    stop(): void;
+    get activeCount(): number;
+}
+export {};

package/dist/agent/scheduler.js

@@ -0,0 +1,106 @@
+import cron from "node-cron";
+import { openDatabase } from "../storage/sqlite/db.js";
+import { SchedulesRepo } from "../storage/sqlite/schedules-repo.js";
+import { runScrape } from "../scraper/core/run-scrape.js";
+import { runDiscovery } from "../discovery/core/run-discovery.js";
+import { DiscoveryJobsRepo } from "../discovery/storage/discovery-jobs-repo.js";
+import { ScrapeRunsRepo } from "../storage/sqlite/scrape-runs-repo.js";
+export class AgentScheduler {
+    tasks = new Map();
+    dbPath;
+    runScrapeImpl;
+    runDiscoveryImpl;
+    constructor(dbPath, deps = {}) {
+        this.dbPath = dbPath;
+        this.runScrapeImpl = deps.runScrape ?? runScrape;
+        this.runDiscoveryImpl = deps.runDiscovery ?? runDiscovery;
+    }
+    discoveryLogger = (payload) => {
+        console.log(`[agent:discover] ${JSON.stringify(payload)}`);
+    };
+    reconcile() {
+        const db = openDatabase(this.dbPath);
+        try {
+            const repo = new SchedulesRepo(db);
+            const schedules = repo.list(true);
+            // Remove tasks for schedules that no longer exist or are disabled
+            const activeIds = new Set(schedules.map((s) => s.id));
+            for (const [id, entry] of this.tasks) {
+                if (!activeIds.has(id)) {
+                    entry.task.stop();
+                    this.tasks.delete(id);
+                }
+            }
+            // Add new schedules
+            for (const schedule of schedules) {
+                const s = schedule;
+                if (!this.tasks.has(s.id) && cron.validate(s.cron)) {
+                    const task = cron.schedule(s.cron, () => {
+                        void this.runScheduledJob(s.id, s.keyword, s.location, s.source, s.run_mode, s.sources);
+                    });
+                    this.tasks.set(s.id, { scheduleId: s.id, task });
+                }
+            }
+        }
+        finally {
+            db.close();
+        }
+    }
+    async runScheduledJob(id, keyword, location, source, runMode, sources) {
+        const db = openDatabase(this.dbPath);
+        const runsRepo = new ScrapeRunsRepo(db);
+        const run = runsRepo.createRun({
+            scheduleId: id,
+            keyword,
+            location,
+            source,
+            runMode: runMode === "discover" ? "discover" : "scrape",
+            sources: sources ?? undefined,
+        });
+        try {
+            if (runMode === "discover") {
+                const result = await this.runDiscoveryImpl({
+                    keyword,
+                    location,
+                    sources: sources ? sources.split(",").map((value) => value.trim()).filter(Boolean) : undefined,
+                    pages: 30,
+                }, {
+                    logger: this.discoveryLogger,
+                });
+                new DiscoveryJobsRepo(db).upsertJobs(result.jobs, {
+                    keyword,
+                    location,
+                    runId: run.id,
+                });
+                runsRepo.finishRun(run.id, { status: "success", jobCount: result.jobs.length });
+            }
+            else {
+                await this.runScrapeImpl({ keyword, location, source, dbPath: this.dbPath });
+                runsRepo.finishRun(run.id, { status: "success" });
+            }
+            new SchedulesRepo(db).updateLastRunAt(id);
+        }
+        catch (error) {
+            runsRepo.finishRun(run.id, {
+                status: "error",
+                error: error instanceof Error ? error.message : String(error),
+            });
+            console.error(`[agent] scrape failed for schedule ${id}:`, error);
+        }
+        finally {
+            db.close();
+        }
+    }
+    async runScheduledJobForTest(id, keyword, location, source, runMode, sources) {
+        return this.runScheduledJob(id, keyword, location, source, runMode, sources);
+    }
+    stop() {
+        for (const [, entry] of this.tasks) {
+            entry.task.stop();
+        }
+        this.tasks.clear();
+    }
+    get activeCount() {
+        return this.tasks.size;
+    }
+}

package/dist/api.d.ts

@@ -0,0 +1,2 @@
+export declare const API_BASE_URL: string;
+export declare function apiCall(endpoint: string, options?: RequestInit, apiKey?: string): Promise<unknown>;

package/dist/api.js

@@ -0,0 +1,18 @@
+export const API_BASE_URL = process.env.JOBJOURNEY_API_URL || "http://localhost:5014";
+export async function apiCall(endpoint, options = {}, apiKey) {
+    const url = `${API_BASE_URL}${endpoint}`;
+    const headers = {
+        "Content-Type": "application/json",
+        ...(apiKey && { "X-API-Key": apiKey }),
+        ...options.headers,
+    };
+    const response = await fetch(url, {
+        ...options,
+        headers,
+    });
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`API error ${response.status}: ${errorText}`);
+    }
+    return response.json();
+}

package/dist/config/paths.d.ts

@@ -0,0 +1,6 @@
+export interface JobJourneyPaths {
+    dataDir: string;
+    dbPath: string;
+    heartbeatPath: string;
+}
+export declare function getJobJourneyPaths(homeDir?: string): JobJourneyPaths;

package/dist/config/paths.js

@@ -0,0 +1,10 @@
+import os from "node:os";
+import path from "node:path";
+export function getJobJourneyPaths(homeDir = os.homedir()) {
+    const dataDir = path.join(homeDir, ".jobjourney");
+    return {
+        dataDir,
+        dbPath: path.join(dataDir, "jobs.db"),
+        heartbeatPath: path.join(dataDir, "agent-heartbeat.json"),
+    };
+}

package/dist/constants.d.ts

@@ -0,0 +1,11 @@
+export declare const JOB_STATUS: {
+    readonly EXPIRED: 0;
+    readonly SAVED: 1;
+    readonly APPLIED: 2;
+    readonly INITIAL_INTERVIEW: 3;
+    readonly FINAL_INTERVIEW: 4;
+    readonly OFFERED: 5;
+    readonly REJECTED: 6;
+};
+export declare const STATUS_TEXT: Record<number, string>;
+export declare const STATUS_MAP: Record<string, number>;