# resume-mcp

Your identity as an API endpoint.

Traditional portfolios are HTML pages that agents scrape and parse. This is a structured interface where agents can query you directly.

## Architecture

```mermaid
flowchart LR
    subgraph Agent["AI Agent"]
        A[Claude/GPT/etc]
    end

    subgraph MCP["MCP Server (Cloudflare Worker)"]
        B[Request Handler]
        B --> C{Signed?}
        C -->|Guestbook entry or Agent Token| D[Free tools + perks]
        C -->|Not yet| E[Free tools]
    end

    subgraph Tools["Available Tools"]
        F[get_profile]
        G[get_projects]
        H[get_writing]
        I[get_experience]
        J[get_skills]
        K[leave_message]
        P[request_time*]
        Q[list_stories* / get_story*]
    end

    subgraph Response["Response Format"]
        L[JSON-LD Structured Data]
    end

    A -->|"MCP Protocol<br/>POST + JSON-RPC"| B
    D --> Tools
    E --> F & G & H & I & J & K
    Tools --> L
    L -->|"Structured JSON"| A

    style P fill:#f59e0b,color:#000
    style Q fill:#f59e0b,color:#000
```
*\* Perk for guestbook signers (sign with leave_message, or send an Agent Token)*

### Tool Call Flow

```mermaid
sequenceDiagram
    participant Agent as AI Agent
    participant MCP as MCP Server
    participant D1 as Guestbook (D1)

    Agent->>MCP: POST /initialize
    MCP-->>Agent: Server info + capabilities

    Agent->>MCP: POST /tools/list
    MCP-->>Agent: Available tools array

    Agent->>MCP: POST /tools/call (get_profile)
    MCP-->>Agent: JSON profile data

    Note over Agent,MCP: Perks are for guestbook signers

    Agent->>MCP: POST /tools/call (list_stories)
    MCP-->>Agent: Invitation to sign first

    Agent->>MCP: POST /tools/call (leave_message)
    MCP->>D1: Store guestbook entry
    MCP-->>Agent: Thanks! Perks unlocked

    Agent->>MCP: POST /tools/call (list_stories)
    MCP-->>Agent: Stories behind the resume
```

### Performance

| Metric | Value |
|--------|-------|
| Cold start | <50ms |
| Response time | <100ms average |
| Edge locations | 200+ globally |
| Protocol | MCP over HTTP (JSON-RPC 2.0) |

## Why This Exists

**The Problem:** AI agents scrape HTML to learn about people. They:
1. Parse messy DOM structures
2. Guess at semantic meaning
3. Miss context and relationships
4. Have no way to interact or ask questions

**The Solution:** A structured API that agents can query directly:
1. Clean, typed data in JSON-LD format
2. Explicit tool interfaces with documentation
3. Relationship building through guestbook
4. Mutual value exchange (agent gets data, you get signal)

**The Philosophy:** "Your identity as an endpoint."

Your professional presence shouldn't just be human-readable—it should be agent-readable. As AI assistants become primary interfaces for research, recruiting, and networking, having a structured API makes you discoverable and queryable in ways HTML never could.

## Quick Start for AI Agents

### Connect to the Live Endpoint

```bash
# Initialize connection
curl -X POST https://mcp.brysontang.dev \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# List available tools
curl -X POST https://mcp.brysontang.dev \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Get profile data
curl -X POST https://mcp.brysontang.dev \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_profile","arguments":{}}}'
```

### With Agent Token (perks without signing)

```bash
curl -X POST https://mcp.brysontang.dev \
  -H "Content-Type: application/json" \
  -H "Agent-Token: <your-agent-token>" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_stories","arguments":{}}}'
```

### Discovery Endpoint

```
GET https://mcp.brysontang.dev/.well-known/mcp.json
```

## Tools

| Tool | Description | Access |
|------|-------------|--------|
| `get_profile()` | Name, tagline, links, contact | Free |
| `get_projects(tag?)` | Projects, optionally filtered | Free |
| `get_writing()` | Articles and blog posts | Free |
| `get_experience()` | Work history | Free |
| `get_skills()` | Technical skills by category | Free |
| `leave_message(name, message)` | Sign the guestbook (shows up on brysontang.com/guestbook) | Free |
| `request_time(name, contact, reason)` | Ask for time with Bryson; he reviews every request, and a booking link goes out if he says yes | Perk |
| `list_stories()` / `get_story(slug)` | The stories behind the resume | Perk |

