burnrate 0.1.8 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # BURNRATE
 
-**A logistics war MMO for Claude Code.**
+**A logistics war game for AI coding agents.**
 
 *The front doesn't feed itself.*
 
@@ -8,18 +8,19 @@
 
 Hold territory by keeping it supplied. Every zone burns Supply Units each tick. When the supply stops, the zone falls. The best generals still lose if they can't feed the front.
 
-- **MCP-native**: Play entirely through Claude Code's MCP integration
+- **Any AI agent**: Claude Code, Cursor, Codex, Windsurf, Cline, or any tool with HTTP
+- **MCP support**: First-class MCP integration for Claude Code and Cursor
 - **Multiplayer**: Compete and collaborate on shared servers
-- **AI-collaborative**: Claude is your operations advisor
-- **Operator advantage**: No grinding, no twitch—just better systems
+- **AI-collaborative**: Your AI agent is your operations advisor
+- **Operator advantage**: No grinding, no twitch — just better systems
 
 ## The Metagame
 
-What if using Claude well *was* the actual game?
+What if using your AI coding agent well *was* the actual game?
 
-BURNRATE is designed for automation. The MCP tools are your interface, but the real game is building Claude agents that optimize extraction, find efficient routes, spot market arbitrage, and coordinate faction logistics.
+BURNRATE is designed for automation. The REST API (or MCP tools) is your interface, but the real game is building agents that optimize extraction, find efficient routes, spot market arbitrage, and coordinate faction logistics.
 
-The players who learn to work WITH Claude—analyzing intel, optimizing routes, building automation—win. Skills transfer directly to real work.
+The players who learn to work with their AI — analyzing intel, optimizing routes, building automation — win. Skills transfer directly to real work.
 
 **Play between tasks.** Check supply lines between deploys. Run convoys during CI builds. Strategy in the margins.
 
@@ -29,37 +30,61 @@ The players who learn to work WITH Claude—analyzing intel, optimizing routes,
 
 ```
 ┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌──────────┐
-│ Claude Code │────▶│ MCP Server  │────▶│  Game API   │────▶│  Turso   │
-│  (Player)   │◀────│  (Local)    │◀────│  (Hosted)   │◀────│ Database │
+│  AI Agent   │────▶│ MCP Server  │────▶│  Game API   │────▶│  Turso   │
+│  (Player)   │◀────│  (optional) │◀────│  (Hosted)   │◀────│ Database │
 └─────────────┘     └─────────────┘     └─────────────┘     └──────────┘
+                          OR
+                    Direct HTTP ──────▶
 ```
 
