@mcp-rating/gateway 0.2.0

package/dist/sandbox/manifest-resolver.js

@@ -0,0 +1,185 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { log } from "../utils/logger.js";
+/**
+ * Trust-tier → default policy mapping.
+ *
+ * The principle: the less we trust a server, the less it gets by default.
+ * Verified/trusted servers get permissive defaults (they've earned it);
+ * community/unknown servers get locked down and must be explicitly granted.
+ */
+const TIER_DEFAULTS = {
+    verified: {
+        enforcement: "l1-process",
+        inheritDefaults: true,
+        network: "all",
+        subprocess: true,
+    },
+    trusted: {
+        enforcement: "l1-process",
+        inheritDefaults: true,
+        network: "all",
+        subprocess: true,
+    },
+    community: {
+        enforcement: "l1-process",
+        inheritDefaults: true,
+        network: "allowlist",
+        subprocess: false,
+    },
+    unknown: {
+        enforcement: "l1-process",
+        inheritDefaults: true, // still need PATH/HOME to start
+        network: "none",
+        subprocess: false,
+    },
+};
+/**
+ * Resolves and persists per-server capability manifests.
+ *
+ * A manifest is derived from (in priority order):
+ *   1. A user-saved override (persisted to disk)
+ *   2. Trust-tier defaults + the server's declared auth env vars
+ */
+export class ManifestResolver {
+    overrides = new Map();
+    filePath;
+    /**
+     * When true, untrusted tiers (community/unknown) default to l2-container
+     * enforcement instead of l1-process. Verified/trusted stay on L1.
+     */
+    containerIsolation;
+    constructor(filePath, containerIsolation = false) {
+        this.filePath = filePath;
+        this.containerIsolation = containerIsolation;
+        this.loadFromDisk();
+    }
+    /**
+     * Resolve the effective manifest for a server. Uses a saved override if one
+     * exists; otherwise derives defaults from the trust tier and the server's
+     * declared auth env vars (so e.g. a GitHub server gets GITHUB_TOKEN allowed
+     * but nothing else).
+     */
+    resolve(slug, trustTier, registryServer, 
+    /** Env var names the user explicitly supplied at connect time. */
+    userProvidedEnvKeys = []) {
+        const override = this.overrides.get(slug);
+        if (override) {
+            log.debug("Using saved manifest override", { slug });
+            return override;
+        }
+        const tier = TIER_DEFAULTS[trustTier];
+        // Escalate untrusted tiers to container isolation when enabled.
+        const enforcement = this.containerIsolation &&
+            (trustTier === "community" || trustTier === "unknown")
+            ? "l2-container"
+            : tier.enforcement;
+        // Build the env allowlist from the server's declared auth vars plus any
+        // vars the user explicitly passed (they clearly intend those to flow).
+        const declaredEnv = (registryServer?.authDetails?.envVars ?? []).map((e) => e.name);
+        const allEnv = new Set([...declaredEnv, ...userProvidedEnvKeys]);
+        return {
+            version: 1,
+            slug,
+            enforcement,
+            env: {
+                allow: [...allEnv],
+                inheritDefaults: tier.inheritDefaults,
+            },
+            network: {
+                mode: tier.network,
+                allow: [],
+            },
+            filesystem: {
+                read: [],
+                write: [],
+            },
+            subprocess: tier.subprocess,
+        };
+    }
+    /** Get a saved override for a slug, if one exists. */
+    getOverride(slug) {
+        return this.overrides.get(slug);
+    }
+    /** Persist a user-customized manifest. */
+    saveOverride(manifest) {
+        this.overrides.set(manifest.slug, manifest);
+        this.saveToDisk();
+    }
+    /** Remove a saved override, reverting to trust-tier defaults. */
+    clearOverride(slug) {
+        if (this.overrides.delete(slug))
+            this.saveToDisk();
+    }
+    /**
+     * Build a human-readable summary of a manifest for the HITL prompt.
+     */
+    static summarize(manifest) {
+        const lines = [];
+        let sensitive = false;
+        // Environment
+        if (manifest.env.allow.length > 0) {
+            lines.push(`Read ${manifest.env.allow.length} environment variable(s): ${manifest.env.allow.join(", ")}`);
+            sensitive = true;
+        }
+        else {
+            lines.push("No environment variables (secrets) exposed");
+        }
+        // Network
+        switch (manifest.network.mode) {
+            case "none":
+                lines.push("No network access (declared)");
+                break;
+            case "allowlist":
+                lines.push(manifest.network.allow.length > 0
+                    ? `Network limited to: ${manifest.network.allow.join(", ")} (declared)`
+                    : "Network: allowlist (none specified) (declared)");
+                break;
+            case "all":
+                lines.push("Full network access (declared)");
+                sensitive = true;
+                break;
+        }
+        // Filesystem
+        const fsRead = manifest.filesystem.read.length;
+        const fsWrite = manifest.filesystem.write.length;
+        if (fsRead > 0 || fsWrite > 0) {
+            lines.push(`Filesystem: ${fsRead} read path(s), ${fsWrite} write path(s) (declared)`);
+            if (fsWrite > 0)
+                sensitive = true;
+        }
+        // Subprocess
+        if (manifest.subprocess) {
+            lines.push("May spawn subprocesses (declared)");
+            sensitive = true;
+        }
+        return { enforcement: manifest.enforcement, lines, hasSensitiveGrants: sensitive };
+    }
+    loadFromDisk() {
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const raw = readFileSync(this.filePath, "utf-8");
+            const data = JSON.parse(raw);
+            for (const [slug, manifest] of Object.entries(data.manifests || {})) {
+                this.overrides.set(slug, manifest);
+            }
+            log.debug("Loaded manifest overrides", { count: this.overrides.size });
+        }
+        catch {
+            log.warn("Failed to load manifests file, using tier defaults");
+        }
+    }
+    saveToDisk() {
+        const data = { manifests: {} };
+        for (const [slug, manifest] of this.overrides) {
+            data.manifests[slug] = manifest;
+        }
+        try {
+            writeFileSync(this.filePath, JSON.stringify(data, null, 2), "utf-8");
+        }
+        catch (err) {
+            log.warn("Failed to save manifests", { error: String(err) });
+        }
+    }
+}
+//# sourceMappingURL=manifest-resolver.js.map

