# RS3 MCP Server

MCP (Model Context Protocol) server that exposes RuneScape 3 data from the RuneMetrics, Grand Exchange, and RuneScape Wiki APIs. Works with any MCP-compatible client — Claude, Gemini, Cursor, and others.

## Tools

### RuneMetrics

| Tool | Description |
|------|-------------|
| `runemetrics_profile` | Player profile: skills, combat level, quest counts, recent activity |
| `runemetrics_monthly_xp` | Monthly XP gains for a specific skill (last 12 months) |
| `runemetrics_quests` | Full quest list with completion status, difficulty, quest points |

### Grand Exchange

| Tool | Description |
|------|-------------|
| `ge_item_detail` | Item lookup by ID: current price, 30/90/180-day trends, description |
| `ge_item_search` | Search items by category and starting letter (paginated, 12 per page) |

### RuneScape Wiki

| Tool | Description |
|------|-------------|
| `wiki_search` | Search the RS Wiki for articles by keyword, returns titles and snippets |
| `wiki_page` | Fetch a wiki page's content by exact title (full or intro only) |

## Quick start

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

### HTTP mode (Claude, Gemini, web clients)

```bash
npm start
# Server listens on http://0.0.0.0:3001/mcp
```

Override the port with the `PORT` environment variable:

```bash
PORT=8080 npm start
```

### stdio mode (Cursor, Claude Desktop)

```bash
npm run start:stdio
```

## Client configuration

### Cursor

Add to `.cursor/mcp.json` (or your global Cursor MCP config):

```json
{
  "mcpServers": {
    "rs3": {
      "command": "node",
      "args": ["dist/index.js", "--stdio"],
      "cwd": "/path/to/RS3-MCP"
    }
  }
}
```

Or connect to the HTTP server:

```json
{
  "mcpServers": {
    "rs3": {
      "url": "http://localhost:3001/mcp"
    }
  }
}
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rs3": {
      "command": "node",
      "args": ["/path/to/RS3-MCP/dist/index.js", "--stdio"]
    }
  }
}
```

### Claude (web) / Gemini / other HTTP clients

Point the client's MCP server URL to:

```
http://<host>:3001/mcp
```

The server uses Streamable HTTP transport with session management.

## Development

```bash
npm run dev          # HTTP mode with hot reload (tsx)
npm run dev:stdio    # stdio mode with hot reload (tsx)
```

## Health check

```
GET http://localhost:3001/health
```

Returns `{ "status": "ok", "server": "rs3-runemetrics", "version": "0.1.0" }`.

## Notes

- RuneMetrics and Grand Exchange endpoints are unofficial Jagex APIs — no auth required, but response shapes may change without notice.
- Players can make their RuneMetrics profile private; the server returns clear error messages when data is unavailable.
- The server sends a descriptive `User-Agent` header (`RS3-MCP/0.1`) with every request.