Skip to main content
Glama
dabs1

cv-mcp

by dabs1
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

cv-mcp

An MCP 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.

Related MCP server: Interactive Curriculum MCP Server

Requirements

  • Node.js 18 or newer (node --version)

  • A backend that serves the CV as JSON (see Backend contract)

Install

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

{
  "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. It does not forward your shell's environment variables to the server, so pass the variable with -e:

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

Available Tools

4 tools
get_cvA

Devolve o CV completo do Tomás Francisco, em texto.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, but the tool is a simple no-parameter read of static content, so risk is low. It usefully discloses the return format ('em texto'), which hints at output shape, but says nothing about size, structure, or truncation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single short sentence that front-loads the verb and resource with zero filler. Nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-param, no-output-schema read tool, the description conveys what is returned and in what form. It is nearly sufficient; only richer return detail (length, sections included) would improve it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the rubric the baseline is 4. There is nothing for the description to clarify beyond confirming that no input is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Devolve') and resource ('CV completo do Tomás Francisco') along with the output form ('em texto'). It implicitly distinguishes from siblings like get_section and search_cv by emphasizing 'complete', though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is given, and none of the sibling tools (list_sections, get_section, search_cv) are referenced. The agent must infer that this returns the whole CV rather than a filtered section.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_sectionA

Devolve o conteúdo de uma secção do CV. Usa list_sections para ver os nomes.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameYesNome (ou parte do nome) da secção

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It implies a read but never says so explicitly, and omits whether partial/fuzzy names resolve, what happens when the section does not exist, or what the returned content looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with zero filler; the action is front-loaded and the prerequisite lookup follows immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read tool with full schema coverage this is minimally adequate, but with no output schema the description should say more about the shape of the returned content and how non-matching names behave.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, and the single parameter already documents that a full or partial section name is accepted. The description adds no meaning beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ("Devolve") and resource ("conteúdo de uma secção do CV"), which is far more precise than a tautology. It does not distinguish itself from get_cv or search_cv, so it falls short of the top mark.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent to list_sections to discover valid section names before calling this tool, which is real usage guidance. It does not state when to prefer this over get_cv (whole CV) or search_cv, so no exclusions are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_sectionsB

Lista os títulos das secções do CV (ex.: experiência, formação, competências).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It discloses what is returned (titles) but not that the operation is read-only, whether results are ordered, whether it covers the whole CV or a subset, or what an empty result means.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no waste; the parenthetical examples ('experiência, formação, competências') add concrete meaning at no cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter read tool with no output schema, the description says enough: it returns section titles. Only ordering and scope (whole CV) are unstated, which is a minor gap at this complexity level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so the baseline is 4. There is nothing for the description to clarify beyond the schema, which is empty.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Lista') and resource ('os títulos das secções do CV') with concrete examples of what a section is. An agent can distinguish it from get_cv (whole CV) and get_section (one section's content), though the description never explicitly names those siblings or contrasts itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance and no alternatives mentioned. It is only implicitly inferable that this is a discovery call to find section names before using get_section; nothing in the text says so or states any preconditions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_cvA

Pesquisa um termo (tecnologia, empresa, palavra-chave) no CV e devolve as linhas onde aparece.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesTermo a procurar, ex.: 'TypeScript'

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It usefully discloses the return form (matching lines), but says nothing about case sensitivity, whether matching is exact or substring, scope across sections, or result limits for a search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence that front-loads the action, the accepted term types, and the return value. No filler, though it is short enough that it could have absorbed a routing pointer at no cost.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a one-parameter read-only search with a fully documented schema and no output schema, the description covers action, input categories and return shape. Missing only minor behavioral details like matching semantics.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter, and schema description coverage is 100% (schema already documents 'query' with the 'TypeScript' example). The description's examples (technology, company, keyword) add mild breadth but no syntax or format detail beyond the schema. Baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (pesquisa) and resource (no CV) and even describes the output shape (as linhas onde aparece). This differentiates it reasonably from get_cv, which presumably returns the whole document, though it never names that sibling explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the verb 'pesquisa' and the example term categories, but there is no explicit when-to-use guidance nor any pointer to get_cv/get_section for retrieving whole content. Nothing misleading, just unstated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updatesv1.1.0
    • First observedget_cv
    • First observedget_section
    • First observedlist_sections
    • First observedsearch_cv
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a clearly distinct retrieval mode: full CV, section listing, section content, and keyword search. No overlapping purposes cause confusion.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (get_cv, list_sections, get_section, search_cv), making the set predictable.

Tool Count5/5

Four tools are well-matched to a simple CV reader, covering full retrieval, section discovery, section retrieval, and search without redundancy.

Completeness5/5

The read-only surface is complete for a static CV: full text, structured sections, section-level access, and keyword search cover all likely agent needs.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Resume MCP Server

    Adarshcharjan
    A
    license
    Not graded
    quality
    D
    maintenance
    Exposes a structured professional resume as a set of AI-queryable tools, enabling AI clients like Claude Desktop to query summary, experience, skills, projects, and tailor resumes to job descriptions.
    1
    MIT

  • Interactive Curriculum MCP

    AnaCataVC
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants and LLM clients to query a professional CV and portfolio, including work history, technical skills, projects, job compatibility evaluation, education, and contact details.
    MIT

  • Resume Tailor MCP Server

    priyanshu-arya
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI assistants to tailor a resume to any job description by extracting keywords, analyzing gaps and ATS compliance, managing versions, and compiling PDF/LaTeX outputs entirely locally without external API keys.
    MIT