@edgegap/mcp 0.1.4 → 0.2.0

package/README.md

@@ -1,11 +1,13 @@
 # edgegap-mcp
 
 An MCP server for Edgegap that lets a coding agent take a developer from "I
-have a game server container" to "players are connected to it" without the
-developer reading the API reference.
+have a headless server build" to "players are connected to it" without the
+developer reading the API reference: checking the Dockerfile and ports, pushing
+to Edgegap's registry, deploying, and — for peer-to-peer games — opening a relay
+instead.
 
-Ten tools, hand-picked. Not generated from the OpenAPI spec — see
-[Scope](#scope) for why.
+Eighteen tools, hand-picked. Not generated from the OpenAPI spec — see
+[Design decisions](#design-decisions) for why.
 
 ## Install
 
@@ -48,7 +50,7 @@ config, nothing to clone, nothing to build.
 ```
 
 Works in Claude Code, Cursor, Codex, and VS Code. Pin a version in production
-(`@edgegap/mcp@0.1.0`) rather than floating on latest.
+(`@edgegap/mcp@0.1.5`) rather than floating on latest.
 
 Registered in the official MCP registry as `dev.edgegap/mcp`.
 
@@ -112,7 +114,7 @@ Recommended setup, in decreasing order of caution:
 | Situation | Setup |
 | --- | --- |
 | Unattended or autonomous agent | Local mode. Separate non-production organization, plus `EDGEGAP_READ_ONLY=1` |
-| Supervised agent, live game in the org | Local mode. `EDGEGAP_APP_ALLOWLIST` scoped to the app being worked on, plus `EDGEGAP_MAX_DURATION_MINUTES` |
+| Supervised agent, live game in the org | Local mode. `EDGEGAP_APP_ALLOWLIST` scoped to the app being worked on, plus `EDGEGAP_MAX_DURATION_MINUTES`. Read [Scope of the allowlist](#scope-of-the-allowlist) first — deployments that are already running are not covered |
 | Solo developer, no production workload | Either mode. Defaults are fine; revoke the token when finished |
 
 The allowlist and read-only flag are enforced in the local server, which means
@@ -120,6 +122,33 @@ they protect against an agent that makes a mistake, not against one that has
 been compromised into calling the API directly. They narrow the blast radius;
 they do not remove it.
 
+### Scope of the allowlist
+
+`EDGEGAP_APP_ALLOWLIST` is enforced by the five tools that take an application
+name: `edgegap_create_app`, `edgegap_list_app_versions`,
+`edgegap_create_app_version`, `edgegap_deploy`, and
+`edgegap_build_matchmaker_config`.
+
+Relay sessions and the container registry belong to the organization, not to an
+application, so the relay and registry tools are not covered by it either.
+
+It is **not** enforced by the five tools keyed on `request_id`:
+`edgegap_get_deployment`, `edgegap_wait_for_deployment`,
+`edgegap_list_deployments`, `edgegap_stop_deployment`, and
+`edgegap_get_deployment_logs`. An agent running with an allowlist set can list
+every deployment in the organization and then inspect, read the logs of, or stop
+any of them — including deployments belonging to applications outside the list.
+
+So the allowlist scopes what an agent can **create and deploy into**, not what it
+can **touch once running**. That is narrower than earlier versions of this
+document implied.
+
+For a stronger guarantee today, use `EDGEGAP_READ_ONLY=1`, which never registers
+the mutating tools at all, or point the agent at a separate non-production
+organization. Both are unaffected by this gap.
+
+Reported by Syed Anas Mohiuddin, September 2026.
+
 ### Environment variables
 
 These configure the local server. On the remote endpoint they are set by
@@ -129,15 +158,26 @@ locally.
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `EDGEGAP_API_TOKEN` | *(prompted)* | API token. Optional — omit it and the developer is asked at first use. The `token ` prefix is added for you. |
-| `EDGEGAP_READ_ONLY` | `0` | Set to `1` and the five mutating tools are never registered. The agent cannot see them, so it cannot be talked into calling them. |
-| `EDGEGAP_APP_ALLOWLIST` | *(empty)* | Comma-separated application names. When set, every tool refuses to touch anything else. |
+| `EDGEGAP_READ_ONLY` | `0` | Set to `1` and the eight mutating tools (●, below) are never registered. The agent cannot see them, so it cannot be talked into calling them. |
+| `EDGEGAP_APP_ALLOWLIST` | *(empty)* | Comma-separated application names. When set, the five application-keyed tools refuse to touch anything else. Does **not** scope the five `request_id`-keyed tools — see [Scope of the allowlist](#scope-of-the-allowlist). |
 | `EDGEGAP_MAX_DURATION_MINUTES` | `60` | Ceiling on `max_duration` the agent may set on a version. Caps runaway cost from an unattended agent. |
 | `EDGEGAP_TIMEOUT_MS` | `30000` | Per-request HTTP timeout. |
 
 ## Tools
 
-Ten tools, listed in the order they fall along the golden path. The same ten in
-both modes.
+Eighteen tools, grouped by where they fall on the path. The same set in both
+modes; `EDGEGAP_READ_ONLY=1` hides the ● ones.
+
+**Before the first deploy** — getting a headless build into a correct image and
+into a registry, which is where agent-driven onboarding actually stalls.
+
+| Tool | Mutating | What it's for |
+| --- | --- | --- |
+| `edgegap_validate_server_config` | | Static check of a Dockerfile, ports, resources and tag against Edgegap's requirements: linux/amd64, Unreal not running as root, Unity `-batchmode -nographics`, loopback binds, EXPOSE vs. version ports, protocol vs. netcode transport, `latest` tags. Returns Edgegap's reference Unity/Unreal Dockerfile when there is none yet or it fails. No API call. |
+| `edgegap_get_registry_credentials` | ● | Push credentials for the org's private `registry.edgegap.com` project, plus the exact login/build/push commands and the values to pass to `edgegap_create_app_version`. Provisions the project on first use. |
+| `edgegap_list_registry_tags` | | Confirm a pushed tag landed before registering it. |
+
+**Dedicated servers** — the original golden path.
 
 | Tool | Mutating | What it's for |
 | --- | --- | --- |
@@ -152,12 +192,29 @@ both modes.
 | `edgegap_stop_deployment` | ● | Graceful SIGTERM, one deployment at a time. |
 | `edgegap_get_deployment_logs` | | Container output and crash exit code after a failure. |
 
+**Peer-to-peer relays** — for co-op and host-client games, which need no server
+image at all.
+
+| Tool | Mutating | What it's for |
+| --- | --- | --- |
+| `edgegap_create_relay_session` | ● | Open a relay session for a set of player IPs, wait until it is ready, and return the relay address, ports, and per-player authorization tokens. |
+| `edgegap_get_relay_session` | | Re-read a session. |
+| `edgegap_authorize_relay_user` | ● | Add a player who joins after the session was created. |
+| `edgegap_delete_relay_session` | ● | Close a session. |
+
+**Matchmaking**
+
+| Tool | Mutating | What it's for |
+| --- | --- | --- |
+| `edgegap_build_matchmaker_config` | | Generate a basic matchmaker configuration (teams, team size, optional latency rule and expansions) checked against the application version it deploys. Edgegap has no API for creating a matchmaker, so the developer uploads the result in the dashboard. |
+
 ## Design decisions
 
 **Curated, not generated.** The Edgegap API has roughly sixty operations.
 Auto-generating one tool per operation puts all sixty descriptions into the
-agent's context on every turn and measurably degrades tool selection. These ten
-cover the path that converts a new developer.
+agent's context on every turn and measurably degrades tool selection. These
+cover the path that converts a new developer — including the steps before the
+first deploy, which are where that path used to end.
 
 **`wait_for_deployment` is a tool, not a loop.** Left to itself an agent will
 call a status endpoint in a tight loop, burn turns, and give up early. Folding
@@ -171,6 +228,19 @@ round trip to the human.
 
 **Local validation before the wire.** The memory-to-CPU ratio and the missing
 player location are caught here rather than surfacing as an opaque 400.
+`edgegap_validate_server_config` extends this to the image itself, before a
+build and push are spent discovering a problem.
+
+**The registry token is handed to the agent; the API token never is.** The agent
+has to run `docker login`, so the registry token is returned in the tool result.
+It is scoped to the org's registry project, and the returned command reads it
+from an environment variable over `--password-stdin` so it stays off command
+lines and out of shell history. The tool is hidden in read-only mode.
+
+**The registry credentials endpoint is not in the public spec.** It is
+`GET /v1/wizard/registry-credentials`, the same call the Unity plugin makes,
+preceded by `POST /v1/wizard/init-quick-start` when the project is not yet
+provisioned.
 
 **Bulk operations are deliberately absent.** `stop` takes one `request_id`.
 There is no bulk-stop tool, because an agent with a filter expression and a bug
@@ -185,13 +255,14 @@ longer version.
 
 ## Scope
 
-Not exposed, on purpose: matchmaking, relays, private fleets, smart fleets,
-endpoint storage, ACL/whitelist entries, deployment tags, metrics, container
-registry management, DNS configuration.
+Not exposed, on purpose: private fleets, smart fleets, endpoint storage,
+ACL/whitelist entries, deployment tags, metrics, registry tag deletion, DNS
+configuration, and matchmaker lifecycle (start, stop, delete).
 
-These are real capabilities, but they belong to studios already operating on
-the platform, not to a developer deploying their first server. Adding them
-would trade the conversion path for surface area.
+These belong to studios already operating on the platform, not to a developer
+getting a first game online. Relays, registry push, and a basic matchmaker
+config were moved in scope because agents hit them before the first deploy,
+not after.
 
 ## Known limitation: asking for the token at all
 
@@ -222,9 +293,11 @@ npm run typecheck
 node smoke.mjs      # handshake, tool registration, read-only mode
 node guards.mjs     # local validation and allowlist enforcement
 node elicit.mjs     # token prompt: accept, refuse acknowledgement, decline, no support
+node newtools.mjs   # validator, registry, relay, matchmaker tools against a local mock API
 ```
 
-None of these make network calls. `elicit.mjs` asserts that the prompt states
+None of these reach Edgegap. `newtools.mjs` points `EDGEGAP_BASE_URL` at a
+mock server on localhost. `elicit.mjs` asserts that the prompt states
 the org-wide scope, that the acknowledgement is required, that the token never
 appears in tool output, and that declining produces a stop-and-report message
 rather than a retry loop.

package/dist/client.js

@@ -112,4 +112,35 @@ export class EdgegapClient {
     getDeploymentLogs(requestId, format = 'text') {
         return this.request('GET', 'v1', `/v1/deployment/${encodeURIComponent(requestId)}/container-logs`, { query: { format } });
     }
+    // --- Container registry -------------------------------------------------
+    /**
+     * Push credentials for the organization's project on registry.edgegap.com.
+     * Not in the published OpenAPI spec: this is the endpoint the Unity plugin
+     * uses, and it can fail until init-quick-start has provisioned the project.
+     */
+    getRegistryCredentials() {
+        return this.request('GET', 'v1', '/v1/wizard/registry-credentials');
+    }
+    /** Provisions the registry project if needed. Idempotent; returns 204. */
+    initQuickStart(source) {
+        return this.request('POST', 'v1', '/v1/wizard/init-quick-start', { body: { source } });
+    }
+    /** imageName is "<project>/<image>"; the slash is part of the route. */
+    listRegistryTags(imageName, query = {}) {
+        const path = imageName.split('/').map(encodeURIComponent).join('/');
+        return this.request('GET', 'v1', `/v1/container-registry/images/${path}/tags`, { query });
+    }
+    // --- Relays -------------------------------------------------------------
+    createRelaySession(body) {
+        return this.request('POST', 'v1', '/v1/relays/sessions', { body });
+    }
+    getRelaySession(sessionId) {
+        return this.request('GET', 'v1', `/v1/relays/sessions/${encodeURIComponent(sessionId)}`);
+    }
+    authorizeRelayUser(body) {
+        return this.request('POST', 'v1', '/v1/relays/sessions:authorize-user', { body });
+    }
+    deleteRelaySession(sessionId) {
+        return this.request('DELETE', 'v1', `/v1/relays/sessions/${encodeURIComponent(sessionId)}`);
+    }
 }

package/dist/index.js

@@ -2,9 +2,10 @@
 /**
  * Edgegap MCP server.
  *
- * Exposes ten curated tools covering the path from "I have a game server
- * container" to "players are connected to it", so a coding agent can take a
- * developer through it without the developer reading the API reference.
+ * Exposes curated tools covering the path from "I have a headless server
+ * build" to "players are connected to it" — Dockerfile checks, registry push,
+ * deploy, relays for peer-to-peer games, and a matchmaker config — so a coding
+ * agent can take a developer through it without reading the API reference.
  *
  * Transport is stdio, which is what Claude Code, Cursor, Codex and VS Code use
  * for locally configured servers.
@@ -28,18 +29,26 @@ async function main() {
         }
         throw err;
     }
-    const server = new McpServer({ name: 'edgegap', version: '0.1.0' }, {
-        instructions: 'Deploy and operate game servers on Edgegap.\n\n' +
-            'Golden path for a first deployment:\n' +
-            '1. edgegap_list_apps to see what already exists\n' +
-            '2. edgegap_create_app if no suitable application is there\n' +
-            '3. edgegap_create_app_version to register the container image\n' +
-            '4. edgegap_deploy to start an instance near the players\n' +
-            '5. edgegap_wait_for_deployment to get the connection address\n' +
-            '6. edgegap_stop_deployment when finished\n\n' +
-            'Deployments cost money while running. Tag test deployments and stop ' +
-            'them before ending the task. If a deployment errors, read the container ' +
-            'logs before redeploying.\n\n' +
+    const server = new McpServer({ name: 'edgegap', version: '0.2.0' }, {
+        instructions: 'Host multiplayer games on Edgegap: dedicated servers, or relays for peer-to-peer.\n\n' +
+            'Pick the path first. Peer-to-peer and host-client games (common for co-op) need no ' +
+            "server image: call edgegap_create_relay_session with the players' public IPs and " +
+            'configure the relay transport with what it returns. Dedicated-server games follow ' +
+            'the golden path below.\n\n' +
+            'Golden path for a first dedicated-server deployment:\n' +
+            '1. edgegap_validate_server_config on the Dockerfile and ports, before building\n' +
+            '2. edgegap_get_registry_credentials, then docker build --platform linux/amd64 and push\n' +
+            '3. edgegap_list_registry_tags to confirm the push landed\n' +
+            '4. edgegap_list_apps, then edgegap_create_app if no suitable application exists\n' +
+            '5. edgegap_create_app_version to register the image\n' +
+            '6. edgegap_deploy to start an instance near the players\n' +
+            '7. edgegap_wait_for_deployment to get the connection address\n' +
+            '8. edgegap_stop_deployment when finished\n' +
+            'To match players into those servers, edgegap_build_matchmaker_config produces the ' +
+            'config the developer uploads in the dashboard.\n\n' +
+            'Deployments and relay sessions cost money while running. Tag test deployments, and ' +
+            'stop deployments and delete relay sessions you created before ending the task. If a ' +
+            'deployment errors, read the container logs before redeploying.\n\n' +
             'Credentials: if no token was configured, the first tool call asks the ' +
             'developer for one. That token is org-wide and cannot be scoped by ' +
             'Edgegap, so it authorises far more than any single task needs. Treat it ' +

package/dist/matchmaker.js

@@ -0,0 +1,101 @@
+/**
+ * Builds and checks a basic Edgegap matchmaker configuration.
+ *
+ * Edgegap has no public API for creating a matchmaker: it is created in the
+ * dashboard by uploading a JSON configuration. What an agent can usefully do is
+ * produce that JSON correctly the first time, pointed at an application version
+ * that actually exists, so the developer's only step is the upload.
+ *
+ * Format reference: https://docs.edgegap.com/learn/matchmaking/matchmaker-in-depth
+ */
+/** Config schema version the docs currently publish. Overridable per call. */
+export const MATCHMAKER_CONFIG_VERSION = '3.3.2';
+export const DASHBOARD_URL = 'https://app.edgegap.com';
+const DURATION = /^\d+(ms|s|m|h)$/;
+function seconds(d) {
+    const m = d.match(/^(\d+)(ms|s|m|h)$/);
+    if (!m)
+        return NaN;
+    const n = Number(m[1]);
+    return m[2] === 'ms' ? n / 1000 : m[2] === 's' ? n : m[2] === 'm' ? n * 60 : n * 3600;
+}
+export function buildMatchmakerConfig(input) {
+    const problems = [];
+    const cautions = [];
+    if (input.min_team_size > input.max_team_size) {
+        problems.push(`min_team_size (${input.min_team_size}) is greater than max_team_size (${input.max_team_size}).`);
+    }
+    if (!/^[a-z0-9][a-z0-9-_]*$/i.test(input.profile_name)) {
+        problems.push(`profile_name "${input.profile_name}" should be letters, digits, "-" or "_". Game clients send it on every ticket.`);
+    }
+    const expiration = input.ticket_expiration ?? '5m';
+    const removal = input.ticket_removal ?? '1m';
+    for (const [field, value] of [['ticket_expiration', expiration], ['ticket_removal', removal]]) {
+        if (!DURATION.test(value))
+            problems.push(`${field} "${value}" is not a duration like "30s", "5m" or "1h".`);
+    }
+    if (seconds(expiration) < 60) {
+        cautions.push(`ticket_expiration ${expiration} is short. Tickets must outlive the queue wait plus server start-up, or players are dropped before the match is ready.`);
+    }
+    const rules = {
+        match_size: {
+            type: 'player_count',
+            attributes: {
+                team_count: input.team_count,
+                min_team_size: input.min_team_size,
+                max_team_size: input.max_team_size,
+            },
+        },
+    };
+    const useLatency = input.max_latency_ms !== undefined || input.latency_difference_ms !== undefined;
+    if (useLatency) {
+        rules.beacons = {
+            type: 'latencies',
+            attributes: {
+                difference: input.latency_difference_ms ?? 100,
+                max_latency: input.max_latency_ms ?? 200,
+            },
+        };
+    }
+    const expansions = {};
+    let lastAfter = 0;
+    for (const e of [...(input.expansions ?? [])].sort((a, b) => a.after_seconds - b.after_seconds)) {
+        const step = {};
+        if (e.min_team_size !== undefined) {
+            if (e.min_team_size > input.max_team_size) {
+                problems.push(`expansion at ${e.after_seconds}s sets min_team_size ${e.min_team_size} above max_team_size ${input.max_team_size}.`);
+            }
+            step.match_size = { min_team_size: e.min_team_size };
+        }
+        if (e.max_latency_ms !== undefined) {
+            if (!useLatency) {
+                problems.push(`expansion at ${e.after_seconds}s relaxes max_latency_ms, but no latency rule is configured. Set max_latency_ms on the profile too.`);
+            }
+            step.beacons = { max_latency: e.max_latency_ms };
+        }
+        if (Object.keys(step).length === 0)
+            continue;
+        if (e.after_seconds === lastAfter)
+            problems.push(`two expansions share after_seconds ${e.after_seconds}.`);
+        lastAfter = e.after_seconds;
+        expansions[String(e.after_seconds)] = step;
+    }
+    if (input.team_count * input.min_team_size === 1) {
+        cautions.push('A match of one player starts a server per ticket. Fine for testing, costly in production.');
+    }
+    const config = {
+        version: input.config_version ?? MATCHMAKER_CONFIG_VERSION,
+        inspect: input.inspect ?? true,
+        max_deployment_retry_count: 3,
+        profiles: {
+            [input.profile_name]: {
+                ticket_expiration_period: expiration,
+                ticket_removal_period: removal,
+                group_inactivity_removal_period: '5m',
+                application: { name: input.application, version: input.version },
+                rules: { initial: rules, expansions },
+            },
+        },
+    };
+    return { config, problems, cautions };
+}

package/dist/serverconfig.js

@@ -0,0 +1,299 @@
+/**
+ * Static checks for a game server Dockerfile and its Edgegap port config.
+ *
+ * This is the step an agent gets wrong most often and learns about latest:
+ * a Dockerfile that builds and runs locally, then fails on Edgegap because the
+ * image is arm64, the server runs as root under Unreal, the port the server
+ * listens on is not the port the version exposes, or the protocol is TCP where
+ * the transport speaks UDP. Every one of those costs a build, a push, a version
+ * and a deployment to discover. Checking the text first costs nothing.
+ *
+ * No network, no Docker daemon. The rules come from the Dockerfiles Edgegap
+ * ships in its Unity and Unreal plugins, and from the constraints the API
+ * enforces on app versions.
+ */
+export const PROTOCOLS = ['UDP', 'TCP', 'TCP/UDP', 'HTTP', 'HTTPS', 'WS', 'WSS'];
+/** Transport → protocol it needs on the wire. Keys are lowercase. */
+const NETCODE_PROTOCOL = {
+    'mirror-kcp': 'UDP',
+    kcp: 'UDP',
+    'mirror-telepathy': 'TCP',
+    telepathy: 'TCP',
+    'mirror-simpleweb': 'WS',
+    simpleweb: 'WS',
+    websocket: 'WS',
+    'fishnet-tugboat': 'UDP',
+    tugboat: 'UDP',
+    'netcode-for-gameobjects': 'UDP',
+    ngo: 'UDP',
+    'unity-transport': 'UDP',
+    utp: 'UDP',
+    'photon-fusion': 'UDP',
+    litenetlib: 'UDP',
+    enet: 'UDP',
+    'unreal-netdriver': 'UDP',
+    'godot-enet': 'UDP',
+    'godot-websocket': 'WS',
+};
+export const NETCODE_NAMES = Object.keys(NETCODE_PROTOCOL);
+/** Edgegap's own plugin Dockerfiles, lightly commented. Returned when the
+ *  agent has none yet, or has one that fails, so it starts from known-good. */
+export const REFERENCE_DOCKERFILES = {
+    unity: [
+        'FROM ubuntu:22.04',
+        '',
+        'ARG DEBIAN_FRONTEND=noninteractive',
+        '# Folder containing the Linux Dedicated Server build (ServerBuild, *_Data, UnityPlayer.so).',
+        'ARG SERVER_BUILD_PATH=Builds/EdgegapServer',
+        '',
+        'COPY ${SERVER_BUILD_PATH} /root/build/',
+        'WORKDIR /root/',
+        'RUN chmod +x /root/build/ServerBuild',
+        '',
+        'RUN apt-get update && \\',
+        '    apt-get install -y ca-certificates && \\',
+        '    apt-get clean && \\',
+        '    update-ca-certificates',
+        '',
+        '# Documentation only; the port that matters is the one on the app version.',
+        'EXPOSE 7777/udp',
+        '',
+        'CMD ["/bin/bash", "-c", "env;/root/build/ServerBuild -batchmode -nographics $UNITY_COMMANDLINE_ARGS"]',
+    ].join('\n'),
+    unreal: [
+        'FROM ubuntu:22.04',
+        '',
+        'RUN apt-get update && \\',
+        '    apt-get install -y sudo jq curl && \\',
+        '    apt-get clean && \\',
+        '    rm -rf /var/lib/{apt,dpkg,cache,log}/',
+        '',
+        '# Unreal refuses to start as root, so run as an unprivileged user.',
+        'RUN useradd -rm -d /home/ubuntu -s /bin/bash -g root -G sudo -u 1000 m -o',
+        '',
+        'WORKDIR /app',
+        '# Contents of the packaged LinuxServer folder, plus StartServer.sh.',
+        'COPY --chown=m:sudo . /app',
+        '',
+        '# Scripts written on Windows carry CRLF endings, which break the shebang.',
+        "RUN sed -i 's/\\r$//' /app/StartServer.sh && chmod +x /app/StartServer.sh",
+        '',
+        'USER m',
+        'EXPOSE 7777/udp',
+        '',
+        'CMD ./StartServer.sh',
+    ].join('\n'),
+};
+/** Joins backslash continuations and drops comments, keeping the start line. */
+function parseDockerfile(text) {
+    const out = [];
+    const lines = text.replace(/\r\n?/g, '\n').split('\n');
+    let buf = '';
+    let start = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        if (!buf && (trimmed === '' || trimmed.startsWith('#')))
+            continue;
+        if (!buf)
+            start = i + 1;
+        if (trimmed.endsWith('\\')) {
+            buf += trimmed.slice(0, -1) + ' ';
+            continue;
+        }
+        buf += trimmed;
+        const m = buf.match(/^(\w+)\s*(.*)$/s);
+        if (m)
+            out.push({ line: start, op: m[1].toUpperCase(), args: m[2].trim() });
+        buf = '';
+    }
+    return out;
+}
+function detectEngine(text) {
+    if (/-batchmode|-nographics|UNITY_|UnityPlayer|\.x86_64\b/i.test(text))
+        return 'unity';
+    if (/StartServer\.sh|UnrealServer|Binaries\/Linux|LinuxServer|Server\.sh\b/i.test(text))
+        return 'unreal';
+    if (/godot|--headless|\.pck\b/i.test(text))
+        return 'godot';
+    return 'other';
+}
+function parseExpose(args) {
+    return args
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((tok) => {
+        const [p, proto] = tok.split('/');
+        return { port: Number.parseInt(p, 10), protocol: (proto ?? 'tcp').toUpperCase() };
+    })
+        .filter((e) => Number.isFinite(e.port));
+}
+/** Does an Edgegap port protocol carry this EXPOSE protocol (tcp|udp)? */
+function carries(edgegapProtocol, exposeProtocol) {
+    const p = edgegapProtocol.toUpperCase();
+    if (p === 'TCP/UDP')
+        return true;
+    if (exposeProtocol === 'UDP')
+        return p === 'UDP';
+    return p !== 'UDP'; // TCP, HTTP, HTTPS, WS, WSS all ride on TCP
+}
+export function validateServerConfig(input) {
+    const findings = [];
+    const err = (code, message, fix, line) => findings.push({ severity: 'error', code, message, fix, line });
+    const warn = (code, message, fix, line) => findings.push({ severity: 'warning', code, message, fix, line });
+    let engine = input.engine ?? 'other';
+    const exposed = [];
+    // ------------------------------------------------------------ Dockerfile --
+    if (input.dockerfile !== undefined) {
+        const text = input.dockerfile;
+        const ins = parseDockerfile(text);
+        if (!input.engine)
+            engine = detectEngine(text);
+        const froms = ins.filter((i) => i.op === 'FROM');
+        const finalFrom = froms[froms.length - 1];
+        if (!finalFrom) {
+            err('no-from', 'The Dockerfile has no FROM instruction.', 'Start from a Linux base image, e.g. "FROM ubuntu:22.04".');
+        }
+        else {
+            const platform = finalFrom.args.match(/--platform=(\S+)/)?.[1];
+            const image = finalFrom.args.replace(/--\S+/g, '').trim().split(/\s+/)[0] ?? '';
+            if (platform && platform.toLowerCase() !== 'linux/amd64' && !platform.includes('$')) {
+                err('wrong-platform', `Final stage is pinned to ${platform}. Edgegap runs linux/amd64 only.`, 'Use "FROM --platform=linux/amd64 ..." or drop the flag and build with "docker build --platform linux/amd64".', finalFrom.line);
+            }
+            if (/(^|\/)(arm64v8|arm32v7|arm32v6)\//i.test(image) || /[-:]arm64\b/i.test(image)) {
+                err('arm-base-image', `Base image "${image}" is an ARM image. Edgegap runs linux/amd64 only.`, 'Use the multi-arch or amd64 variant of the image.', finalFrom.line);
+            }
+            if (/windows|nanoserver|servercore/i.test(image)) {
+                err('windows-base-image', `Base image "${image}" is a Windows container. Edgegap runs Linux containers.`, 'Build a Linux dedicated server and use a Linux base such as ubuntu:22.04.', finalFrom.line);
+            }
+            if (image && image !== 'scratch' && !image.includes('$') && (!/[:@]/.test(image.split('/').pop() ?? '') || image.endsWith(':latest'))) {
+                warn('unpinned-base', `Base image "${image}" is unpinned or uses "latest", so rebuilds are not reproducible.`, 'Pin a version, e.g. ubuntu:22.04.', finalFrom.line);
+            }
+        }
+        const run = [...ins].reverse().find((i) => i.op === 'CMD' || i.op === 'ENTRYPOINT');
+        if (!run) {
+            err('no-cmd', 'No CMD or ENTRYPOINT: the container will exit as soon as it starts and the deployment will error.', 'Add a CMD that launches the server binary in the foreground.');
+        }
+        const launch = ins.filter((i) => i.op === 'CMD' || i.op === 'ENTRYPOINT').map((i) => i.args).join(' ');
+        if (/\.exe\b/i.test(ins.filter((i) => ['COPY', 'ADD', 'CMD', 'ENTRYPOINT'].includes(i.op)).map((i) => i.args).join(' '))) {
+            err('windows-binary', 'The image copies or launches a .exe. Edgegap runs Linux containers, so a Windows build cannot start.', 'Build the Linux dedicated server target (Unity: Linux Dedicated Server; Unreal: LinuxServer).');
+        }
+        if (/\b(127\.0\.0\.1|localhost)\b/.test(launch)) {
+            warn('loopback-bind', 'The launch command mentions 127.0.0.1/localhost. A server bound to loopback is unreachable from outside the container.', 'Bind to 0.0.0.0 (or omit the address so the server listens on all interfaces).', run?.line);
+        }
+        for (const e of ins.filter((i) => i.op === 'EXPOSE')) {
+            for (const p of parseExpose(e.args)) {
+                exposed.push({ ...p, line: e.line });
+                if (p.port === 22) {
+                    warn('ssh-exposed', 'Port 22 (SSH) is exposed. Edgegap advises never exposing SSH in production images.', 'Remove EXPOSE 22 and the sshd start-up from the production image.', e.line);
+                }
+            }
+        }
+        const users = ins.filter((i) => i.op === 'USER');
+        const finalUser = users[users.length - 1]?.args.split(':')[0];
+        const runsAsRoot = !finalUser || finalUser === 'root' || finalUser === '0';
+        if (engine === 'unity') {
+            if (run && !/-batchmode/.test(launch)) {
+                warn('unity-no-batchmode', 'Unity server launched without -batchmode.', 'Append "-batchmode -nographics" to the server command.', run.line);
+            }
+            if (run && !/-nographics/.test(launch)) {
+                warn('unity-no-nographics', 'Unity server launched without -nographics; it may try to initialise a GPU the container does not have.', 'Append "-nographics" to the server command.', run.line);
+            }
+            if (!/chmod\s+(\+x|[0-7]*[157][0-7]{0,2})/.test(text)) {
+                warn('no-chmod', 'No "chmod +x" on the server binary. Builds copied from Windows often lose the executable bit, giving "permission denied" at start.', 'Add "RUN chmod +x /path/to/ServerBuild".');
+            }
+        }
+        if (engine === 'unreal') {
+            if (runsAsRoot) {
+                err('unreal-root', 'The container runs as root. Unreal Engine servers refuse to start as root and exit immediately.', 'Create a user (useradd ... -u 1000 m) and add "USER m" before CMD.', users[users.length - 1]?.line);
+            }
+            if (/\.sh\b/.test(launch) && !/sed\s+-i\s+['"]?s\/\\r\$\/\/|dos2unix/.test(text)) {
+                warn('crlf-script', 'The start script is not normalised to LF line endings. Scripts saved on Windows fail with "bad interpreter" or "not found".', "Add \"RUN sed -i 's/\\r$//' /app/StartServer.sh\" after the COPY.");
+            }
+        }
+        if (engine === 'godot' && run && !/--headless/.test(launch)) {
+            warn('godot-no-headless', 'Godot server launched without --headless.', 'Add "--headless" to the server command.', run.line);
+        }
+    }
+    // ----------------------------------------------------------------- Ports --
+    const ports = input.ports;
+    if (ports !== undefined) {
+        if (ports.length === 0) {
+            err('no-ports', 'No ports configured. Players cannot connect to a version with no ports.', 'Add the port the server listens on, e.g. {port: 7777, protocol: "UDP"}.');
+        }
+        const seenPorts = new Map();
+        const seenNames = new Set();
+        ports.forEach((p, idx) => {
+            const proto = p.protocol.toUpperCase();
+            if (!PROTOCOLS.includes(proto)) {
+                err('bad-protocol', `ports[${idx}].protocol "${p.protocol}" is not one Edgegap accepts.`, `Use one of: ${PROTOCOLS.join(', ')}.`);
+            }
+            if (!Number.isInteger(p.port) || p.port < 1 || p.port > 59999) {
+                err('port-range', `ports[${idx}].port ${p.port} is outside 1-59999.`, 'Use the internal port the server listens on inside the container.');
+            }
+            if (seenPorts.has(p.port)) {
+                err('duplicate-port', `Port ${p.port} is listed twice.`, 'Use one entry with protocol "TCP/UDP" if the server needs both.');
+            }
+            seenPorts.set(p.port, idx);
+            const name = p.name ?? 'gameport';
+            if (seenNames.has(name)) {
+                err('duplicate-port-name', `Port name "${name}" is used twice. Deployment ports are keyed by name, so one would hide the other.`, 'Give every port a distinct name, e.g. "gameport" and "webport".');
+            }
+            seenNames.add(name);
+        });
+        if (input.netcode) {
+            const expected = NETCODE_PROTOCOL[input.netcode.toLowerCase()];
+            if (!expected) {
+                warn('unknown-netcode', `Netcode "${input.netcode}" is not one this check knows.`, `Known values: ${NETCODE_NAMES.join(', ')}.`);
+            }
+            else if (ports.length > 0 && !ports.some((p) => {
+                const proto = p.protocol.toUpperCase();
+                return proto === expected || (proto === 'TCP/UDP' && (expected === 'UDP' || expected === 'TCP')) || (expected === 'WS' && proto === 'WSS');
+            })) {
+                err('netcode-protocol', `${input.netcode} speaks ${expected}, but no configured port uses ${expected}. Clients will time out connecting.`, `Set the game port's protocol to ${expected}.`);
+            }
+        }
+        // Cross-check EXPOSE against the version ports. EXPOSE is documentation,
+        // so a mismatch is not fatal on its own, but it is the best signal we have
+        // for "the server listens on a different port than the version exposes".
+        if (exposed.length > 0) {
+            for (const p of ports) {
+                const match = exposed.find((e) => e.port === p.port);
+                if (!match) {
+                    warn('port-not-exposed', `Port ${p.port} is configured on the version but not EXPOSEd in the Dockerfile, which suggests the server listens elsewhere.`, `Confirm the server listens on ${p.port}, and add "EXPOSE ${p.port}/${p.protocol.toUpperCase() === 'UDP' ? 'udp' : 'tcp'}".`);
+                }
+                else if (!carries(p.protocol, match.protocol)) {
+                    warn('protocol-mismatch', `Dockerfile exposes ${p.port}/${match.protocol.toLowerCase()} but the version configures it as ${p.protocol}.`, 'Make the two agree; the version setting is the one Edgegap uses.', match.line);
+                }
+            }
+            for (const e of exposed) {
+                if (e.port !== 22 && !ports.some((p) => p.port === e.port)) {
+                    warn('exposed-not-configured', `Dockerfile exposes ${e.port}/${e.protocol.toLowerCase()} but no version port maps it, so players cannot reach it.`, `Add {port: ${e.port}, protocol: "${e.protocol}"} to the version ports if clients need it.`, e.line);
+                }
+            }
+        }
+    }
+    // ------------------------------------------------------------- Resources --
+    if (input.cpu_units !== undefined && input.cpu_units < 256) {
+        err('cpu-too-low', `cpu_units ${input.cpu_units} is below the 256 minimum.`, 'Use at least 256 (1024 = 1 vCPU).');
+    }
+    if (input.memory_mb !== undefined && input.memory_mb < 256) {
+        err('memory-too-low', `memory_mb ${input.memory_mb} is below the 256 minimum.`, 'Use at least 256.');
+    }
+    if (input.cpu_units !== undefined && input.memory_mb !== undefined && input.memory_mb > input.cpu_units * 2) {
+        err('memory-ratio', `memory_mb (${input.memory_mb}) exceeds twice cpu_units (${input.cpu_units}). Edgegap rejects this.`, `Lower memory_mb to ${input.cpu_units * 2} or raise cpu_units.`);
+    }
+    // ----------------------------------------------------------------- Image --
+    if (input.docker_tag !== undefined && (input.docker_tag === '' || input.docker_tag === 'latest')) {
+        err('latest-tag', `docker_tag "${input.docker_tag || '(empty)'}" is not reproducible, and Edgegap caches images by tag, so a re-pushed "latest" can deploy a stale build.`, 'Tag every build uniquely, e.g. a build ID or timestamp.');
+    }
+    if (input.docker_repository?.includes('registry.edgegap.com') && input.docker_image && !input.docker_image.includes('/')) {
+        err('missing-project', `docker_image "${input.docker_image}" has no project prefix. Images on registry.edgegap.com live under your project.`, 'Use "<project>/<image>"; edgegap_get_registry_credentials returns the project name.');
+    }
+    if (input.docker_repository && /^https?:\/\//.test(input.docker_repository)) {
+        err('repository-scheme', `docker_repository "${input.docker_repository}" includes a URL scheme.`, 'Use the bare host, e.g. "registry.edgegap.com".');
+    }
+    const errors = findings.filter((f) => f.severity === 'error');
+    const warnings = findings.filter((f) => f.severity === 'warning');
+    return { engine, errors, warnings };
+}

package/dist/tools.js

@@ -1,5 +1,7 @@
 /**
- * The ten golden-path tools.
+ * The golden-path tools: getting a server image right and into a registry,
+ * deploying it, and the two things players need around it — a relay for
+ * peer-to-peer games and a matchmaker config for dedicated ones.
  *
  * Tool descriptions are written for a coding agent, not a human reading docs.
  * Each one says when to reach for it and what to call next, because the main
@@ -9,6 +11,8 @@ import { z } from 'zod';
 import { EdgegapApiError } from './client.js';
 import { assertAppAllowed, redact } from './config.js';
 import { TokenUnavailableError } from './auth.js';
+import { validateServerConfig, REFERENCE_DOCKERFILES, PROTOCOLS, NETCODE_NAMES, } from './serverconfig.js';
+import { buildMatchmakerConfig, DASHBOARD_URL } from './matchmaker.js';
 /** 1x1 transparent PNG. The create-app endpoint requires an image and agents
  *  have no sensible one to supply; a placeholder beats a blocked flow. */
 const PLACEHOLDER_IMAGE = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
@@ -227,7 +231,8 @@ export function registerTools(server, client, config, auth) {
         server.registerTool('edgegap_create_app_version', {
             title: 'Create an application version',
             description: 'Register a container image as a deployable version of an application. The image must ' +
-                'already be pushed to a registry that Edgegap can pull from. Resource units: 1024 cpu ' +
+                'already be pushed to a registry that Edgegap can pull from (see ' +
+                'edgegap_get_registry_credentials and edgegap_list_registry_tags). Resource units: 1024 cpu ' +
                 'units = 1 vCPU; memory_mb must be at least 256 and at most double the cpu units. ' +
                 'Set verify_image true on the first version so a bad image fails here rather than at ' +
                 'deploy time. Avoid the "latest" docker tag — use a build ID so deployments are reproducible.',
@@ -250,7 +255,7 @@ export function registerTools(server, client, config, auth) {
                     port: z.number().int().min(1).max(59999).describe('Port the server listens on.'),
                     protocol: z
                         .string()
-                        .describe('UDP, TCP, WS, or HTTP. Most game servers use UDP.'),
+                        .describe(`One of ${PROTOCOLS.join(', ')}. Most game servers use UDP.`),
                     name: z.string().optional().describe('Label, e.g. "gameport".'),
                     to_check: z
                         .boolean()
@@ -498,4 +503,377 @@ export function registerTools(server, client, config, auth) {
             storage_link: res.logs_link ?? undefined,
         });
     }));
+    // ============================================= before the first deploy ====
+    // --------------------------------------------------------------- 11 ----
+    // Pure text analysis: no token, no network, so it is always registered and
+    // never goes through guard().
+    server.registerTool('edgegap_validate_server_config', {
+        title: 'Validate a game server Dockerfile and port config',
+        description: 'Check a game server Dockerfile and the ports/resources you intend to register against ' +
+            'what Edgegap requires, BEFORE building and pushing. Catches the failures that otherwise ' +
+            'only show up after a build, push, version and deploy: ARM or Windows images (Edgegap ' +
+            'runs linux/amd64), Unreal running as root, missing Unity -batchmode -nographics, a ' +
+            'server bound to localhost, EXPOSE ports that do not match the version ports, a protocol ' +
+            'that does not match the netcode transport, the "latest" tag, and bad CPU/memory ratios. ' +
+            'Pass the Dockerfile text (read it from disk first). With no Dockerfile and an engine of ' +
+            'unity or unreal, returns Edgegap\'s reference Dockerfile to start from. Makes no API calls.',
+        inputSchema: {
+            dockerfile: z.string().optional().describe('Full text of the Dockerfile.'),
+            engine: z
+                .enum(['unity', 'unreal', 'godot', 'other'])
+                .optional()
+                .describe('Game engine. Detected from the Dockerfile when omitted.'),
+            netcode: z
+                .string()
+                .optional()
+                .describe(`Networking transport, to check the port protocol. Known: ${NETCODE_NAMES.join(', ')}.`),
+            ports: z
+                .array(z.object({
+                port: z.number().int(),
+                protocol: z.string(),
+                name: z.string().optional(),
+            }))
+                .optional()
+                .describe('Ports you plan to pass to edgegap_create_app_version.'),
+            cpu_units: z.number().int().optional(),
+            memory_mb: z.number().int().optional(),
+            docker_repository: z.string().optional(),
+            docker_image: z.string().optional(),
+            docker_tag: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, async (args) => {
+        const { engine, errors, warnings } = validateServerConfig(args);
+        const reference = REFERENCE_DOCKERFILES[engine];
+        const wantReference = reference && (args.dockerfile === undefined || errors.length > 0);
+        const verdict = errors.length > 0 ? 'fail' : warnings.length > 0 ? 'pass_with_warnings' : 'pass';
+        return ok({
+            verdict,
+            engine,
+            errors,
+            warnings,
+            checked: {
+                dockerfile: args.dockerfile !== undefined,
+                ports: args.ports !== undefined,
+                resources: args.cpu_units !== undefined || args.memory_mb !== undefined,
+                image: args.docker_tag !== undefined || args.docker_image !== undefined,
+            },
+            reference_dockerfile: wantReference ? reference : undefined,
+            next_step: verdict === 'fail'
+                ? 'Fix every error and call this again before building. Do not build or push an image that fails here.'
+                : 'Build with "docker build --platform linux/amd64 -t <image>:<unique-tag> ." and run it ' +
+                    'locally with the same port mapping to confirm it starts. Then push it; ' +
+                    'edgegap_get_registry_credentials gives you a registry and the exact commands.',
+        });
+    });
+    // --------------------------------------------------------------- 12 ----
+    // Mutating-only: it can provision the registry project, and it hands a
+    // secret to the agent. A read-only session has no business receiving one.
+    if (mutating) {
+        server.registerTool('edgegap_get_registry_credentials', {
+            title: 'Get Edgegap container registry push credentials',
+            description: 'Return the registry URL, project, username and token for this organization\'s private ' +
+                'Edgegap container registry (registry.edgegap.com), plus the exact docker login, build ' +
+                'and push commands for your image. Use this when the server image is not in a registry ' +
+                'yet — no Docker Hub account needed. Provisions the registry project on first use. The ' +
+                'token is registry-scoped (push/pull images in this project), not the org API token: ' +
+                'pass it to docker login via --password-stdin, never as a command-line argument, and do ' +
+                'not write it into files. Call edgegap_validate_server_config before building.',
+            inputSchema: {
+                image_name: z
+                    .string()
+                    .regex(/^[a-z0-9]+([._-][a-z0-9]+)*$/, 'lowercase letters, digits, ".", "_" or "-"')
+                    .optional()
+                    .describe('Image name without project or tag, e.g. "my-game-server". Used to build the commands.'),
+                tag: z
+                    .string()
+                    .optional()
+                    .describe('Unique build tag for the commands, e.g. a build ID. Never "latest".'),
+            },
+            annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        }, async ({ image_name, tag }) => guard(auth, async () => {
+            if (tag === 'latest') {
+                return fail('Do not use the "latest" tag: Edgegap caches by tag, so a re-pushed "latest" can deploy a stale build. Pass a build ID or timestamp.');
+            }
+            let creds;
+            try {
+                creds = await client.getRegistryCredentials();
+            }
+            catch (err) {
+                if (!(err instanceof EdgegapApiError) || err.status === 401)
+                    throw err;
+                // Usually means the registry project has not been provisioned for
+                // this org yet. The plugins provision it this way on every login.
+                await client.initQuickStart('mcp');
+                creds = await client.getRegistryCredentials();
+            }
+            if (!creds.project || !creds.username || !creds.token) {
+                return fail('Edgegap did not return registry credentials for this organization. The developer ' +
+                    `can request them in the dashboard (${DASHBOARD_URL}, Container Registry page), or ` +
+                    'push to any other registry Edgegap can pull from (Docker Hub, GHCR, ECR, GCR, GitLab) ' +
+                    'and pass registry_username/registry_token to edgegap_create_app_version.');
+            }
+            const host = (creds.registry_url || 'registry.edgegap.com').replace(/^https?:\/\//, '').replace(/\/$/, '');
+            const image = image_name ?? '<image-name>';
+            const buildTag = tag ?? '<unique-build-tag>';
+            const ref = `${host}/${creds.project}/${image}:${buildTag}`;
+            return ok({
+                registry_url: host,
+                project: creds.project,
+                username: creds.username,
+                token: creds.token,
+                image_ref: ref,
+                commands: {
+                    login: `printf '%s' "$EDGEGAP_REGISTRY_TOKEN" | docker login ${host} -u '${creds.username}' --password-stdin`,
+                    build: `docker build --platform linux/amd64 -t ${ref} .`,
+                    push: `docker push ${ref}`,
+                },
+                for_create_app_version: {
+                    docker_repository: host,
+                    docker_image: `${creds.project}/${image}`,
+                    docker_tag: buildTag,
+                    registry_username: creds.username,
+                    registry_token: '<the token above>',
+                },
+                next_step: 'Export the token as EDGEGAP_REGISTRY_TOKEN in the shell that runs docker login ' +
+                    '(it never needs to appear in a command line or file), then build and push. ' +
+                    `Confirm the push with edgegap_list_registry_tags (image_name "${creds.project}/${image}"), ` +
+                    'then call edgegap_create_app_version with the values in for_create_app_version.',
+            });
+        }));
+    }
+    // --------------------------------------------------------------- 13 ----
+    server.registerTool('edgegap_list_registry_tags', {
+        title: 'List image tags in the Edgegap registry',
+        description: 'List the tags pushed for one image in this organization\'s Edgegap container registry, ' +
+            'with push time and size. Call it after docker push to confirm the tag landed before ' +
+            'edgegap_create_app_version, which otherwise fails later with an image-pull error.',
+        inputSchema: {
+            image_name: z
+                .string()
+                .describe('"<project>/<image>", e.g. "my-org-cv2l3w3vy6fg/my-game-server". Project comes from edgegap_get_registry_credentials.'),
+            page: z.number().int().min(1).optional(),
+            limit: z.number().int().min(1).max(100).optional().describe('Default 20.'),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ image_name, page, limit }) => guard(auth, async () => {
+        if (!image_name.includes('/')) {
+            return fail(`image_name "${image_name}" needs the project prefix: "<project>/${image_name}".`);
+        }
+        const res = await client.listRegistryTags(image_name, { page, limit: limit ?? 20 });
+        const tags = (res.data ?? []).map((t) => ({
+            tag: t.tag,
+            pushed: t.last_push_at,
+            size_mb: t.artifact?.size_mb,
+            digest: t.artifact?.image_hash,
+        }));
+        return ok({ image_name, ...pageInfo(res.total_count, tags.length, page ?? 1), tags });
+    }));
+    // ================================================== peer-to-peer relays ====
+    // --------------------------------------------------------------- 14 ----
+    if (mutating) {
+        server.registerTool('edgegap_create_relay_session', {
+            title: 'Create a relay session for a peer-to-peer game',
+            description: 'Create an Edgegap relay session so players in a peer-to-peer or host-client game connect ' +
+                'through the nearest relay instead of needing NAT punch-through or a dedicated server. ' +
+                'Use this for co-op and P2P games; use edgegap_deploy for dedicated servers. Needs no ' +
+                'application, version or image. Pass every player\'s public IP, host first. Waits until ' +
+                'the relay is ready and returns its address plus a per-player authorization token for the ' +
+                'relay transport. Relay sessions are billed while open: delete test sessions with ' +
+                'edgegap_delete_relay_session when finished.',
+            inputSchema: {
+                user_ips: z
+                    .array(z.string().min(3))
+                    .min(1)
+                    .describe('Public IP of each player, host first. Add late joiners with edgegap_authorize_relay_user.'),
+                webhook_url: z.string().url().optional().describe('Called when the session is ready.'),
+                wait_until_ready: z.boolean().optional().describe('Poll until the relay is assigned. Default true.'),
+                timeout_seconds: z.number().int().min(5).max(120).optional().describe('Default 30.'),
+            },
+            annotations: { destructiveHint: false, idempotentHint: false, openWorldHint: true },
+        }, async ({ user_ips, webhook_url, wait_until_ready, timeout_seconds }) => guard(auth, async () => {
+            const created = await client.createRelaySession({
+                users: user_ips.map((ip) => ({ ip })),
+                ...(webhook_url ? { webhook_url } : {}),
+            });
+            if (wait_until_ready === false) {
+                return ok({
+                    ...compactRelay(created),
+                    next_step: `Call edgegap_get_relay_session with session_id ${created.session_id} until ready is true.`,
+                });
+            }
+            const budgetMs = (timeout_seconds ?? 30) * 1000;
+            const startedAt = Date.now();
+            let intervalMs = 1000;
+            let last = created;
+            while (!last.ready && !last.error && Date.now() - startedAt < budgetMs) {
+                await new Promise((r) => setTimeout(r, intervalMs));
+                intervalMs = Math.min(intervalMs * 1.5, 5000);
+                last = await client.getRelaySession(created.session_id);
+            }
+            if (last.error) {
+                return fail(`Relay session ${created.session_id} failed: ${last.error}\n\n` +
+                    'Check that every IP is a public address (not 127.x, 10.x, 192.168.x), then delete ' +
+                    'this session with edgegap_delete_relay_session and create a new one.');
+            }
+            if (!last.ready) {
+                return fail(`Relay session ${created.session_id} was not ready after ${timeout_seconds ?? 30}s ` +
+                    `(status ${last.status ?? 'unknown'}). Call edgegap_get_relay_session to check again.`);
+            }
+            return ok({ ...compactRelay(last), waited_seconds: Math.round((Date.now() - startedAt) / 1000) });
+        }));
+    }
+    // --------------------------------------------------------------- 15 ----
+    server.registerTool('edgegap_get_relay_session', {
+        title: 'Get a relay session',
+        description: 'Read one relay session: whether it is ready, the relay address and ports, and each ' +
+            'authorized player with their authorization token. edgegap_create_relay_session already ' +
+            'waits for readiness; use this to re-read a session or one created with wait_until_ready false.',
+        inputSchema: { session_id: z.string().describe('Returned by edgegap_create_relay_session.') },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ session_id }) => guard(auth, async () => ok(compactRelay(await client.getRelaySession(session_id)))));
+    if (mutating) {
+        // ------------------------------------------------------------- 16 ----
+        server.registerTool('edgegap_authorize_relay_user', {
+            title: 'Add a player to a relay session',
+            description: 'Authorize one more player (by public IP) on an existing relay session, for a player ' +
+                'joining after the session was created. Returns that player\'s authorization token.',
+            inputSchema: {
+                session_id: z.string(),
+                user_ip: z.string().min(3).describe('Public IP of the joining player.'),
+            },
+            annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: true },
+        }, async ({ session_id, user_ip }) => guard(auth, async () => {
+            const res = await client.authorizeRelayUser({ session_id, user_ip });
+            return ok({
+                session_id: res.session_id,
+                user_ip,
+                user_authorization_token: res.session_user?.authorization_token,
+                session_authorization_token: res.authorization_token,
+            });
+        }));
+        // ------------------------------------------------------------- 17 ----
+        server.registerTool('edgegap_delete_relay_session', {
+            title: 'Delete a relay session',
+            description: 'Close one relay session. Connected players lose their relay connection. Delete every ' +
+                'session you created for testing before ending your task.',
+            inputSchema: { session_id: z.string() },
+            annotations: { destructiveHint: true, idempotentHint: true, openWorldHint: true },
+        }, async ({ session_id }) => guard(auth, async () => {
+            await client.deleteRelaySession(session_id);
+            return ok({ session_id, result: 'deleted' });
+        }));
+    }
+    // ============================================================ matchmaker ====
+    // --------------------------------------------------------------- 18 ----
+    // Edgegap has no public API to create a matchmaker, so this does not create
+    // one. It produces the configuration the dashboard asks for, checked against
+    // the application version it points at.
+    server.registerTool('edgegap_build_matchmaker_config', {
+        title: 'Build a basic matchmaker configuration',
+        description: 'Generate a ready-to-upload Edgegap matchmaker JSON configuration with one profile: team ' +
+            'count and size, optional latency rule, and optional expansions that relax the rules the ' +
+            'longer a player waits. Checks the referenced application version exists and has ports. ' +
+            'Edgegap has no API for creating a matchmaker, so this tool does NOT create one: save the ' +
+            'returned config to a file (e.g. matchmaker-config.json) and have the developer upload it ' +
+            'on the Matchmaker page of the dashboard. Use it for dedicated-server games; P2P games ' +
+            'want edgegap_create_relay_session instead.',
+        inputSchema: {
+            profile_name: z.string().describe('Profile clients will queue into, e.g. "casual-2v2".'),
+            application: z.string().describe('Application the matchmaker deploys.'),
+            version: z.string().describe('Version the matchmaker deploys.'),
+            team_count: z.number().int().min(1).describe('Teams per match. 1 for free-for-all or co-op.'),
+            min_team_size: z.number().int().min(1),
+            max_team_size: z.number().int().min(1),
+            max_latency_ms: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe('Adds a latency rule: drop players above this ping to the chosen region. Needs beacon pings from the client.'),
+            latency_difference_ms: z.number().int().min(0).optional().describe('Max ping spread between matched players. Default 100.'),
+            expansions: z
+                .array(z.object({
+                after_seconds: z.number().int().min(1),
+                min_team_size: z.number().int().min(1).optional(),
+                max_latency_ms: z.number().int().min(1).optional(),
+            }))
+                .optional()
+                .describe('Rule relaxations after a player has waited this long, e.g. [{after_seconds: 30, min_team_size: 1}].'),
+            ticket_expiration: z.string().optional().describe('Default "5m".'),
+            inspect: z.boolean().optional().describe('Expose the inspection API for debugging. Default true; turn off for production.'),
+            verify_version: z.boolean().optional().describe('Look up the application version first. Default true.'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    }, async (args) => guard(auth, async () => {
+        assertAppAllowed(config, args.application);
+        const { config: mmConfig, problems, cautions } = buildMatchmakerConfig(args);
+        if (args.verify_version !== false) {
+            try {
+                const res = await client.listAppVersions(args.application);
+                const v = (res.versions ?? []).find((x) => x.name === args.version);
+                if (!v) {
+                    problems.push(`Version "${args.version}" was not found in application "${args.application}". ` +
+                        'Create it with edgegap_create_app_version, or pick one from edgegap_list_app_versions.');
+                }
+                else {
+                    if (v.is_active === false)
+                        problems.push(`Version "${args.version}" is inactive, so the matchmaker cannot deploy it.`);
+                    if (!v.ports?.length)
+                        problems.push(`Version "${args.version}" has no ports, so matched players have nothing to connect to.`);
+                }
+            }
+            catch (err) {
+                if (err instanceof EdgegapApiError && err.status === 404) {
+                    problems.push(`Application "${args.application}" does not exist. Call edgegap_list_apps.`);
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        if (problems.length > 0) {
+            return fail('The matchmaker configuration has problems; fix them before uploading:\n- ' +
+                problems.join('\n- ') +
+                `\n\nDraft config:\n${JSON.stringify(mmConfig, null, 2)}`);
+        }
+        return ok({
+            config: mmConfig,
+            cautions: cautions.length ? cautions : undefined,
+            next_steps: [
+                'Write config to matchmaker-config.json in the project.',
+                `The developer uploads it in the dashboard (${DASHBOARD_URL}, Matchmaker page, Create Matchmaker) and waits for it to show as ready. The free tier runs on a shared test cluster for up to 3 hours per restart.`,
+                'The dashboard then shows the matchmaker API URL and auth token. Game clients call POST {api_url}/tickets ' +
+                    `with header "Authorization: <auth token>" and profile "${args.profile_name}", then poll GET {api_url}/memberships/{id} until it returns the server address.`,
+                'That auth token is safe to ship in game clients: it grants no access to the Edgegap API.',
+            ],
+        });
+    }));
+}
+/** Trims a relay session down to what a game client integration needs. */
+function compactRelay(s) {
+    return {
+        session_id: s.session_id,
+        ready: s.ready ?? false,
+        status: s.status,
+        error: s.error || undefined,
+        session_authorization_token: s.authorization_token,
+        relay: s.relay
+            ? {
+                host: s.relay.host,
+                ip: s.relay.ip,
+                server_port: s.relay.ports?.server,
+                client_port: s.relay.ports?.client,
+            }
+            : undefined,
+        users: (s.session_users ?? []).map((u) => ({
+            ip: u.ip_address,
+            authorization_token: u.authorization_token,
+        })),
+        how_to_connect: s.ready
+            ? 'Configure the Edgegap relay transport with the relay address, the session authorization ' +
+                'token, and each player\'s own authorization token. The host connects on server_port; ' +
+                'every other player connects on client_port.'
+            : undefined,
+    };
 }

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@edgegap/mcp",
   "mcpName": "dev.edgegap/mcp",
-  "version": "0.1.4",
-  "description": "Deploy game servers on Edgegap from your coding agent. Runs locally; your API token never leaves your machine.",
+  "version": "0.2.0",
+  "description": "Check, push, and deploy game servers on Edgegap from your coding agent, with relays for P2P games. Runs locally; your API token never leaves your machine.",
   "scripts": {
     "prebuild": "rm -rf dist",
     "build": "tsc && chmod +x dist/index.js",
     "typecheck": "tsc --noEmit",
     "typecheck:worker": "tsc -p worker/tsconfig.json --noEmit",
-    "test": "node smoke.mjs && node guards.mjs && node elicit.mjs",
+    "test": "node smoke.mjs && node guards.mjs && node elicit.mjs && node newtools.mjs",
     "worker:dev": "wrangler dev --config worker/wrangler.jsonc --local --port 8787",
     "worker:check": "wrangler deploy --config worker/wrangler.jsonc --dry-run --outdir=.wrangler/dryrun",
     "worker:deploy": "wrangler deploy --config worker/wrangler.jsonc",