# mcp-exaroton

[![Docker Publish](https://github.com/ferronicardoso/mcp-exaroton/actions/workflows/docker-publish.yml/badge.svg)](https://github.com/ferronicardoso/mcp-exaroton/actions/workflows/docker-publish.yml)
[![GHCR](https://img.shields.io/badge/ghcr.io-mcp--exaroton-2496ED?logo=docker&logoColor=white)](https://github.com/ferronicardoso/mcp-exaroton/pkgs/container/mcp-exaroton)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](package.json)

MCP server for natural-language interaction with the Exaroton API, exposing account, server, file, configuration and player list management to MCP hosts (Claude Desktop, VS Code, Cursor and compatible clients).

## Features

- Account and credits lookup, plus shared credit pools
- Server listing and resolution by friendly name (dashboard alias) — no need to know the server id
- Server lifecycle control (start/stop/restart), command execution, RAM, MOTD and auto-stop timer extension
- File read/write, directory creation and structured configuration editing (e.g. `server.properties`)
- Player list management (whitelist, ops, banned players)
- Log retrieval and sharing via mclo.gs

## Available Tools

| Tool | Description |
|---|---|
| `get_account` | Account data (name, email, credits) |
| `list_credit_pools` | Lists shared credit pools |
| `get_credit_pool` | Pool details: members and servers |
| `list_servers` | Lists servers in the account |
| `get_server_status` | Status, MOTD and players of a server |
| `control_server` | Starts, stops or restarts a server (idempotent) |
| `execute_command` | Executes a command on the console |
| `get_ram` / `set_ram` | Reads/changes allocated RAM (2–16 GB) |
| `get_motd` / `set_motd` | Reads/changes the message of the day |
| `extend_stop_time` | Extends the auto-stop timer |
| `list_directory` | Lists files/directories at a path |
| `read_file` / `write_file` | Reads/writes a file's content |
| `delete_file` | Deletes a file or directory |
| `create_directory` | Creates a new directory |
| `get_config_options` / `set_config_option` | Reads/changes options in a structured configuration file |
| `list_player_lists` | Lists available player lists (whitelist, ops, etc.) |
| `get_player_list_entries` | Lists entries of a player list |
| `add_player_list_entries` / `remove_player_list_entries` | Adds/removes entries from a player list |
| `get_logs` | Retrieves the most recent server log |
| `share_logs` | Shares the log via mclo.gs |

## Requirements

- Node.js 18+
- Exaroton API token (Exaroton dashboard → Account → API Key)

## Configuration

| Variable | Required | Default | Description |
|---|---|---|---|
| `EXAROTON_API_TOKEN` | Yes | — | Exaroton API token |
| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` (default, for `npx`/Claude Desktop/VS Code) or `http` (Streamable HTTP, for Docker/remote clients) |
| `MCP_HTTP_PORT` | No | `3004` | HTTP server port (only used when `MCP_TRANSPORT=http`) |
| `MCP_HTTP_HOST` | No | `0.0.0.0` | HTTP server bind address (only used when `MCP_TRANSPORT=http`) |

**Security:** never commit your real token. `EXAROTON_API_TOKEN` should be provided via environment (env var, orchestrator secret, etc.).

## Usage

### Run directly from GitHub

```bash
npx github:ferronicardoso/mcp-exaroton
```

### Claude Desktop configuration

`%APPDATA%\\Claude\\claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "exaroton": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-exaroton"],
      "env": {
        "EXAROTON_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### VS Code MCP configuration

`.vscode/mcp.json`:

```json
{
  "servers": {
    "exaroton": {
      "command": "npx",
      "args": ["github:ferronicardoso/mcp-exaroton"],
      "env": {
        "EXAROTON_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

### Running with Docker (HTTP transport)

The published image runs in Streamable HTTP mode by default, for use as a remote MCP endpoint:

```bash
docker run -d --name mcp-exaroton \
  -p 3004:3004 \
  -e EXAROTON_API_TOKEN=your-token-here \
  ghcr.io/ferronicardoso/mcp-exaroton:latest
```

The MCP endpoint is available at `http://localhost:3004/mcp`.

## Local Development

```bash
git clone https://github.com/ferronicardoso/mcp-exaroton
cd mcp-exaroton
npm install
npm run build
```

Start the compiled server:

```bash
EXAROTON_API_TOKEN=your-token-here npm start
```

### Tests

```bash
npm test
```

Tests mock `fetch` for the REST client and use an in-memory transport from `@modelcontextprotocol/sdk` for the tool handlers — no real calls are made to the Exaroton API.

## Build and Commit Workflow

This repository intentionally versions `dist/`, to support usage via `npx github:user/repo`.

The project uses a Husky `pre-commit` hook to:
1. compile TypeScript (`npm run build`)
2. add the generated artifacts (`git add dist`)

Manual fallback:

```bash
npm run build
git add dist
```

## Security Notes

- Never commit your real token or `.env` files.
- Use `EXAROTON_API_TOKEN` via environment for continuous use.
- Real-time streaming (live console, TPS, memory usage via WebSocket) is not exposed in this version — tools operate on a request/response basis.