Rustic Craft 2 MCP

This is a local, stdio-only MCP server for the Rustic Craft 2 staging services. It is a thin client-side proxy: every tool call is one authenticated HTTP request to an existing console, FileBrowser, admin-dashboard, or personal restart-webhook endpoint. It does not expose a listening port, mount the Minecraft host filesystem, run Docker commands, or add a server-side endpoint.

The package uses the official TypeScript @modelcontextprotocol/sdk. TypeScript keeps the distributable dependency footprint small for friends who already have Node/npm and gives the package a normal npx-style executable entrypoint.

What is exposed

The ordinary tools are available when their corresponding URL and credentials are configured:

| MCP tool | Existing request | | --- | --- | | get_status | console or admin GET /api/status | | get_stats | console or admin GET /api/stats | | get_stats_history | console or admin GET /api/stats/history?hours=N | | run_rcon_command | console POST /run, JSON { "cmd": "..." } | | list_files | FileBrowser GET /api/resources/items?path=...&source=... | | read_file | FileBrowser GET /api/resources?path=...&source=...&content=true | | write_file | FileBrowser PUT /api/resources?path=...&source=... with raw UTF-8 content | | restart_server | one GET to the configured personal RESTART_URL |

run_rcon_command sends the command to the upstream unchanged. The existing 256-character cap and rate limiter remain authoritative; HTTP 400/429 responses are returned as MCP tool errors and are never retried around.

When RUSTIC_ADMIN_USER and RUSTIC_ADMIN_PASS are both supplied together with RUSTIC_ADMIN_URL, three additional tools are registered:

| MCP tool | Existing request | | --- | --- | | list_friends | admin GET /api/friends | | get_email_log | admin GET /api/email-log | | get_audit_log | admin GET /api/audit-log |

These tools are not registered at all for a friend-only configuration. Invite, resend, and revoke endpoints are deliberately not exposed.

Friend setup

Install Node 18 or newer, activate the existing WireGuard tunnel, and keep the credential values private. Copy the values from the personal .env file Vlad gave you; do not use another person's credentials.

For a checkout of this repository:

npm install
npm run build

Then configure your MCP client. Claude Desktop and Claude Code use the same shape; the exact config file location depends on the client and operating system:

{
  "mcpServers": {
    "rustic-craft-2": {
      "command": "node",
      "args": ["/absolute/path/to/rustic-craft-2-mcp/dist/index.js"],
      "env": {
        "RUSTIC_CONSOLE_URL": "https://rustic-test-console.dwurdy.com",
        "RUSTIC_CONSOLE_USER": "your-personal-username",
        "RUSTIC_CONSOLE_PASS": "your-personal-password",
        "RUSTIC_FILEBROWSER_URL": "https://rustic-test.dwurdy.com",
        "RUSTIC_RESTART_URL": "https://rustic-test-restart.dwurdy.com/hooks/restart-mc?token=your-personal-token",
        "RUSTIC_ALLOW_INSECURE_TLS": "true"
      }
    }
  }
}

RUSTIC_FILEBROWSER_USER and RUSTIC_FILEBROWSER_PASS are optional. When omitted, FileBrowser uses the console credential pair because the staging console intentionally accepts each friend's FileBrowser identity. Set the FileBrowser pair explicitly when they differ.

The staging FileBrowser uses a self-signed certificate. Set RUSTIC_ALLOW_INSECURE_TLS=true only when that is the certificate you expect on the private tunnel; otherwise leave it unset so normal TLS verification stays enabled. The option only affects this local process's outbound HTTPS client.

The RESTART_URL may also be supplied as RUSTIC_RESTART_URL (preferred) or RESTART_URL. Treat it like a password: anyone who has it can trigger the existing webhook. The server checks both the HTTP status and the webhook body, because the current webhook responds HTTP 200 even when its token rule did not match.

The package is published to npm as a scoped package. The equivalent client command, which needs no local clone or manual build at all, is:

{
  "command": "npx",
  "args": ["--yes", "@durdeuvlad/rustic-craft-2-mcp"]
}

Vlad/admin setup

Use Vlad's own existing dashboard credentials, never a friend's credentials:

{
  "env": {
    "RUSTIC_ADMIN_URL": "https://rustic-admin.dwurdy.com",
    "RUSTIC_ADMIN_USER": "your-own-admin-username",
    "RUSTIC_ADMIN_PASS": "your-own-admin-password",
    "RUSTIC_CONSOLE_URL": "https://rustic-test-console.dwurdy.com",
    "RUSTIC_CONSOLE_USER": "your-own-console-username",
    "RUSTIC_CONSOLE_PASS": "your-own-console-password",
    "RUSTIC_FILEBROWSER_URL": "https://rustic-test.dwurdy.com",
    "RUSTIC_FILEBROWSER_USER": "your-own-filebrowser-username",
    "RUSTIC_FILEBROWSER_PASS": "your-own-filebrowser-password",
    "RUSTIC_RESTART_URL": "your-own-personal-restart-url"
  }
}

Admin credentials are only sent to RUSTIC_ADMIN_URL. They are not implicitly used for console or FileBrowser calls; configure those services with the corresponding existing identity. The admin-only tools appear only when the admin URL and complete admin credential pair are present.

Authentication and errors

For the console, the proxy first tries the existing POST /api/login JSON credential exchange and stores the returned session cookie. For FileBrowser it first tries its existing POST /api/auth/login?username=... flow with the URL-encoded X-Password header and stores the returned session cookie. If a service is an older deployment without that login route, the proxy falls back to HTTP Basic Auth with the same supplied credentials. A stale session may be replaced by that same Basic-auth request once; 429 responses are never retried.

Non-2xx upstream responses become MCP tool errors containing the real method, HTTP status, and response body. Network failures are also reported as tool errors. Credentials and restart-token query values are never included in error messages.

Development and verification

npm test
npm run verify:roundtrip

npm test runs the build and unit tests. verify:roundtrip starts a local instance of the current console app.py with test credentials and a fake RCON socket, connects to the compiled server through the official SDK client, and exercises the console, FileBrowser-contract, webhook, and admin tools. It also checks friend-only tool registration, wrong-credential errors, webhook token failure detection, the 256-character command error, and the real console rate limit response. It uses temporary test data only. Running this verification requires Flask for the imported console app; use a temporary venv if the host does not already provide it, for example:

python3 -m venv /tmp/rustic-craft-2-mcp-test-venv
/tmp/rustic-craft-2-mcp-test-venv/bin/pip install -r test/requirements.txt
TEST_PYTHON=/tmp/rustic-craft-2-mcp-test-venv/bin/python npm run verify:roundtrip

Scope boundary

No server-side surface was added. In particular, this project does not add /api/status, /api/login, /api/audit-log, FileBrowser routes, restart webhook behavior, a shared credential, or a new privilege tier. The proxy will surface an upstream 404 if a deployment does not yet have one of the requested existing routes. Updating a live stack or adding a missing endpoint requires a separate explicit decision.