@edgegap/mcp 0.1.0

package/dist/client.js

@@ -0,0 +1,115 @@
+/**
+ * Thin client over the Edgegap REST API.
+ *
+ * Deliberately not generated from the OpenAPI spec: the generated surface is
+ * ~60 operations, which is more than an agent can hold in context without
+ * picking the wrong one. This wraps only what the golden path needs.
+ */
+import { redact } from './config.js';
+export class EdgegapApiError extends Error {
+    status;
+    apiMessage;
+    details;
+    constructor(status, apiMessage, details) {
+        super(`Edgegap API ${status}: ${apiMessage}`);
+        this.status = status;
+        this.apiMessage = apiMessage;
+        this.details = details;
+        this.name = 'EdgegapApiError';
+    }
+}
+export class EdgegapClient {
+    config;
+    auth;
+    constructor(config, auth) {
+        this.config = config;
+        this.auth = auth;
+    }
+    async request(method, version, path, options = {}) {
+        const base = version === 'v2' ? this.config.baseUrlV2 : this.config.baseUrlV1;
+        const url = new URL(base + path);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined && value !== null) {
+                url.searchParams.set(key, String(value));
+            }
+        }
+        // Resolved per request rather than at construction: the developer may not
+        // have been asked for a token yet.
+        const token = await this.auth.get();
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.config.requestTimeoutMs);
+        let response;
+        try {
+            response = await fetch(url.toString(), {
+                method,
+                headers: {
+                    // Edgegap expects the literal word "token" before the value.
+                    Authorization: `token ${token}`,
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    'User-Agent': 'edgegap-mcp',
+                },
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === 'AbortError') {
+                throw new Error(`Request to ${method} ${path} timed out after ${this.config.requestTimeoutMs}ms.`);
+            }
+            throw new Error(redact(`Network error calling ${method} ${path}: ${err.message}`, token));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const raw = await response.text();
+        let parsed = undefined;
+        if (raw) {
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                parsed = { message: raw.slice(0, 500) };
+            }
+        }
+        if (!response.ok) {
+            // A rejected token is worth forgetting immediately, so the next call
+            // re-prompts instead of failing repeatedly against a revoked credential.
+            if (response.status === 401)
+                this.auth.invalidate();
+            const body = (parsed ?? {});
+            throw new EdgegapApiError(response.status, redact(body.message ?? response.statusText, token), body.details);
+        }
+        return (parsed ?? {});
+    }
+    // --- Applications and versions (v1) ------------------------------------
+    listApps(query = {}) {
+        return this.request('GET', 'v1', '/v1/apps', { query });
+    }
+    createApp(body) {
+        return this.request('POST', 'v1', '/v1/app', { body });
+    }
+    listAppVersions(appName) {
+        return this.request('GET', 'v1', `/v1/app/${encodeURIComponent(appName)}/versions`);
+    }
+    createAppVersion(appName, body) {
+        return this.request('POST', 'v1', `/v1/app/${encodeURIComponent(appName)}/version`, { body });
+    }
+    // --- Deployments --------------------------------------------------------
+    /** v2 deploy. Returns only a request_id; the deployment is still starting. */
+    deploy(body) {
+        return this.request('POST', 'v2', '/deployments', { body });
+    }
+    getDeployment(requestId) {
+        return this.request('GET', 'v1', `/v1/status/${encodeURIComponent(requestId)}`);
+    }
+    listDeployments(query = {}) {
+        return this.request('GET', 'v1', '/v1/deployments', { query });
+    }
+    stopDeployment(requestId) {
+        return this.request('DELETE', 'v1', `/v1/stop/${encodeURIComponent(requestId)}`);
+    }
+    getDeploymentLogs(requestId, format = 'text') {
+        return this.request('GET', 'v1', `/v1/deployment/${encodeURIComponent(requestId)}/container-logs`, { query: { format } });
+    }
+}

package/dist/config.js

