careerproof-mcp

Evidence-backed interview preparation through the Model Context Protocol.

CareerProof turns a candidate's real project history — GitHub repositories, a CV, and project notes — into interview preparation that is traceable to specific evidence: commits, pull requests, architecture docs, and dependency manifests. Every answer it helps produce distinguishes between:

• Verified evidence — pulled directly from GitHub

• Reasonable inference — evidence added manually, not independently verified

• User-provided claim — extracted from the candidate's own CV

• Missing evidence — explicitly flagged, never silently invented

Why

Ask a connected MCP client:

Analyse this Solutions Architect job description and show me where my GitHub projects prove each requirement.

and get back a requirement-by-requirement match, each one backed by a cited source:

See docs/demonstration.md for a full walkthrough and examples/sample-evidence-report.json for a complete sample response.

Design principle: no LLM in v1

CareerProof deliberately does not call an LLM API. Job description parsing and requirement matching use bullet parsing, a curated keyword dictionary, and token-overlap scoring. STAR-answer generation builds a cited outline, not prose. The connected MCP client (Claude Desktop, VS Code Copilot, etc.) supplies the language reasoning on top of this server's structured, traceable evidence — which keeps the server cheap, private, and easy to self-host. See docs/architecture.md for the full rationale.

MCP primitives

Tools (11) — actions such as indexing repositories, analysing job descriptions, matching requirements, generating STAR outlines, and exporting a preparation pack:

careerproof_add_candidate_profile, careerproof_index_repository, careerproof_add_project_evidence, careerproof_analyse_job_description, careerproof_match_requirements, careerproof_find_evidence, careerproof_generate_star_answer, careerproof_find_evidence_gaps, careerproof_generate_interview_questions, careerproof_score_interview_answer, careerproof_export_preparation_pack

Resources (5) — read-only, application-controlled views:

careerproof://candidate/profile, careerproof://jobs/{jobId}, careerproof://projects/{projectId}, careerproof://evidence/{evidenceId}, careerproof://skills/matrix

Prompts (5) — reusable, host-surfaced workflows:

prepare_for_interview, create_star_answer, challenge_cv_claim, run_mock_technical_interview, identify_portfolio_gaps

Quick start

npm install
npm run build
npm start          # runs dist/server.js over stdio

Or run directly from source during development:

npm run dev

Try it with the MCP Inspector:

npx @modelcontextprotocol/inspector npx tsx src/server.ts

Register with an MCP host

Point your host at the built server (see mcp.json for a ready-made config):

{
  "mcpServers": {
    "careerproof": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": { "CAREERPROOF_DB_PATH": "./data/careerproof.db" }
    }
  }
}

Environment variables

Example tool call

{
  "tool": "careerproof_generate_star_answer",
  "arguments": {
    "competency": "Describe a time you designed a complex solution",
    "project": "CertMate EICR",
    "maximumWords": 250
  }
}

{
  "answer": {
    "situation": "...",
    "task": "...",
    "action": "...",
    "result": "..."
  },
  "confidence": 0.84,
  "evidence": [
    { "source": "docs/architecture.md", "lines": "18-42", "type": "verified" }
  ],
  "missingInformation": [
    "No measurable performance improvement was documented"
  ]
}

Repository structure

careerproof-mcp/
├── src/
│   ├── server.ts       # entry point (stdio transport)
│   ├── tools/           # 11 MCP tools
│   ├── resources/       # 5 MCP resources
│   ├── prompts/         # 5 MCP prompts
│   ├── github/          # GitHub REST client + repository indexer
│   ├── evidence/        # CV parsing, evidence store, export pack
│   ├── matching/         # requirement extraction, matching, STAR/gap/question logic
│   └── database/        # Drizzle schema + SQLite client
├── examples/             # sample CV, job description, evidence report
├── evals/                 # judgement evals for the matching logic
├── tests/                # Vitest unit + MCP protocol tests
├── docs/                 # architecture, threat model, demonstration walkthrough
├── Dockerfile
├── mcp.json
└── README.md

Development

npm test              # vitest unit + protocol tests
npm run lint          # tsc --noEmit
npx tsx evals/requirement-matching.eval.ts   # judgement eval

Docker

docker build -t careerproof-mcp .
docker run -i -v careerproof-data:/data careerproof-mcp

The server speaks stdio, so docker run -i (interactive, no TTY) is how an MCP host would launch it as a subprocess.

Roadmap

• Streamable HTTP transport + OAuth for a remotely-hosted deployment

• Optional local embeddings for semantic evidence search

• PDF CV import

Docs

• Architecture

• Threat model

• Demonstration walkthrough

License

MIT