# career-compass-mcp [Health: Active]
**Category:** π’ Workplace & Productivity
**Repository:** https://github.com/benskamps/career-compass-mcp
**GitHub Stars:** 6
**npm Downloads (last month):** 2393
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/career-compass-mcp
## Description
AI-native career co-pilot for Claude β Career KB, resume tailoring, job pipeline, interview prep, and offer evaluation via MCP
## Tools
Capabilities this server exposes over MCP:
- **explore_opportunity** β Judges a posting against your KB **and your stated preferences** β salary band, remote, relocation, notice period. Opens with a verdict (Strong fit, Stretch, or Long shot) and the biggest reason, then an explicit comp and location check, evidence per requirement, honest gaps, talking points and redβ¦
- **research_company** β Builds an intelligence brief: product, culture, funding, interview process, strategic fit
- **tailor_resume** β Writes a rΓ©sumΓ© tailored to one posting from your KB β standard, federal, academic, or functional β using the posting's words only where your history says the same thing
- **generate_cover_letter** β Writes a cover letter with your actual achievements woven in, in a tone you pick β professional, conversational, enthusiastic, or concise
- **format_for_ats** β Reformats rΓ©sumΓ© text you already have into plain sections an applicant tracking system can parse, ready to paste field by field (Workday, Greenhouse, Lever, LinkedIn, iCIMS, Taleo, SmartRecruiters, or generic). Reformats only; it never rewrites what you did
- **answer_application** β Answers an application form's questions from your KB, each within its limit. Work authorization, salary and start date come only from what you saved or said, and a "years with X" your history can't support is flagged, never inflated
- **pipeline_view** β Lists applications, funnel stats, what needs attention, or one application by id
- **pipeline_add** β Adds one application, dated the day you applied (`dateApplied`, defaults to today). Optional starting `status` (defaults to `applied`); unknown statuses are rejected with a did-you-mean suggestion
- **pipeline_update** β Updates one application β status, notes, follow-up date, a contact, an interview round and how it went, or an offer's terms and answer deadline
- **classify_email** β Classifies a job-search email and extracts contacts, dates, and suggested pipeline updates
- **prepare_interview** β Full prep: opening pitch, STAR stories, likely questions, company alignment, questions to ask
- **interview_arc** β Mid-process projection. Reconstructs the arc so far from your recorded rounds and journal signals, then projects what the **next** round will probe β ground already covered, threads the last interview left open, gaps nobody has tested yet, ranked likely questions
- **evaluate_offer** β Breaks down total comp, compares to market, builds negotiation strategy, drafts counter scripts
- **generate_rejection_response** β Drafts a graceful keep-the-door-open reply. Pass `applicationId` and it also marks that application rejected
- **save_career_section** β Writes one section of your Career KB as plain YAML β this is how the KB gets populated. Replaces the whole section; the previous version is kept as a `.bak
- **ingest_document** β Extracts achievements from any document: performance review, award email, recommendation, project summary
- **capture_insight** β Appends a dated signal to your career journal β fit signals, interview insights, offer reflections, rejection patterns, skill evidence, wins β which later rΓ©sumΓ©, interview, and fit prompts read back
- **harvest_evidence** β Reads a local project's git history and reports what you measurably did there β months active, files and file types touched, your share of commits, test ratio β each with the exact command that produced it. Only your own commits count, and it names the identity it used. It writes nothing, anywhere
- **check_setup** β Health-checks the install in one pass β version vs. the current npm release, data directory, filled KB sections, pipeline parse, leftover temp files, dashboard status β each with the one command that fixes it. Run it first when anything seems off
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):
```json
"mcpServers": {
"career-compass-mcp": {
"command": "npx",
"args": ["-y","career-compass-mcp"]
}
}
```
## Documentation & README
[](https://www.npmjs.com/package/career-compass-mcp)
[](https://www.npmjs.com/package/career-compass-mcp)
[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
**Paste a job posting. Get an honest fit verdict.**
Paste a job posting and your resume, and ask "Do I fit this?" You get a straight verdict
(strong fit, stretch, or long shot), each of the posting's must-haves matched to evidence
from your own background, and the top two gaps with how to handle them. Then Claude can
tailor your rΓ©sumΓ©, write the cover letter and prep the interview without padding your
history. Free, MIT-licensed, and in Claude Code and Cowork your files stay on your own
computer.
## Try it now
Just installed it and not sure what to type? Open a new chat and send whichever of these
fits where you are. Each one works on its own in claude.ai chat, Cowork and Claude Code.
**You have a job in mind.** Send this, with your rΓ©sumΓ© and the posting pasted or attached
underneath (a PDF is fine):
```
Here's my rΓ©sumΓ© and a job I'm considering. Do I fit this?
```
**You only have your rΓ©sumΓ©.**
```
Here's my rΓ©sumΓ©. What roles does it support today, and what would a screener skip?
```
**You have neither at hand.** See a full fit check on a made-up profile first, with nothing
of yours shared:
```
Show me a sample Career Compass fit check.
```
## What a fit check looks like
*A real run:* the `explore_opportunity` output on the bundled sample data,
and Claude's reply to it, trimmed for length (every cut is shown as "β¦"). Also as an
[MP4](https://github.com/benskamps/career-compass-mcp/blob/HEAD/docs/assets/demo/demo.mp4); how it was made is in
[docs/assets/demo/source](https://github.com/benskamps/career-compass-mcp/blob/HEAD/docs/assets/demo/source/README.md).
Another example in text, on the same fictional Alex Rivera who ships with the package and a
different made-up posting:
```
You: [pastes a VP of Operations posting from a payments company]
Do I fit this?
Claude: Stretch: strong on operations at scale, but no P&L or payments
experience yet.
Must-haves, with your evidence
- 8+ years leading operations teams: Operations Manager at Apex
Logistics, team of 42; Senior Program Manager at MedFlow, 6 PMs.
- Scaling a process across sites: patient onboarding cut from 47 days
to 11 across 3 acquired health systems.
- Vendor and cost management: procurement cycle cut from 9 months to
6 weeks; headcount costs down 18% while throughput rose 31%.
Top two gaps
1. P&L ownership. You ran $8M in program budgets, which isn't a P&L.
Say what that budget covered, and ask in the screen whether the
role owns a P&L from day one.
2. Payments. Nothing in your history is payments or fintech. Lead
with the healthcare compliance work as the closest thing, and
don't claim more.
Want me to tailor your rΓ©sumΓ© to this one, or track it?
```
The real reply goes on with talking points, red flags and questions to ask. A "day in the
life" of the role comes only when you ask for one.
## It won't pad your rΓ©sumΓ©
Every sentence it writes about you has to come from your history or from what you told it.
When a stronger draft needs a fact it doesn't have, the draft says so in place:
```
- Cut patient onboarding from 47 days to 11 after the acquisition of 3
regional health systems, leading a team of [confirm: team size] and
eliminating $2.1M in compliance penalties over 18 months.
```
The sample record says what changed, not how many people did it, so the bullet asks. You
fill in the bracket or cut it; nothing gets invented to sound stronger.
## Get it in the Claude directory
In the Claude app or on claude.ai, open **Customize β Plugins**, search for
**Career Compass**, and add it. That's the whole install.
| Where you use Claude | What you get |
|---|---|
| **claude.ai chat** (web, desktop, mobile) | The skills only. Paste a rΓ©sumΓ© and a posting and Claude does the fit check, tailoring, interview prep or offer review in the conversation. A short Career Compass card carries your roles and dates into your next chat (keep it in a "Job search" Project and every chat there starts from it), and Claude can put your next follow-up on your calendar. |
| **Cowork** and **Claude Code** on your computer | The skills plus the local server: your career history and every application are kept as plain YAML on your computer, so later answers start from them. Needs **Node.js 22 or newer**. |
The commands below work in Claude Code and Cowork. In claude.ai chat, just ask in plain
words ("prep me for my interview on Friday").
| Command | What it does |
|---|---|
| `/career-compass:start` | Sets up your career history from a pasted rΓ©sumΓ©, or shows what to try first |
| `/career-compass:fit-check` | A fit verdict for a pasted posting |
| `/career-compass:interview-prep` | Likely questions, three to five STAR stories from your real work, and questions to ask |
| `/career-compass:today` | One "start here" move, then the rest of today's list |
| `/career-compass:debrief` | Right after an interview: what landed, what to sharpen, and a thank-you note per interviewer from your own notes |
| `/career-compass:week` | Your week: what moved, stalled or closed, your pace, and one focus for next week |
| `/career-compass:sweep` | Checks your inbox and calendar (through connectors you already use) for job-search mail and invites, then updates applications in one batch you approve. Never sends email |
| `/career-compass:find` | Finds open roles that match you, ranks the best few against your real history with a link to each, and skips what you already track. Never applies for you |
| `/career-compass:feedback` | Turns something it got wrong into a short report with your personal details taken out, shows you every word, and gives you a link to send it to the maker. Nothing is sent unless you send it |
| `/career-compass:answer` | Answer an application form's questions from your real history |
A few things it does once you've used it for a while: saves end with a receipt of what
changed, you can record an offer or how an interview round went, and `/career-compass:today`
leads with a debrief the day after an interview. When you accept an offer it switches to
closing out the search and then to your first weeks in the new job. If you want a nudge,
you can set up a [morning briefing](#a-morning-briefing-if-you-want-one) on your own
computer.
## Turn your git history into honest rΓ©sumΓ© evidence
If you write code, you have a record of what you did. Ask:
> **"Look at my project in ~/code/billing-service and tell me what I can honestly claim on my rΓ©sumΓ©."**
`harvest_evidence` reads that project's git history on your computer and reports counts,
each with the command that produced it. It writes nothing and sends nothing.
```
## What is measurably true
- Committed to billing-service across 14 distinct months, 2024-11 to 2025-12.
- how: git log --no-merges --author= --since=2024-10-07; counted distinct YYYY-MM values.
- 212 of 530 non-merge commits in this window are yours (40%).
- how: git rev-list --count --no-merges, with and without --author. Share of commits,
which is a measure of participation and NOT of contribution size.
## What this cannot tell you
- Did any of this ship to real users, and did anything measurable change when it did?
That number is the rΓ©sumΓ© line; none of the above is.
```
*Example on made-up numbers.* Counts are not achievements, so Claude asks the questions the
log can't answer first. Say you built the invoicing service and it shipped, and the draft
keeps to that:
```
- Built the invoicing service in billing-service over 14 months (212 commits),
which [confirm: what changed for users once it shipped, and by how much?].
```
## Tell me what it got wrong
There is no telemetry, so the only way I hear about a bad fit check is if you say so.
[Open a "What did your first fit check get wrong?" issue](https://github.com/benskamps/career-compass-mcp/issues/new?template=fit-check-wrong.yml)
(leave out anything personal), or say what you used it for in
[Discussions](https://github.com/benskamps/career-compass-mcp/discussions).
More: [How Career Compass works](https://benskamps.github.io/career-compass-mcp/how-it-works/),
with pages for [people who were laid off](https://benskamps.github.io/career-compass-mcp/for/laid-off/),
[career switchers](https://benskamps.github.io/career-compass-mcp/for/career-switchers/) and
[new grads](https://benskamps.github.io/career-compass-mcp/for/new-grads/).
---
## For other MCP clients
Everything below is for running the server yourself, outside the Claude directory: Claude
Desktop, Cursor, other MCP clients, or Claude Code without the plugin. If you installed the
plugin, skip it. Running the command below as well would register a second copy of every
tool, so `install` detects the plugin and leaves Claude Code alone.
The package has 19 tools, 4 prompts, 9 resources and a local dashboard. To see the
dashboard on the bundled sample first, with no install and no data of your own:
```bash
npx -y career-compass-mcp dashboard --sample
```
It opens in your browser, read-only, against the fictional Alex Rivera search. Nothing is
written and nothing leaves your machine.
### Everywhere else, in one command
One command wires every Claude client on your machine β Claude Desktop, Claude Code, and
Cursor β and tells you what to restart:
```bash
npx -y career-compass-mcp install
```
It backs up any config it touches, leaves your other servers alone, skips clients you don't
have, and does nothing twice. It pins the version it installs and downloads it once up front,
so no launch ever reinstalls; run it again to upgrade. `--dry-run` shows the plan first; `--data /path/to/career-data`
puts your files somewhere other than `~/.career-compass`. Then say to Claude: **"Run the
Career Compass setup check."**
Prefer to do it by hand, or use another client? Every route below runs the same server, and
none of them needs a clone or a build.
### Claude Code
One command:
```bash
claude mcp add career-compass -s user -- npx -y career-compass-mcp
```
`-s user` installs it for every project rather than just this one. Confirm it landed with
`claude mcp list`.
To keep your career files somewhere other than the default `~/.career-compass`:
```bash
claude mcp add career-compass -s user -e CAREER_DATA_PATH=/path/to/career-data -- npx -y career-compass-mcp
```
### Claude Desktop
**The extension bundle is the short way.** Download the `.mcpb` file from the
[Releases page](https://github.com/benskamps/career-compass-mcp/releases/latest), then in
Claude Desktop go to **Settings β Extensions** and install it. There is no JSON to edit and
nothing to install first. Set `CAREER_DATA_PATH` in the extension's own settings if you
want your files somewhere other than `~/.career-compass`.
The bundle does not self-update: to upgrade, download the newer `.mcpb`, remove the
installed extension, and install the new file. Note your data path before removing it β
settings are re-entered on install, and `check_setup` prints the path.
**Or point Claude Desktop at npx.** Open **Settings β Developer β Edit Config**, or edit
the file directly:
| OS | Config file |
|----|-------------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
Add the server:
```json
{
"mcpServers": {
"career-compass": {
"command": "npx",
"args": ["-y", "career-compass-mcp"]
}
}
}
```
Pin a version in `args` (`"career-compass-mcp@2.14.1"` rather than the bare name) if you can:
Desktop starts the server twice at once, and an unpinned name reinstalls on every release,
which can leave npx's cache half-written (see **On npx** below). `install` does this for you.
Restart Claude Desktop. To choose your own data directory, add an `env` block alongside
`args`:
```json
"env": { "CAREER_DATA_PATH": "/Users/you/career-data" }
```
### Any other MCP client
Cursor, Windsurf, Cline, Continue and friends all take the same shape β a stdio server
with `command: "npx"` and `args: ["-y", "career-compass-mcp"]`. Drop that into whatever the
client calls its MCP config.
**Zed** β add to your `settings.json`:
```json
{
"context_servers": {
"career-compass": {
"command": {
"path": "npx",
"args": ["-y", "career-compass-mcp"]
}
}
}
}
```
### Prefer a global install
```bash
npm install -g career-compass-mcp
```
Then use `"command": "career-compass-mcp"` with no `args`, or
`claude mcp add career-compass -s user -- career-compass-mcp`.
### Confirm it worked
Ask Claude:
> **"Run the Career Compass setup check."**
That calls `check_setup`, which reports your version against the current npm release, where
your data directory is, which Career KB sections are filled in, whether your pipeline
parses, and whether the dashboard is running β each finding with the one command that fixes
it. It is read-only, so it runs without a permission prompt.
---
## Your first conversation
Open Claude and say:
> **"Set up my Career KB. Here's my rΓ©sumΓ©:"** [paste your rΓ©sumΓ©]
Claude will extract your work history, achievements, and skills into structured YAML, ask
clarifying questions about gaps or vague metrics, and call `save_career_section` once per
section to write it to disk.
`save_career_section` is where your history actually lands. It saves one section at a time
(`profile`, `experience`, `skills`, `education`, `projects`, `testimonials`), validates
against the schema before touching the file, and keeps the previous version as a
timestamped `.bak`. It compares each save with what is stored: a save that would drop roles
or achievements is refused unless the call says to replace them, and every save ends with a
one-line receipt of what changed. Your client asks you to confirm each write; approving them
is what fills the KB.
That is the whole setup. From there every tool has full context on who you are, and the KB
compounds β each posting you explore, interview you debrief, and offer you weigh can add a
dated signal back to it.
**Already have material lying around?** Performance reviews, award emails, recommendations,
old project write-ups β paste any of them and ask Claude to pull the achievements out. That
is `ingest_document`. It reads and extracts but never writes; `save_career_section` is still
what puts the results on disk.
---
## Your data stays on your machine
Career Compass is local-first by design. Your real career data β rΓ©sumΓ© history, the
companies you are talking to, salary numbers, interview notes β lives in **plain YAML files
on your own disk**.
- **Where it lives:** `~/.career-compass/` by default, or wherever you point
`CAREER_DATA_PATH`. The directory is created the first time you save something, on
*your* machine, and is not part of the npm package.
- **Who sees it:** only the MCP client you connect it to, and through that client your model
provider, under *their* policy β and only for the requests you make. Career Compass sends
it nowhere on its own.
- **The server makes no network requests.** No update check, no analytics, no
phone-home path anywhere in the package.
- **Requests you run yourself:** any `npx β¦ career-compass-mcp` command, including the
dashboard command `check_setup` prints, has npm download the package from the same
registry. That is npm fetching code, and it carries none of your data.
- **The dashboard's `--ask-claude` option** runs Claude Code on your computer, which sends
the Career KB content it reads to Anthropic under your own Claude account and billing.
It is off unless you start the dashboard with it, and read-only unless you start it with
`--ask-claude-writes`.
- **Schedules are yours:** Career Compass runs nothing on a timer. A
[morning briefing](#a-morning-briefing-if-you-want-one) is a task you create in your own
Claude app; it runs on your computer and only reads.
- **What ships in the package:** the server code and a small set of **fictional** example
files (`data/example/` β the Alex Rivera persona). A publish-time leak guard enforces that
no real career data can ride along.
- **The dashboard reads at request time, locally.** Your YAML is read when you open a page,
by a server on your own `localhost`. It is never baked into a build, never prerendered,
and never sent over the network.
- **What else is in that folder:** timestamped `.bak` copies of previous versions (only
the newest 5 per data file are kept; older ones are deleted automatically on the next
write, and backups you make by hand are never touched), plus β only while a write is actually happening β a
`.write-claim` file that stops a second Career Compass process from writing at the same
time.
- **Retention is yours:** files stay until you delete them. Remove the `CAREER_DATA_PATH`
directory and everything is gone.
Treat `~/.career-compass/` like any private notebook β back it up, and do not commit it to a
public repo. (This repo's `.gitignore` already excludes `data/career/` and `data/pipeline/`.)
Full policy: **[PRIVACY.md](https://github.com/benskamps/career-compass-mcp/blob/HEAD/PRIVACY.md)** Β·
published at Β·
questions or concerns: [open an issue](https://github.com/benskamps/career-compass-mcp/issues)
---
## A morning briefing, if you want one
Career Compass never runs on a timer. If you'd like your job-search list waiting each
morning, you can create a **local** scheduled task in the Claude Code desktop app (see
[desktop scheduled tasks](https://code.claude.com/docs/en/desktop-scheduled-tasks)). A local
task runs on your computer, so it reaches the server and your data folder. Give it this
prompt, as plain text:
> Call pipeline_view with action next_actions. Lead with the Start here item in eight lines or fewer, and change nothing. If it's after 2pm, say it's a catch-up run.
Use the plain prompt rather than `/career-compass:today`: scheduled runs don't start
commands that only run when you type them. `pipeline_view` only reads, so the briefing
changes nothing. Cowork's scheduled tasks may run remotely, where your local data folder
isn't available, so try one by hand before relying on it. Cloud routines and `/loop` don't
fit this: cloud runs can't see your files, and `/loop` ends with the session.
---
## Tools
Eighteen tools, grouped by where they land in a search. **Read** tools take no permission
prompt in most clients; **Write** tools ask before touching your files.
### Find and assess a role
| Tool | Access | What it does |
|------|--------|-------------|
| `explore_opportunity` | Read | Judges a posting against your KB **and your stated preferences** β salary band, remote, relocation, notice period. Opens with a verdict (Strong fit, Stretch, or Long shot) and the biggest reason, then an explicit comp and location check, evidence per requirement, honest gaps, talking points and red flags. A "day in the life" only when you ask. Pass `sourceFitLabel` ("LinkedIn: strong match") and it will agree or disagree with the job board, in both directions |
| `research_company` | Read | Builds an intelligence brief: product, culture, funding, interview process, strategic fit |
### Apply
| Tool | Access | What it does |
|------|--------|-------------|
| `tailor_resume` | Read | Writes a rΓ©sumΓ© tailored to one posting from your KB β standard, federal, academic, or functional β using the posting's words only where your history says the same thing |
| `generate_cover_letter` | Read | Writes a cover letter with your actual achievements woven in, in a tone you pick β professional, conversational, enthusiastic, or concise |
| `format_for_ats` | Read | Reformats rΓ©sumΓ© text you already have into plain sections an applicant tracking system can parse, ready to paste field by field (Workday, Greenhouse, Lever, LinkedIn, iCIMS, Taleo, SmartRecruiters, or generic). Reformats only; it never rewrites what you did |
| `answer_application` | Read | Answers an application form's questions from your KB, each within its limit. Work authorization, salary and start date come only from what you saved or said, and a "years with X" your history can't support is flagged, never inflated |
### Track the pipeline
| Tool | Access | What it does |
|------|--------|-------------|
| `pipeline_view` | Read | Lists applications, funnel stats, what needs attention, or one application by id |
| `pipeline_add` | Write | Adds one application, dated the day you applied (`dateApplied`, defaults to today). Optional starting `status` (defaults to `applied`); unknown statuses are rejected with a did-you-mean suggestion |
| `pipeline_update` | Write | Updates one application β status, notes, follow-up date, a contact, an interview round and how it went, or an offer's terms and answer deadline |
| `classify_email` | Read | Classifies a job-search email and extracts contacts, dates, and suggested pipeline updates |
### Interview and decide
| Tool | Access | What it does |
|------|--------|-------------|
| `prepare_interview` | Read | Full prep: opening pitch, STAR stories, likely questions, company alignment, questions to ask |
| `interview_arc` | Read | Mid-process projection. Reconstructs the arc so far from your recorded rounds and journal signals, then projects what the **next** round will probe β ground already covered, threads the last interview left open, gaps nobody has tested yet, ranked likely questions |
| `evaluate_offer` | Read | Breaks down total comp, compares to market, builds negotiation strategy, drafts counter scripts |
| `generate_rejection_response` | Write | Drafts a graceful keep-the-door-open reply. Pass `applicationId` and it also marks that application rejected |
### Feed the knowledge base
| Tool | Access | What it does |
|------|--------|-------------|
| `save_career_section` | Write | Writes one section of your Career KB as plain YAML β this is how the KB gets populated. Replaces the whole section; the previous version is kept as a `.bak` |
| `ingest_document` | Read | Extracts achievements from any document: performance review, award email, recommendation, project summary |
| `capture_insight` | Write | Appends a dated signal to your career journal β fit signals, interview insights, offer reflections, rejection patterns, skill evidence, wins β which later rΓ©sumΓ©, interview, and fit prompts read back |
| `harvest_evidence` | Read | Reads a local project's git history and reports what you measurably did there β months active, files and file types touched, your share of commits, test ratio β each with the exact command that produced it. Only your own commits count, and it names the identity it used. It writes nothing, anywhere |
### Keep the install healthy
| Tool | Access | What it does |
|------|--------|-------------|
| `check_setup` | Read | Health-checks the install in one pass β version vs. the current npm release, data directory, filled KB sections, pipeline parse, leftover temp files, dashboard status β each with the one command that fixes it. Run it first when anything seems off |
---
## Resources
Claude can read these directly ("read my career profile"):
| Resource | URI | Contents |
|----------|-----|----------|
| Career Profile | `career://profile` | Name, contact, summary, targets, preferences |
| Work Experience | `career://experience` | Full history with achievements |
| Skills Inventory | `career://skills` | Skills with proficiency and recency |
| Projects | `career://projects` | Portfolio with outcomes |
| Education | `career://education` | Degrees, certifications, coursework |
| Testimonials | `career://testimonials` | Quotes, recommendations |
| Career Journal | `career://journal` | Dated signals captured over time |
| Full KB | `career://full` | Everything above in one read |
| Pipeline | `career://pipeline` | All applications with status |
**They are live.** Career Compass implements MCP resource subscriptions: subscribe to a
resource and the server tells you when the file behind it changes on disk β whoever changed
it, whether that was a tool call, the dashboard, or you in an editor. Three peers share one
directory of plain files and none of them owns it. Nothing is watched until a client
subscribes, so a client that never does pays nothing for the feature.
---
## Prompts
Power-user shortcuts for MCP clients that show prompts, usually as slash commands. Plugin
users get the `/career-compass:β¦` commands above instead.
| Prompt | What it does |
|--------|-------------|
| `resume-tailor` | Drop in a posting β get a tailored rΓ©sumΓ© |
| `negotiation-coach` | Paste an offer β analysis, strategy, and counter scripts |
| `post-interview-debrief` | Capture what an interview surfaced β record the durable signal, set up the next step |
| `weekly-retro` | Review the week's movement and journal signals β one takeaway that compounds |
Retired: `daily-review`, `interview-coach` and `setup-career-kb` duplicated the plugin's
`/career-compass:today`, `/career-compass:interview-prep` and `/career-compass:start`. Ask
for the same thing in plain words and the tools do it.
---
## The dashboard
A local web view of the same YAML the tools read. It ships inside the npm package as a
single self-contained HTML page with no build step, no dependencies, and no external
assets β pipeline KPIs, a kanban board by stage, a next-actions panel (overdue follow-ups,
upcoming interviews, expiring offers), and a stage-distribution chart.
```bash
# The bundled demo β no clone, no build, no data of your own:
npx -y career-compass-mcp dashboard --sample
# Your own data (CAREER_DATA_PATH, or ~/.career-compass if unset):
npx -y career-compass-mcp dashboard
```
It re-reads your YAML on **every request**, so a browser refresh always shows the current
state of your files. Stages change through Claude β ask it to move an application and it
calls `pipeline_update`; the board reflects that on the next load. Click a card to open its
detail drawer (days in stage, follow-up, posting link, contacts, interview rounds, latest
note); the drawer's button and every next-action row copy a ready-to-paste prompt for
Claude, which is where the work actually happens. Type in the filter box (or press `/`) to
narrow the board by company or role; the column counts follow.
`--sample` (alias `--demo`) resolves the demo *inside the installed package*, wherever npx
put it, so it works from any directory and any shell. The sample's dates are shifted to sit
around today each time it is read β so the pipeline always looks like a live search β and
Career Compass refuses to write into it.
**Make the buttons ask Claude for you.** If you have [Claude Code](https://docs.anthropic.com/en/docs/claude-code)
installed, start the dashboard with `--ask-claude`:
```bash
npx -y career-compass-mcp dashboard --ask-claude
```
Every card, next-action row, and toolbar button then asks Claude directly instead of copying a
prompt β the server runs `claude` headless with Career Compass as its only tool set, and the
answer streams into a panel on the page, with a *Reload the board* button when Claude may have
changed your files. It is opt-in, loopback-only, one question at a time, and Claude Code runs
without your user hooks, without other MCP servers, and without shell or file-editing tools.
It is read-only unless you start it with `--ask-claude-writes`. Prompts that need you to
paste a posting still copy. Without the flag (or without Claude Code) the buttons copy,
exactly as before.
Each question runs under your own Claude account: Claude Code sends the Career KB content it
reads to Anthropic, and the usage is billed to you like any other Claude Code session.
Other flags: `--port ` (default 3141, falling back to the next free port), `--no-open` to
skip launching a browser, `--lite` to force this dashboard explicitly. Full list:
`career-compass-mcp --help`.
> **A second, frozen dashboard exists.** The repo also contains a full Next.js app β kanban
> with a detail view, an onboarding wizard, analytics. It is **not** in the npm package and
> is frozen as a design reference rather than a product; GUI investment goes to the
> dashboard above. See [`dashboard/FROZEN.md`](https://github.com/benskamps/career-compass-mcp/blob/HEAD/dashboard/FROZEN.md) for the reasoning. An
> in-Claude MCP App board is deferred too: Claude renders MCP Apps only for remote HTTP
> connectors, not the local stdio transport this ships as.
---
## The files on disk
```
~/.career-compass/ # or wherever CAREER_DATA_PATH points
βββ career/
β βββ profile.yaml # who you are, what you're targeting
β βββ experience.yaml # roles, achievements (metrics + context + impact)
β βββ skills.yaml # skills with proficiency and recency
β βββ education.yaml # degrees, certifications, coursework
β βββ projects.yaml # portfolio projects
β βββ testimonials.yaml # quotes and recommendations
β βββ journal.yaml # dated signals, appended over time
βββ pipeline/
βββ applications.yaml # all job applications
```
Optional sections (`narrative.yaml`, `stories.yaml`, `people.yaml`) appear in `career/`
the first time you save one.
This is your single source of truth β built once, enriched over time, read by every tool.
You never need to edit these files by hand: paste a document and ask Claude to save it. But
they are plain YAML, so you can.
[`data/example/`](https://github.com/benskamps/career-compass-mcp/blob/HEAD/data/example/) in this repo is a fully populated sample (the fictional
Alex Rivera) if you want to see the shape before writing your own.
---
## Configuration
| Env var | Default | Description |
|---------|---------|-------------|
| `CAREER_DATA_PATH` | `~/.career-compass` | Directory holding your career and pipeline YAML |
Plugin users set the same thing in the plugin's settings as **Career data folder**
(`data_path`, default `~/.career-compass`). The plugin passes it to the server as
`CAREER_DATA_PATH`.
---
## Troubleshooting and upgrading
**If anything seems off, start here:**
> **"Run the Career Compass setup check."**
`check_setup` is read-only and usually answers the question before you have to debug
anything. It is also the fastest way to find out you are simply on an old version, which is
the most common cause of "this feels rough around the edges."
Your career data is never touched by an upgrade. It lives in `CAREER_DATA_PATH`, not in the
package, and older data directories keep working β sections added by later releases are
created when you first write them.
**On npx.** `install` pins the version it writes (`career-compass-mcp@`), so
upgrading is running it again, then restarting your client:
```bash
npx -y career-compass-mcp@latest install
```
A hand-written entry with the bare name (`npx -y career-compass-mcp`) asks npm for the latest
version on every launch and reinstalls into one shared cache folder after each release. Claude
Desktop starts the server twice at once, and the two reinstalls can collide and leave that
folder half-written. If the server log shows `Cannot find module` or `ENOTEMPTY` under
`npm-cache\_npx`, delete the `_npx` folder inside your npm cache (`npm config get cache` prints
where it is; `npm cache clean --force` does not touch it), then run the `install` command above.
**On a global install.** `npm install -g career-compass-mcp@latest`, then
`career-compass-mcp --version`. Restart your client afterward β it keeps the old server
process alive until it does.
**From source.** `git pull && npm install && npm run build:mcp`, then restart your client. A
source checkout normally reports itself as *ahead* of npm in `check_setup`; that is
expected, not drift.
---
## How it works
```
βββββββββββββββ ββββββββββββββββββββββββββββββββββββββββββ
β β MCP β MCP server (Node.js) β
β Claude βββββββββββΊβ β
β β stdio β Tools Β·Β·Β·Β·Β·Β· rΓ©sumΓ©, pipeline, prep β
βββββββββββββββ β Resources Β·Β· Career KB, pipeline β
β Prompts Β·Β·Β·Β· slash-command shortcuts β
βββββββββββββββββββββ¬βββββββββββββββββββββ
β reads + writes
ββββββββββββββββΌββββββββββββββββ
β Plain YAML on your disk β
β CAREER_DATA_PATH β
ββββββββββββββββ²ββββββββββββββββ
β re-reads per request
ββββββββββββββββ΄ββββββββββββββββ
β Local dashboard (localhost) β
ββββββββββββββββββββββββββββββββ
```
No database, no server to host, no state the model has to carry between sessions. The files
are the interface.
**Diagrams:** [`docs/architecture.md`](https://github.com/benskamps/career-compass-mcp/blob/HEAD/docs/architecture.md) has the detailed version β
the path a posting takes from paste to offer, the application state machine, what happens
during your first conversation, how three peers share one directory without stepping on
each other, and why a write cannot be left half-done.
---
## Building from source
```bash
git clone https://github.com/benskamps/career-compass-mcp.git
cd career-compass-mcp
npm install # MCP server deps
cd dashboard && npm install && cd .. # only if you want the frozen Next.js app
npm run build:mcp # or `npm run build` to include that app
```
Point your MCP config at `node /path/to/career-compass-mcp/build/src/index.js`.
The Next.js dashboard is a separate package with its own `package.json` and lockfile, so it
needs its own `npm install` β the root install deliberately carries neither Next.js nor
React, which keeps 166 MB out of every `npm i career-compass-mcp`.
Common tasks:
```bash
npm run dev # TypeScript watch mode
npm run inspect # MCP Inspector β exercise tools interactively
npm run test:mcp # MCP server test suite
npm test # server + dashboard suites
npm run visuals # regenerate the screenshots in this README
npm run pack:mcpb # build the Claude Desktop .mcpb extension bundle
npm run dev:dashboard # frozen Next.js app, hot reload
# Develop against the fictional sample rather than your real data
CAREER_DATA_PATH=data/example npm run dev:dashboard
```
---
## Why Career Compass
Job searching is one of the highest-stakes, most document-intensive things most people ever
do β and most tools treat it as a data-entry problem. Spreadsheets for tracking. Templates
for rΓ©sumΓ©s. Generic advice for interviews.
Career Compass treats it as a knowledge problem. Your career history is a corpus. Every
application is a retrieval and synthesis task. Every interview is a pattern-match against a
known dataset (the posting) and a known corpus (you).
The Career KB is the single source of truth β built once, enriched over time, read by every
tool. A tailored rΓ©sumΓ© draws from it. Interview prep draws from it. Cover letters draw from
it. The pipeline tracks against it. Nothing gets lost, because nothing lives in a tab you
will close.
---
## Did this help?
There is no telemetry in this package, so I have genuinely no idea whether it is working for
anyone. Download counts are mostly registry mirrors rather than people. That is the trade: the
privacy is real, and the consequence is silence.
So if Career Compass got you through a week of applications:
- **[Star the repo](https://github.com/benskamps/career-compass-mcp)** β the only signal that
survives having no analytics.
- **[Say so in Discussions](https://github.com/benskamps/career-compass-mcp/discussions)** β
what you used it for, what was missing, what you wish it did instead. Job searches differ
enough that I would rather hear about yours than guess at it.
- **[Tell me what a fit check got wrong](https://github.com/benskamps/career-compass-mcp/issues/new?template=fit-check-wrong.yml)**
β a short form; leave out anything personal.
None of these sends me anything you have not chosen to type.
## Contributing
[Issues](https://github.com/benskamps/career-compass-mcp/issues) and PRs welcome β bug
reports with a reproduction are especially useful, and they do get fixed.
[Discussions](https://github.com/benskamps/career-compass-mcp/discussions) is the place for
anything that is not a defect: questions, workflows, or a tool you wish existed. If you add a tool,
register it in `src/server.ts` and follow the
pattern in any existing tool file β each tool returns a structured prompt that Claude acts
on with the full KB in context. The test suite includes docs-truth guards, so a new tool or
prompt that is not documented here fails CI rather than surprising a stranger.
## License
MIT
---
*Part of the [Brokenbranch Lab](https://www.brokenbranch.dev/lab/) β Ben Schippers' workshop of AI-native tools and research.*
