@edgegap/mcp 0.1.2 → 0.1.4

package/README.md

@@ -1,15 +1,40 @@
 # edgegap-mcp
 
-An MCP server 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.
+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.
 
 Ten tools, hand-picked. Not generated from the OpenAPI spec — see
 [Scope](#scope) for why.
 
 ## Install
 
-One line in your MCP client config. Nothing to clone, nothing to build.
+Two ways to run it. Pick based on how much you care about where your token
+goes — see [Where your token goes](#where-your-token-goes).
+
+### Remote endpoint
+
+Hosted by Edgegap as a Cloudflare Worker. Nothing to install.
+
+```json
+{
+  "mcpServers": {
+    "edgegap": {
+      "type": "http",
+      "url": "https://mcp.edgegap.dev/mcp",
+      "headers": { "Authorization": "token YOUR_API_TOKEN" }
+    }
+  }
+}
+```
+
+Also works as a custom connector in claude.ai: add
+`https://mcp.edgegap.dev/mcp` and supply the same token.
+
+### Local
+
+Runs on your own machine, spawned by your editor. One line in your MCP client
+config, nothing to clone, nothing to build.
 
 ```json
 {
@@ -25,15 +50,18 @@ One line in your MCP client 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.
 
-> **Node version:** the server itself needs Node 18+. Deploying the optional
-> Cloudflare Worker needs Node 22+, because `wrangler` requires it.
+Registered in the official MCP registry as `dev.edgegap/mcp`.
+
+> **Node version:** the local server needs Node 18+. Deploying your own copy of
+> the Cloudflare Worker needs Node 22+, because `wrangler` requires it.
+
+## Where your token goes
 
-## Your token never leaves your machine
+This differs by mode, and the difference is the reason both modes exist.
 
-There is no Edgegap-hosted component. This server runs as a process on your
-own computer, spawned by your editor. The first tool call asks you for a token,
-shows what it authorises, and requires an explicit acknowledgement before
-accepting it. Where that token then lives, exhaustively:
+**Local.** The server runs as a process on your own computer. The first tool
+call asks you for a token, shows what it authorises, and requires an explicit
+acknowledgement before accepting it. Where that token then lives, exhaustively:
 
 - one variable in that process's memory, for the life of your editor session
 
@@ -42,18 +70,24 @@ any Edgegap server — the only thing sent to Edgegap is the API call itself,
 exactly as if you had run `curl`. Closing your editor revokes this server's
 access completely.
 
+**Remote.** Your token is sent to `mcp.edgegap.dev` on every request and
+forwarded from there to the Edgegap API. It transits infrastructure Edgegap
+operates. The worker holds it for the life of the request and does not persist
+it, but that is a "we don't store it" claim rather than a "we never see it"
+claim. The two are different, and only local mode makes the second one.
+
 Generate a token at <https://app.edgegap.com/user-settings?tab=tokens>.
 
-Setting `EDGEGAP_API_TOKEN` still works and takes precedence, for CI and for
-clients that cannot show prompts. Do not pass a token as a command-line
-argument — arguments are visible to other processes via `ps`, and the server
-warns if it detects one.
+In local mode, setting `EDGEGAP_API_TOKEN` takes precedence over the prompt,
+for CI and for clients that cannot show prompts. Do not pass a token as a
+command-line argument — arguments are visible to other processes via `ps`, and
+the server warns if it detects one.
 
-**Why this is not hosted.** A hosted server would have to either store your
-token or receive it on every request. "We don't store it" and "we never see it"
-are different claims, and only a local process makes the second one. See
-`worker/DECISION.md` for the full reasoning and the conditions under which a
-hosted version becomes worth building.
+**Which to use.** Remote for a first try, a demo, or a supervised session where
+setup friction matters more than custody. Local for anything unattended,
+anything in an organization with a live game in it, and anything where you
+would rather not extend trust you don't have to. The guardrails described below
+exist only in local mode.
 
 ## Read this before connecting an agent
 
@@ -70,22 +104,28 @@ Consequences worth being deliberate about:
 - Anything the agent logs, echoes, or sends to a model provider is a place the
   token could end up. This server does not log it, but it cannot control what
   the rest of the agent does.
+- On the remote endpoint, the same unscoped token is additionally handled by
+  Edgegap's worker on every call.
 
 Recommended setup, in decreasing order of caution:
 
 | Situation | Setup |
 | --- | --- |
-| Unattended or autonomous agent | Separate non-production organization, plus `EDGEGAP_READ_ONLY=1` |
-| Supervised agent, live game in the org | `EDGEGAP_APP_ALLOWLIST` scoped to the app being worked on, plus `EDGEGAP_MAX_DURATION_MINUTES` |
-| Solo developer, no production workload | Defaults are fine; revoke the token when finished |
+| 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` |
+| Solo developer, no production workload | Either mode. Defaults are fine; revoke the token when finished |
 
-The allowlist and read-only flag are enforced in this server, which means 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.
+The allowlist and read-only flag are enforced in the local server, which means
+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.
 
 ### Environment variables
 
+These configure the local server. On the remote endpoint they are set by
+Edgegap and cannot be changed per developer — if you need any of them, run
+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. |
@@ -94,22 +134,23 @@ do not remove it.
 | `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. |
 
-## The ten tools
+## Tools
 
-Ordered along the golden path.
+Ten tools, listed in the order they fall along the golden path. The same ten in
+both modes.
 
-| # | Tool | Mutating | What it's for |
-| --- | --- | --- | --- |
-| 1 | `edgegap_list_apps` | | Orient before doing anything. Prevents duplicate applications. |
-| 2 | `edgegap_create_app` | ● | Create the container for versions. |
-| 3 | `edgegap_list_app_versions` | | Find a deployable version, or copy settings from a working one. |
-| 4 | `edgegap_create_app_version` | ● | Register a container image with CPU, memory, and ports. |
-| 5 | `edgegap_deploy` | ● | Start one instance near specified players. |
-| 6 | `edgegap_get_deployment` | | Single status read. |
-| 7 | `edgegap_wait_for_deployment` | | Poll to ready with backoff, then return the connection address. |
-| 8 | `edgegap_list_deployments` | | Find orphaned servers from earlier sessions. |
-| 9 | `edgegap_stop_deployment` | ● | Graceful SIGTERM, one deployment at a time. |
-| 10 | `edgegap_get_deployment_logs` | | Container output and crash exit code after a failure. |
+| Tool | Mutating | What it's for |
+| --- | --- | --- |
+| `edgegap_list_apps` | | Orient before doing anything. Prevents duplicate applications. |
+| `edgegap_create_app` | ● | Create the container for versions. |
+| `edgegap_list_app_versions` | | Find a deployable version, or copy settings from a working one. |
+| `edgegap_create_app_version` | ● | Register a container image with CPU, memory, and ports. |
+| `edgegap_deploy` | ● | Start one instance near specified players. |
+| `edgegap_get_deployment` | | Single status read. |
+| `edgegap_wait_for_deployment` | | Poll to ready with backoff, then return the connection address. |
+| `edgegap_list_deployments` | | Find orphaned servers from earlier sessions. |
+| `edgegap_stop_deployment` | ● | Graceful SIGTERM, one deployment at a time. |
+| `edgegap_get_deployment_logs` | | Container output and crash exit code after a failure. |
 
 ## Design decisions
 
@@ -135,6 +176,13 @@ player location are caught here rather than surfacing as an opaque 400.
 There is no bulk-stop tool, because an agent with a filter expression and a bug
 can stop a production fleet.
 
+**Both a hosted endpoint and a local package.** The hosted endpoint removes
+every step between finding this server and calling a tool, which is where most
+developers drop out. The local package is the only way to run the server
+without extending custody of an unscoped token to a third party, including us.
+Neither one dominates the other, so both ship. See `worker/DECISION.md` for the
+longer version.
+
 ## Scope
 
 Not exposed, on purpose: matchmaking, relays, private fleets, smart fleets,
@@ -147,6 +195,9 @@ would trade the conversion path for surface area.
 
 ## Known limitation: asking for the token at all
 
+This applies to local mode, where the token is collected through elicitation
+rather than read from config.
+
 The MCP specification says servers should not use elicitation to collect
 sensitive data, and an API token is sensitive. This server does it anyway,
 because requiring a token in a config file before anything works is the largest
@@ -159,9 +210,10 @@ plain-language disclosure, required acknowledgement, redaction from all output,
 and the environment variable always winning when present. Removing any of them
 breaks the trade.
 
-The real fix is on Edgegap's side: scoped, revocable, deploy-only credentials,
-issued through OAuth rather than pasted as a secret. Until those exist, the
-interactive prompt is a workaround and is labelled as one in the code.
+The real fix is on Edgegap's side and would improve both modes: scoped,
+revocable, deploy-only credentials, issued through OAuth rather than pasted as
+a secret. Until those exist, the interactive prompt is a workaround and is
+labelled as one in the code.
 
 ## Development
 

package/dist/auth.js

@@ -189,24 +189,30 @@ export class TokenProvider {
         return token;
     }
 }
-/**
- * Credential source for the hosted Worker: the token arrives on the request
- * and lives only as long as this object, which is created per request and
- * garbage collected with it. Nothing is cached across requests, deliberately.
- */
 export class StaticTokenProvider {
     token;
+    unavailableMessage;
     used = false;
-    constructor(token) {
+    /**
+     * @param token          credential for this request, if the caller found a usable one
+     * @param unavailableMessage  what to tell the agent when it calls a tool and
+     *   there is no token. The transport knows WHY the token is missing — absent
+     *   header, or a header carrying some other client's credential — and that
+     *   distinction is the whole difference between a developer who can fix their
+     *   setup and one staring at a generic 401. Defaults to the generic text.
+     */
+    constructor(token, unavailableMessage) {
         this.token = token;
+        this.unavailableMessage = unavailableMessage;
     }
     get current() {
         return this.token;
     }
     async get() {
         if (!this.token) {
-            throw new TokenUnavailableError('No Edgegap API token on this request. Send it as an Authorization ' +
-                'header on the MCP connection.');
+            throw new TokenUnavailableError(this.unavailableMessage ??
+                'No Edgegap API token on this request. Send it as an Authorization ' +
+                    'header on the MCP connection.');
         }
         return this.token;
     }

package/dist/tools.js

@@ -55,7 +55,13 @@ function guard(auth, fn) {
 function errorHint(err) {
     switch (err.status) {
         case 401:
-            return 'the token was rejected. It has been discarded; the next call will ask for a new one.';
+            // Deliberately does not promise a re-prompt: the local server asks again
+            // on the next call, the hosted relay cannot, and a hint that lies about
+            // what happens next sends the developer looking in the wrong place.
+            return ('Edgegap rejected the token. It may be expired, revoked, or from a ' +
+                'different organization. Check it at ' +
+                'https://app.edgegap.com/user-settings?tab=tokens. The token has been ' +
+                'discarded from this session.');
         case 404:
             return 'the application or version name does not exist. Call edgegap_list_apps first.';
         case 409:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@edgegap/mcp",
   "mcpName": "dev.edgegap/mcp",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Deploy game servers on Edgegap from your coding agent. Runs locally; your API token never leaves your machine.",
   "scripts": {
     "prebuild": "rm -rf dist",