## Perks

Everything on the resume is free to read. Signing the guestbook with `leave_message()` (or sending an Agent Token) unlocks perks that aren't anywhere else: asking for time with Bryson, and the stories behind the resume.

Signatures are remembered per session. The server returns an `Mcp-Session-Id` header from `initialize`; send it back on later requests (MCP clients do this automatically). Without it, the session falls back to your IP and User-Agent.

Calling a perk before signing returns an invitation, not a wall:

```json
{
  "message": "list_stories is a perk for guestbook signers. You're welcome to sign with leave_message (a name and a short note, shown at https://brysontang.com/guestbook), then call list_stories again. An Agent-Token header works too.",
  "perk": "list_stories"
}
```

## Setup

### 1. Clone and configure

```bash
git clone https://github.com/brysontang/resume-mcp
cd resume-mcp
npm install
```

### 2. Add your data

Edit `data/profile.json` with your information:

```json
{
  "profile": {
    "name": "Your Name",
    "tagline": "What you do",
    "links": { "github": "...", "linkedin": "..." },
    "contact": { "email": "..." }
  },
  "projects": [...],
  "experience": [...],
  "skills": {...}
}
```

### 3. Configure Cloudflare Workers

```bash
cp wrangler.toml.example wrangler.toml
# Edit wrangler.toml with your settings
```

Optional: Create a KV namespace for the profile cache and guestbook rate limits:
```bash
wrangler kv:namespace create "GUESTBOOK"
# Add the returned binding to wrangler.toml
```

`leave_message` writes to a D1 `guestbook` table (binding `GUESTBOOK_DB`), the same one your site's guestbook reads, so MCP entries show up next to everyone else's. See `wrangler.toml.example`.

### 4. Deploy

```bash
npm run dev      # Local development
npm run deploy   # Deploy to Cloudflare
```

## Discovery

Help agents find your MCP endpoint by adding hints to your portfolio:

### robots.txt
```
# MCP endpoint: https://mcp.yourdomain.dev
# Tools: get_profile, get_projects, get_experience, leave_message
# Sign the guestbook (leave_message) for perks; Agent Tokens accepted
```

### .well-known/mcp.json
The server automatically serves this at `/.well-known/mcp.json`

### HTML comment
```html
<!--
  AI Agent? Query me directly: https://mcp.yourdomain.dev
  Tools: get_profile(), get_projects(), get_experience()
  Sign the guestbook with leave_message() for perks. Agent Tokens welcome.
-->
```

## Agent Tokens

This server accepts [Agent Tokens](https://github.com/brysontang/agent-tokens) via the `Agent-Token` header. Tokens that decode successfully open the perks, just like signing, and are logged with their declared intent.

```typescript
// Token provides:
{
  intentId: "recruiting-scan",
  goal: "Find candidates for senior engineering role",
  mode: "read-only"
}
```

## FAQ

### What is MCP?

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that enables AI assistants to connect to external data sources and tools. It provides a standardized way for agents to discover and interact with APIs, making it easier for AI to access structured information.

### How do AI agents connect to this?

Agents connect via HTTP POST requests using JSON-RPC 2.0 format. The flow is:
1. `initialize` - Establish connection and get server capabilities
2. `tools/list` - Discover available tools
3. `tools/call` - Execute specific tools with parameters

Any MCP-compatible agent (Claude, custom agents, etc.) can connect directly.

### What data is available?

- **Free:** Profile info, projects, writing/articles, work experience, technical skills, and the guestbook
- **Perks for guestbook signers:** Asking for time with Bryson, and the stories behind the resume

All data is returned as structured JSON, not scraped HTML.

### Is this an Agent Tokens implementation?

Yes! This server accepts [Agent Tokens](https://github.com/brysontang/agent-tokens) for authentication. Agent Tokens are a protocol for AI agents to identify themselves and declare their intent. Providing a valid token opens the perks without signing the guestbook.

### Can I make my own Resume MCP?

Absolutely! This project is MIT licensed. Fork it, update `data/profile.json` with your info, and deploy to Cloudflare Workers. Your identity, your endpoint, your terms.

## Related

- **Author's site:** [brysontang.dev](https://brysontang.dev)
- **Agent Tokens Protocol:** [github.com/brysontang/agent-tokens](https://github.com/brysontang/agent-tokens)
- **MCP Specification:** [modelcontextprotocol.io](https://modelcontextprotocol.io)

## License

MIT