# 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:

| Job requirement | Match | Supporting evidence |
|---|---|---|
| Power Platform | Strong | CertMate workflow documentation |
| API architecture | Strong | REST integration and service-layer code |
| SQL | Strong | Database schema and stored procedures |
| CI/CD | Weak | GitHub Actions exists but deployment evidence is limited |
| Team leadership | Unproven | No evidence found in the supplied sources |

See [`docs/demonstration.md`](docs/demonstration.md) for a full walkthrough and
[`examples/sample-evidence-report.json`](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`](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

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

Or run directly from source during development:

```sh
npm run dev
```

Try it with the MCP Inspector:

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

### Register with an MCP host

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

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

### Environment variables

| Variable | Purpose | Default |
|---|---|---|
| `CAREERPROOF_DB_PATH` | Path to the local SQLite database | `./data/careerproof.db` |
| `GITHUB_TOKEN` | Optional GitHub token for higher API rate limits / private repos | unset (public, unauthenticated) |

## Example tool call

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

```json
{
  "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

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

## Docker

```sh
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](docs/architecture.md)
- [Threat model](docs/threat-model.md)
- [Demonstration walkthrough](docs/demonstration.md)

## License

MIT