@edgegap/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,178 @@
+# 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.
+
+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.
+
+```json
+{
+  "mcpServers": {
+    "edgegap": {
+      "command": "npx",
+      "args": ["-y", "@edgegap/mcp"]
+    }
+  }
+}
+```
+
+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.
+
+## Your token never leaves your machine
+
+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:
+
+- one variable in that process's memory, for the life of your editor session
+
+That is the whole list. Not on disk. Not in a config file. Not in logs. Not on
+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.
+
+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.
+
+**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.
+
+## Read this before connecting an agent
+
+**The Edgegap API token cannot be scoped.** One token authorises every
+application, every version, every running deployment, and your usage across the
+whole organization. There is no deploy-only token and no per-application token.
+
+Consequences worth being deliberate about:
+
+- An agent holding this token can stop production deployments, not just the
+  test ones it created.
+- Prompt injection reaching the agent — from a repo file, an issue, a fetched
+  page — reaches the token too.
+- 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.
+
+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 |
+
+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.
+
+### Environment variables
+
+| 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_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
+
+Ordered along the golden path.
+
+| # | 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. |
+
+## 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.
+
+**`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
+the polling and backoff into one call removes the most common failure in
+agent-driven deploys.
+
+**Errors are written for self-correction.** A 424 comes back saying the image
+could not be pulled and which fields to check. A 422 says to try different
+coordinates or lower the resource request. The agent can act on these without a
+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.
+
+**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
+can stop a production fleet.
+
+## Scope
+
+Not exposed, on purpose: matchmaking, relays, private fleets, smart fleets,
+endpoint storage, ACL/whitelist entries, deployment tags, metrics, container
+registry management, DNS configuration.
+
+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.
+
+## Known limitation: asking for the token at all
+
+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
+drop in the onboarding funnel, and the whole point of the server is to remove
+setup friction.
+
+That is a deliberate trade rather than a pattern to copy. What makes it
+defensible is the set of mitigations in `src/auth.ts` — memory-only storage,
+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.
+
+## Development
+
+```bash
+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
+```
+
+None of these make network calls. `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/auth.js

