@entergram/mcp 0.1.0

package/README.md

@@ -0,0 +1,266 @@
+# Entergram MCP
+
+Official npm CLI for connecting local MCP hosts to the public Entergram MCP gateway.
+
+This package is for local MCP hosts that can only launch local commands, such as Codex, Claude Desktop, and similar tools. It handles:
+
+- OAuth login against the Entergram MCP gateway
+- secure local token storage
+- a local `stdio` bridge that proxies requests to the public Entergram MCP gateway
+- ready-to-paste host config snippets
+
+Architecture:
+
+`Local MCP host -> entergram-mcp (stdio bridge) -> Entergram MCP gateway -> Entergram Public API`
+
+## Install
+
+Global install:
+
+```bash
+npm install -g @entergram/mcp
+```
+
+Or run it on demand:
+
+```bash
+npx -y @entergram/mcp serve
+```
+
+## Quick Start
+
+Production:
+
+```bash
+entergram-mcp login
+entergram-mcp serve
+```
+
+Development:
+
+```bash
+entergram-mcp login --env dev
+entergram-mcp serve --env dev
+```
+
+If you use a non-default OAuth client, pass it explicitly during login and in your MCP host config:
+
+```bash
+entergram-mcp login --env dev --client-id entergram-ws-your-client-id
+```
+
+## Commands
+
+Show help:
+
+```bash
+entergram-mcp --help
+```
+
+Login:
+
+```bash
+entergram-mcp login
+entergram-mcp login --env dev
+entergram-mcp login --env dev --client-id entergram-ws-your-client-id
+```
+
+Start the local bridge:
+
+```bash
+entergram-mcp serve
+entergram-mcp serve --env dev
+```
+
+Show the currently authenticated actor:
+
+```bash
+entergram-mcp whoami
+```
+
+Clear the local session for the selected environment and client:
+
+```bash
+entergram-mcp logout
+entergram-mcp logout --env dev --client-id entergram-ws-your-client-id
+```
+
+Print a host config snippet:
+
+```bash
+entergram-mcp print-config
+entergram-mcp print-config --format toml
+entergram-mcp print-config --env dev --client-id entergram-ws-your-client-id --format toml
+```
+
+## Host Config
+
+### JSON hosts
+
+```bash
+entergram-mcp print-config --name entergram
+```
+
+Example output:
+
+```json
+{
+  "mcpServers": {
+    "entergram": {
+      "command": "npx",
+      "args": ["-y", "@entergram/mcp", "serve"],
+      "env": {
+        "ENTERGRAM_MCP_ENV": "production",
+        "ENTERGRAM_MCP_CLIENT_ID": "entergram-mcp-cli",
+        "ENTERGRAM_MCP_SCOPE": "workspace.read members.read accounts.read contacts.read chats.read messages.read messages.write custom_fields.read custom_fields.write tickets.read offline_access"
+      }
+    }
+  }
+}
+```
+
+### TOML hosts such as Codex
+
+```bash
+entergram-mcp print-config --format toml --name entergram-dev --env dev --client-id entergram-ws-your-client-id
+```
+
+Example output:
+
+```toml
+[mcp_servers.entergram-dev]
+command = "npx"
+args = ["-y", "@entergram/mcp", "serve"]
+
+[mcp_servers.entergram-dev.env]
+ENTERGRAM_MCP_ENV = "dev"
+ENTERGRAM_MCP_CLIENT_ID = "entergram-ws-your-client-id"
+ENTERGRAM_MCP_SCOPE = "workspace.read members.read accounts.read contacts.read chats.read messages.read messages.write custom_fields.read custom_fields.write tickets.read offline_access"
+```
+
+If your host already uses the globally installed binary, you can replace the command section with:
+
+```toml
+[mcp_servers.entergram-dev]
+command = "entergram-mcp"
+args = ["serve"]
+```
+
+## Environment Overrides
+
+You can override the built-in defaults with environment variables:
+
+- `ENTERGRAM_MCP_ENV`
+- `ENTERGRAM_MCP_GATEWAY_URL`
+- `ENTERGRAM_MCP_CLIENT_ID`
+- `ENTERGRAM_MCP_SCOPE`
+- `ENTERGRAM_MCP_CALLBACK_PORT`
+- `ENTERGRAM_MCP_CONFIG_DIR`
+
+Default local OAuth callback:
+
+`http://127.0.0.1:8787/oauth/callback`
+
+## Built-in Environments
+
+Production:
+
+- gateway: `https://mcp.entergram.com/mcp`
+- client id: `entergram-mcp-cli`
+
+Development:
+
+- gateway: `https://devmcp.entergram.com/mcp`
+- client id: `entergram-dev-mcp-client`
+
+## Local Session Storage
+
+By default, Entergram MCP stores local session files in:
+
+`~/.entergram-mcp/`
+
+Each environment and client id gets its own session file, so you can keep separate sessions for:
+
+- production vs dev
+- personal vs workspace OAuth clients
+- multiple workspace clients with different scopes
+
+## Choosing the Right OAuth Client
+
+Use a personal client when you want a seat-scoped local agent with safer read-only access.
+
+Use a workspace client when you need broader scopes such as:
+
+- `members.read`
+- `messages.write`
+- `custom_fields.read`
+- `custom_fields.write`
+
+If your consent screen does not show the scopes you expect, the OAuth client itself is missing those `allowedScopes`. Update the client in Entergram first, then run login again.
+
+## Troubleshooting
+
+### `invalid_scope`
+
+The selected OAuth client does not allow one or more requested scopes.
+
+Fix:
+
+1. update the OAuth client in Entergram so its `allowedScopes` include the requested scopes
+2. run `entergram-mcp login` again
+
+### `MCP startup failed: handshaking with MCP server failed`
+
+Your MCP host started the local bridge, but the bridge could not authenticate or connect cleanly to the remote Entergram MCP gateway.
+
+Fix:
+
+1. run login first for the same environment and client id used by the host
+2. make sure the host config includes the correct `ENTERGRAM_MCP_CLIENT_ID`
+3. restart the MCP host after login
+
+### `401` or expired token errors
+
+The local session is stale or no longer refreshable.
+
+Fix:
+
+```bash
+entergram-mcp logout --env dev --client-id entergram-ws-your-client-id
+entergram-mcp login --env dev --client-id entergram-ws-your-client-id
+```
+
+### Browser opens during MCP host startup
+
+For local MCP hosts, the intended flow is:
+
+1. run `entergram-mcp login` yourself first
+2. then let the host run `entergram-mcp serve`
+
+The bridge is designed to reuse an existing local session instead of performing interactive login during the MCP handshake.
+
+## Development
+
+Build:
+
+```bash
+npm run build
+```
+
+Typecheck:
+
+```bash
+npm run typecheck
+```
+
+CLI smoke test:
+
+```bash
+npm run smoke:cli
+```
+
+Dry-run the publish tarball:
+
+```bash
+npm run pack:dry-run
+```

