rs-sdk/mcp

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):

   bun install
   

2. Create a bot (if you haven't):

   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.

{
  "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 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.

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.

list_bots();
// Returns: { bots: [{ name: "mybot", username: "mybot", connected: true }], count: 1 }

disconnect_bot

Disconnect a connected bot.

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:

{
  "mcpServers": {
    "rs-agent": {
      "command": "bun",
      "args": ["run", "/path/to/rs-sdk/mcp/server.ts"]
    }
  }
}

Or run directly for testing:

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 for the full auto-generated API documentation.