# Model Context Protocol (MCP) Server Setup & Usage Guide

This site provides a remote **Model Context Protocol (MCP)** server endpoint that exposes William's portfolio AI agent and knowledge base corpus to any MCP-compliant client (such as Claude Desktop, Cursor, Antigravity IDE, Windsurf, Continue, or custom LLM client apps).

---

## Capabilities

The MCP server exposes:

- **Tools**:
  - `ask_portfolio_agent`: Queries the portfolio agent about William's work experience, resume, projects, technical skills, and background using retrieval context.
- **Resources**:
  - `portfolio://corpus`: Returns the complete indexed portfolio knowledge documents in Markdown format.

---

## Remote Endpoint Details

- **Production Endpoint**: `https://williamtsang.me/api/mcp`
- **Protocol**: JSON-RPC 2.0 over HTTP POST

---

## Client Setup (using `mcp-remote` bridge)

To connect MCP desktop and CLI tools (like Claude Desktop, Cursor, Antigravity IDE) to the remote MCP server:

### Option A: Configuration via `claude_desktop_config.json` / Client Config

Add the following to your MCP client config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "william-portfolio-remote": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://williamtsang.me/api/mcp"
      ]
    }
  }
}
```

### Option B: Cursor / Antigravity IDE Setup

1. Go to **Settings** > **MCP Servers** (or **Features** > **MCP**).
2. Add a new MCP server with:
   - **Name**: `william-portfolio-remote`
   - **Type**: `command` (or stdio bridge via npx)
   - **Command**: `npx -y mcp-remote https://williamtsang.me/api/mcp`

---

## Direct HTTP API Usage (JSON-RPC 2.0)

You can also send standard JSON-RPC 2.0 requests directly to the remote API route using HTTP POST:

### List Tools
```bash
curl -X POST https://williamtsang.me/api/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'
```

### Execute Tool
```bash
curl -X POST https://williamtsang.me/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "ask_portfolio_agent",
      "arguments": {
        "question": "What key projects has William built?"
      }
    }
  }'
```

### Read Knowledge Corpus Resource
```bash
curl -X POST https://williamtsang.me/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "resources/read",
    "params": {
      "uri": "portfolio://corpus"
    }
  }'
```

---

## Agent System Prompt Templates

To enable an AI agent (such as Claude Desktop, Cursor, Custom Agents, or Antigravity IDE) to automatically discover and use the MCP server when searching for information about William, add one of the prompt templates below to your agent's **System Prompt**, **Custom Instructions**, or **Rules**:

### Template A: System Prompt for LLM / AI Assistants (Recommended)

```markdown
### William Tsang Portfolio Knowledge Integration

You have access to the Model Context Protocol (MCP) tool `ask_portfolio_agent` (via server `william-portfolio-remote`).

1. **Trigger Condition**: Whenever the user asks any question about:
   - William Tsang (his bio, experience, background, skills, resume, contact info)
   - Projects, portfolio repositories, technical stack, or achievements

2. **Tool Execution**:
   - ALWAYS call `ask_portfolio_agent` with the user's question before responding.
   - Example: `ask_portfolio_agent(question="What are William's key projects and technical skills?")`
   - Do NOT guess or rely on default knowledge for William Tsang.

3. **Response Formatting**:
   - Synthesize the returned information accurately into your final response.
   - Maintain the original markdown formatting, project details, and links returned by the tool.
```

### Template B: Custom Instructions / Rules File (`.cursorrules` or `.agents/AGENTS.md`)

```markdown
# Portfolio MCP Agent Instructions

When answering any user request concerning William Tsang, his background, resume, or projects:
- Execute the MCP tool `ask_portfolio_agent` (or `william-portfolio-remote/ask_portfolio_agent`).
- Supply the user's specific query to the tool.
- Rely exclusively on the retrieved data to formulate your response.
```

### Template C: Chat Prompt Example

If your client does not support custom system prompts, prefix your prompt in chat like this:

> *"Please use the `ask_portfolio_agent` tool to search for information about William Tsang and summarize his background and key projects."*