package/dist/cli/args.js

@@ -0,0 +1,43 @@
+function normalizeFlagName(value) {
+    return value.trim().replace(/^-+/, "");
+}
+export function parseCliArgs(argv) {
+    const tokens = [...argv];
+    const command = tokens[0] && !tokens[0].startsWith("-") ? tokens.shift() : "serve";
+    const flags = {};
+    const positionals = [];
+    while (tokens.length > 0) {
+        const token = tokens.shift();
+        if (!token.startsWith("-")) {
+            positionals.push(token);
+            continue;
+        }
+        if (token.startsWith("--")) {
+            const [rawName, inlineValue] = token.split("=", 2);
+            const name = normalizeFlagName(rawName);
+            if (inlineValue !== undefined) {
+                flags[name] = inlineValue;
+                continue;
+            }
+            const next = tokens[0];
+            if (!next || next.startsWith("-")) {
+                flags[name] = true;
+                continue;
+            }
+            flags[name] = tokens.shift();
+            continue;
+        }
+        const name = normalizeFlagName(token);
+        const next = tokens[0];
+        if (!next || next.startsWith("-")) {
+            flags[name] = true;
+            continue;
+        }
+        flags[name] = tokens.shift();
+    }
+    return {
+        command,
+        flags,
+        positionals,
+    };
+}