package/dist/sandbox/manifest-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-resolver.js","sourceRoot":"","sources":["../../src/sandbox/manifest-resolver.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Sandbox capability model.
+ *
+ * A CapabilityManifest declares what a downstream MCP server is permitted to
+ * access. It is the security contract between the gateway and an untrusted
+ * server.
+ *
+ * Enforcement is layered:
+ *  - **L1 (this release)**: environment-variable scoping is enforced at process
+ *    spawn (cross-platform, in-process). Network / filesystem / subprocess
+ *    fields are DECLARED and surfaced to the user via HITL, with hard
+ *    enforcement delegated to L2 (container/microVM) and L3 (WASM).
+ *  - **L2 / L3 (future)**: network egress filtering, filesystem jails,
+ *    subprocess blocking, and resource limits become enforced.
+ *
+ * Declaring a capability today (even before it is hard-enforced) is valuable:
+ * it makes the security posture visible, gives the user an informed consent
+ * prompt, and means the manifest format is stable when enforcement lands.
+ */
+/** How a server may reach the network. */
+export type NetworkMode = "none" | "allowlist" | "all";
+/** Enforcement level actually applied to a running connection. */
+export type EnforcementLevel = "none" | "l1-process" | "l2-container" | "l3-wasm";
+/** Environment-variable access policy. */
+export interface EnvPolicy {
+    /**
+     * Explicit allowlist of environment variable NAMES the server may receive.
+     * Anything not listed is stripped before spawn. Example: ["GITHUB_TOKEN"].
+     */
+    allow: string[];
+    /**
+     * When true, also inherit the SDK's safe default vars (PATH, HOME, etc.)
+     * needed for the process to start. The allowlist is layered on top.
+     */
+    inheritDefaults: boolean;
+}
+/** Network egress policy. */
+export interface NetworkPolicy {
+    mode: NetworkMode;
+    /**
+     * Host:port patterns the server may reach when mode is "allowlist".
+     * Example: ["api.github.com:443", "*.githubusercontent.com:443"].
+     * Declared in L1; enforced in L2+.
+     */
+    allow: string[];
+}
+/** Filesystem access policy. Declared in L1; enforced in L2+. */
+export interface FilesystemPolicy {
+    /** Absolute paths (or globs) the server may read. */
+    read: string[];
+    /** Absolute paths (or globs) the server may write. */
+    write: string[];
+}
+/** Optional resource limits. Declared in L1; enforced in L2+. */
+export interface ResourceLimits {
+    maxMemoryMb?: number;
+    maxCpuPercent?: number;
+    /** Wall-clock timeout for a single tool call, ms. */
+    toolCallTimeoutMs?: number;
+}
+/**
+ * The complete capability contract for one downstream server.
+ */
+export interface CapabilityManifest {
+    /** Schema version for forward-compatibility. */
+    version: 1;
+    /** Server slug this manifest applies to. */
+    slug: string;
+    /** Enforcement level the gateway will actually apply. */
+    enforcement: EnforcementLevel;
+    env: EnvPolicy;
+    network: NetworkPolicy;
+    filesystem: FilesystemPolicy;
+    /** Whether the server may spawn subprocesses. Declared in L1; enforced L2+. */
+    subprocess: boolean;
+    limits?: ResourceLimits;
+}
+/**
+ * Human-readable summary of a manifest's notable grants, for display in the
+ * HITL confirmation prompt. Each entry is a short risk-relevant statement.
+ */
+export interface ManifestSummary {
+    enforcement: EnforcementLevel;
+    /** e.g. "Read 1 environment variable: GITHUB_TOKEN" */
+    lines: string[];
+    /** True if the manifest grants anything the user should scrutinize. */
+    hasSensitiveGrants: boolean;
+}

