Content
# Resume MCP Server
> AI-powered Resume MCP Server built with the **Model Context Protocol (MCP)**, **TypeScript**, **Express**, and the **official MCP SDK**.
>
> Expose resume information as structured AI tools over both **stdio** and **HTTP** transports for seamless integration with MCP-compatible AI clients.
---
## 🌐 Live Deployment
| Endpoint | URL |
|---|---|
| **MCP Endpoint** | `https://resume-mcp-server-z04b.onrender.com/mcp` |
| **Health Check** | `https://resume-mcp-server-z04b.onrender.com/health` |
| **Deployment Platform** | [Render](https://render.com) (Free Tier) |
---
## 💡 Why This Project?
Although a resume can easily be uploaded as a PDF, this project demonstrates how **structured information can be exposed to AI applications** using the Model Context Protocol.
Instead of treating the resume as an unstructured document, AI clients can retrieve specific information through **dedicated tools** — skills, projects, education, experience, keyword search, and resume tailoring — with structured, predictable responses.
The same architecture can be extended to enterprise systems like **HR platforms, CRMs, hospital databases, ERP systems, and internal business applications**.
> This is exactly why MCP exists — to give AI agents structured, programmatic access to data sources instead of relying on raw document parsing.
---
## ✅ Project Highlights
| | |
|---|---|
| ✔ | Built using the **official MCP SDK** |
| ✔ | Supports both **stdio** and **HTTP/Streamable** transports |
| ✔ | **Deployed on Render** with a live public endpoint |
| ✔ | **Integrated with Claude Desktop** (stdio) |
| ✔ | **Integrated with Cursor AI** (HTTP) |
| ✔ | **8 fully functional AI Tools** |
| ✔ | Full **TypeScript** implementation with Zod validation |
| ✔ | **Automated test suite** — 16/16 stdio + 6/6 HTTP tests passing |
---
## 🏗️ Architecture
### Local (stdio Transport)
```
Claude Desktop
│
│ stdin / stdout (stdio)
│
Resume MCP Server (node dist/stdioMain.js)
│
│ reads
│
resume.json
```
### Remote (HTTP Transport)
```
Cursor AI / Claude Desktop / Any MCP Client
│
│ POST /mcp (HTTP + Streamable)
│
Render.com
│
Resume MCP Server (node dist/httpMain.js)
│
│ reads
│
resume.json
```
---
## 🧪 Tested AI Clients
| Client | Transport | Status |
|---|---|---|
| **Claude Desktop** | stdio | ✅ Tested & Working |
| **Cursor AI** | HTTP | ✅ Tested & Working |
| **Render Deployment** | HTTP/Streamable | ✅ Tested & Working |
| **MCP Inspector** | stdio | ✅ Tested & Working |
| Claude Web | — | ⚠️ Currently doesn't support arbitrary custom MCP servers |
| ChatGPT | — | ⚠️ Currently doesn't support connecting to custom MCP servers |
---
## 🌍 Possible Business Use Cases
This architecture can be adapted far beyond a personal resume:
| Use Case | Description |
|---|---|
| **Employee Database MCP** | HR teams query employee skills, roles, and history via AI |
| **Hospital Records MCP** | AI retrieves patient records, appointments, or prescriptions |
| **CRM Assistant** | AI queries customer data, leads, and deal history |
| **HR Recruitment Assistant** | AI screens candidates and matches JDs to profiles |
| **ERP Systems** | AI fetches inventory, orders, and financial records |
| **Knowledge Base** | AI searches internal company documentation |
| **Company Documentation** | AI answers policy and process questions |
| **GitHub Repository Assistant** | AI queries codebase structure, contributors, and issues |
> The MCP architecture in this project is the **same pattern** used in all of these enterprise scenarios.
---
## ✨ Features
| Feature | Description |
|---|---|
| **8 MCP Tools** | Query summary, experience, skills, projects, education, search, fetch by ID, and tailor resume to a JD |
| **Two Transport Modes** | **stdio** (local, zero-config) and **HTTP/Streamable** (remote, deployable) |
| **Resume Tailoring** | Rule-based keyword overlap analysis — matches your resume against any job description |
| **Full-Text Search** | Search across all resume sections with stable IDs for drill-down |
| **Optional API Key Auth** | Protect your HTTP endpoint with `x-api-key` header validation |
| **Health Check Endpoint** | `GET /health` for uptime monitoring and deployment health checks |
| **Type-Safe** | Written in strict TypeScript with Zod schema validation |
---
## 🛠️ Available Tools
### `getSummary`
Returns the candidate's name, professional title, summary, and contact information.
- **Parameters:** None
- **Example prompt:** *"What is this candidate's professional summary?"*
### `getExperience`
Returns work experience history. Optionally filter by company name (case-insensitive partial match).
- **Parameters:** `company` *(optional string)* — e.g. `"RBrickks"`
- **Example prompt:** *"What companies has this person worked at?"*
### `getSkills`
Returns skills organized by category. Optionally filter to a specific category.
- **Parameters:** `category` *(optional enum)* — `"languages"` | `"frameworks"` | `"tools"` | `"soft"`
- **Example prompt:** *"What programming languages does this candidate know?"*
### `getProjects`
Returns projects built by the candidate. Optionally filter by technology stack tag.
- **Parameters:** `tag` *(optional string)* — e.g. `"Angular"`, `"Spring Boot"`
- **Example prompt:** *"Show me projects that use Angular"*
### `getEducation`
Returns the academic education history with degrees, institutions, and grades.
- **Parameters:** None
- **Example prompt:** *"Where did this candidate study?"*
### `search`
Full-text search across all resume sections — summary, experience bullets, skills, project descriptions, and education. Returns stable IDs that can be passed to `fetch` for full details.
- **Parameters:** `query` *(required string)* — e.g. `"Spring Boot"`, `"automation"`
- **Example prompt:** *"Search the resume for anything related to security"*
### `fetch`
Fetches the complete details of a specific resume section by its stable ID (returned by `search`).
- **Parameters:** `id` *(required string)* — e.g. `"summary"`, `"experience-0"`, `"projects-1"`, `"skills"`, `"education-2"`
- **Example prompt:** *"Get the full details for experience-0"*
### `tailorResume`
Analyzes a job description and ranks the most relevant skills, experience bullets, and projects by keyword overlap. Purely rule-based — no external AI dependency.
- **Parameters:** `jobDescription` *(required string)* — the full text of a job posting
- **Example prompt:** *"Here's a job description for a Java backend role at Google: [paste JD]. How well does this resume match?"*
---
## 📦 Prerequisites
- [Node.js](https://nodejs.org/) **v18 or higher**
- npm (included with Node.js)
---
## 🚀 Installation
```bash
# Clone the repository
git clone https://github.com/Adarshcharjan/resume-mcp-server.git
cd resume-mcp-server
# Install dependencies
npm install
# Build TypeScript to JavaScript
npm run build
```
---
## ▶️ Running the Server
### Option 1: stdio Transport (Local)
Designed for direct integration with AI clients running on the same machine (e.g., Claude Desktop). The client launches the server process and communicates via standard input/output.
```bash
npm run dev:stdio
```
### Option 2: HTTP Transport (Local or Remote)
Runs as a standard web server. Use this for remote deployment or when the AI client connects over HTTP.
```bash
npm run dev:http
```
The server starts at `http://localhost:3000` with:
- **MCP endpoint:** `POST http://localhost:3000/mcp`
- **Health check:** `GET http://localhost:3000/health`
---
## 🔐 API Key Authentication
The HTTP server supports **optional API-key authentication**.
If `RESUME_MCP_API_KEY` is set in your environment variables, every request to `/mcp` must include the header:
```
x-api-key: your-secret-key
```
Otherwise the server runs in **public mode** (no authentication required).
**Setting it up:**
```bash
# Copy the example env file
cp .env.example .env
```
Edit `.env`:
```env
PORT=3000
RESUME_MCP_API_KEY=your_custom_secret_key_here
```
When the API key is active, Claude Desktop config must include it:
```json
{
"mcpServers": {
"resume": {
"type": "streamable-http",
"url": "https://your-server.onrender.com/mcp",
"headers": {
"x-api-key": "your_custom_secret_key_here"
}
}
}
}
```
---
## 🔌 Integrating with MCP-Compatible AI Clients
### Claude Desktop
Claude Desktop supports MCP natively. You can connect using either transport mode.
#### stdio (Recommended for Local Use)
1. Open your Claude Desktop configuration file:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux:** `~/.config/Claude/claude_desktop_config.json`
2. Add the `mcpServers` entry (create the file if it doesn't exist):
```json
{
"mcpServers": {
"resume": {
"command": "node",
"args": ["/absolute/path/to/resume-mcp-server/dist/stdioMain.js"]
}
}
}
```
> ⚠️ **Windows users:** Use double backslashes in the path:
> `"D:\\Study\\Resume _MCP_server\\dist\\stdioMain.js"`
3. **Restart Claude Desktop** completely (quit from system tray, then reopen).
4. Start a new chat. The hammer 🔨 tools icon near the chat input will show all 8 resume tools.
#### HTTP / Streamable (Remote Server)
```json
{
"mcpServers": {
"resume": {
"type": "streamable-http",
"url": "https://resume-mcp-server-z04b.onrender.com/mcp"
}
}
}
```
---
### Cursor AI
1. Open **Cursor Settings** → **MCP** (or `Ctrl+Shift+P` → "MCP: Add Server").
2. Add a new server:
**stdio:**
```json
{
"resume": {
"command": "node",
"args": ["/absolute/path/to/resume-mcp-server/dist/stdioMain.js"]
}
}
```
**HTTP (Recommended — uses the live Render deployment):**
```json
{
"resume": {
"type": "streamable-http",
"url": "https://resume-mcp-server-z04b.onrender.com/mcp"
}
}
```
3. The resume tools will be available in Cursor's AI chat immediately.
---
### VS Code + GitHub Copilot
1. Create or edit `.vscode/mcp.json` in your workspace:
```json
{
"servers": {
"resume": {
"command": "node",
"args": ["/absolute/path/to/resume-mcp-server/dist/stdioMain.js"]
}
}
}
```
2. Open GitHub Copilot Chat in Agent mode — the resume tools will be available.
---
### Windsurf
1. Open **Windsurf Settings** → **MCP**.
2. Add a new server:
```json
{
"resume": {
"type": "streamable-http",
"url": "https://resume-mcp-server-z04b.onrender.com/mcp"
}
}
```
---
### MCP Inspector (Testing & Debugging)
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a visual tool for testing MCP servers without any AI client.
```bash
npx @modelcontextprotocol/inspector
```
When the Inspector UI opens in your browser:
1. Set **Transport Type** → `STDIO`
2. Set **Command** → `node`
3. Set **Arguments** → `dist/stdioMain.js`
4. Click **Connect**
All 8 tools will appear. Click any tool, fill in parameters, and hit **Run** to see live JSON responses.
---
## ☁️ Deployment on Render
This project is deployed on Render using the HTTP Streamable transport.
### Configuration
| Setting | Value |
|---|---|
| **Runtime** | Node |
| **Build Command** | `npm install && npm run build` |
| **Start Command** | `npm start` |
| **Plan** | Free |
### Environment Variables on Render
| Variable | Value |
|---|---|
| `PORT` | `3000` |
| `RESUME_MCP_API_KEY` | *(your secret key — optional)* |
> **Note:** Render's free tier spins down after 15 minutes of inactivity. The first request after a cold start may take ~30 seconds to respond.
---
## 🧪 Testing
### Automated Test Suite — stdio (16 test cases)
```bash
npm run build
node test-all-tools.mjs
```
Expected output:
```
✓ PASS 1. getSummary — Name: Adarsh Charjan | Title: Junior Software Developer
✓ PASS 2. getExperience — Jobs returned: 3
✓ PASS 3. getExperience — filter "RBrickks" → 2 jobs
✓ PASS 4. getSkills — Languages: Java, SQL, HTML, CSS
✓ PASS 5. getSkills — filter "frameworks" → Spring Boot, Spring MVC, Hibernate, Angular, REST APIs
✓ PASS 6. getProjects — 2 projects returned
✓ PASS 7. getProjects — filter "Angular" → WELLCARE Hospital Management System
✓ PASS 8. getEducation — B.Tech, HSC, SSC
✓ PASS 9. search "Spring Boot" — 4 matches
✓ PASS 10. search "automation" — 2 matches
✓ PASS 11. fetch "summary" — Professional Summary
✓ PASS 12. fetch "experience-0" — Junior Software Developer at RBrickks Technology
✓ PASS 13. fetch "projects-1" — WELLCARE Hospital Management System
✓ PASS 14. fetch "skills" — Skills and Technologies
✓ PASS 15. tailorResume — Matched languages: [Java, SQL] | Top bullet score: 7
✓ PASS 16. fetch invalid id — Graceful error handling
Results: 16 passed 0 failed / 16 total 🎉
```
### Automated Test Suite — HTTP (6 test cases)
```bash
# Terminal 1
npm run dev:http
# Terminal 2
node test-http.mjs
```
Expected output:
```
✓ PASS 1. initialize — Server: resume-mcp-server v1.0.0
✓ PASS 2. getSummary — Name: Adarsh Charjan
✓ PASS 3. getExperience — filter "AutomationEdge" → RPA Intern
✓ PASS 4. search "RBAC" — 3 matches
✓ PASS 5. tailorResume — Matched frameworks: [Spring Boot, Angular, REST APIs]
✓ PASS 6. GET /health — Status: ok
Results: 6 passed 0 failed / 6 total 🎉
```
---
## 📁 Project Structure
```
resume-mcp-server/
├── src/
│ ├── data/
│ │ ├── resume.json # Structured resume data
│ │ └── resumeLoader.ts # Type-safe JSON loader with interfaces
│ ├── tools/
│ │ ├── getSummary.ts # Returns name, title, summary, contact
│ │ ├── getExperience.ts # Work history with company filter
│ │ ├── getSkills.ts # Skills by category
│ │ ├── getProjects.ts # Projects with stack tag filter
│ │ ├── getEducation.ts # Education history
│ │ ├── search.ts # Full-text search across all sections
│ │ ├── fetch.ts # Fetch full record by stable ID
│ │ └── tailorResume.ts # JD keyword matching & ranking
│ ├── server.ts # McpServer factory — registers all 8 tools
│ ├── stdioMain.ts # Entry point: stdio transport (local)
│ └── httpMain.ts # Entry point: HTTP transport (remote)
├── dist/ # Compiled JavaScript (generated by npm run build)
├── test-all-tools.mjs # Automated stdio test suite (16 cases)
├── test-http.mjs # Automated HTTP test suite (6 cases)
├── package.json # Dependencies and npm scripts
├── tsconfig.json # TypeScript compiler configuration
├── .env.example # Environment variable template
├── .gitignore # Excludes node_modules, dist, .env
└── README.md # This file
```
---
## 📜 NPM Scripts
| Script | Command | Description |
|---|---|---|
| `npm run dev:stdio` | `tsx src/stdioMain.ts` | Run locally with stdio transport (Claude Desktop) |
| `npm run dev:http` | `tsx src/httpMain.ts` | Run locally with HTTP transport (development) |
| `npm run build` | `tsc` | Compile TypeScript source to `dist/` |
| `npm start` | `node dist/httpMain.js` | Run compiled HTTP server (production/Render) |
---
## 🏗️ Tech Stack
| Technology | Purpose |
|---|---|
| [TypeScript](https://www.typescriptlang.org/) | Type-safe server implementation |
| [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) | Official MCP SDK — tool registration and transport handling |
| [Express](https://expressjs.com/) | HTTP server framework for the remote transport |
| [Zod](https://zod.dev/) | Runtime schema validation for tool parameters |
| [tsx](https://github.com/privatenumber/tsx) | TypeScript execution for development |
---
## 🛡️ Security
- **API Key Authentication:** When `RESUME_MCP_API_KEY` is set, the HTTP server validates every `/mcp` request. Requests with a missing or incorrect key receive `401 Unauthorized`.
- **CORS:** The HTTP server includes full CORS headers to allow browser-based MCP clients to connect.
- **No External AI Calls:** The `tailorResume` tool uses purely rule-based keyword matching. No resume data is sent to any external APIs or LLMs.
- **`.env` excluded from Git:** Secrets never reach GitHub — only `.env.example` (with empty values) is committed.
---
## 📄 License
ISC
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available