@mcp-rating/gateway 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 [YOUR FULL NAME]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,130 @@
+# @mcp-rating/gateway
+
+**MCP Gateway** is a meta-MCP server that auto-discovers, connects, and proxies other MCP servers. Add one line to your AI desktop client config and get dynamic access to the entire MCP ecosystem.
+
+## How It Works
+
+```
+┌────────────────────┐       ┌──────────────┐       ┌──────────────────┐
+│  Claude Desktop /  │ stdio │              │ stdio  │ MCP Server A     │
+│  Cursor / Windsurf │◄─────►│  MCP Gateway │◄──────►│ (e.g. filesystem)│
+│  (host client)     │       │              │◄──┐    └──────────────────┘
+└────────────────────┘       └──────────────┘   │    ┌──────────────────┐
+                                    │           └───►│ MCP Server B     │
+                                    ▼                │ (e.g. github)    │
+                             ┌──────────────┐        └──────────────────┘
+                             │ MCP-Rating   │
+                             │ Registry API │
+                             └──────────────┘
+```
+
+Instead of manually configuring each MCP server in your client, the Gateway:
+
+1. **Discovers** servers via the MCP-Rating registry
+2. **Connects** to them on-demand (spawns as child processes)
+3. **Proxies** their tools through namespaced names (`servername__toolname`)
+4. **Notifies** your client when tools are added/removed
+
+## Quick Start
+
+### With Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gateway": {
+      "command": "npx",
+      "args": ["-y", "@mcp-rating/gateway"]
+    }
+  }
+}
+```
+
+Then ask Claude:
+- *"Search for MCP servers that work with databases"* (uses `mcp_discover`)
+- *"Connect to the sqlite server"* (uses `mcp_connect`)
+- *"Query my database"* (calls the proxied tool directly)
+
+### With Any MCP Client
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "@mcp-rating/gateway"]
+}
+```
+
+## Meta-Tools
+
+The gateway exposes 5 built-in tools:
+
+| Tool | Description |
+|------|-------------|
+| `mcp_discover` | Search the MCP-Rating registry for servers |
+| `mcp_connect` | Connect to a server (by slug or explicit command) |
+| `mcp_disconnect` | Disconnect a server and remove its tools |
+| `mcp_list_active` | List all connected servers |
+| `mcp_server_info` | Get detailed info about a server |
+
+## Trust Tiers
+
+Every connected server is labeled with a trust tier based on its MCP-Rating quality score:
+
+- **[Verified]** — High quality + officially verified
+- **[Trusted]** — Good quality with repository and install command
+- **[Community]** — Listed in registry with basic quality
+- **[Unverified]** — Unknown origin (manually connected)
+
+## Configuration
+
+The gateway reads config from `~/.mcp-gateway/config.json`:
+
+```json
+{
+  "registryApiUrl": "https://mcp-rating.example.com/api/v1",
+  "proxyTimeoutMs": 30000,
+  "maxConnections": 10,
+  "logLevel": "info"
+}
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MCP_GATEWAY_REGISTRY_URL` | MCP-Rating API base URL | `https://mcprating.io/api/v1` |
+| `MCP_GATEWAY_TIMEOUT` | Proxy timeout (ms) | `30000` |
+| `MCP_GATEWAY_MAX_CONNECTIONS` | Max simultaneous connections | `10` |
+| `MCP_GATEWAY_LOG_LEVEL` | Log level (debug/info/warn/error) | `info` |
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run in development mode
+pnpm dev
+
+# Type check
+pnpm typecheck
+
+# Build
+pnpm build
+```
+
+## Architecture
+
+The gateway is built on the [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) and uses:
+
+- **StdioServerTransport** — communicates with the host client
+- **StdioClientTransport** — spawns and communicates with downstream servers
+- **Dynamic tool registration** — `McpServer.registerTool()` + `sendToolListChanged()`
+- **Tool namespacing** — `slug__toolname` pattern prevents collisions
+- **Passthrough Zod schemas** — preserves parameter names for host client UI while letting downstream servers validate
+
+## License
+
+ISC

package/dist/ads/ad-tracker.d.ts

@@ -0,0 +1,63 @@
+export interface AdEvent {
+    serverSlug: string;
+    eventType: "connect" | "tool_usage";
+    toolName?: string;
+    sessionId: string;
+    timestamp: Date;
+}
+/**
+ * Tracks connect and tool-usage events for promoted servers.
+ * Reports events back to the MCP-Rating API via fire-and-forget HTTP POST.
+ */
+export declare class AdTracker {
+    private readonly registryApiUrl;
+    private readonly partnerKey;
+    /** Unique session ID for this gateway instance */
+    readonly sessionId: string;
+    /** In-memory event log for diagnostics */
+    private events;
+    /** Count of tracked events by type */
+    private eventCounts;
+    constructor(registryApiUrl: string, partnerKey: string);
+    /**
+     * Track a server connect event.
+     * Records as high-value click (click_type: 'install') in the ad network.
+     */
+    trackConnect(serverSlug: string): Promise<void>;
+    /**
+     * Track a proxied tool usage event.
+     * Records as action (CPA event) in the ad network.
+     */
+    trackToolUsage(serverSlug: string, toolName: string): Promise<void>;
+    /**
+     * Get partner earnings from the registry API.
+     */
+    getPartnerEarnings(): Promise<{
+        totalGrossCents: number;
+        totalPartnerShareCents: number;
+        eventCount: number;
+    } | null>;
+    /**
+     * Get diagnostics info for the ad status meta-tool.
+     */
+    getStatus(): {
+        sessionId: string;
+        partnerKeyConfigured: boolean;
+        eventCounts: {
+            connect: number;
+            tool_usage: number;
+        };
+        totalEvents: number;
+        recentEvents: {
+            serverSlug: string;
+            eventType: "connect" | "tool_usage";
+            toolName: string | undefined;
+            timestamp: string;
+        }[];
+    };
+    /**
+     * Report an ad event to the MCP-Rating API.
+     * Fire-and-forget — errors are logged but don't propagate.
+     */
+    private reportEvent;
+}

package/dist/ads/ad-tracker.js

@@ -0,0 +1,144 @@
+import { log } from "../utils/logger.js";
+import { randomUUID } from "node:crypto";
+/**
+ * Tracks connect and tool-usage events for promoted servers.
+ * Reports events back to the MCP-Rating API via fire-and-forget HTTP POST.
+ */
+export class AdTracker {
+    registryApiUrl;
+    partnerKey;
+    /** Unique session ID for this gateway instance */
+    sessionId;
+    /** In-memory event log for diagnostics */
+    events = [];
+    /** Count of tracked events by type */
+    eventCounts = { connect: 0, tool_usage: 0 };
+    constructor(registryApiUrl, partnerKey) {
+        this.registryApiUrl = registryApiUrl;
+        this.partnerKey = partnerKey;
+        this.sessionId = randomUUID();
+        log.info("Ad tracker initialized", {
+            sessionId: this.sessionId,
+            registryApiUrl,
+        });
+    }
+    /**
+     * Track a server connect event.
+     * Records as high-value click (click_type: 'install') in the ad network.
+     */
+    async trackConnect(serverSlug) {
+        this.events.push({
+            serverSlug,
+            eventType: "connect",
+            sessionId: this.sessionId,
+            timestamp: new Date(),
+        });
+        this.eventCounts.connect++;
+        // Trim in-memory log to last 500 events
+        if (this.events.length > 500) {
+            this.events = this.events.slice(-500);
+        }
+        // Fire-and-forget report to API
+        this.reportEvent("install", serverSlug).catch((err) => {
+            log.debug("Failed to report connect event", {
+                serverSlug,
+                error: String(err),
+            });
+        });
+    }
+    /**
+     * Track a proxied tool usage event.
+     * Records as action (CPA event) in the ad network.
+     */
+    async trackToolUsage(serverSlug, toolName) {
+        this.events.push({
+            serverSlug,
+            eventType: "tool_usage",
+            toolName,
+            sessionId: this.sessionId,
+            timestamp: new Date(),
+        });
+        this.eventCounts.tool_usage++;
+        // Trim in-memory log
+        if (this.events.length > 500) {
+            this.events = this.events.slice(-500);
+        }
+        // Fire-and-forget report to API
+        this.reportEvent("action_completed", serverSlug).catch((err) => {
+            log.debug("Failed to report tool usage event", {
+                serverSlug,
+                toolName,
+                error: String(err),
+            });
+        });
+    }
+    /**
+     * Get partner earnings from the registry API.
+     */
+    async getPartnerEarnings() {
+        try {
+            const res = await fetch(`${this.registryApiUrl}/partners/me/revenue`, {
+                headers: {
+                    "x-partner-key": this.partnerKey,
+                },
+                signal: AbortSignal.timeout(5_000),
+            });
+            if (!res.ok)
+                return null;
+            const data = (await res.json());
+            return {
+                totalGrossCents: data.totalGross,
+                totalPartnerShareCents: data.totalPartnerShare,
+                eventCount: data.count,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Get diagnostics info for the ad status meta-tool.
+     */
+    getStatus() {
+        return {
+            sessionId: this.sessionId,
+            partnerKeyConfigured: true,
+            eventCounts: { ...this.eventCounts },
+            totalEvents: this.events.length,
+            recentEvents: this.events.slice(-10).map((e) => ({
+                serverSlug: e.serverSlug,
+                eventType: e.eventType,
+                toolName: e.toolName,
+                timestamp: e.timestamp.toISOString(),
+            })),
+        };
+    }
+    /**
+     * Report an ad event to the MCP-Rating API.
+     * Fire-and-forget — errors are logged but don't propagate.
+     */
+    async reportEvent(clickType, serverSlug) {
+        const url = `${this.registryApiUrl}/partners/report-click`;
+        const res = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "x-partner-key": this.partnerKey,
+            },
+            body: JSON.stringify({
+                serverSlug,
+                clickType,
+                sessionId: this.sessionId,
+            }),
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (!res.ok) {
+            log.debug("Ad event report failed", {
+                status: res.status,
+                clickType,
+                serverSlug,
+            });
+        }
+    }
+}
+//# sourceMappingURL=ad-tracker.js.map

package/dist/ads/ad-tracker.js.map

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

package/dist/analytics/usage-tracker.d.ts

@@ -0,0 +1,67 @@
+export interface ToolCallEvent {
+    slug: string;
+    toolName: string;
+    startedAt: number;
+    durationMs: number;
+    success: boolean;
+    error?: string;
+}
+export interface ToolAggregates {
+    key: string;
+    callCount: number;
+    errorCount: number;
+    totalDurationMs: number;
+    avgLatencyMs: number;
+    p95LatencyMs: number;
+    lastCalledAt: number;
+    /** Recent latencies for p95 calculation (last 100) */
+    latencies: number[];
+}
+export interface ServerAggregates {
+    slug: string;
+    totalCalls: number;
+    totalErrors: number;
+    avgLatencyMs: number;
+}
+export interface UsageStats {
+    totalCalls: number;
+    totalErrors: number;
+    avgLatencyMs: number;
+    topToolsByCalls: ToolAggregates[];
+    slowestTools: ToolAggregates[];
+    perServer: ServerAggregates[];
+    recentCalls: ToolCallEvent[];
+}
+/**
+ * In-memory usage analytics tracker.
+ * Uses a ring buffer for events and maintains per-tool aggregates.
+ */
+export declare class UsageTracker {
+    private events;
+    private maxEvents;
+    private insertIdx;
+    private totalInserted;
+    /** Per-tool aggregates keyed by "slug::toolName" */
+    private toolAggregates;
+    constructor(bufferSize?: number);
+    /**
+     * Record a completed tool call event.
+     */
+    recordCall(event: ToolCallEvent): void;
+    /**
+     * Get overall usage statistics.
+     */
+    getStats(slug?: string): UsageStats;
+    /**
+     * Get the most recent tool call events.
+     */
+    getRecentCalls(limit?: number): ToolCallEvent[];
+    /**
+     * Get tool calls that exceeded a latency threshold.
+     */
+    getSlowCalls(thresholdMs?: number): ToolCallEvent[];
+    /**
+     * Reset all analytics data.
+     */
+    reset(): void;
+}

package/dist/analytics/usage-tracker.js

@@ -0,0 +1,148 @@
+import { log } from "../utils/logger.js";
+// ── Usage Tracker ────────────────────────────────────────────────────────────
+const DEFAULT_BUFFER_SIZE = 10_000;
+const LATENCY_WINDOW = 100; // Keep last 100 latencies for p95 calculation
+/**
+ * In-memory usage analytics tracker.
+ * Uses a ring buffer for events and maintains per-tool aggregates.
+ */
+export class UsageTracker {
+    events = [];
+    maxEvents;
+    insertIdx = 0;
+    totalInserted = 0;
+    /** Per-tool aggregates keyed by "slug::toolName" */
+    toolAggregates = new Map();
+    constructor(bufferSize = DEFAULT_BUFFER_SIZE) {
+        this.maxEvents = bufferSize;
+    }
+    /**
+     * Record a completed tool call event.
+     */
+    recordCall(event) {
+        // Ring buffer insert
+        if (this.totalInserted < this.maxEvents) {
+            this.events.push(event);
+        }
+        else {
+            this.events[this.insertIdx] = event;
+        }
+        this.insertIdx = (this.insertIdx + 1) % this.maxEvents;
+        this.totalInserted++;
+        // Update aggregates
+        const key = `${event.slug}::${event.toolName}`;
+        let agg = this.toolAggregates.get(key);
+        if (!agg) {
+            agg = {
+                key,
+                callCount: 0,
+                errorCount: 0,
+                totalDurationMs: 0,
+                avgLatencyMs: 0,
+                p95LatencyMs: 0,
+                lastCalledAt: 0,
+                latencies: [],
+            };
+            this.toolAggregates.set(key, agg);
+        }
+        agg.callCount++;
+        if (!event.success)
+            agg.errorCount++;
+        agg.totalDurationMs += event.durationMs;
+        agg.avgLatencyMs = agg.totalDurationMs / agg.callCount;
+        agg.lastCalledAt = event.startedAt;
+        // Track latencies for p95 (rolling window)
+        agg.latencies.push(event.durationMs);
+        if (agg.latencies.length > LATENCY_WINDOW) {
+            agg.latencies.shift();
+        }
+        agg.p95LatencyMs = percentile(agg.latencies, 95);
+    }
+    /**
+     * Get overall usage statistics.
+     */
+    getStats(slug) {
+        const allAggregates = [...this.toolAggregates.values()];
+        const filtered = slug
+            ? allAggregates.filter((a) => a.key.startsWith(`${slug}::`))
+            : allAggregates;
+        const totalCalls = filtered.reduce((s, a) => s + a.callCount, 0);
+        const totalErrors = filtered.reduce((s, a) => s + a.errorCount, 0);
+        const totalDuration = filtered.reduce((s, a) => s + a.totalDurationMs, 0);
+        const avgLatencyMs = totalCalls > 0 ? totalDuration / totalCalls : 0;
+        // Top tools by call count
+        const topToolsByCalls = [...filtered]
+            .sort((a, b) => b.callCount - a.callCount)
+            .slice(0, 10);
+        // Slowest tools by avg latency (min 5 calls to be relevant)
+        const slowestTools = [...filtered]
+            .filter((a) => a.callCount >= 5)
+            .sort((a, b) => b.avgLatencyMs - a.avgLatencyMs)
+            .slice(0, 10);
+        // Per-server aggregates
+        const serverMap = new Map();
+        for (const agg of filtered) {
+            const aggSlug = agg.key.split("::")[0];
+            const server = serverMap.get(aggSlug) || { totalCalls: 0, totalErrors: 0, totalDuration: 0 };
+            server.totalCalls += agg.callCount;
+            server.totalErrors += agg.errorCount;
+            server.totalDuration += agg.totalDurationMs;
+            serverMap.set(aggSlug, server);
+        }
+        const perServer = [...serverMap.entries()].map(([s, v]) => ({
+            slug: s,
+            totalCalls: v.totalCalls,
+            totalErrors: v.totalErrors,
+            avgLatencyMs: v.totalCalls > 0 ? v.totalDuration / v.totalCalls : 0,
+        }));
+        return {
+            totalCalls,
+            totalErrors,
+            avgLatencyMs,
+            topToolsByCalls,
+            slowestTools,
+            perServer,
+            recentCalls: this.getRecentCalls(20),
+        };
+    }
+    /**
+     * Get the most recent tool call events.
+     */
+    getRecentCalls(limit = 20) {
+        const len = Math.min(this.events.length, limit);
+        const recent = [];
+        // Read backwards from the insertion point
+        for (let i = 0; i < len; i++) {
+            const idx = (this.insertIdx - 1 - i + this.events.length) % this.events.length;
+            if (idx >= 0 && idx < this.events.length) {
+                recent.push(this.events[idx]);
+            }
+        }
+        return recent;
+    }
+    /**
+     * Get tool calls that exceeded a latency threshold.
+     */
+    getSlowCalls(thresholdMs = 5000) {
+        return this.events.filter((e) => e.durationMs >= thresholdMs);
+    }
+    /**
+     * Reset all analytics data.
+     */
+    reset() {
+        this.events = [];
+        this.insertIdx = 0;
+        this.totalInserted = 0;
+        this.toolAggregates.clear();
+        log.info("Usage analytics reset");
+    }
+}
+// ── Helpers ──────────────────────────────────────────────────────────────────
+function percentile(values, p) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const idx = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+}
+//# sourceMappingURL=usage-tracker.js.map

package/dist/analytics/usage-tracker.js.map

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

package/dist/audit/audit-log.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Safety audit trail — a forensics record of what sandboxed MCP servers
+ * actually did, and what the sandbox blocked.
+ *
+ * This is deliberately NOT generic observability (tool-call telemetry exists
+ * in UsageTracker). It's a *security* artifact: the evidence that containment
+ * worked. A security team reviewing "did this untrusted server try anything?"
+ * reads this log — it records sandbox-relevant events (calls under an
+ * enforcement level, blocked egress, blocked tools, connects with their
+ * granted capability envelope), not performance metrics.
+ *
+ * Storage: an in-memory ring buffer (always) plus optional append-only JSONL
+ * file (for durable forensics / SIEM ingestion).
+ */
+export type AuditEventType = "connect" | "tool_call" | "tool_blocked" | "egress_blocked" | "egress_allowed" | "disconnect";
+export interface AuditEvent {
+    /** ISO timestamp. */
+    ts: string;
+    type: AuditEventType;
+    /** Downstream server slug the event concerns. */
+    slug: string;
+    /** Sandbox enforcement level in effect (none | l1-process | l2-container | l3-wasm). */
+    enforcement?: string;
+    /** Tool name, for tool_* events. */
+    tool?: string;
+    /** Target host:port, for egress_* events. */
+    target?: string;
+    /** Whether the action succeeded (tool_call) — false on downstream error. */
+    ok?: boolean;
+    /** Short reason (block cause, error class). Never contains args/secrets. */
+    reason?: string;
+    /** Session id (multi-tenant daemon), if available. */
+    sessionId?: string;
+}
+export interface AuditLogOptions {
+    /** Max events kept in memory (ring buffer). Default 5000. */
+    bufferSize?: number;
+    /** Optional JSONL file path for durable, append-only forensics. */
+    filePath?: string;
+}
+/**
+ * Append-only safety audit log. Recording never throws — a forensics logger
+ * must not break the thing it observes.
+ */
+export declare class AuditLog {
+    private readonly buffer;
+    private readonly bufferSize;
+    private readonly filePath?;
+    private counts;
+    constructor(opts?: AuditLogOptions);
+    /** Record an event. Caller supplies everything except the timestamp. */
+    record(event: Omit<AuditEvent, "ts">): void;
+    /**
+     * Query recent events, newest first. Filterable by slug, type, and a
+     * "security-relevant only" flag (blocks + errors — the events a reviewer
+     * actually cares about).
+     */
+    query(opts?: {
+        slug?: string;
+        type?: AuditEventType;
+        securityRelevantOnly?: boolean;
+        limit?: number;
+    }): AuditEvent[];
+    /** Aggregate counts by event type (for the summary view). */
+    summary(): {
+        counts: Record<AuditEventType, number>;
+        total: number;
+        /** Count of security-relevant events (blocks + errors). */
+        securityEvents: number;
+    };
+}