# wiseoldman-mcp

An MCP server that wraps the [Wise Old Man](https://wiseoldman.net) OSRS stat-tracking API
(https://docs.wiseoldman.net/api), exposing it as tools for MCP-compatible clients (Claude
Code, Claude Desktop, etc).

Covers the full documented API surface: players, groups, competitions, records, deltas,
name changes, and efficiency (EHP/EHB) — 54 tools total, all prefixed `wom_`.

## Setup

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

Optionally copy `.env.example` to `.env` and set `WOM_API_KEY` (raises the rate limit from
20 to 100 requests/60s — request one in the [WOM Discord](https://wiseoldman.net/discord)).
Mutating actions (create/edit/delete groups & competitions) don't need this key; they use a
per-resource `verificationCode` returned when you create that resource.

## Running locally

```bash
npm run dev          # run directly with tsx, no build step
npm run inspector     # open the MCP Inspector against the server for manual testing
```

### Register with Claude Code

```bash
claude mcp add wiseoldman -- node /path/to/wiseoldman_mcp/dist/index.js
```

(Run `npm run build` first so `dist/index.js` exists. Re-run the build after pulling changes.)

### Register with Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wiseoldman": {
      "command": "node",
      "args": ["/path/to/wiseoldman_mcp/dist/index.js"],
      "env": { "WOM_API_KEY": "..." }
    }
  }
}
```

## Project layout

- `src/womClient.ts` — thin fetch wrapper around the WOM REST API (auth headers, error
  normalization). Nothing here is MCP-specific.
- `src/enums.ts` — reference lists (skills, bosses, periods, etc) baked into tool
  descriptions. Kept as plain strings rather than strict zod enums, since WOM adds new
  bosses/activities over time — the live API remains the source of truth for validation.
- `src/toolHelpers.ts` — shared result/error formatting for tool handlers.
- `src/tools/*.ts` — one file per API resource, each registering its tools on the
  `McpServer` instance.
- `src/index.ts` — wires everything together and connects over stdio.

## Roadmap: remote hosting with OAuth (Authentik)

Right now this only runs locally over stdio, which is fine for a single user's local
clients. Deploying it as a shared/remote server later will need:

- Swapping `StdioServerTransport` for the SDK's `StreamableHTTPServerTransport`, run behind
  an actual HTTP server (e.g. Express/Hono).
- An OAuth layer in front of it (the MCP spec expects OAuth 2.1 with PKCE for remote
  servers) — Authentik can act as the authorization server; the transport setup would
  validate the bearer token per-request against Authentik's introspection/JWKS endpoint.
- The `wom` client and all tool registration code is transport-agnostic already, so none of
  `src/tools/*` or `src/womClient.ts` should need to change — only `src/index.ts` and a new
  auth-checking layer around it.

Not implemented yet — flagging so the current structure doesn't need rework when we get there.