# Developer Portfolio MCP Server

> **An MCP server that lets recruiters and AI assistants explore your profile, skills, and projects through natural language.**

[![Python](https://img.shields.io/badge/Python-3.11%2B-blue)](https://python.org)
[![MCP](https://img.shields.io/badge/MCP-1.x-green)](https://modelcontextprotocol.io)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## What is this?

This project is a **Model Context Protocol (MCP) server** — a standardized bridge between AI assistants (Cursor, Claude Desktop, etc.) and your developer portfolio data.

Instead of sending recruiters a static PDF resume, you give them (or their AI tools) a live MCP server they can **query interactively**:

- *"What Python projects has this developer built?"*
- *"How well does their stack match this job description?"*
- *"Generate an interview prep brief for a Senior Engineer role."*

**Why recruiters care:** It demonstrates you understand modern AI tooling, can build production integrations, and think about developer experience.

---

## Quick Start

### 1. Clone and install

```bash
git clone https://github.com/YOUR_USERNAME/developer-portfolio-mcp.git
cd developer-portfolio-mcp
uv sync --extra dev
```

### 2. Customize your data

Edit these JSON files with **your real information**:

| File | What to update |
|------|----------------|
| `src/developer_portfolio_mcp/data/profile.json` | Name, email, GitHub, LinkedIn, summary |
| `src/developer_portfolio_mcp/data/projects.json` | Your real projects |
| `src/developer_portfolio_mcp/data/skills.json` | Your actual skills |

### 3. Run the server

```bash
uv run developer-portfolio-mcp
```

### 4. Connect to Cursor

Copy the example config and update the path:

```bash
cp .cursor/mcp.json.example .cursor/mcp.json
# Edit the absolute path in mcp.json to your project directory
```

Then in Cursor: **Settings → MCP** — your server should appear. Try asking:

> "Use the developer-portfolio MCP to show me this candidate's top projects."

---

## What's Inside

### Tools (6) — Actions the AI can perform

| Tool | Description |
|------|-------------|
| `get_developer_profile` | Core profile and availability |
| `list_projects` | Portfolio projects (filterable by status) |
| `get_project_details` | Deep dive on one project |
| `search_skills` | Search skills by keyword/category |
| `get_contact_info` | Contact links and scheduling info |
| `compare_stack` | Match job requirements vs. your skills |

### Resources (3) — Read-only data endpoints

| URI | Content |
|-----|---------|
| `profile://resume` | Full resume in Markdown |
| `profile://skills/{category}` | Skills by category |
| `projects://list` | All projects as JSON |

### Prompts (3) — Reusable AI templates

| Prompt | Use case |
|--------|----------|
| `interview_prep` | Generate role-specific interview prep |
| `recruiter_brief` | One-page candidate summary |
| `project_pitch` | Pitch a project to a hiring manager |

---

## Project Structure

```
developer-portfolio-mcp/
├── src/developer_portfolio_mcp/
│   ├── server.py          # MCP server (tools, resources, prompts)
│   ├── loaders.py         # Data loading utilities
│   └── data/              # Your portfolio JSON (customize these!)
│       ├── profile.json
│       ├── projects.json
│       └── skills.json
├── tests/                 # Unit tests
├── docs/
│   └── LEARNING_GUIDE.md  # MCP basics → advanced (start here to learn!)
├── .cursor/mcp.json.example
├── pyproject.toml
└── README.md
```

---

## Run Tests

```bash
uv run pytest -v
```

---

## Learning MCP

New to MCP? Read **[docs/LEARNING_GUIDE.md](docs/LEARNING_GUIDE.md)** — a structured path from basics to advanced concepts, using this project as your hands-on lab.

Topics covered:
- What MCP is and why it matters
- Tools vs Resources vs Prompts
- Transports (stdio, HTTP)
- Building your own tools
- Deploying for recruiters

---

## Push to GitHub

```bash
# After customizing your data:
git add .
git commit -m "Add developer portfolio MCP server"
git remote add origin https://github.com/YOUR_USERNAME/developer-portfolio-mcp.git
git push -u origin main
```

Add this to your resume/LinkedIn:
> Built an MCP server exposing developer portfolio data to AI assistants — [github.com/YOUR_USERNAME/developer-portfolio-mcp](https://github.com/YOUR_USERNAME/developer-portfolio-mcp)

---

## Tech Stack

- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) (FastMCP)
- Python 3.11+
- [uv](https://docs.astral.sh/uv/) for package management

---

## License

MIT — use freely, customize for your portfolio, and share with recruiters.