Metadata-Version: 2.5
Name: nodepal-mcp
Version: 0.3.0
Summary: MCP server that lets AI agents manage NodePal Minecraft servers through the portal API
Project-URL: Homepage, https://nodepal.net
Project-URL: Documentation, https://nodepal.net/developers
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,mcp,minecraft,model-context-protocol,nodepal
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp<3,>=2.3
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# nodepal-mcp

An [MCP](https://modelcontextprotocol.io) server that lets AI agents manage your NodePal Minecraft servers through the portal API: check the PCs hosting servers, find a modpack, check it fits, create the server, start it, add mods, and back it up.

You can connect in two ways:

1. **Remote endpoint (OAuth)** — `https://nodepal.net/mcp` for AI apps with remote connectors (no API token to paste).
2. **Local stdio (`uvx nodepal-mcp`)** — runs on your PC for desktop and terminal AI apps, using a personal API token (`NODEPAL_TOKEN`). Also supports local file uploads.

## Remote endpoint (`https://nodepal.net/mcp`)

For AI apps that connect to remote MCP servers by URL:

- **URL:** `https://nodepal.net/mcp`
- **Auth:** OAuth — sign in with your NodePal account when the AI app asks. There is no API token to copy or paste.
- **Toolsets:** by default the endpoint lists about 30 essential tools. Append `?toolsets=all` for every tool, or `?toolsets=essential,configs` to add domains (see [Toolsets](#toolsets-fewer-tools-less-context)).

The remote endpoint exposes the same tools over MCP Streamable HTTP (spec 2026-07-28), stateless, with JSON responses. It runs as its own container (`nodepal-mcp --http` or `NODEPAL_MCP_MODE=http`; Docker target `runner`; port 8080 inside the stack, reached only through the portal's nginx at `/mcp`).

- **Auth details:** `Authorization: Bearer` on every request. Missing or invalid returns `401` with `WWW-Authenticate: Bearer resource_metadata=".../.well-known/oauth-protected-resource/mcp"`. The token is checked against the backend (`GET <NODEPAL_INTERNAL_API>/api/oauth/token-info`, cached up to 30 s by token hash); an OAuth token issued for another resource is refused. Personal API tokens (`npl_`) work too.
- The tools call the backend's API with the caller's own token. That is the same system that issued the token, not a pass-through to a third party; the scopes, group limits and approvals of the token apply.
- `Origin`: absent (not a browser) is accepted; present it must be the portal's own origin, else `403`.
- `GET` and `DELETE` answer `405`; `Mcp-Session-Id` is ignored and never sent. `MCP-Protocol-Version` / `Mcp-Method` checks and the 4 MiB body limit are the SDK's. Tools that upload a local file answer that uploads only work in local mode.
- **Server environment:** `NODEPAL_URL` (public address = OAuth issuer, must equal the backend's `FRONTEND_URL`), `NODEPAL_INTERNAL_API` (default `http://backend:8000`), `NODEPAL_MCP_PORT` (default `8080`).
- The token is never logged; log lines carry a short id (the start of its SHA-256).

## Local stdio (`uvx nodepal-mcp`)

Requires Python 3.10+ or [uv](https://docs.astral.sh/uv/) (`uvx` downloads and runs `nodepal-mcp` in an isolated environment).

### Create an API token

1. Sign in at <https://nodepal.net> and open **Account > API & agents** (`/app/account/api`).
2. Create a token: give it a name, choose the scopes it needs (see [Safety](#safety)), the groups it may touch (or all of yours), an expiry (30 days by default), and the approval mode.
3. Copy the token (`npl_...`). It is shown **once**.

Configuration is by environment variables:

| Variable | Meaning |
|---|---|
| `NODEPAL_TOKEN` | Required in stdio mode. The API token. Never logged or printed by the server. |
| `NODEPAL_URL` | Optional. Default `https://nodepal.net` (use `http://127.0.0.1:3060` for a local stack). |
| `NODEPAL_MCP_TOOLSETS` | Optional. Comma-separated toolsets: default `essential` (about 30 tools); `all` for every tool; or domain names, combinable (`essential,configs`). |

### Desktop and terminal AI app configuration

Generic `mcpServers` JSON configuration for desktop and terminal AI apps:

```json
{
  "mcpServers": {
    "nodepal": {
      "command": "uvx",
      "args": ["nodepal-mcp"],
      "env": {
        "NODEPAL_TOKEN": "npl_xxx"
      }
    }
  }
}
```

If you installed the package directly with `pip install nodepal-mcp`, use `"command": "nodepal-mcp"` with no `"args"`.

### One-click desktop bundle (`.mcpb`)

The `.mcpb` desktop bundle wraps `uvx nodepal-mcp` and asks securely for your `NODEPAL_TOKEN` during setup. Using the bundle requires [`uv`](https://docs.astral.sh/uv/) to be installed on your computer so `uvx` is available on your `PATH`.

## Tools

Everything a person does with their groups in the portal has a tool, grouped by domain in `src/nodepal_mcp/tools/`: `account`, `groups`, `members`, `nodes`, `servers`, `fit`, `console`, `diagnostics`, `backups`, `worlds`, `content`, `modpacks`, `storage`, and `configs`. Names are `verb_object` (`list_servers`, `create_world_from_modpack`, `set_node_p2p`, ...). Each tool says in its description what needs a scope or an approval: `read` < `control` (power, backups, console) < `manage` (create/change) < `destructive` (deletes, restores, roles, ownership: `approval_id` flow).

**Local uploads:** `upload_modpack`, `upload_custom_content`, `import_world_archive`, `set_group_icon`, and `set_server_icon` take a **local file path** and **only work locally** in the stdio server running on your PC (they are disabled on the remote `https://nodepal.net/mcp` endpoint).

What an agent never gets: sign-in, account and API-token management, admin, node secrets and storage credentials (session only); tokens or links in answers; secret-looking values of config files (shown as `***`).

Resources are reported as `"unknown"` when a PC's daemon has not reported them; nothing is invented. `estimate_fit` compares a modpack's (estimated) needs with a node's free RAM and disk and answers `fits`, `tight`, `does_not_fit`, or `unknown`, with reasons.

### Diagnosis

- `diagnose_server`: one call with the last failed start and its suggested actions, health warnings, the jar inventory (approved on the node, on disk), conflicts, Java required vs configured, and the node/daemon state. Unknown values are `null`.
- `console_tail`: takes `level` (`all|warn|error`; a stack trace stays with its error), `since` (`start` = the output of the last start; `since_start_known: false` when the portal did not see it begin), and `grep` (literal text, up to 100 characters).
- `check_instance`: returns the "Check this instance" result your own NodePal Companion reported for a server (file names, mod ids, versions only; never folders), or says how to generate it.
- Prompts (recipes) list the tools in order and when to ask you: `diagnose_server_that_does_not_start`, `add_mods_safely`, `create_world_from_modpack_with_seed`, `move_world_to_another_node`, `recover_from_bad_backup`.

Developer setup and API reference: <https://nodepal.net/developers>.

### Toolsets (fewer tools, less context)

Listing every tool costs about 38k tokens of model context, so by default only the **essential** set (about 30 tools: `get_overview`, servers, worlds, backups, console, diagnosis, content, recommended packs) is exposed. The rest is grouped by domain; the names match the modules under `src/nodepal_mcp/tools/`: `account`, `groups`, `members`, `nodes`, `servers`, `fit`, `console`, `diagnostics`, `backups`, `worlds`, `content`, `modpacks`, `storage`, `configs`. Names can be combined: `essential,configs`, `servers,worlds`. `all` exposes every tool.

- **stdio:** `NODEPAL_MCP_TOOLSETS=all` (or `essential,configs`, `servers,console,diagnostics`) in the server's environment (unknown names are an error).
- **remote:** `https://nodepal.net/mcp?toolsets=all` (or `?toolsets=essential,configs`; unknown names return `400`).

Long-running tools (installing packs, backups, uploads) send `notifications/progress` in stdio mode when the client asks for them. The remote endpoint is stateless with JSON responses, so it has no stream for progress.

Prompts are not affected.

## Safety

- **Scopes:** `read` (all reads), `control` (start/stop/restart, backups), `manage` (create/change servers, worlds, content), `destructive` (deletes, restores). Give the agent only what it needs; a read-only token is a fine start.
- **Approval modes** for destructive actions: in **confirm** mode (default) the portal does *not* execute them; it answers "approval required" with a link. The tool tells the agent to ask you, you approve in the portal, and the agent repeats the call with the `approval_id` (works once, for exactly that request, for 15 minutes). In **free** mode they run immediately: only enable it for tokens and agents you fully trust.
- Revoke a token or disconnect an OAuth app at any time in the portal (`/app/account/api`); tokens expire on their own (max 1 year).
- The token is a secret like a password: keep it out of repositories and chats.
- Account security (password, 2FA, sessions, tokens themselves) can never be reached with a token.

## Development

The host has no Python toolchain; everything runs in Docker. From this `mcp/` folder (Git Bash):

```sh
MSYS_NO_PATHCONV=1 docker build -q --target test -t nodepal-mcp-test .
MSYS_NO_PATHCONV=1 docker run --rm -v "$(pwd -W):/app" -w /app nodepal-mcp-test sh -c "python -m pytest -q && ruff check ."
```

To build the PyPI artifacts and `.mcpb` bundle inside Docker:

```sh
sh scripts/build-bundle.sh
```

mcp-name: net.nodepal/nodepal-mcp