package/dist/cli/bin.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+import { EntergramOAuthProvider } from "./oauth-provider.js";
+import { parseCliArgs } from "./args.js";
+import { startLocalBridge } from "./bridge.js";
+import { resolveCliRuntimeConfig } from "./config.js";
+import { ENTERGRAM_HOST_NAME } from "./constants.js";
+import { buildHostConfigSnippet, buildHostConfigToml, } from "./print-config.js";
+import { EntergramRemoteClient } from "./remote-client.js";
+import { EntergramSessionStore } from "./session-store.js";
+function printHelp() {
+    process.stdout.write(`Entergram MCP CLI
+
+Usage:
+  entergram-mcp serve
+  entergram-mcp login
+  entergram-mcp whoami
+  entergram-mcp logout
+  entergram-mcp print-config [--name entergram]
+
+Flags:
+  --env dev|production
+  --gateway-url https://custom.example.com/mcp
+  --client-id entergram-mcp-cli
+  --scope "workspace.read ..."
+  --callback-port 8787
+  --config-dir /custom/path
+  --format json|toml
+`);
+}
+function getConfigFormat(flags) {
+    const value = flags.format;
+    if (value === undefined) {
+        return "json";
+    }
+    if (typeof value !== "string") {
+        throw new Error('Expected "--format" to be either "json" or "toml".');
+    }
+    if (value === "json" || value === "toml") {
+        return value;
+    }
+    throw new Error(`Unsupported Entergram MCP config format: ${value}`);
+}
+async function withRemoteClient(flags, callback) {
+    const config = resolveCliRuntimeConfig(flags);
+    const store = new EntergramSessionStore(config.sessionFilePath);
+    const provider = new EntergramOAuthProvider(config, store);
+    const client = new EntergramRemoteClient(config, provider);
+    try {
+        return await callback(client, store);
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+async function run() {
+    const parsed = parseCliArgs(process.argv.slice(2));
+    if (parsed.flags.help === true || parsed.flags.h === true) {
+        printHelp();
+        return;
+    }
+    const config = resolveCliRuntimeConfig(parsed.flags);
+    switch (parsed.command) {
+        case "help":
+        case "--help":
+        case "-h":
+            printHelp();
+            return;
+        case "serve":
+            await startLocalBridge(config);
+            return;
+        case "login":
+            await withRemoteClient(parsed.flags, async (client) => {
+                await client.connect({ interactive: true });
+                const me = await client.callTool({
+                    arguments: {},
+                    name: "entergram_get_me",
+                });
+                process.stdout.write(`${JSON.stringify(me.structuredContent ?? me, null, 2)}\n`);
+            });
+            return;
+        case "whoami":
+            await withRemoteClient(parsed.flags, async (client) => {
+                await client.connect({ interactive: true });
+                const me = await client.callTool({
+                    arguments: {},
+                    name: "entergram_get_me",
+                });
+                process.stdout.write(`${JSON.stringify(me.structuredContent ?? me, null, 2)}\n`);
+            });
+            return;
+        case "logout":
+            await withRemoteClient(parsed.flags, async (_client, store) => {
+                await store.clear();
+                process.stdout.write(`Cleared local Entergram MCP session for ${config.environment} (${config.clientId}).\n`);
+            });
+            return;
+        case "print-config": {
+            const configuredName = typeof parsed.flags.name === "string" && parsed.flags.name.trim()
+                ? parsed.flags.name.trim()
+                : "entergram";
+            const format = getConfigFormat(parsed.flags);
+            if (format === "toml") {
+                process.stdout.write(buildHostConfigToml(config, configuredName));
+                return;
+            }
+            const snippet = buildHostConfigSnippet(config, configuredName);
+            process.stdout.write(`${JSON.stringify(snippet, null, 2)}\n`);
+            return;
+        }
+        default:
+            throw new Error(`Unknown Entergram MCP command "${parsed.command}". Run "${ENTERGRAM_HOST_NAME.toLowerCase().replaceAll(" ", "-")} help" for usage.`);
+    }
+}
+void run().catch((error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`${message}\n`);
+    process.exit(1);
+});

package/dist/cli/bridge.js

@@ -0,0 +1,81 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ListToolsRequestSchema, PromptListChangedNotificationSchema, ReadResourceRequestSchema, ResourceListChangedNotificationSchema, ResourceUpdatedNotificationSchema, SubscribeRequestSchema, ToolListChangedNotificationSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CLI_VERSION, ENTERGRAM_HOST_NAME } from "./constants.js";
+import { EntergramOAuthProvider } from "./oauth-provider.js";
+import { EntergramRemoteClient } from "./remote-client.js";
+import { EntergramSessionStore } from "./session-store.js";
+function createCapabilities(remoteClient) {
+    const capabilities = remoteClient.connectedClient.getServerCapabilities();
+    return {
+        prompts: capabilities?.prompts,
+        resources: capabilities?.resources,
+        tools: capabilities?.tools ?? {},
+    };
+}
+function buildInstructions(remoteClient) {
+    const remoteInstructions = remoteClient.connectedClient.getInstructions();
+    const bridgeInstructions = "This is the local stdio Entergram MCP bridge. It transparently proxies requests to the public Entergram MCP gateway over OAuth-protected Streamable HTTP.";
+    return remoteInstructions
+        ? `${remoteInstructions}\n\n${bridgeInstructions}`
+        : bridgeInstructions;
+}
+export async function startLocalBridge(config) {
+    const store = new EntergramSessionStore(config.sessionFilePath);
+    const authProvider = new EntergramOAuthProvider(config, store);
+    const remoteClient = new EntergramRemoteClient(config, authProvider);
+    try {
+        await remoteClient.connect({ interactive: false });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Entergram MCP bridge could not connect to the remote gateway. Run "entergram-mcp login --env ${config.environment} --client-id ${config.clientId}" first, then restart your MCP host. Original error: ${message}`);
+    }
+    const server = new Server({
+        name: ENTERGRAM_HOST_NAME,
+        version: CLI_VERSION,
+    }, {
+        capabilities: createCapabilities(remoteClient),
+        instructions: buildInstructions(remoteClient),
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async (request) => remoteClient.listTools(request.params));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => remoteClient.callTool(request.params));
+    if (remoteClient.connectedClient.getServerCapabilities()?.prompts) {
+        server.setRequestHandler(ListPromptsRequestSchema, async (request) => remoteClient.listPrompts(request.params));
+        server.setRequestHandler(GetPromptRequestSchema, async (request) => remoteClient.getPrompt(request.params));
+    }
+    if (remoteClient.connectedClient.getServerCapabilities()?.resources) {
+        server.setRequestHandler(ListResourcesRequestSchema, async (request) => remoteClient.listResources(request.params));
+        server.setRequestHandler(ListResourceTemplatesRequestSchema, async (request) => remoteClient.listResourceTemplates(request.params));
+        server.setRequestHandler(ReadResourceRequestSchema, async (request) => remoteClient.readResource(request.params));
+        if (remoteClient.connectedClient.getServerCapabilities()?.resources?.subscribe) {
+            server.setRequestHandler(SubscribeRequestSchema, async (request) => remoteClient.subscribeResource(request.params));
+            server.setRequestHandler(UnsubscribeRequestSchema, async (request) => remoteClient.unsubscribeResource(request.params));
+        }
+    }
+    remoteClient.connectedClient.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+        await server.sendToolListChanged();
+    });
+    remoteClient.connectedClient.setNotificationHandler(PromptListChangedNotificationSchema, async () => {
+        await server.sendPromptListChanged();
+    });
+    remoteClient.connectedClient.setNotificationHandler(ResourceListChangedNotificationSchema, async () => {
+        await server.sendResourceListChanged();
+    });
+    remoteClient.connectedClient.setNotificationHandler(ResourceUpdatedNotificationSchema, async (notification) => {
+        await server.sendResourceUpdated(notification.params);
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const close = async () => {
+        await remoteClient.close();
+        await server.close().catch(() => undefined);
+        await transport.close().catch(() => undefined);
+    };
+    process.once("SIGINT", () => {
+        void close().finally(() => process.exit(0));
+    });
+    process.once("SIGTERM", () => {
+        void close().finally(() => process.exit(0));
+    });
+}

package/dist/cli/browser.js

@@ -0,0 +1,20 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export async function openBrowser(url) {
+    try {
+        if (process.platform === "darwin") {
+            await execFileAsync("open", [url]);
+            return true;
+        }
+        if (process.platform === "win32") {
+            await execFileAsync("cmd", ["/c", "start", "", url]);
+            return true;
+        }
+        await execFileAsync("xdg-open", [url]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/cli/config.js

@@ -0,0 +1,77 @@
+import os from "node:os";
+import path from "node:path";
+import { DEFAULT_CALLBACK_HOST, DEFAULT_CALLBACK_PATH, DEFAULT_CALLBACK_PORT, DEFAULT_CONFIG_DIRECTORY_NAME, DEFAULT_SCOPE, } from "./constants.js";
+const ENVIRONMENT_PRESETS = {
+    dev: {
+        clientId: "entergram-dev-mcp-client",
+        displayName: "Entergram MCP Dev",
+        gatewayUrl: "https://devmcp.entergram.com/mcp",
+        oauthIssuerUrl: "https://dev.entergram.com/",
+    },
+    production: {
+        clientId: "entergram-mcp-cli",
+        displayName: "Entergram MCP",
+        gatewayUrl: "https://mcp.entergram.com/mcp",
+    },
+};
+function getStringFlag(flags, name) {
+    const value = flags[name];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function getEnvironmentName(flags) {
+    const value = getStringFlag(flags, "env") ||
+        process.env.ENTERGRAM_MCP_ENV?.trim() ||
+        "production";
+    if (value === "dev" || value === "production") {
+        return value;
+    }
+    throw new Error(`Unsupported Entergram MCP environment: ${value}`);
+}
+function parsePositiveInteger(value, fallback) {
+    if (!value) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(`Expected a positive integer, received: ${value}`);
+    }
+    return parsed;
+}
+function sanitizeFileSegment(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+export function resolveCliRuntimeConfig(flags) {
+    const environment = getEnvironmentName(flags);
+    const preset = ENVIRONMENT_PRESETS[environment];
+    const gatewayUrl = getStringFlag(flags, "gateway-url") ||
+        process.env.ENTERGRAM_MCP_GATEWAY_URL?.trim() ||
+        preset.gatewayUrl;
+    const clientId = getStringFlag(flags, "client-id") ||
+        process.env.ENTERGRAM_MCP_CLIENT_ID?.trim() ||
+        preset.clientId;
+    const oauthIssuerUrl = getStringFlag(flags, "oauth-issuer-url") ||
+        process.env.ENTERGRAM_MCP_OAUTH_ISSUER_URL?.trim() ||
+        preset.oauthIssuerUrl;
+    const scope = getStringFlag(flags, "scope") ||
+        process.env.ENTERGRAM_MCP_SCOPE?.trim() ||
+        DEFAULT_SCOPE;
+    const callbackPort = parsePositiveInteger(getStringFlag(flags, "callback-port") ||
+        process.env.ENTERGRAM_MCP_CALLBACK_PORT?.trim(), DEFAULT_CALLBACK_PORT);
+    const configDir = getStringFlag(flags, "config-dir") ||
+        process.env.ENTERGRAM_MCP_CONFIG_DIR?.trim() ||
+        path.join(os.homedir(), DEFAULT_CONFIG_DIRECTORY_NAME);
+    const gateway = new URL(gatewayUrl);
+    const callbackUrl = new URL(DEFAULT_CALLBACK_PATH, `http://${DEFAULT_CALLBACK_HOST}:${callbackPort}`).href;
+    const fileKey = sanitizeFileSegment(`${environment}-${gateway.host}-${clientId}`);
+    return {
+        callbackUrl,
+        clientId,
+        configDir,
+        displayName: preset.displayName,
+        environment,
+        gatewayUrl: gateway.href,
+        oauthIssuerUrl,
+        scope,
+        sessionFilePath: path.join(configDir, `${fileKey}.json`),
+    };
+}

package/dist/cli/constants.js

@@ -0,0 +1,7 @@
+export const CLI_VERSION = "0.1.0";
+export const DEFAULT_SCOPE = "workspace.read members.read accounts.read contacts.read chats.read messages.read messages.write custom_fields.read custom_fields.write tickets.read offline_access";
+export const DEFAULT_CALLBACK_HOST = "127.0.0.1";
+export const DEFAULT_CALLBACK_PORT = 8787;
+export const DEFAULT_CALLBACK_PATH = "/oauth/callback";
+export const DEFAULT_CONFIG_DIRECTORY_NAME = ".entergram-mcp";
+export const ENTERGRAM_HOST_NAME = "Entergram MCP";

package/dist/cli/oauth-callback.js

@@ -0,0 +1,131 @@
+import http from "node:http";
+function renderCallbackHtml(options) {
+    return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${options.title}</title>
+    <style>
+      :root {
+        color-scheme: light;
+        font-family: ui-sans-serif, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        background:
+          radial-gradient(circle at top, rgba(255, 186, 73, 0.28), transparent 42%),
+          linear-gradient(180deg, #fffaf2 0%, #f6efe4 100%);
+        color: #2f2418;
+      }
+      main {
+        width: min(560px, calc(100vw - 40px));
+        padding: 32px;
+        border-radius: 24px;
+        background: rgba(255, 255, 255, 0.9);
+        box-shadow: 0 30px 80px rgba(78, 49, 20, 0.15);
+      }
+      h1 {
+        margin: 0 0 12px;
+        font-size: 28px;
+        line-height: 1.1;
+      }
+      p {
+        margin: 0;
+        font-size: 16px;
+        line-height: 1.6;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <h1>${options.title}</h1>
+      <p>${options.message}</p>
+    </main>
+  </body>
+</html>`;
+}
+export async function waitForOAuthCallback(callbackUrl, timeoutMs, getExpectedState) {
+    const callback = new URL(callbackUrl);
+    const server = http.createServer();
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(Number(callback.port), callback.hostname, () => resolve());
+    });
+    const result = await new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+            reject(new Error("Timed out waiting for Entergram OAuth callback."));
+        }, timeoutMs);
+        server.on("request", (request, response) => {
+            const requestUrl = new URL(request.url || "/", callback);
+            if (requestUrl.pathname !== callback.pathname) {
+                response.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+                response.end("Not found");
+                return;
+            }
+            const error = requestUrl.searchParams.get("error");
+            const errorDescription = requestUrl.searchParams.get("error_description") || undefined;
+            const code = requestUrl.searchParams.get("code");
+            const state = requestUrl.searchParams.get("state") || undefined;
+            const expectedState = getExpectedState?.();
+            clearTimeout(timeout);
+            if (error) {
+                response.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                response.end(renderCallbackHtml({
+                    message: errorDescription || "The authorization flow was cancelled or failed.",
+                    title: "Entergram MCP authorization failed",
+                }));
+                resolve({
+                    error,
+                    errorDescription,
+                });
+                return;
+            }
+            if (!code) {
+                response.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                response.end(renderCallbackHtml({
+                    message: "No authorization code was returned to the Entergram MCP client.",
+                    title: "Entergram MCP authorization failed",
+                }));
+                resolve({
+                    error: "missing_code",
+                    errorDescription: "No authorization code was returned.",
+                });
+                return;
+            }
+            if (getExpectedState && (!expectedState || state !== expectedState)) {
+                response.writeHead(400, { "Content-Type": "text/html; charset=utf-8" });
+                response.end(renderCallbackHtml({
+                    message: "The authorization response could not be verified. Please retry the Entergram MCP sign-in flow.",
+                    title: "Entergram MCP authorization failed",
+                }));
+                resolve({
+                    error: "invalid_state",
+                    errorDescription: "The returned OAuth state did not match the active authorization request.",
+                });
+                return;
+            }
+            response.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+            response.end(renderCallbackHtml({
+                message: "Authorization completed. You can close this browser tab and return to your MCP host.",
+                title: "Entergram MCP connected",
+            }));
+            resolve({ code, state });
+        });
+    });
+    try {
+        if ("error" in result) {
+            throw new Error(result.errorDescription ||
+                `Entergram OAuth failed with error: ${result.error}`);
+        }
+        return result.code;
+    }
+    finally {
+        await new Promise((resolve) => {
+            server.close(() => resolve());
+        });
+    }
+}

package/dist/cli/oauth-provider.js

@@ -0,0 +1,170 @@
+import { randomUUID } from "node:crypto";
+import { openBrowser } from "./browser.js";
+function trimTrailingSlash(value) {
+    return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+export class EntergramOAuthProvider {
+    config;
+    store;
+    pendingState;
+    constructor(config, store) {
+        this.config = config;
+        this.store = store;
+    }
+    get redirectUrl() {
+        return this.config.callbackUrl;
+    }
+    get clientMetadata() {
+        return {
+            client_name: this.config.displayName,
+            grant_types: ["authorization_code", "refresh_token"],
+            redirect_uris: [this.config.callbackUrl],
+            response_types: ["code"],
+            scope: this.config.scope,
+            token_endpoint_auth_method: "none",
+        };
+    }
+    async clientInformation() {
+        return {
+            client_id: this.config.clientId,
+        };
+    }
+    async tokens() {
+        return (await this.store.load())?.tokens;
+    }
+    async saveTokens(tokens) {
+        this.pendingState = undefined;
+        await this.store.save((current) => ({
+            clientId: this.config.clientId,
+            codeVerifier: current?.codeVerifier,
+            discoveryState: current?.discoveryState,
+            expectedState: undefined,
+            gatewayUrl: this.config.gatewayUrl,
+            lastAuthenticatedAt: new Date().toISOString(),
+            scope: this.config.scope,
+            tokens,
+            updatedAt: new Date().toISOString(),
+        }));
+    }
+    async redirectToAuthorization(authorizationUrl) {
+        const opened = await openBrowser(authorizationUrl.href);
+        const output = opened
+            ? `Opening browser for Entergram authorization: ${authorizationUrl.href}\n`
+            : `Open this URL to authorize Entergram MCP:\n${authorizationUrl.href}\n`;
+        process.stderr.write(output);
+    }
+    async saveCodeVerifier(codeVerifier) {
+        await this.store.save((current) => ({
+            clientId: this.config.clientId,
+            codeVerifier,
+            discoveryState: current?.discoveryState,
+            expectedState: current?.expectedState ?? this.pendingState,
+            gatewayUrl: this.config.gatewayUrl,
+            lastAuthenticatedAt: current?.lastAuthenticatedAt,
+            scope: this.config.scope,
+            tokens: current?.tokens,
+            updatedAt: new Date().toISOString(),
+        }));
+    }
+    async codeVerifier() {
+        const codeVerifier = (await this.store.load())?.codeVerifier;
+        if (!codeVerifier) {
+            throw new Error("Entergram OAuth code verifier is missing from local session storage.");
+        }
+        return codeVerifier;
+    }
+    async invalidateCredentials(scope) {
+        this.pendingState = undefined;
+        if (scope === "all") {
+            await this.store.clear();
+            return;
+        }
+        await this.store.save((current) => ({
+            clientId: this.config.clientId,
+            codeVerifier: scope === "verifier" ? undefined : current?.codeVerifier,
+            discoveryState: scope === "discovery" ? undefined : current?.discoveryState,
+            expectedState: undefined,
+            gatewayUrl: this.config.gatewayUrl,
+            lastAuthenticatedAt: current?.lastAuthenticatedAt,
+            scope: this.config.scope,
+            tokens: scope === "tokens" ? undefined : current?.tokens,
+            updatedAt: new Date().toISOString(),
+        }));
+    }
+    async validateResourceURL(_serverUrl, resource) {
+        const expected = new URL(this.config.gatewayUrl);
+        if (!resource) {
+            return expected;
+        }
+        const actual = new URL(resource);
+        if (actual.href !== expected.href) {
+            throw new Error(`Unexpected OAuth resource URL. Expected ${expected.href}, received ${actual.href}.`);
+        }
+        return actual;
+    }
+    async saveDiscoveryState(state) {
+        await this.store.save((current) => ({
+            clientId: this.config.clientId,
+            codeVerifier: current?.codeVerifier,
+            discoveryState: state,
+            expectedState: current?.expectedState ?? this.pendingState,
+            gatewayUrl: this.config.gatewayUrl,
+            lastAuthenticatedAt: current?.lastAuthenticatedAt,
+            scope: this.config.scope,
+            tokens: current?.tokens,
+            updatedAt: new Date().toISOString(),
+        }));
+    }
+    async discoveryState() {
+        const persistedState = (await this.store.load())?.discoveryState;
+        if (persistedState) {
+            return persistedState;
+        }
+        if (!this.config.oauthIssuerUrl) {
+            return undefined;
+        }
+        const issuer = new URL(this.config.oauthIssuerUrl);
+        const normalizedIssuer = trimTrailingSlash(issuer.href);
+        return {
+            authorizationServerMetadata: {
+                authorization_endpoint: new URL("/oauth/authorize", issuer).href,
+                code_challenge_methods_supported: ["S256"],
+                grant_types_supported: ["authorization_code", "refresh_token"],
+                issuer: normalizedIssuer,
+                jwks_uri: new URL("/oauth/jwks.json", issuer).href,
+                response_modes_supported: ["query"],
+                response_types_supported: ["code"],
+                token_endpoint: new URL("/oauth/token", issuer).href,
+                token_endpoint_auth_methods_supported: ["none"],
+            },
+            authorizationServerUrl: issuer.href,
+            resourceMetadata: {
+                authorization_servers: [issuer.href],
+                resource: this.config.gatewayUrl,
+                resource_documentation: new URL("/settings", issuer).href,
+                resource_name: this.config.displayName,
+            },
+        };
+    }
+    expectedState() {
+        return this.pendingState;
+    }
+    state() {
+        const state = randomUUID();
+        this.pendingState = state;
+        void this.store
+            .save((current) => ({
+            clientId: this.config.clientId,
+            codeVerifier: current?.codeVerifier,
+            discoveryState: current?.discoveryState,
+            expectedState: state,
+            gatewayUrl: this.config.gatewayUrl,
+            lastAuthenticatedAt: current?.lastAuthenticatedAt,
+            scope: this.config.scope,
+            tokens: current?.tokens,
+            updatedAt: new Date().toISOString(),
+        }))
+            .catch(() => undefined);
+        return state;
+    }
+}

package/dist/cli/print-config.js

@@ -0,0 +1,31 @@
+export function buildHostConfigSnippet(config, serverName) {
+    return {
+        mcpServers: {
+            [serverName]: {
+                command: "npx",
+                args: ["-y", "@entergram/mcp", "serve"],
+                env: {
+                    ENTERGRAM_MCP_ENV: config.environment,
+                    ENTERGRAM_MCP_CLIENT_ID: config.clientId,
+                    ENTERGRAM_MCP_SCOPE: config.scope,
+                },
+            },
+        },
+    };
+}
+function tomlString(value) {
+    return `"${value.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"")}"`;
+}
+export function buildHostConfigToml(config, serverName) {
+    return [
+        `[mcp_servers.${serverName}]`,
+        `command = "npx"`,
+        `args = ["-y", "@entergram/mcp", "serve"]`,
+        "",
+        `[mcp_servers.${serverName}.env]`,
+        `ENTERGRAM_MCP_ENV = ${tomlString(config.environment)}`,
+        `ENTERGRAM_MCP_CLIENT_ID = ${tomlString(config.clientId)}`,
+        `ENTERGRAM_MCP_SCOPE = ${tomlString(config.scope)}`,
+        "",
+    ].join("\n");
+}

package/dist/cli/remote-client.js

@@ -0,0 +1,115 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { UnauthorizedError, } from "@modelcontextprotocol/sdk/client/auth.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { waitForOAuthCallback } from "./oauth-callback.js";
+import { CLI_VERSION, ENTERGRAM_HOST_NAME } from "./constants.js";
+export class EntergramRemoteClient {
+    config;
+    authProvider;
+    client;
+    transport;
+    constructor(config, authProvider) {
+        this.config = config;
+        this.authProvider = authProvider;
+    }
+    get connectedClient() {
+        if (!this.client) {
+            throw new Error("Entergram remote client is not connected.");
+        }
+        return this.client;
+    }
+    async callTool(params) {
+        return this.withRetry((client) => client.callTool(params), true);
+    }
+    async close() {
+        await this.transport?.terminateSession().catch(() => undefined);
+        await this.client?.close().catch(() => undefined);
+        this.transport = undefined;
+        this.client = undefined;
+    }
+    async connect(options) {
+        await this.close();
+        const createPair = () => {
+            const client = new Client({
+                name: ENTERGRAM_HOST_NAME,
+                version: CLI_VERSION,
+            });
+            const transport = new StreamableHTTPClientTransport(new URL(this.config.gatewayUrl), {
+                authProvider: this.authProvider,
+            });
+            return {
+                client,
+                transport,
+            };
+        };
+        let { client, transport } = createPair();
+        try {
+            await client.connect(transport);
+        }
+        catch (error) {
+            if (!(error instanceof UnauthorizedError) || !options.interactive) {
+                throw error;
+            }
+            await client.close().catch(() => undefined);
+            ({ client, transport } = createPair());
+            const callbackPromise = waitForOAuthCallback(this.config.callbackUrl, 5 * 60 * 1000, () => this.authProvider.expectedState());
+            try {
+                await client.connect(transport);
+            }
+            catch (interactiveError) {
+                if (!(interactiveError instanceof UnauthorizedError)) {
+                    throw interactiveError;
+                }
+            }
+            const code = await callbackPromise;
+            await transport.finishAuth(code);
+            await client.connect(transport);
+        }
+        this.client = client;
+        this.transport = transport;
+        return client;
+    }
+    async ensureConnected(options) {
+        if (this.client) {
+            return this.client;
+        }
+        return this.connect(options);
+    }
+    async getPrompt(params) {
+        return this.withRetry((client) => client.getPrompt(params), true);
+    }
+    async listPrompts(params) {
+        return this.withRetry((client) => client.listPrompts(params), true);
+    }
+    async listResources(params) {
+        return this.withRetry((client) => client.listResources(params), true);
+    }
+    async listResourceTemplates(params) {
+        return this.withRetry((client) => client.listResourceTemplates(params), true);
+    }
+    async listTools(params) {
+        return this.withRetry((client) => client.listTools(params), true);
+    }
+    async readResource(params) {
+        return this.withRetry((client) => client.readResource(params), true);
+    }
+    async subscribeResource(params) {
+        return this.withRetry((client) => client.subscribeResource(params), true);
+    }
+    async unsubscribeResource(params) {
+        return this.withRetry((client) => client.unsubscribeResource(params), true);
+    }
+    async withRetry(callback, interactive) {
+        const client = await this.ensureConnected({ interactive });
+        try {
+            return await callback(client);
+        }
+        catch (error) {
+            if (!(error instanceof UnauthorizedError)) {
+                throw error;
+            }
+            const refreshedClient = await this.connect({ interactive });
+            return callback(refreshedClient);
+        }
+    }
+}

package/dist/cli/session-store.js

@@ -0,0 +1,44 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export class EntergramSessionStore {
+    sessionFilePath;
+    constructor(sessionFilePath) {
+        this.sessionFilePath = sessionFilePath;
+    }
+    async clear() {
+        try {
+            await fs.rm(this.sessionFilePath, { force: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    }
+    async load() {
+        try {
+            const raw = await fs.readFile(this.sessionFilePath, "utf8");
+            return JSON.parse(raw);
+        }
+        catch (error) {
+            const err = error;
+            if (err.code === "ENOENT") {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    async save(updater) {
+        const current = await this.load();
+        const next = updater(current);
+        await fs.mkdir(this.sessionDirectoryPath(), { recursive: true });
+        await fs.writeFile(this.sessionFilePath, `${JSON.stringify(next, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        return next;
+    }
+    sessionDirectoryPath() {
+        return path.dirname(this.sessionFilePath);
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@entergram/mcp",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Official Entergram MCP CLI for local MCP hosts with OAuth login, stdio bridging, and host config helpers.",
+  "type": "module",
+  "keywords": [
+    "entergram",
+    "mcp",
+    "model-context-protocol",
+    "oauth",
+    "claude-desktop",
+    "codex",
+    "cursor"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "entergram-mcp": "./dist/cli/bin.js"
+  },
+  "files": [
+    "dist/cli",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "cli": "node dist/cli/bin.js",
+    "dev:cli": "tsx src/cli/bin.ts serve",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepublishOnly": "npm run build && npm run typecheck",
+    "smoke:cli": "node dist/cli/bin.js help && node dist/cli/bin.js print-config --format toml --env dev --client-id entergram-smoke-client --name entergram-dev > /dev/null",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "jose": "^6.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}