package/dist/sandbox/types.js

@@ -0,0 +1,21 @@
+/**
+ * Sandbox capability model.
+ *
+ * A CapabilityManifest declares what a downstream MCP server is permitted to
+ * access. It is the security contract between the gateway and an untrusted
+ * server.
+ *
+ * Enforcement is layered:
+ *  - **L1 (this release)**: environment-variable scoping is enforced at process
+ *    spawn (cross-platform, in-process). Network / filesystem / subprocess
+ *    fields are DECLARED and surfaced to the user via HITL, with hard
+ *    enforcement delegated to L2 (container/microVM) and L3 (WASM).
+ *  - **L2 / L3 (future)**: network egress filtering, filesystem jails,
+ *    subprocess blocking, and resource limits become enforced.
+ *
+ * Declaring a capability today (even before it is hard-enforced) is valuable:
+ * it makes the security posture visible, gives the user an informed consent
+ * prompt, and means the manifest format is stable when enforcement lands.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/sandbox/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/sandbox/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/utils/errors.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Typed error classes for the MCP Gateway.
+ */
+export declare class GatewayError extends Error {
+    readonly code: string;
+    constructor(message: string, code: string);
+}
+export declare class ConnectionError extends GatewayError {
+    readonly serverSlug: string;
+    constructor(message: string, serverSlug: string);
+}
+export declare class RegistryError extends GatewayError {
+    constructor(message: string);
+}
+export declare class TimeoutError extends GatewayError {
+    readonly serverSlug: string;
+    readonly timeoutMs: number;
+    constructor(message: string, serverSlug: string, timeoutMs: number);
+}
+export declare class MaxConnectionsError extends GatewayError {
+    readonly maxConnections: number;
+    constructor(maxConnections: number);
+}
+export declare class DuplicateConnectionError extends GatewayError {
+    readonly serverSlug: string;
+    constructor(serverSlug: string);
+}
+export declare class PermissionDeniedError extends GatewayError {
+    readonly serverSlug: string;
+    constructor(serverSlug: string, message?: string);
+}
+/** Format any error as an MCP tool error result */
+export declare function toolError(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};

package/dist/utils/errors.js

