# Bitburner MCP Server

MCP server and local HTTP API bridge for the Bitburner Remote API.

## Features

- WebSocket listener for Bitburner Remote API
- REST API for remote method calls and file helpers
- MCP stdio server with one tool per remote API method
- MCP Streamable HTTP server
- Local dashboard for connection status and events

## Requirements

- Node.js 20+
- Bitburner Remote API configured to connect to this server:
  - Host: `localhost`
  - Port: `12525`
  - TLS/WSS: disabled (`ws`)

## Install

```bash
npm install
npm run build
```

## Run

```bash
# REST API + dashboard
npm run start:api

# MCP stdio transport
npm run start:mcp

# MCP Streamable HTTP transport
npm run start:mcp:http
```

## MCP Client Setup

For stdio clients, point your MCP config to:

```text
dist/mcp-server.js
```

For Streamable HTTP clients, use:

```text
http://localhost:3003/mcp
```

## Environment Variables

- `BB_WS_HOST` default: `0.0.0.0`
- `BB_WS_PORT` default: `12525`
- `BB_API_PORT` default: `3001`
- `BB_API_BASE_URL` default: `http://localhost:3001`
- `BB_DASHBOARD_HOST` default: `127.0.0.1`
- `BB_DASHBOARD_PORT` default: `3002`
- `BB_MCP_HTTP_HOST` default: `127.0.0.1`
- `BB_MCP_HTTP_PORT` default: `3003`
- `BB_MCP_HTTP_PATH` default: `/mcp`
- `BB_API_TOKEN` optional bearer token for API and MCP endpoints

## API Overview

Health and dashboard:

- `GET /health`
- `GET /dashboard`
- `GET /api/dashboard/events`
- `GET /api/dashboard/status`
- `GET /api/docs/remote-api`
- `GET /api/docs/globals`

Remote API proxy endpoints:

- `POST /api/remote/pushFile`
- `POST /api/remote/getFile`
- `POST /api/remote/deleteFile`
- `POST /api/remote/getFileNames`
- `POST /api/remote/getAllFiles`
- `POST /api/remote/calculateRam`
- `POST /api/remote/getDefinitionFile`
- `POST /api/remote/getSaveFile`
- `POST /api/remote/getAllServers`

Convenience file endpoints:

- `GET /api/file/:filename?server=home`
- `POST /api/file/write`
- `POST /api/file/append`
- `POST /api/file/upload`
- `DELETE /api/file/:filename?server=home`
- `GET /api/files?server=home&path=.`

## Docs

- `docs/ARCHITECTURE.md`
- `docs/MCP_AI_GUIDE.md`
- `docs/REMOTE_API_TOOLS.md`