# whoami-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes a person's structured professional profile — experience, projects, skills, education, certifications — as MCP tools. Point Claude (or any MCP client) at it and it can answer questions about that person from real data instead of guesswork.

One package, three ways to use it:

- **Library** — `npm i whoami-mcp`, build your own integration on the tools.
- **Local (stdio)** — `npx whoami-mcp` for Claude Desktop.
- **Deployable (HTTP)** — a stateless Streamable-HTTP server you can host (Docker-ready).

## Install

One click — pick your client:

[![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-000?style=for-the-badge&logo=cursor)](cursor://anysphere.cursor-deeplink/mcp/install?name=whoami&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIndob2FtaS1tY3AiXSwiZW52Ijp7IlBST0ZJTEVfUEFUSCI6Ii9hYnMvcGF0aC90by9wcm9maWxlLmpzb24ifX0=)
[![Add to VS Code](https://img.shields.io/badge/Add%20to-VS%20Code-007ACC?style=for-the-badge&logo=visualstudiocode)](https://insiders.vscode.dev/redirect/mcp/install?name=whoami&config=%7B%22command%22%3A%20%22npx%22%2C%22args%22%3A%20%5B%22-y%22%2C%20%22whoami-mcp%22%5D%2C%22env%22%3A%20%7B%22PROFILE_PATH%22%3A%20%22%24%7Binput%3AprofilePath%7D%22%7D%7D)

Or follow a per-client guide:

| Client | Guide |
|---|---|
| Cursor | [installation/install-cursor.md](installation/install-cursor.md) |
| Claude Desktop | [installation/install-claude-desktop.md](installation/install-claude-desktop.md) |
| Claude Code | [installation/install-claude-code.md](installation/install-claude-code.md) |
| VS Code (Copilot) | [installation/install-vscode.md](installation/install-vscode.md) |
| Windsurf | [installation/install-windsurf.md](installation/install-windsurf.md) |
| Remote / HTTP deploy | [installation/install-http.md](installation/install-http.md) |

After install, point the server at [your profile](#your-profile).

## Contents

- [Install](#install)
- [Tools](#tools)
- [Chat (optional)](#chat-optional)
- [Your profile](#your-profile)
- [Local (stdio) — Claude Desktop](#local-stdio--claude-desktop)
- [Deploy (Streamable HTTP)](#deploy-streamable-http)
- [Build on the library](#build-on-the-library)
- [Layout](#layout)
- [License](#license)

## Tools

| Tool | Returns |
|---|---|
| `get_profile` | Name, role, company, location, bio, availability, preferred stack, links |
| `get_experience` | Work history: companies, roles, dates, descriptions, achievements |
| `get_projects` | Projects: tech stack, problem solved, your specific role, links |
| `get_skills` | Skills by category with proficiency levels |
| `get_education` | Education history + professional certifications |

## Chat (optional)

Set a chat provider and the server gains an extra **`ask`** tool — it answers
free-form questions in the person's voice, grounded in the profile, instead of
just returning raw data. Off by default (the data tools work without it).

It speaks the **OpenAI-compatible `/chat/completions`** API, so *any* provider
works — set a base URL + model (+ key if needed):

| Provider | `CHAT_BASE_URL` | `CHAT_MODEL` |
|---|---|---|
| OpenAI | `https://api.openai.com/v1` | `gpt-4o-mini` |
| Google | `https://generativelanguage.googleapis.com/v1beta/openai` | `gemini-2.0-flash` |
| Ollama (local, no key) | `http://localhost:11434/v1` | `llama3.2` |
| Groq | `https://api.groq.com/openai/v1` | `llama-3.3-70b-versatile` |

```bash
CHAT_BASE_URL=https://api.openai.com/v1 CHAT_API_KEY=sk-... CHAT_MODEL=gpt-4o-mini \
  PROFILE_PATH=data/profile.json npm run start:http
```

Env: `CHAT_BASE_URL`, `CHAT_MODEL` (both required to enable), `CHAT_API_KEY`
(optional), `CHAT_TEMPERATURE` (default `0.4`). See [`.env.example`](.env.example).

## Your profile

Every server reads one profile JSON with six top-level keys: `basic`, `experience`, `projects`, `skills`, `education`, `certifications`. See [`data/profile.example.json`](data/profile.example.json) for the exact shape.

```bash
cp data/profile.example.json data/profile.json   # then edit
```

Point a server at it however suits your deploy (precedence top to bottom):

- `PROFILE_URL` — fetch the JSON over HTTP (a GitHub gist, your hosted profile API, any endpoint)
- `PROFILE_PATH` — read this file
- `./profile.json` — default file in the working directory

## Local (stdio) — Claude Desktop

```json
{
  "mcpServers": {
    "whoami": {
      "command": "npx",
      "args": ["-y", "whoami-mcp"],
      "env": { "PROFILE_PATH": "/abs/path/to/your/profile.json" }
    }
  }
}
```

From a clone instead: `npm install && npm run build`, then point `command`/`args` at `node /abs/path/to/dist/stdio.js`.

> Other clients: [Cursor](installation/install-cursor.md) · [Claude Code](installation/install-claude-code.md) · [VS Code](installation/install-vscode.md) · [Windsurf](installation/install-windsurf.md).

## Deploy (Streamable HTTP)

A long-running, stateless HTTP server — host it anywhere that runs a container.

```bash
docker compose up --build      # serves MCP at http://localhost:8080/mcp
```

Without Docker:

```bash
npm install && npm run build
PROFILE_PATH=data/profile.json npm run start:http
```

Connect an MCP client to the endpoint:

```json
{ "mcpServers": { "whoami": { "url": "http://localhost:8080/mcp" } } }
```

Health check: `GET /health` → `{"status":"ok"}`.

> Full deploy + remote-client guide: [installation/install-http.md](installation/install-http.md).

## Build on the library

```bash
npm i whoami-mcp
```

```ts
import { registerTools, type NormalizedProfile } from "whoami-mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({ name: "whoami", version: "1.0.0" });
registerTools(server, profile);   // profile: NormalizedProfile
```

`whoami-mcp/http` also exports `createHttpHandler(profile, opts)` for Next.js / fetch runtimes.

## Layout

```
src/
  index.ts        library entry — TOOLS, registerTools, types
  http.ts         createHttpHandler (fetch/Next factory)  → exported as whoami-mcp/http
  tools.ts        the five tool definitions
  types.ts        NormalizedProfile + tool types
  register.ts     registerTools(server, profile)
  loadProfile.ts  read PROFILE_PATH / ./profile.json
  stdio.ts        bin: whoami-stdio
  http-server.ts  bin: whoami-http (deployable, SDK StreamableHTTP)
```

```bash
npm install
npm run build
```

## License

MIT — see [LICENSE](./LICENSE).