@@ -0,0 +1,228 @@
+/**
+ * Token acquisition.
+ *
+ * The developer is asked for their token at first use rather than having to
+ * paste it into a client config file before anything works.
+ *
+ * WHERE THE TOKEN LIVES, EXHAUSTIVELY:
+ *
+ *   - one variable in this process's memory, for the life of this process
+ *
+ * That is the complete list. It is never written to disk, never sent to any
+ * Edgegap-operated service, never logged, never included in a tool result, and
+ * never persisted across restarts. The process runs on the developer's own
+ * machine, spawned by their editor, and dies with it. Closing the editor is a
+ * complete revocation of this server's access.
+ *
+ * This is the reason the server is distributed as a local stdio process rather
+ * than hosted. A hosted version would put customer credentials in transit
+ * through Edgegap infrastructure on every call, which is a different security
+ * claim no matter how carefully the hosting is written.
+ *
+ * IMPORTANT — read before extending this file.
+ *
+ * The MCP specification says servers should not use elicitation to collect
+ * sensitive data, and an API token is sensitive. This implementation exists
+ * because the setup friction of a config-file token is the single largest drop
+ * in the onboarding funnel, but it is a deliberate trade, not a default to copy.
+ * The mitigations below are what make the trade defensible, and removing any of
+ * them breaks it:
+ *
+ *   - the environment variable is always preferred when present
+ *   - the token is held in memory only, for one process lifetime
+ *   - the elicitation states the token's blast radius in plain language
+ *   - the developer must tick an acknowledgement before the token is accepted
+ *   - the token is stripped from every error string before it reaches the model
+ *
+ * The real fix is scoped, revocable, deploy-only credentials issued by Edgegap.
+ * Until those exist, this file is a workaround and should be labelled as one.
+ */
+export class TokenUnavailableError extends Error {
+}
+/** Shown to the developer at the moment they are asked to hand over a token. */
+export const PRIVILEGE_WARNING = 'This token grants full access to your entire Edgegap organization: every ' +
+    'application, every version, every running deployment, and your billing-' +
+    'relevant usage. Edgegap does not currently issue scoped or deploy-only ' +
+    'tokens, so it cannot be narrowed.\n\n' +
+    'Whatever agent you are running will be able to use it for anything the API ' +
+    'allows. Only continue if you are supervising this session. For unattended ' +
+    'or autonomous agents, use a token from a separate non-production ' +
+    'organization, and set EDGEGAP_READ_ONLY=1 and EDGEGAP_APP_ALLOWLIST to ' +
+    'limit what the agent can reach.';
+/**
+ * Warns if a token was passed as a command-line argument. Process arguments
+ * are visible to every other process on the machine via `ps`, and get captured
+ * by shell history and crash reporters. Config env vars do not have this
+ * problem, and the interactive prompt has it least of all.
+ */
+export function warnIfTokenInArgv(argv = process.argv) {
+    const looksLikeToken = argv.some((a) => /^--?token[=\s]/i.test(a) || /^[0-9a-f]{8}-[0-9a-f]{4}-/i.test(a));
+    if (looksLikeToken) {
+        process.stderr.write('[edgegap-mcp] WARNING: a token appears to have been passed on the command ' +
+            'line. Command-line arguments are visible to other processes on this machine. ' +
+            'Remove it and let the server prompt you, or use the EDGEGAP_API_TOKEN env var.\n');
+    }
+    return looksLikeToken;
+}
+export class TokenProvider {
+    config;
+    cached;
+    inFlight;
+    server;
+    constructor(config) {
+        this.config = config;
+        this.cached = config.envToken;
+    }
+    /** Wired up after the server is constructed, since elicitation needs it. */
+    attach(server) {
+        this.server = server;
+    }
+    /** The token currently in hand, for redaction purposes. May be undefined. */
+    get current() {
+        return this.cached;
+    }
+    /** Drops the cached token so the next call re-prompts. Called on a 401. */
+    invalidate() {
+        if (this.config.envToken)
+            return; // env-supplied tokens are not re-prompted
+        this.cached = undefined;
+    }
+    /**
+     * Clears the token from memory. Wired to process exit signals so a token
+     * supplied interactively does not outlive the session even briefly in a core
+     * dump or a lingering handle.
+     */
+    scrub() {
+        this.cached = undefined;
+    }
+    /** Registers scrub() against the signals an editor uses to stop the server. */
+    installExitHandlers() {
+        const clear = () => this.scrub();
+        process.once('exit', clear);
+        process.once('SIGINT', () => {
+            clear();
+            process.exit(0);
+        });
+        process.once('SIGTERM', () => {
+            clear();
+            process.exit(0);
+        });
+    }
+    /** True the first time a token is obtained, so callers can attach a notice. */
+    firstAcquisition = true;
+    consumeFirstUseNotice() {
+        if (!this.firstAcquisition)
+            return undefined;
+        this.firstAcquisition = false;
+        return ('Token held in memory for this session only — nothing was written to ' +
+            'disk and nothing was sent to Edgegap beyond the API call itself. It ' +
+            'stops being usable when this editor session ends. Reminder: the token ' +
+            'is org-wide and cannot be scoped, so revoke it at ' +
+            'https://app.edgegap.com/user-settings?tab=tokens if it is ever exposed.');
+    }
+    async get() {
+        if (this.cached)
+            return this.cached;
+        if (this.inFlight)
+            return this.inFlight; // collapse concurrent tool calls
+        this.inFlight = this.elicit().finally(() => {
+            this.inFlight = undefined;
+        });
+        return this.inFlight;
+    }
+    async elicit() {
+        if (!this.server) {
+            throw new TokenUnavailableError('No Edgegap API token available and the server is not ready to ask for one.');
+        }
+        const capabilities = this.server.getClientCapabilities();
+        if (!capabilities?.elicitation) {
+            throw new TokenUnavailableError('No Edgegap API token available.\n\n' +
+                'This MCP client does not support interactive prompts, so the token has ' +
+                'to be supplied up front. Add it to your MCP client config:\n\n' +
+                '  "env": { "EDGEGAP_API_TOKEN": "your-token" }\n\n' +
+                'Generate a token at https://app.edgegap.com/user-settings?tab=tokens\n\n' +
+                PRIVILEGE_WARNING);
+        }
+        const result = await this.server.elicitInput({
+            message: 'Edgegap needs an API token to continue.\n\n' +
+                'Generate one at https://app.edgegap.com/user-settings?tab=tokens\n\n' +
+                PRIVILEGE_WARNING,
+            requestedSchema: {
+                type: 'object',
+                properties: {
+                    api_token: {
+                        type: 'string',
+                        title: 'Edgegap API token',
+                        description: 'Paste the token value. It is held in one variable in memory for ' +
+                            'this session, is not saved to disk, is not shown to the model, ' +
+                            'and never reaches any Edgegap-operated server.',
+                    },
+                    acknowledged: {
+                        type: 'boolean',
+                        title: 'I understand this token gives the agent full access to my Edgegap organization',
+                        description: 'Required. Edgegap cannot currently issue a narrower token, so this ' +
+                            'is the only scope available.',
+                        default: false,
+                    },
+                },
+                required: ['api_token', 'acknowledged'],
+            },
+        });
+        if (result.action !== 'accept' || !result.content) {
+            throw new TokenUnavailableError('The developer declined to provide an Edgegap API token. Do not retry ' +
+                'automatically. Stop and tell them which operation needed it, so they ' +
+                'can decide whether to continue.');
+        }
+        const acknowledged = result.content.acknowledged === true;
+        if (!acknowledged) {
+            throw new TokenUnavailableError('The token privilege acknowledgement was not accepted, so no token was ' +
+                'stored. Nothing has been sent to Edgegap. If the org-wide scope is the ' +
+                'concern, the safer setup is a token from a separate non-production ' +
+                'organization with EDGEGAP_READ_ONLY=1.');
+        }
+        const raw = String(result.content.api_token ?? '').trim();
+        const token = raw.replace(/^token\s+/i, '');
+        if (!token) {
+            throw new TokenUnavailableError('An empty token was submitted. Nothing was stored.');
+        }
+        this.cached = token;
+        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;
+    used = false;
+    constructor(token) {
+        this.token = token;
+    }
+    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.');
+        }
+        return this.token;
+    }
+    invalidate() {
+        // Nothing to forget between requests — there is no cache. The next request
+        // carries its own token, so a rejected one simply fails and the developer
+        // fixes their client config.
+        this.token = undefined;
+    }
+    consumeFirstUseNotice() {
+        if (this.used)
+            return undefined;
+        this.used = true;
+        return ('This is the hosted relay: your token is read from the request header, ' +
+            'used for this call, and discarded. It is not stored. It does, however, ' +
+            'pass through Edgegap infrastructure — the local server (npx @edgegap/mcp) ' +
+            'avoids that entirely. Your token is org-wide and cannot be scoped.');
+    }
+}