JobTrack MCP server
Commit Nov 4, 2026Tracks job applications with semantic search and duplicate detection to prevent redundant applications to the same company.
Also known as CuplexUser/JobTrack
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- MIT
What is JobTrack MCP?
JobTrack tracks job applications with semantic search and duplicate detection to prevent redundant applications to the same company.
Summary generated from the project's README
About JobTrack MCP server
Managing job applications and professional networking is what JobTrack enables for individual job seekers. This tool runs locally on your machine using a SQLite database to store application history, company details, and professional contacts. It functions as a personal command center to ensure you never apply to the same company twice by mistake.
The system uses a hybrid search approach that combines lexical keyword matching with local semantic search via transformers.js. This allows you to find previous roles using meaning rather than exact words, such as finding a backend engineer role when searching for a server-side developer. It requires Node 24 or higher to run and manages its own embedding models locally without needing external API keys.
Beyond simple tracking, the server provides duplicate detection that normalizes company names to catch variations like Spotify AB and Spotify, Inc. It also includes features for scoring job openings against your personal profile and managing a network of professional contacts. Users can capture job postings directly from the web using a browser extension or by parsing text and links.
What you can do with it
- 1Prevent redundant applicationsCheck if you have already applied to a specific company or role before submitting a new one.
- 2Search applications by meaningFind past job roles using semantic concepts even if the exact keywords do not match.
- 3Clean up duplicate recordsIdentify and merge multiple entries for the same job that were accidentally imported or saved twice.
- 4Score job fitEvaluate how well a new job opening matches your desired salary, titles, and skills.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
DB_DRIVERDB_TARGETSJOBTRACK_HOME
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablecuplexuser/jobtrack is public and reachablegithub.com/cuplexuser/jobtrack ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/cuplexuser/jobtrack ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubJobTrack
A personal job-application tracker. Record what you applied for, where and when; find it again by meaning rather than exact wording; and — the point of the whole thing — see before you enter a new application whether you have already been down that road with the same company.
Single user, runs on your machine, data in a local SQLite file.
Quick start
npm install
npm run seed # 40 sample applications across 2024-2026 (skip for an empty database)
npm run dev # API on :3002, web on :5173
Open http://localhost:5173.
npm run dev binds the API to :3002, not the API's usual :3001 default (see
"Configuration" below) — that keeps it from colliding with a tray build already running
on this machine, so both can be up at the same time.
The first search after startup is keyword-only for about a minute while the embedding model downloads (~25 MB, once per machine). The UI says so while it happens, and everything else works normally meanwhile.
Requires Node 24+ (node:sqlite is stable there; repolayer needs ≥22.5). Developed on
Node 26.7 / npm 11.12.
What it does
Duplicate detection. The feature everything else is arranged around. As you type a company and job title into the New Application form, a debounced check runs and reports one of four verdicts:
| verdict | meaning |
|---|---|
exact |
same company, same normalized title — saving requires confirmation |
similar |
same company, and the titles match on wording (Dice ≥ 0.8) or on meaning (cosine ≥ 0.75) |
company |
you have applied here before, for a different role |
none |
genuinely new |
Company names are normalized before comparison — lowercased, de-accented, legal suffixes
stripped — so Spotify AB, spotify and Spotify, Inc. are one employer, not three. In
the seed data that is why 40 applications produce 32 companies.
The same check is available without starting an application, from the dashboard's Check before you apply box.
Duplicates already in the database. The live check only helps for records you are about to create; Applications → Duplicates runs the same rules over everything already stored — an import run twice, a posting clipped from two tabs — and groups the repeats by employer. Each group nominates the record to keep (the one furthest along the pipeline, then the one carrying the most notes, tags and filled-in fields), you can pick a different one, and the rest are deleted on confirmation.
The bulk Remove button covers only the exact repeats. Similar-title groups are a judgment call — Software Engineer in 2025 and Senior Software Engineer in 2026 at one employer are two real applications — so those are removed a group at a time, or dismissed as "not a duplicate" for the session.
Hybrid search. Two retrievers over the same documents, fused by Reciprocal Rank Fusion:
- Lexical (MiniSearch): typo-tolerant BM25. Finds
pyhton devloper. - Semantic (all-MiniLM-L6-v2 via transformers.js, local, no API key): finds Backend
Engineer when you searched
server-side developer— no shared words at all.
Ranks are fused rather than scores, because BM25 is unbounded and cosine sits in [-1, 1]; normalizing between them would mean inventing a conversion that is wrong in ways nobody can see. The semantic half has a similarity floor, because vector search has no concept of "no match" and will otherwise return the whole table ranked by accident.
Job openings. A lighter-weight record for a role you found but are not ready to apply to yet — no status, no tags, just enough to find it again. "Convert" turns one into a real, tracked application on demand, using the same company-resolution and creation path the New Application form uses; the opening itself is kept (marked archived), not deleted, so there is still a record of what it became.
Capture from the web. Three ways to get a posting in without retyping it: paste a link
and the API reads the site's own schema.org/JobPosting data, paste the text and it is
parsed locally, or click a browser extension on the page you are already looking at. The
last one is what makes LinkedIn and Indeed work — they block servers, not the browser you
are reading them in. All three land as a job opening, run the same duplicate check, and are
written up in docs/capture.md.
The people behind it. A People page for your network: who works where, how you know
them, every conversation you have logged, and a reconnect date that lands on the dashboard
when it comes due. Link someone to an application as the person who referred you or
interviewed you. The duplicate check names who you know at a company before you apply, even a
company you have never applied to, and you can import your whole network from LinkedIn's own
data export. See docs/networking.md.
Ranked by fit, and kept tidy for you. Fill in a profile (a CV summary, the titles and
places you want, a salary floor, words to look for or avoid) and saved openings are scored 0
to 100 with the reasons shown. Two opt-in rules take chores off your hands: a default
follow-up date for new applications, and marking long-silent applications as ghosted, with a
preview of exactly what would change. The Windows tray app notifies you when a follow-up or a
reconnect comes due. See docs/automation.md.
Everything else. Applications divided by year and month, full status pipeline with a dated history, companies as first-class records, a free-form tag vocabulary attachable to both companies and applications, notes that link to either, CSV/Excel export and import, and a Settings page for switching between pre-configured databases and for full-fidelity backup/restore (see "Switching databases" and "Backup & restore" below).
A dashboard that reads the history, not just the current state. The pipeline funnel counts what each application ever reached, so one that interviewed and was then turned down still counts at the interview stage — which is the only way the conversion rate between stages means anything. Alongside it: applications per month over two years, and a "gone quiet" list of live applications with no follow-up date that nothing has moved in three weeks. Charts are inline SVG against the app's palette; no charting dependency.
Layout
apps/web/ React 19 + Vite + Ant Design 6 :5173
apps/api/ Fastify + repolayer + search :3001
apps/mcp/ MCP server (stdio) over the same repos, publishable as `@jobtrack/mcp`
apps/tray/ background process + Windows tray icon, publishable as `jobtrack`
apps/extension/ browser extension that clips a posting into an opening (signed for Firefox)
packages/shared/ domain types, zod schemas, pure logic
data/jobtrack.db SQLite (gitignored)
docs/ longer reference docs (web capture, networking, automation, npm publishing, ...)
npm workspaces — one npm install at the root covers everything.
packages/shared is browser-safe and must not import repolayer. The database row types
live in apps/api/src/db/schema.ts; a compile-time test
(apps/api/test/schema-contract.test.ts) asserts the two never drift apart.
Storage, and the Postgres path
Data access goes through repolayer, so the engine is one config value:
npm install pg
DB_DRIVER=postgres DATABASE_URL=postgres://... npm run dev
Nothing outside apps/api/src/db/repos.ts names a driver, and every query stays inside
repolayer's portable operator set — there is no dialect-specific SQL anywhere in the app.
That portability costs something, and the design works around it deliberately:
| repolayer has no… | so instead |
|---|---|
| joins or relations | apps/api/src/db/hydrate.ts stitches rows with batched in queries — three queries per page regardless of page size, with a test that counts them |
aggregation beyond count() |
year/month totals are tallied in one pass in JS |
| SQL date functions | periodYear / periodMonth are denormalized columns, written from appliedOn in exactly one place |
| full-text search | search is built above the repo (see above) |
| identifier quoting | no column is named after a reserved word — the job title column is job_title, never position |
| cascading deletes | deletes clean up their own tag links, notes, status events and vectors, in a transaction |
Configuration
Every variable below can be set in the environment or in a .env file in the app data
directory — the repo root for a clone, %APPDATA%\jobtrack (or ~/.local/share/jobtrack)
for an installed jobtrack, which is the file the tray's Open App Settings opens. It is
read at startup by the API, the tray and the MCP server alike. A variable set in the real
environment wins over the file, so PORT=3002 npm run dev still overrides it.
| variable | default | meaning |
|---|---|---|
DB_DRIVER |
sqlite |
sqlite, postgres or mysql — the implicit "default" target |
DB_FILE |
data/jobtrack.db |
SQLite only; a bare filename is a second database in data/, a relative path resolves from the app data directory |
DATABASE_URL |
— | required for postgres/mysql |
DB_TARGETS |
— | JSON array of additional named targets, see below |
PORT / HOST |
3001 / 127.0.0.1 |
API bind address |
SEMANTIC_SEARCH |
true |
false skips the model entirely; search stays lexical |
EMBEDDING_MODEL |
Xenova/all-MiniLM-L6-v2 |
any transformers.js feature-extraction model |
MODEL_CACHE_DIR |
.models |
where the ONNX model is cached; relative to the app data directory |
CORS_ORIGINS |
— | extra browser origins allowed without a token, comma-separated |
API_TOKEN |
generated | what a browser extension presents; kept in data/api-token |
Who can call the API
The API binds to 127.0.0.1, but that still leaves it reachable from every page open in the
browser on the same machine — so it does not reflect arbitrary origins. A wrong token is
refused outright; a request with no Origin header (curl, the MCP server, the tray itself)
is allowed; a request from this app's own UI is allowed; anything else needs the token,
which is how the browser extension gets in. GET /api/meta stays open as a health probe,
and GET /api/auth/check is the reverse — only a valid token opens it, so "is this token
right?" has an answer that depends on nothing else. Details and the reasoning are in
docs/capture.md.
Switching databases
DB_DRIVER / DB_FILE / DATABASE_URL always describe one implicit target named
"default". DB_TARGETS can name more:
DB_TARGETS='[{"name":"cloud","driver":"postgres","url":"postgres://user:pass@host/db"}]'
When more than one target is configured, the app's Settings page shows a switcher.
Connection settings themselves are never shown or editable there — only .env holds them.
Switching writes which target is active to data/active-db.json (a name only, never a
credential) and restarts the server to connect to it — it is not a live hot-swap. That
means something has to bring the process back up:
npm run dev'stsx watchdoes not restart on a self-exit (only on a file change), so a dev server needs restarting by hand after a switch.- A production deployment needs a process supervisor with a restart policy — pm2, systemd
Restart=always, Dockerrestart: unless-stopped, or similar — for the switch to be seamless.
Scripts
| command | does |
|---|---|
npm run dev |
API + web + shared in watch mode |
npm test |
every workspace (497 tests) |
npm run lint |
oxlint over every workspace (npm run lint:fix applies what it can fix) |
npm run typecheck |
tsc --build across the project references |
npm run build |
production web bundle |
npm run seed |
sample data (-- --force to add to a non-empty database) |
npm run mcp |
start the MCP server (stdio) — see MCP server |
npm run tray |
run the API + web UI as one process, with a Windows tray icon — see Tray app |
npm run clean |
remove build output and caches |
npm run bump <major|minor|patch> |
raise the version of every published package that changed, so the next push to main releases it (-- --dry-run to preview) — see Releasing |
npm run icons --workspace=@jobtrack/web |
regenerate favicon.ico / apple-touch-icon from the SVG sources |
npm run build --workspace=@jobtrack/extension |
build the browser clipper into apps/extension/dist (load unpacked) |
npm run package --workspace=@jobtrack/extension |
build and package the clipper for release into apps/extension/release |
Testing
Vitest across four projects: shared, API, MCP and web.
The MCP suite (apps/mcp/test) connects a real MCP client to the server over an in-memory
transport, so it checks what a client actually sees: that every tool's schema can be
advertised, the prompts render, and results survive serialization.
Service tests run against repolayer's MemoryRepo — no database, no fixtures, no cleanup —
which is trustworthy only because it passes the same conformance suite as the SQLite
adapter. The embedder is injected, so tests use a deterministic fake and never download a
model.
One suite (sqlite-integration.test.ts) runs against a real temporary SQLite file, because
a fake cannot prove that ensureTable() emits DDL a real engine accepts or that a Date
survives storage unchanged.
One caveat worth knowing. repolayer's
timestamps: trueshorthand is honored by the SQLite adapter but leaves both fieldsnullonMemoryRepo. Both this app and its test support use the explicit{ createdAt, updatedAt }form, which behaves identically on both. Worth a conformance case upstream.
Export
CSV and .xlsx, both driven by the same filter object as the list view — so what you export
is exactly what you were looking at, including an active search.
By default, six columns: Position, Company, Location, Date, Status, Notes. A list, not a report; there is no summary or statistics sheet. The workbook keeps one worksheet per year, matching how the app organizes applications everywhere else.
The Export button opens a dialog where you pick the format, tick which columns to include
(work mode, source, follow-up date, salary, job URL and tags are offered too), drag them into
order, and optionally rename each header. A header left blank uses the field's name in the
active UI language. These choices are the export profile, saved in the database
(GET/PUT /api/settings/export-profile) on every export, so every browser exports the same
way. GET /api/export takes them as columns (comma list of fields) and headers (a JSON
array matched by position); without them it writes the default six under English headers.
Import reads the default headers in either language, so an export in Swedish imports back too. A header you renamed yourself only imports if it is one of the names Import knows.
CSV is written by hand against RFC 4180 with a UTF-8 BOM, so titles containing commas do not
shift columns and Malmö survives a double-click into Excel.
Why the buffered xlsx writer. exceljs's streaming
WorkbookWriterproduced archives whose zip central directory recordedcrc = 0anduncompressed size = 0for several entries. The compressed bytes were intact, so lenient readers — including exceljs's own — opened them happily, while spec-correct readers saw those entries as empty and rejected the workbook.writeBuffer()uses a different packing path and is correct. The tests now assert on the central directory directly (test/support/zip.ts) rather than round-tripping through the library that wrote the file, since that tolerance is what let the bug through.
Import
CSV and .xlsx, in the same shape Export produces — Position, Company, Location, Date,
Status, Notes, matched by header name rather than position. Only Position, Company and Date
are required, so a file exported before the Location column existed, or with only some
columns picked in the export dialog, still imports; a missing status reads as Applied. Each
column answers to its English and Swedish export header and a few common names (Role, City,
Ort, ...); see IMPORT_HEADER_NAMES in apps/api/src/import/columns.ts. The obvious source is the app's own
Export output, so a filtered export round-trips back in; a hand-built spreadsheet in the
same shape works too.
Two steps, both hitting POST /api/import?format=csv|xlsx&mode=preview|commit, and neither
holds server-side upload state — the browser just posts the same file twice:
- Preview parses and validates every row against the exact zod schema the New
Application form uses, then runs each one through the same duplicate check the form runs
while you type. A row whose verdict is
exact— the same ruleshouldBlockSaveuses everywhere else — is marked a duplicate and will be skipped; everything else isnew. Two identical rows within the same file are caught too, even though neither is in the database yet. - Commit re-runs that classification and creates every
newrow through the samecreateApplicationcall the API and the web form use — company resolution, the opening status event, the linked note, all included. Duplicates are skipped, not overwritten; a row that fails to parse is reported and does not stop the rest of the batch.
The one thing that does not round-trip exactly: Export merges every note on an application
into one Notes cell, so Import creates that cell back as a single new note rather than
reconstructing the original set.
Capturing postings from the web
Paste a link, paste the text, or click a browser extension on the posting you are reading. All three produce a job opening through the same path the form uses, with the same duplicate check attached.
The browser extension is released for Firefox: open the add-on file in Firefox, allow the install, and press Connect to JobTrack in its settings. It updates itself. Chrome and Edge can load a local build unpacked.
Which route works where is not a detail — LinkedIn, Indeed and Glassdoor block servers from
reading postings, so the link route cannot work there and the extension is the answer, since
it reads the page already rendered in your own browser. The full write-up, the extension's
install and how connecting hands it the API token are in docs/capture.md.
JobTrack MCP questions
How does the duplicate detection work?
It uses a debounced check that compares company names and job titles, providing verdicts like exact, similar, or company-only matches.
Where is the application data stored?
The data is stored locally in a SQLite file by default, though it can be configured to use PostgreSQL or MySQL.
Can I import my professional network?
Yes, you can import your entire network from a LinkedIn data export.