![mcp-server-runescape](./public/banner.svg)

# 🎮 RS3-MCP - Professional RuneScape Automation Server

A production-ready implementation of the **Model Context Protocol (MCP)**, providing AI agents (like Claude and ChatGPT) with high-fidelity tools to interact with the **RuneScape 3** and **OSRS** ecosystems.

> [!NOTE]
> This project is forked and significantly enhanced from [stefanxyz/mcp-server-runescape](https://github.com/stefan-xyz/mcp-server-runescape).

## 🚀 Enhancements & Modernization
While the core API interactions were established by `stefanxyz`, this repository features **comprehensive enterprise-grade improvements**:

- **🛡️ Full Validation Suite**: Includes a rigorous automated testing framework (Vitest) for API stability.
- **🛡️ Error Resilience**: Enhanced error handling and fallback logic for unreliable RuneScape endpoints.
- **🛡️ Performance Audit**: Detailed benchmarking and optimization reports for low-latency tool execution.
- **🛡️ Agentic Integration**: Specific optimizations for "Cursor" and "Claude Desktop" environments.

## ✨ Core Tools

The server provides 6 essential tools for AI-driven gameplay analysis:

1.  **💰 get_item_details**: Real-time Grand Exchange prices and 180-day trends.
2.  **📈 get_item_price_history**: Historical data visualization for market analysis.
3.  **🏆 get_player_hiscore**: Deep-dive into player ranks, XP, and activity scores.
4.  **🥇 get_top_rankings**: Skill-specific leaderboards and competitive analysis.
5.  **👥 get_player_count**: Real-time server population tracking.
6.  **📋 get_rsuser_total**: Global account creation and historical growth metrics.

## 📦 Getting Started

### 1. Requirements
- Node.js 18+
- [MCP Client](https://modelcontextprotocol.io/clients) (Claude Desktop, Cursor, etc.)

### 2. Configuration (Claude Desktop)

Paste this into your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rs3-mcp": {
      "command": "node",
      "args": ["F:/Software Developement/Portfolio/Games/rs3bot/mcp-server-runescape/src/server.js"]
    }
  }
}
```

## 🛠️ Testing & Validation
We maintain a detailed log of system health:
- `API_VALIDATION_REPORT.md`: Comprehensive endpoint status.
- `PERFORMANCE_OPTIMIZATION_SUMMARY.md`: Latency benchmarks.
- `MCP_CONNECTION_VALIDATION_SUMMARY.md`: Client-side handshake verification.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Original core logic © 2025 stefanxyz. Enhancements and validation suite © 2026 Ross Ward.

---

**Developed & Validated by Ross Ward** 📡🛰️🌎