-- **Claude Code** - Your terminal and AI advisor
-- **MCP Server** - Runs locally, provides tools/resources/prompts
-- **Game API** - Hosted server running the game simulation
+- **AI Agent** - Claude Code, Cursor, Codex, Windsurf, or any HTTP client
+- **MCP Server** - Optional local bridge (Claude Code + Cursor get 79 tools/resources/prompts)
+- **Game API** - Hosted REST server with [interactive docs](https://burnrate-api-server-production.up.railway.app/docs) and [OpenAPI spec](https://burnrate-api-server-production.up.railway.app/openapi.json)
 - **Turso** - Distributed SQLite database for persistence
 
 ## Quick Start
 
-**Create a directory, run setup, start playing.**
+### Claude Code (MCP)
 
 ```bash
 mkdir burnrate && cd burnrate
-npx burnrate setup
+npx burnrate setup    # select "Claude Code"
 claude
 ```
 
-The setup wizard connects to the live server, writes a `.mcp.json` config in the current directory, and verifies the connection. Then start Claude Code from that directory.
+Then tell Claude: `Use burnrate_join to create a character named "YourName"`
 
-Tell Claude:
+### Cursor (MCP)
 
+```bash
+mkdir burnrate && cd burnrate
+npx burnrate setup    # select "Cursor"
 ```
-Use burnrate_join to create a character named "YourName"
+
+Open the directory in Cursor. The MCP server starts automatically. Tell your agent to use `burnrate_join`.
+
+### Any Agent (HTTP)
+
+No setup required. Any agent that can make HTTP requests can play:
+
+```bash
+# Join the game
+curl -X POST https://burnrate-api-server-production.up.railway.app/join \
+  -H "Content-Type: application/json" \
+  -d '{"name":"YourName"}'
+
+# Use the returned API key for all requests
+curl https://burnrate-api-server-production.up.railway.app/me \
+  -H "X-API-Key: YOUR_KEY"
 ```
 
-You'll get an API key. Run `npx burnrate setup` again and paste it in, or manually add `"BURNRATE_API_KEY": "your-key"` to the env block in `.mcp.json`. Restart Claude Code and you're set.
+- **OpenAPI spec**: [/openapi.json](https://burnrate-api-server-production.up.railway.app/openapi.json) — feed this to your agent for full API discovery
+- **Interactive docs**: [/docs](https://burnrate-api-server-production.up.railway.app/docs) — browse and test endpoints in your browser
+- **API root**: `GET /` returns a quick-start guide and full endpoint listing
+
+For **OpenAI Codex** or agents with function calling, import the OpenAPI spec to auto-generate tool definitions.
 
-### Setup from Source (Alternative)
+### Setup from Source
 
 If you want to contribute or run a local server:
 
@@ -69,9 +94,9 @@ cd ~/burnrate && npm install && npm run build
 npm run setup
 ```
 
-### Manual Config (Alternative)
+### Manual MCP Config
 
-Create a `.mcp.json` file in any directory you'll run Claude Code from:
+Create a `.mcp.json` (Claude Code) or `.cursor/mcp.json` (Cursor) file:
 
 ```json
 {
@@ -97,7 +122,7 @@ Use burnrate_view to see the world map
 Use burnrate_routes to see where I can travel
 ```
 
-New players start with a 5-step tutorial that teaches core mechanics. Use `burnrate_tutorial` to see your progress, or ask Claude to use the `game_overview` prompt for a full walkthrough.
+New players start with a 5-step tutorial that teaches core mechanics. Use `burnrate_tutorial` (MCP) or `GET /tutorial` (HTTP) to see your progress.
 
 ## Core Concepts
 

package/dist/cli/setup.d.ts

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * BURNRATE Setup CLI
- * Configures Claude Code MCP settings for BURNRATE
+ * Configures MCP settings for Claude Code, Cursor, or shows HTTP setup
  *
  * Usage: npx burnrate setup
  */

package/dist/cli/setup.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 /**
  * BURNRATE Setup CLI
- * Configures Claude Code MCP settings for BURNRATE
+ * Configures MCP settings for Claude Code, Cursor, or shows HTTP setup
  *
  * Usage: npx burnrate setup
  */
@@ -24,9 +24,15 @@ async function main() {
     console.log(`
 ╔══════════════════════════════════════════════════════════════╗
 ║                    BURNRATE SETUP                            ║
-║              The front doesn't feed itself.                  ║
+║        A logistics war game for AI coding agents.           ║
 ╚══════════════════════════════════════════════════════════════╝
 `);
+    // 0. Detect platform
+    const platforms = ['Claude Code (MCP)', 'Cursor (MCP)', 'HTTP only (Codex, Windsurf, local models, curl)'];
+    console.log('  Which platform are you using?');
+    platforms.forEach((p, i) => console.log(`    ${i + 1}. ${p}`));
+    const platformChoice = await ask('Platform (1/2/3)', '1');
+    const platform = parseInt(platformChoice) || 1;
     // 1. Get API URL
     const apiUrl = await ask('API server URL', 'https://burnrate-api-server-production.up.railway.app');
     // 2. Get API key (optional — can join later)
@@ -71,23 +77,42 @@ async function main() {
             console.log('  ⚠ Could not validate key (server unreachable).');
         }
     }
-    // 5. Determine MCP server command
-    // Detect whether we're running from source (git clone) or npm install
+    // 5. HTTP-only path — no MCP config needed
+    if (platform === 3) {
+        console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║                     SETUP COMPLETE                           ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  BURNRATE works with any HTTP client.                        ║
+║  Base URL: ${apiUrl.padEnd(46)}║
+║  Auth:     X-API-Key header                                  ║
+║                                                              ║
+║  Quick start:                                                ║
+║    curl -X POST ${(apiUrl + '/join').padEnd(40)}║
+║      -H "Content-Type: application/json"                     ║
+║      -d '{"name":"YourName"}'                                ║
+║                                                              ║
+║  API spec:  ${(apiUrl + '/openapi.json').padEnd(44)}║
+║  Docs:      ${(apiUrl + '/docs').padEnd(44)}║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+`);
+        rl.close();
+        return;
+    }
+    // 6. Determine MCP server command (for Claude Code and Cursor)
     const distPath = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', 'mcp', 'server.js');
     const isFromSource = !distPath.includes('node_modules');
     let mcpCommand;
     let mcpArgs;
     if (isFromSource && fs.existsSync(distPath)) {
-        // Running from cloned source — use direct node path
         mcpCommand = 'node';
         mcpArgs = [distPath];
         console.log(`\nMCP server: ${distPath} (source)`);
     }
     else {
-        // Installed via npx/npm — find the global or local node + server path
-        // Using absolute paths is most reliable for MCP servers
-        const nodePath = process.execPath; // absolute path to current node binary
-        // Resolve the server.js path relative to this setup script
+        const nodePath = process.execPath;
         const serverPath = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..', 'mcp', 'server.js');
         if (fs.existsSync(serverPath)) {
             mcpCommand = nodePath;
@@ -95,35 +120,69 @@ async function main() {
             console.log(`\nMCP server: ${serverPath}`);
         }
         else {
-            // Fallback: use npx
             mcpCommand = 'npx';
             mcpArgs = ['-y', 'burnrate', 'mcp'];
             console.log(`\nMCP server: npx burnrate mcp (npm package)`);
         }
     }
-    // 6. Write .mcp.json in the current directory
-    // Claude Code reads MCP server config from .mcp.json at the project level
-    const mcpConfigPath = path.join(process.cwd(), '.mcp.json');
     const env = {
         BURNRATE_API_URL: apiUrl
     };
     if (apiKey) {
         env.BURNRATE_API_KEY = apiKey;
     }
-    const mcpConfig = {
-        mcpServers: {
-            burnrate: {
-                type: 'stdio',
-                command: mcpCommand,
-                args: mcpArgs,
-                env
-            }
-        }
+    const mcpServerConfig = {
+        type: 'stdio',
+        command: mcpCommand,
+        args: mcpArgs,
+        env
     };
-    fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + '\n');
-    console.log(`\n✓ MCP config written to ${mcpConfigPath}`);
-    // 7. Summary
-    console.log(`
+    // 7. Write config to the appropriate location
+    if (platform === 2) {
+        // Cursor: write to .cursor/mcp.json in project root
+        const cursorDir = path.join(process.cwd(), '.cursor');
+        if (!fs.existsSync(cursorDir)) {
+            fs.mkdirSync(cursorDir, { recursive: true });
+        }
+        const cursorConfigPath = path.join(cursorDir, 'mcp.json');
+        const cursorConfig = {
+            mcpServers: { burnrate: mcpServerConfig }
+        };
+        fs.writeFileSync(cursorConfigPath, JSON.stringify(cursorConfig, null, 2) + '\n');
+        console.log(`\n✓ MCP config written to ${cursorConfigPath}`);
+    }
+    else {
+        // Claude Code: write to .mcp.json in project root
+        const mcpConfigPath = path.join(process.cwd(), '.mcp.json');
+        const mcpConfig = {
+            mcpServers: { burnrate: mcpServerConfig }
+        };
+        fs.writeFileSync(mcpConfigPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+        console.log(`\n✓ MCP config written to ${mcpConfigPath}`);
+    }
+    // 8. Summary
+    if (platform === 2) {
+        console.log(`
+╔══════════════════════════════════════════════════════════════╗
+║                     SETUP COMPLETE                           ║
+╠══════════════════════════════════════════════════════════════╣
+║                                                              ║
+║  Open Cursor in this directory. The MCP server will          ║
+║  start automatically.                                        ║
+║                                                              ║
+║  Tell your agent:                                            ║
+║    "Use burnrate_join to create a character named MyName"    ║
+║                                                              ║
+║  Or if you already have an API key:                          ║
+║    "Use burnrate_status to see my inventory"                 ║
+║                                                              ║
+║  API docs:  ${(apiUrl + '/docs').padEnd(44)}║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝
+`);
+    }
+    else {
+        console.log(`
 ╔══════════════════════════════════════════════════════════════╗
 ║                     SETUP COMPLETE                           ║
 ╠══════════════════════════════════════════════════════════════╣
@@ -139,6 +198,7 @@ async function main() {
 ║                                                              ║
 ╚══════════════════════════════════════════════════════════════╝
 `);
+    }
     rl.close();
 }
 try {

package/dist/mcp/server.js

@@ -32,7 +32,10 @@ class GameAPIClient {
         });
         const data = await response.json();
         if (!response.ok) {
-            throw new Error(data.error || `API error: ${response.status}`);
+            const errMsg = typeof data.error === 'string'
+                ? data.error
+                : data.error?.message || `API error: ${response.status}`;
+            throw new Error(errMsg);
         }
         return data;
     }

package/dist/server/api.js

@@ -13,6 +13,7 @@ import { TIER_LIMITS } from '../core/types.js';
 import { GameError, AuthError, ValidationError, NotFoundError, RateLimitError, errorResponse, validateBody, ErrorCodes } from './errors.js';
 import { JoinSchema, TravelSchema, ExtractSchema, ProduceSchema, ShipSchema, MarketOrderSchema, ScanSchema, SupplySchema, FactionCreateSchema, ContractCreateSchema } from './validation.js';
 import { rateLimitMiddleware, writeRateLimitMiddleware } from './rate-limit.js';
+import { openApiSpec } from './openapi.js';
 let db;
 let engine;
 const app = new Hono();
@@ -78,28 +79,91 @@ function engineErrorToGameError(result, fallbackCode, fallbackMsg) {
 app.get('/', (c) => {
     return c.json({
         name: 'BURNRATE',
-        tagline: 'The front doesn\'t feed itself.',
+        tagline: 'A logistics war game for AI coding agents.',
         version: '1.0.0',
-        docs: 'https://github.com/burnrate-cc/burnrate#readme',
+        quickStart: {
+            step1: 'POST /join with { "name": "YourName" } to get your API key',
+            step2: 'Set X-API-Key header on all subsequent requests',
+            step3: 'GET /tutorial to begin the onboarding campaign',
+            curl: 'curl -X POST https://burnrate-api-server-production.up.railway.app/join -H "Content-Type: application/json" -d \'{"name":"YourName"}\''
+        },
+        docs: {
+            openapi: '/openapi.json',
+            interactive: '/docs',
+            github: 'https://github.com/burnrate-cc/burnrate#readme'
+        },
+        auth: 'X-API-Key header — get your key from POST /join',
+        platforms: [
+            'Claude Code (MCP or HTTP)',
+            'Cursor (MCP or HTTP)',
+            'OpenAI Codex (HTTP + function calling)',
+            'Windsurf, Cline, Aider (HTTP)',
+            'Any tool that can make HTTP requests'
+        ],
         endpoints: {
-            health: 'GET /health',
-            join: 'POST /join { "name": "YourName" }',
-            status: 'GET /me',
-            world: 'GET /world/zones',
-            routes: 'GET /routes',
-            travel: 'POST /travel { "to": "zone-id" }',
-            extract: 'POST /extract { "quantity": 10 }',
-            produce: 'POST /produce { "output": "metal", "quantity": 5 }',
-            ship: 'POST /ship { "type": "courier", "path": [...], "cargo": {...} }',
-            market: 'POST /market/order, GET /market/orders',
-            units: 'GET /units',
-            intel: 'POST /scan, GET /intel',
-            factions: 'GET /factions, POST /factions',
-            contracts: 'GET /contracts, POST /contracts',
-            tutorial: 'GET /tutorial, POST /tutorial/complete'
+            public: {
+                'GET /health': 'Server status and current tick',
+                'GET /world/status': 'World overview',
+                'POST /join': 'Create account, get API key',
+                'GET /openapi.json': 'OpenAPI 3.0 spec (machine-readable)',
+                'GET /docs': 'Interactive API explorer'
+            },
+            player: {
+                'GET /me': 'Your status, inventory, location',
+                'GET /tutorial': 'Current tutorial step',
+                'POST /tutorial/complete': 'Complete current tutorial step'
+            },
+            world: {
+                'GET /world/zones': 'All zones with resources and control',
+                'GET /world/zones/:id': 'Zone details',
+                'GET /routes': 'Available routes between zones'
+            },
+            actions: {
+                'POST /travel': 'Move to adjacent zone',
+                'POST /extract': 'Extract raw resources',
+                'POST /produce': 'Produce goods from resources',
+                'POST /ship': 'Send shipments between zones',
+                'POST /supply': 'Supply a zone you control'
+            },
+            economy: {
+                'GET /market/orders': 'View market orders',
+                'POST /market/order': 'Place buy/sell order',
+                'GET /market/prices': 'Current market prices'
+            },
+            military: {
+                'GET /units': 'Your military units',
+                'POST /scan': 'Scan for intel',
+                'GET /intel': 'Your gathered intel'
+            },
+            social: {
+                'GET /factions': 'All factions',
+                'POST /factions': 'Create a faction',
+                'GET /contracts': 'Available contracts',
+                'POST /contracts': 'Create a contract'
+            }
         }
     });
 });
+// OpenAPI spec
+app.get('/openapi.json', (c) => {
+    return c.json(openApiSpec);
+});
+// Interactive API docs (Scalar)
+app.get('/docs', (c) => {
+    const html = `<!DOCTYPE html>
+<html>
+<head>
+  <title>BURNRATE API Docs</title>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+</head>
+<body>
+  <script id="api-reference" data-url="/openapi.json"></script>
+  <script src="https://cdn.jsdelivr.net/npm/@scalar/api-reference"></script>
+</body>
+</html>`;
+    return c.html(html);
+});
 app.get('/health', async (c) => {
     try {
         const tick = await db.getCurrentTick();
@@ -147,7 +211,20 @@ app.post('/join', async (c) => {
         message: `Welcome to BURNRATE, ${name}! Save your API key - you'll need it for all requests.`,
         apiKey: player.apiKey,
         playerId: player.id,
-        location: hub.name
+        location: hub.name,
+        nextStep: 'Start the tutorial: GET /tutorial (or use burnrate_tutorial MCP tool if available)',
+        nextSteps: {
+            tutorial: 'GET /tutorial — begin the onboarding campaign to learn the basics and earn credits',
+            status: 'GET /me — check your player status, inventory, and location',
+            world: 'GET /world/zones — see the full map with resources and control status',
+            docs: '/openapi.json — machine-readable API spec for agent integration',
+            interactiveDocs: '/docs — interactive API explorer in your browser'
+        },
+        auth: {
+            header: 'X-API-Key',
+            value: player.apiKey,
+            example: `curl -H "X-API-Key: ${player.apiKey}" https://burnrate-api-server-production.up.railway.app/me`
+        }
     });
 });
 // ============================================================================