# cv-mcp

An [MCP](https://modelcontextprotocol.io) server (TypeScript, stdio) that exposes my CV to AI assistants such as Claude. It reads the CV from a backend REST API (`GET /api/cv`, Spring Boot + MongoDB), so the data lives in one place and the assistant always sees the current version.

```
Claude Desktop  <-- stdio -->  cv-mcp (Node.js)  <-- HTTPS -->  REST API  <-->  MongoDB
```

## What it exposes

| Type     | Name                | Description                                                         |
| -------- | ------------------- | ------------------------------------------------------------------- |
| Tool     | `get_cv`            | Returns the full CV as text.                                        |
| Tool     | `list_sections`     | Lists the CV section titles.                                        |
| Tool     | `get_section`       | Returns one section by name (exact match first, then partial).      |
| Tool     | `search_cv`         | Searches a term (technology, company, keyword) and returns the lines where it appears. |
| Resource | `cv://completo`     | Full CV text, attachable as context.                                |
| Prompt   | `adaptar_cv_a_vaga` | Compares the CV against a job description and suggests improvements. |

Tool descriptions and the prompt are written in Portuguese.

## Requirements

- Node.js 18 or newer (`node --version`)
- A backend that serves the CV as JSON (see [Backend contract](#backend-contract))

## Install

```bash
git clone <this-repo-url>
cd cv-mcp
npm install
npm run build
```

The server is configured through one environment variable:

| Variable     | Description                                              |
| ------------ | -------------------------------------------------------- |
| `CV_API_URL` | Full URL of the CV endpoint, e.g. `https://your-backend.example.com/api/cv` |

## Use with Claude Desktop

Open **Settings → Developer → Edit Config** and add the server to `claude_desktop_config.json` (keep any servers you already have):

```json
{
  "mcpServers": {
    "cv-tomas": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/cv-mcp/build/index.js"],
      "env": { "CV_API_URL": "https://your-backend.example.com/api/cv" }
    }
  }
}
```

- Use an **absolute** path. On Windows, escape the backslashes: `"C:\\Users\\you\\cv-mcp\\build\\index.js"`.
- Claude Desktop does not pass your terminal's environment variables to the server, so `CV_API_URL` must be in the `env` block.
- Fully quit Claude Desktop (including the system tray icon) and reopen it after editing the config.

Config file locations:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Windows (Microsoft Store install): `%LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json`

Then ask Claude something like *"Use list_sections"* or *"What TypeScript experience does Tomás have?"*.

## Test without Claude

Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector). It does not forward your shell's environment variables to the server, so pass the variable with `-e`:

```bash
npx @modelcontextprotocol/inspector -e CV_API_URL=https://your-backend.example.com/api/cv node build/index.js
```

(`npm run inspect` starts the Inspector too; in that case add `CV_API_URL` under *Environment Variables* in the Inspector UI before connecting.)

To test the backend on its own: `curl https://your-backend.example.com/api/cv`.

## Backend contract

`GET CV_API_URL` must return JSON. Each top-level key becomes a CV section (for example `personalInfo`, `experience`, `education`, `skills`, `languages`, `volunteer`). Details:

- A one-element array is unwrapped to its single object.
- Technical fields (`id`, `_id`, `_class`) are dropped at any depth.
- Responses are cached in memory for 10 minutes.
- Requests time out after 60 seconds, to tolerate free-tier hosts that sleep.

## Troubleshooting

- **First request is slow or times out**: free-tier backends sleep when idle. Wait about a minute and try again.
- **Server does not show up in Claude Desktop**: invalid JSON in the config, or the path to `build/index.js` is not absolute.
- **`CV_API_URL` is not set**: add it to the `env` block of the config (Claude Desktop) or pass it with `-e` (Inspector).
- **See errors**: Claude Desktop → Settings → Developer → click the server → Logs.

## Project structure

```
src/index.ts   MCP server: tools, resource, prompt, stdio transport
src/cv.ts      Fetches the CV from the API, caches it and splits it into sections
build/         Compiled output (generated by `npm run build`, not committed)
```

With stdio, the server must never write to stdout (`console.log` corrupts the protocol); logs go to stderr via `console.error`.

## License

[MIT](LICENSE)