mirror of
https://github.com/bdnugget/rs-sdk.git
synced 2026-11-07 09:07:30 +00:00
max bittkerandClaude Opus 5.5
df3d8888ae
execute_code - Cancellation now reaches inside the SDK via an AsyncLocalStorage scope: timeout, MCP cancel, or a newer call rejects pending waits and blocks further action packets, including those inside walkTo(). - One execution per bot: a new call supersedes the running one and starts once it has unwound; disconnect_bot does the same. - Cancelled user code parks on bot/sdk calls instead of throwing, so a catch-all loop can't spin and starve the server. - Console capture is routed per execution, so concurrent bots no longer clobber each other's output; leftover logs go to stderr. - Stale world state warns and still runs, so a stale client can be diagnosed. - Credentials are redacted from logs, results and launch messages. SDK - bot.mineRock() waits for ore plus Mining XP; interactLoc docs note that success can mean the action only started. - walkTo() takes options.timeout (default 120s), refuses stale state, and reports the real last position. - runScript uses the same cancellation scope for timeouts and signals. Docs trimmed of duplicated or stale execute_code text. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
157 lines
3.9 KiB
Markdown
157 lines
3.9 KiB
Markdown
# RS-Agent MCP Server
|
|
|
|
MCP (Model Context Protocol) server for controlling RS-Agent bots. Supports multiple simultaneous bot connections.
|
|
|
|
## Quick Start (Claude Code)
|
|
|
|
Claude Code auto-discovers the MCP server via `.mcp.json`. Just:
|
|
|
|
1. **Install dependencies (from the project root):**
|
|
|
|
```bash
|
|
bun install
|
|
```
|
|
|
|
2. **Create a bot (if you haven't):**
|
|
|
|
```bash
|
|
bun bots/create-bot.ts mybot
|
|
```
|
|
|
|
3. **Open the project in Claude Code** — it will prompt you to approve the MCP server.
|
|
|
|
4. **Control your bot:**
|
|
```
|
|
Execute code on "mybot" to chop some trees
|
|
```
|
|
|
|
## Tools
|
|
|
|
### `get_market`
|
|
|
|
Public Grand Exchange research without a bot connection or controller takeover:
|
|
Use `get_market` with `operation: "status"` to check whether the server enables GE.
|
|
Disabled servers return a clear `ge_unavailable` error for market data reads.
|
|
|
|
```json
|
|
{
|
|
"origin": "http://localhost:8888",
|
|
"operation": "items",
|
|
"query": "logs",
|
|
"sort": "buyValue",
|
|
"days": 7
|
|
}
|
|
```
|
|
|
|
Operations: `status`, `items`, `item` (requires `item_id`), `history` (requires `item_id`).
|
|
Use the game HTTP origin, not the gateway port. This tool cannot trade or read
|
|
private offers. See [the GE guide](../sdk/MARKET.md) for typed options and trading
|
|
through `bot.openGE()`, `bot.placeGEOffer()`, `bot.cancelGEOffer()` and collection.
|
|
|
|
### `execute_code`
|
|
|
|
Execute TypeScript on a bot. The first call auto-connects with the credentials
|
|
in `bots/{name}/bot.env` and opens a browser game client; leave it running if
|
|
you switch to a standalone script.
|
|
|
|
Each bot runs one execution at a time: a new call cancels the one still running.
|
|
Timeout, MCP cancellation, or a newer call stops further SDK waits and action
|
|
packets, including those inside `walkTo()`; packets already sent may still take
|
|
effect. Different bots run concurrently. If world state is stale, the code
|
|
still runs and the output starts with a warning.
|
|
|
|
```typescript
|
|
execute_code({
|
|
bot_name: "mybot",
|
|
code: `
|
|
const tree = sdk.findNearbyLoc(/^tree$/i);
|
|
if (tree) {
|
|
const result = await bot.chopTree(tree);
|
|
console.log('Chopped:', result);
|
|
}
|
|
return sdk.getInventory();
|
|
`,
|
|
});
|
|
```
|
|
|
|
### `list_bots`
|
|
|
|
List all connected bots and their status.
|
|
|
|
```typescript
|
|
list_bots();
|
|
// Returns: { bots: [{ name: "mybot", username: "mybot", connected: true }], count: 1 }
|
|
```
|
|
|
|
### `disconnect_bot`
|
|
|
|
Disconnect a connected bot.
|
|
|
|
```typescript
|
|
disconnect_bot({ name: "mybot" });
|
|
```
|
|
|
|
## Resources
|
|
|
|
The server exposes API documentation as a resource:
|
|
|
|
- `file://../sdk/MARKET.md` — GE workflow, market data, receipts and recovery.
|
|
- `file://../sdk/API.md` — Auto-generated reference for `bot.*` (high-level actions) and `sdk.*` (low-level SDK)
|
|
|
|
## Manual Setup (without auto-discovery)
|
|
|
|
If you're not using Claude Code's auto-discovery, add to your MCP client config:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"rs-agent": {
|
|
"command": "bun",
|
|
"args": ["run", "/path/to/rs-sdk/mcp/server.ts"]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
Or run directly for testing:
|
|
|
|
```bash
|
|
bun run mcp/server.ts
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
mcp/
|
|
├── server.ts # MCP server (stdio transport) and tool definitions
|
|
├── execute-code.ts # execute_code: per-bot cancellation, console capture, output
|
|
├── console-capture.ts # Bounded, per-execution console buffer
|
|
├── market-tools.ts # get_market
|
|
└── api/
|
|
└── index.ts # BotManager - manages multiple connections
|
|
```
|
|
|
|
The `@modelcontextprotocol/sdk` dependency lives in the root `package.json`.
|
|
|
|
## Troubleshooting
|
|
|
|
**"Bot not found"**
|
|
|
|
- Create the bot first: `bun bots/create-bot.ts {name}`
|
|
- Check `bots/{name}/bot.env` exists
|
|
|
|
**"Connection failed"**
|
|
|
|
- Check the gateway is running
|
|
- Verify credentials in `bots/{name}/bot.env`
|
|
|
|
**MCP server not appearing in Claude Code**
|
|
|
|
- Run `bun install` at the project root
|
|
- Check `.mcp.json` exists at project root
|
|
- Restart Claude Code
|
|
|
|
## API Reference
|
|
|
|
See [`sdk/API.md`](../sdk/API.md) for the full auto-generated API documentation.
|