# @mistereman22/osrs-wiki-mcp-server

MCP server for the Old School RuneScape Wiki (`https://oldschool.runescape.wiki`). Serves the full tool surface of [`@professional-wiki/mediawiki-mcp-server`](https://github.com/ProfessionalWiki/MediaWiki-MCP-Server) against a pinned, read-only wiki definition.

| Capability | Details |
| --- | --- |
| MediaWiki tools | Full upstream tool surface (page reads, search, watchlists, siteinfo, ...) with wiki fixed to `oldschool.runescape.wiki`. **Read-only** - write and wiki-management tools are gated off. |
| `context://bucket-index` | On-demand hint list of known Bucket buckets for `bucket-query`; read fresh per request with runtime discovery as fallback. |

## Quick start (users)

**Requirement:** Node.js >= 22.19.0

### OpenCode
```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "osrs-wiki": {
        "type": "local",
        "command": ["npx", "@mistereman22/osrs-wiki-mcp-server@1.0.0"],
        "environment": { "MCP_CONTACT": "you@example.com" }
      }
    }
  }
}
```

### Cursor
```json
{
  "mcpServers": {
    "osrs-wiki": {
      "command": "npx",
      "args": ["@mistereman22/osrs-wiki-mcp-server@1.0.0"],
      "env": { "MCP_CONTACT": "you@example.com" }
    }
  }
}
```

### Claude Code
```sh
/plugin marketplace add mistereman22/osrs-wiki-mcp-server
/plugin install osrs-wiki-mcp-server@osrs-wiki-mcp-server
```

### Run directly
```sh
MCP_CONTACT="you@example.com" npx @mistereman22/osrs-wiki-mcp-server@1.0.0
```

## Configuration

| Variable | Required | Meaning |
| --- | --- | --- |
| `MCP_CONTACT` | **Yes** | Your contact (email or name + URL), appended to the server's base User-Agent on every OSRS wiki request. Example: `you@example.com`. Server fails fast at startup if missing. |

## Composed User-Agent
```
osrs-wiki-mcp-server/1.0.0 (https://github.com/mistereman22/osrs-wiki-mcp-server) you@example.com
```

## Rate limits

Two independent sliding-window budgets (tuned in `src/server.ts`):

| Surface | Budget | Counted per |
| --- | --- | --- |
| MediaWiki API | 30 requests / 60 s | each upstream tool call |
| External APIs | 30 requests / 60 s | each HTTP request by external API tool |

Over budget: waits up to 10s for a slot, then returns rate-limit error with retry hint.

## Development

### Requirements
- Node.js >= 22.19.0
- `npm install` in this directory

### Commands
```sh
npm run build   # TypeScript -> dist/
npm start       # Run built server (requires MCP_CONTACT)
npm run dev     # Build + run
```

### Repository layout
```
.
+-- src/
|   +-- index.ts          # Entry point: env gate, stdio transport, lifecycle
|   +-- env.ts            # MCP_CONTACT fail-fast gate + User-Agent composition
|   +-- server.ts         # McpServer assembly + tool gating + wiki config + rate limiting
|   +-- resources.ts      # Generic resource loader (bucket-index)
|   +-- external.ts       # HTTP utilities (callHttp) for future external APIs
|   +-- declarations.d.ts # Type declarations for upstream JS-only package
+-- resources/
|   +-- bucket-index.md   # Bucket hint list for context://bucket-index
+-- .claude-plugin/
|   +-- marketplace.json  # Claude Code marketplace manifest
+-- dist/                 # Compiled output (generated by build)
+-- package.json
+-- tsconfig.json
+-- README.md
+-- LICENSE
```

### Rate limit constants
Tuned in `src/server.ts`:
- `WINDOW_MS = 60_000` (60s window)
- `MAX_WAIT_MS = 10_000` (max 10s wait)
- `WIKI_MAX_REQUESTS = 30`
- `EXTERNAL_MAX_REQUESTS = 30`

## Contact
- Maintainer: [github.com/mistereman22](https://github.com/mistereman22)
- Issues: [github.com/mistereman22/osrs-wiki-mcp-server/issues](https://github.com/mistereman22/osrs-wiki-mcp-server/issues)

## License

[MIT](LICENSE)