@@ -0,0 +1,63 @@
+/**
+ * Configuration and safety gates.
+ *
+ * Everything here exists to keep the blast radius of an autonomous agent small.
+ * The Edgegap API token is org-wide, so the server layers its own limits on top.
+ */
+export class ConfigError extends Error {
+}
+function parseList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function parseIntEnv(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    return Number.isFinite(n) ? n : fallback;
+}
+export function loadConfig(env = process.env) {
+    // A token in the environment is optional. When it is absent the server asks
+    // the developer for one at first use, which removes the "configure before
+    // anything works" step that loses people during onboarding.
+    const raw = env.EDGEGAP_API_TOKEN?.trim();
+    // Tokens are pasted by hand often enough that it is worth catching the
+    // common mistake of including the "token " prefix twice.
+    const envToken = raw ? raw.replace(/^token\s+/i, '') : undefined;
+    return {
+        envToken,
+        baseUrlV1: env.EDGEGAP_BASE_URL?.trim() || 'https://api.edgegap.com',
+        baseUrlV2: (env.EDGEGAP_BASE_URL?.trim() || 'https://api.edgegap.com') + '/v2',
+        readOnly: env.EDGEGAP_READ_ONLY === '1' || env.EDGEGAP_READ_ONLY === 'true',
+        appAllowlist: parseList(env.EDGEGAP_APP_ALLOWLIST),
+        maxDurationCeiling: parseIntEnv(env.EDGEGAP_MAX_DURATION_MINUTES, 60),
+        requestTimeoutMs: parseIntEnv(env.EDGEGAP_TIMEOUT_MS, 30_000),
+    };
+}
+/**
+ * Throws if the agent is reaching for an application it was not scoped to.
+ * No allowlist configured means no restriction.
+ */
+export function assertAppAllowed(config, appName) {
+    if (config.appAllowlist.length === 0)
+        return;
+    if (!config.appAllowlist.includes(appName)) {
+        throw new Error(`Application "${appName}" is not in EDGEGAP_APP_ALLOWLIST. ` +
+            `Allowed: ${config.appAllowlist.join(', ')}. ` +
+            `This server is scoped deliberately; ask the human to widen the ` +
+            `allowlist rather than trying another application name.`);
+    }
+}
+/**
+ * Strips the live token out of text before it reaches the model.
+ * Error strings from HTTP layers sometimes echo request headers back.
+ */
+export function redact(text, token) {
+    if (!token)
+        return text;
+    return text.split(token).join('<redacted-token>');
+}

package/dist/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * 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.
+ *
+ * Transport is stdio, which is what Claude Code, Cursor, Codex and VS Code use
+ * for locally configured servers.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig, ConfigError } from './config.js';
+import { EdgegapClient } from './client.js';
+import { registerTools } from './tools.js';
+import { TokenProvider, warnIfTokenInArgv } from './auth.js';
+async function main() {
+    let config;
+    try {
+        config = loadConfig();
+    }
+    catch (err) {
+        if (err instanceof ConfigError) {
+            // stderr only: stdout is the MCP protocol channel and must stay clean.
+            process.stderr.write(`[edgegap-mcp] ${err.message}\n`);
+            process.exit(1);
+        }
+        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' +
+            '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 ' +
+            'as a supervised credential: do not use it for work the developer did ' +
+            'not ask for, do not enumerate or modify unrelated applications, and do ' +
+            'not repeat operations against it to explore what is possible. If the ' +
+            'developer declines to provide a token, stop and report which operation ' +
+            'needed it — do not retry.',
+    });
+    warnIfTokenInArgv();
+    const auth = new TokenProvider(config);
+    auth.attach(server.server);
+    auth.installExitHandlers();
+    registerTools(server, new EdgegapClient(config, auth), config, auth);
+    if (!config.envToken) {
+        process.stderr.write('[edgegap-mcp] no token configured: you will be asked for one at first ' +
+            'use. It stays in memory on this machine and is never written to disk ' +
+            'or sent to Edgegap.\n');
+    }
+    if (config.readOnly) {
+        process.stderr.write('[edgegap-mcp] read-only mode: mutating tools are not registered\n');
+    }
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    process.stderr.write(`[edgegap-mcp] fatal: ${err.message}\n`);
+    process.exit(1);
+});