@@ -0,0 +1,67 @@
+/**
+ * Typed error classes for the MCP Gateway.
+ */
+export class GatewayError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "GatewayError";
+    }
+}
+export class ConnectionError extends GatewayError {
+    serverSlug;
+    constructor(message, serverSlug) {
+        super(message, "CONNECTION_ERROR");
+        this.serverSlug = serverSlug;
+        this.name = "ConnectionError";
+    }
+}
+export class RegistryError extends GatewayError {
+    constructor(message) {
+        super(message, "REGISTRY_ERROR");
+        this.name = "RegistryError";
+    }
+}
+export class TimeoutError extends GatewayError {
+    serverSlug;
+    timeoutMs;
+    constructor(message, serverSlug, timeoutMs) {
+        super(message, "TIMEOUT_ERROR");
+        this.serverSlug = serverSlug;
+        this.timeoutMs = timeoutMs;
+        this.name = "TimeoutError";
+    }
+}
+export class MaxConnectionsError extends GatewayError {
+    maxConnections;
+    constructor(maxConnections) {
+        super(`Maximum connections (${maxConnections}) reached. Disconnect a server first.`, "MAX_CONNECTIONS");
+        this.maxConnections = maxConnections;
+        this.name = "MaxConnectionsError";
+    }
+}
+export class DuplicateConnectionError extends GatewayError {
+    serverSlug;
+    constructor(serverSlug) {
+        super(`Server "${serverSlug}" is already connected.`, "DUPLICATE_CONNECTION");
+        this.serverSlug = serverSlug;
+        this.name = "DuplicateConnectionError";
+    }
+}
+export class PermissionDeniedError extends GatewayError {
+    serverSlug;
+    constructor(serverSlug, message) {
+        super(message || `Connection to "${serverSlug}" was denied by trust policy.`, "PERMISSION_DENIED");
+        this.serverSlug = serverSlug;
+        this.name = "PermissionDeniedError";
+    }
+}
+/** Format any error as an MCP tool error result */
+export function toolError(message) {
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,YAAa,SAAQ,KAAK;IACQ;IAA7C,YAAY,OAAe,EAAkB,IAAY;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QAD4B,SAAI,GAAJ,IAAI,CAAQ;QAEvD,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,YAAY;IAG7B;IAFlB,YACE,OAAe,EACC,UAAkB;QAElC,KAAK,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;QAFnB,eAAU,GAAV,UAAU,CAAQ;QAGlC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,aAAc,SAAQ,YAAY;IAC7C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;QACjC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,OAAO,YAAa,SAAQ,YAAY;IAG1B;IACA;IAHlB,YACE,OAAe,EACC,UAAkB,EAClB,SAAiB;QAEjC,KAAK,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC;QAHhB,eAAU,GAAV,UAAU,CAAQ;QAClB,cAAS,GAAT,SAAS,CAAQ;QAGjC,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,YAAY;IACvB;IAA5B,YAA4B,cAAsB;QAChD,KAAK,CACH,wBAAwB,cAAc,uCAAuC,EAC7E,iBAAiB,CAClB,CAAC;QAJwB,mBAAc,GAAd,cAAc,CAAQ;QAKhD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,YAAY;IAC5B;IAA5B,YAA4B,UAAkB;QAC5C,KAAK,CACH,WAAW,UAAU,yBAAyB,EAC9C,sBAAsB,CACvB,CAAC;QAJwB,eAAU,GAAV,UAAU,CAAQ;QAK5C,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,MAAM,OAAO,qBAAsB,SAAQ,YAAY;IAEnC;IADlB,YACkB,UAAkB,EAClC,OAAgB;QAEhB,KAAK,CACH,OAAO,IAAI,kBAAkB,UAAU,+BAA+B,EACtE,mBAAmB,CACpB,CAAC;QANc,eAAU,GAAV,UAAU,CAAQ;QAOlC,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED,mDAAmD;AACnD,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QACnD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC"}

package/dist/utils/logger.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stderr-only logger for the MCP Gateway.
+ *
+ * CRITICAL: All output MUST go to stderr because stdout is reserved
+ * for MCP JSON-RPC protocol messages. Writing anything else to stdout
+ * would corrupt the protocol stream.
+ */
+type LogLevel = "debug" | "info" | "warn" | "error";
+export declare function setLogLevel(level: LogLevel): void;
+export declare const log: {
+    debug(msg: string, data?: unknown): void;
+    info(msg: string, data?: unknown): void;
+    warn(msg: string, data?: unknown): void;
+    error(msg: string, data?: unknown): void;
+};
+export {};

package/dist/utils/logger.js

@@ -0,0 +1,51 @@
+/**
+ * Stderr-only logger for the MCP Gateway.
+ *
+ * CRITICAL: All output MUST go to stderr because stdout is reserved
+ * for MCP JSON-RPC protocol messages. Writing anything else to stdout
+ * would corrupt the protocol stream.
+ */
+const LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+let currentLevel = "info";
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+function shouldLog(level) {
+    return LEVEL_ORDER[level] >= LEVEL_ORDER[currentLevel];
+}
+function formatMessage(level, msg, data) {
+    const ts = new Date().toISOString();
+    const prefix = `[${ts}] [${level.toUpperCase()}] [mcp-gateway]`;
+    if (data !== undefined) {
+        return `${prefix} ${msg} ${JSON.stringify(data)}\n`;
+    }
+    return `${prefix} ${msg}\n`;
+}
+export const log = {
+    debug(msg, data) {
+        if (shouldLog("debug")) {
+            process.stderr.write(formatMessage("debug", msg, data));
+        }
+    },
+    info(msg, data) {
+        if (shouldLog("info")) {
+            process.stderr.write(formatMessage("info", msg, data));
+        }
+    },
+    warn(msg, data) {
+        if (shouldLog("warn")) {
+            process.stderr.write(formatMessage("warn", msg, data));
+        }
+    },
+    error(msg, data) {
+        if (shouldLog("error")) {
+            process.stderr.write(formatMessage("error", msg, data));
+        }
+    },
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,WAAW,GAA6B;IAC5C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,IAAI,YAAY,GAAa,MAAM,CAAC;AAEpC,MAAM,UAAU,WAAW,CAAC,KAAe;IACzC,YAAY,GAAG,KAAK,CAAC;AACvB,CAAC;AAED,SAAS,SAAS,CAAC,KAAe;IAChC,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,YAAY,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,aAAa,CAAC,KAAe,EAAE,GAAW,EAAE,IAAc;IACjE,MAAM,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpC,MAAM,MAAM,GAAG,IAAI,EAAE,MAAM,KAAK,CAAC,WAAW,EAAE,iBAAiB,CAAC;IAChE,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,OAAO,GAAG,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;IACtD,CAAC;IACD,OAAO,GAAG,MAAM,IAAI,GAAG,IAAI,CAAC;AAC9B,CAAC;AAED,MAAM,CAAC,MAAM,GAAG,GAAG;IACjB,KAAK,CAAC,GAAW,EAAE,IAAc;QAC/B,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,IAAc;QAC9B,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED,IAAI,CAAC,GAAW,EAAE,IAAc;QAC9B,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,GAAW,EAAE,IAAc;QAC/B,IAAI,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;YACvB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;CACF,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@mcp-rating/gateway",
+  "version": "0.2.0",
+  "description": "MCP Gateway — auto-discover, connect, and proxy MCP servers from any AI desktop client",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "mcp-gateway": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "homepage": "https://mcprating.io/gateway",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mcprating/platform.git",
+    "directory": "packages/gateway"
+  },
+  "bugs": {
+    "url": "https://github.com/mcprating/platform/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./dist/gateway-server.d.ts",
+      "import": "./dist/gateway-server.js"
+    }
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gateway",
+    "proxy",
+    "mcp-server",
+    "mcp-rating",
+    "ai",
+    "tools"
+  ],
+  "license": "MIT",
+  "author": "[YOUR FULL NAME]",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "eventsource": "^4.1.0",
+    "ws": "^8.19.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "start:daemon": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "test:e2e": "node --import tsx test-e2e.mjs"
+  }
+}