# OSRS MCP Server

MCP server for the Old School RuneScape Wiki, in-game data definitions, Grand Exchange prices, and hiscores. Live data from `oldschool.runescape.wiki` with proper redirect handling, retry/backoff, identifying User-Agent, and section + wikitext + extracts tools.

This is a community fork: previous work by [@JayArrowz](https://github.com/jayarrowz/mcp-osrs) (much appreciated). Forked here to add better pagination, redirect handling, identifying User-Agent, additional retrieval modes (wikitext / extracts / section / opensearch), and polite client behavior.

## Tools

### OSRS Wiki

| # | Tool | Description |
|---|---|---|
| 1 | `osrs_wiki_search` | Full-text search of the OSRS Wiki (CirrusSearch). Returns snippets with section titles. |
| 2 | `osrs_wiki_get_page_info` | Get metadata (pageid, length, last modified, redirects) for one or more titles. |
| 3 | `osrs_wiki_parse_page` | Full-page parse → rendered HTML. Follows redirects automatically. |
| 4 | `osrs_wiki_wikitext` | **New.** Raw wikitext for a page (preserves templates/infoboxes). Useful for AI to see templated context. |
| 5 | `osrs_wiki_extract` | **New.** Cheap plain-text or limited-HTML extract via the search index. Much faster than full parse. Supports `intro`, `chars` cap, `sectionformat`. |
| 6 | `osrs_wiki_parse_section` | **New.** Parse a single section by 0-based index (saves tokens on huge pages like `Slayer`). |
| 7 | `osrs_wiki_opensearch` | **New.** Title autocomplete (e.g., `"abys"` → Abyssal whip / dagger / demon). Returns tidy `{title, description, url}` rows. |

All wiki tools follow `redirects=1`, set an identifying `User-Agent`, and retry on 429/503 with exponential backoff. The client also honors the wiki's `maxlag` advisory by waiting and retrying once.

### Game Data Search (local cache files)

```
search_varptypes · search_varbittypes · search_iftypes · search_invtypes
search_loctypes · search_npctypes · search_objtypes · search_rowtypes
search_seqtypes · search_soundtypes · search_spottypes · search_spritetypes
search_tabletypes
```
Plus the generic file tools: `search_data_file`, `get_file_details`, `list_data_files`.

### Live OSRS Data

- `lookup_player` — Hiscores stats (skills, bosses, clues, activities).
- `search_ge_items` — Search GE items by name (the underlying mapping is cached on first call).
- `get_ge_latest` / `get_ge_timeseries` — Instant and historical Grand Exchange prices.

## Installation

```bash
npx -y mcp-osrs
```

…or, locally:

```bash
git clone https://github.com/fisherrjd/mcp-osrs.git
cd mcp-osrs
npm install
npm run build
```

## Configuration

Add to your MCP client's `mcpServers` config:

```json
{
  "mcpServers": {
    "mcp-osrs": {
      "command": "npx",
      "args": ["-y", "mcp-osrs"]
    }
  }
}
```

Path config for `claude_desktop_config.json`:

| OS | Path |
|---|---|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%/Claude/claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |

## Requirements

- Node.js 18+
- Outbound HTTPS access to `oldschool.runescape.wiki`, `prices.runescape.wiki`, and `secure.runescape.com` (hiscores).

## Examples

```
# Search wiki
> search the OSRS Wiki for pages matching "dragon"

# Get an intro summary only — fast and small
> get an intro paragraph for the Abyssal whip page

# Parse just one section of a long page
> parse section 3 of "Slayer"

# Autocomplete a title
> wiki title autocomplete for "abys"

# Get raw wikitext for infobox data
> get the wikitext for "Abyssal_whip"

# Player + GE
> how's Zezima doing?  +  what's the 1h price history of cannonballs (id 2)?
```

## What changed vs upstream

| Before (`@jayarrowz/mcp-osrs` 0.7.x) | This fork (`mcp-osrs` 0.8.x) |
|---|---|
| Bare `axios/1.x` User-Agent — throttled by the wiki | Identifying UA: `mcp-osrs/0.8.0 (+https://github.com/fisherrjd/mcp-osrs; +discord:rjfisher; dev@jade.rip) node/<v>` |
| No retry / backoff | 3 retries on 429/5xx with exponential backoff; honors `Retry-After` |
| No `maxlag` handling | Honors wiki's `maxlag` advisory (one retry with jittered delay) |
| `parse_page` did not follow redirects ("Abyssal whip" → "Abyssal_whip" fails) | `parse_page`, `wikitext`, `extract`, `parse_section` all set `redirects=1` |
| Only rendered HTML output (`prop=text`) | + raw `wikitext`, cheap `extracts`, per-`section`, `opensearch` autocomplete |
| Timeout: none | 10 s per request |
| gzip, etc. headers not set | `Accept-Encoding: gzip, deflate` |
| Source code refs `jayarrowz` everywhere | Renamed to `fisherrjd` (GitHub username); author `rjfisher` is their Discord handle; bare `mcp-osrs` on npm; all data path clients ship the same UA |

## Bonus: upstream pi-web-access patch

This fork ships a minimal patch for a known crash in the upstream pi package:
[`@nicobailon/pi-web-access`](https://github.com/nicobailon/pi-web-access) v0.13.0 has a
`ReferenceError: sendCuratorFallbackUpdate is not defined` bug — issue #103 — that
kills pi when the search curator can't open a browser. The fix (hoist a `let`
binding out of the `try` block so the `catch` can see it) is captured in
[`patches/pi-web-access+0.13.0.patch`](patches/pi-web-access+0.13.0.patch). Apply
with `patch -p0 -i patches/pi-web-access+0.13.0.patch` (after the file has been
checked out from v0.13.0).

## Development

```bash
npm install
npm run build   # tsc + chmod + copy data
npm test        # jest unit tests
npm start       # stdio MCP server
```

## License

MIT — see [LICENSE](LICENSE). Upstream: [JayArrowz/mcp-osrs](https://github.com/JayArrowz/mcp-osrs).