# career-navigator-mcp

An MCP (Model Context Protocol) server that exposes the career diagnosis AI system as callable tools — powered by Google Gemini and a RAG knowledge base of 10 professions.

Any MCP-compatible client (Claude Desktop, Cursor, etc.) can integrate this server and call its tools directly.

---

## Tools

### `analyze_skills`
Analyzes free text describing a user and returns a list of skills with match percentages.

**Input:**
```json
{ "text": "I enjoy working with people and solving complex problems..." }
```

**Output:**
```json
[
  { "skill": "Interpersonal Communication", "match_percentage": 95 },
  { "skill": "Problem Solving",             "match_percentage": 85 }
]
```

---

### `recommend_profession`
Receives a skills array and recommends the most suitable profession using RAG — matched against a real knowledge base of 10 professions.

**Input:**
```json
{
  "skills": [
    { "skill": "Interpersonal Communication", "match_percentage": 95 },
    { "skill": "Problem Solving",             "match_percentage": 85 }
  ]
}
```

**Output:**
```json
[
  {
    "profession": "מנהל משאבי אנוש",
    "match_percentage": 91,
    "explanation": "..."
  }
]
```

---

## Architecture

```
MCP Client (Claude Desktop / Cursor / any AI agent)
    │
    │  tools/call: analyze_skills / recommend_profession
    ▼
career-navigator-mcp (StdioServerTransport)
    │
    ├── analyze_skills ──► Gemini API (structured JSON output)
    │
    └── recommend_profession ──► RAG: professions_data.json
                                      └── top 3 matches injected into Gemini prompt
```

---

## Setup

### Prerequisites
- Node.js 18+
- A `GEMINI_API_KEY` from [Google AI Studio](https://aistudio.google.com/)

### Install
```bash
git clone https://github.com/Miriam-Epstein/career-navigator-mcp.git
cd career-navigator-mcp
npm install
```

### Environment
Create a `.env` file in the project root:
```env
GEMINI_API_KEY=your_key_here
```

---

## Connecting to Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "career-navigator": {
      "command": "node",
      "args": ["/absolute/path/to/career-navigator-mcp/index.js"]
    }
  }
}
```

---

## Model Fallback

Every Gemini call uses an automatic fallback chain:
```
gemini-2.5-flash-lite  →  (on 429 / quota error)  →  gemini-2.5-flash
```

---

## Tech Stack

| Layer | Technology |
|---|---|
| Protocol | MCP SDK (`@modelcontextprotocol/sdk`) |
| Transport | StdioServerTransport |
| AI | Google Gemini (`@google/genai`) |
| RAG | Local JSON knowledge base (10 professions) |