Jobmatch

jobmatch-mcp is a TypeScript Model Context Protocol server for job discovery backed by the TheirStack Jobs API.

What Exists Today

• A runnable TypeScript MCP server over stdio
• MCP tools for search_jobs, get_job_details, rank_jobs_for_candidate, and list_sources
• Zod-backed input schemas
• Environment variable loading and validation
• A single TheirStack-backed job search integration
• ESLint, Prettier, Vitest, and TypeScript build scripts

Tools

search_jobs

Search normalized jobs from TheirStack.

Current behavior:

• Calls TheirStack POST /v1/jobs/search
• Uses query as a title search
• Treats location: "remote" as a remote-only search
• Uses JOBMATCH_THEIRSTACK_POSTED_AT_MAX_AGE_DAYS to satisfy TheirStack's required date filter

Example input:

{
  "query": "backend engineer",
  "location": "remote",
  "limit": 10
}

get_job_details

Fetch normalized details for a single job by jobId and sourceId.

Current behavior:

• Supports sourceId: "theirstack"
• Resolves the job by calling TheirStack search with job_id_or

Example input:

{
  "jobId": "123456789",
  "sourceId": "theirstack"
}

rank_jobs_for_candidate

Rank a provided set of normalized jobs against a candidate profile.

Example input:

{
  "candidateProfile": {
    "headline": "Senior backend engineer",
    "targetRoles": ["Backend Engineer", "Platform Engineer"],
    "preferredLocations": ["Remote"],
    "skills": ["TypeScript", "Node.js", "PostgreSQL"]
  },
  "jobs": []
}

list_sources

List sources known to the server and whether each one is planned or active.

Install

pnpm install

Environment

Copy .env.example to .env and set your TheirStack API key.

cp .env.example .env

Current variables:

• JOBMATCH_MCP_SERVER_NAME
• JOBMATCH_MCP_SERVER_VERSION
• JOBMATCH_MCP_DEFAULT_TIMEOUT_MS
• JOBMATCH_THEIRSTACK_API_KEY
• JOBMATCH_THEIRSTACK_BASE_URL
• JOBMATCH_THEIRSTACK_POSTED_AT_MAX_AGE_DAYS

Run Locally

Start the server in watch mode:

pnpm dev

Start the server for an MCP client over stdio:

pnpm mcp

Build for production:

pnpm build
pnpm start

Example MCP client setup:

codex mcp add jobmatch -- node --import tsx /absolute/path/to/jobmatch-mcp/src/index.ts

If you prefer to launch via pnpm, use:

codex mcp add jobmatch -- pnpm --dir /absolute/path/to/jobmatch-mcp --silent mcp

Do not use plain pnpm --dir /absolute/path/to/jobmatch-mcp mcp as the MCP command. pnpm writes its script banner to stdout, and MCP servers that communicate over stdio must keep stdout protocol-clean or client initialization will fail.

For a built server, point the client at:

node /absolute/path/to/jobmatch-mcp/dist/index.js

Do not use pnpm dev as the MCP command. tsx watch is a file-watcher process and writes its own output, which interferes with stdio-based MCP tool discovery and calls.

Test And Validate

pnpm test
pnpm lint
pnpm format:check
pnpm build