@mcp-rating/gateway 0.2.0

package/dist/meta-tools/sandbox.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import { ManifestResolver } from "../sandbox/manifest-resolver.js";
+import { toolError } from "../utils/errors.js";
+/**
+ * Register the `mcp_sandbox` meta-tool — view and customize per-server
+ * capability manifests (the sandbox security contract).
+ *
+ *  - view:  show the effective/saved manifest + a human-readable summary
+ *  - set:   override fields (network, env, filesystem, subprocess, enforcement)
+ *           — takes effect on the next connection to that server
+ *  - reset: clear the override, reverting to trust-tier defaults
+ */
+export function registerSandbox(server, connectionManager) {
+    server.tool("mcp_sandbox", "View or customize a server's sandbox capability manifest (env/network/filesystem/subprocess access). Use action 'view' to inspect, 'set' to tighten or loosen grants (applies on next connect), or 'reset' to revert to defaults.", {
+        action: z
+            .enum(["view", "set", "reset"])
+            .describe("view = inspect manifest; set = override grants; reset = revert to defaults"),
+        slug: z.string().describe("Server slug (as shown by mcp_list_active or mcp_discover)"),
+        enforcement: z
+            .enum(["none", "l1-process", "l2-container"])
+            .optional()
+            .describe("[set] Isolation level. l2-container requires Docker/Podman."),
+        network: z
+            .enum(["none", "allowlist", "all"])
+            .optional()
+            .describe("[set] Network mode. 'none' = no network, 'allowlist' = only listed hosts, 'all' = unrestricted"),
+        networkAllow: z
+            .array(z.string())
+            .optional()
+            .describe("[set] Allowed host:port patterns for allowlist mode, e.g. ['api.github.com:443', '*.example.com']"),
+        envAllow: z
+            .array(z.string())
+            .optional()
+            .describe("[set] Environment variable NAMES the server may receive, e.g. ['GITHUB_TOKEN']"),
+        fsRead: z.array(z.string()).optional().describe("[set] Absolute paths the server may read"),
+        fsWrite: z.array(z.string()).optional().describe("[set] Absolute paths the server may write"),
+        subprocess: z.boolean().optional().describe("[set] Whether the server may spawn subprocesses"),
+    }, async (params) => {
+        try {
+            const resolver = connectionManager.manifestResolver;
+            if (!resolver) {
+                return toolError("Sandbox is not enabled on this gateway.");
+            }
+            const { action, slug } = params;
+            // ── RESET ──────────────────────────────────────────────────────────
+            if (action === "reset") {
+                resolver.clearOverride(slug);
+                return text(`## 🛡️ Sandbox override cleared for \`${slug}\`\n\nThe server will use trust-tier defaults on the next connection.`);
+            }
+            // ── VIEW ───────────────────────────────────────────────────────────
+            if (action === "view") {
+                // Prefer the live connection's resolved manifest, then a saved
+                // override, then a note that defaults will apply on connect.
+                const conn = connectionManager.getConnection(slug);
+                const manifest = conn?.manifest ?? resolver.getOverride(slug);
+                if (!manifest) {
+                    return text(`## 🛡️ Sandbox: \`${slug}\`\n\nNo saved override and not currently connected. Trust-tier defaults will apply when you connect. Use \`mcp_sandbox({action: "set", slug: "${slug}", ...})\` to pre-configure grants.`);
+                }
+                return text(renderManifest(slug, manifest, Boolean(conn)));
+            }
+            // ── SET ────────────────────────────────────────────────────────────
+            // Start from existing override / live manifest / a locked baseline.
+            const conn = connectionManager.getConnection(slug);
+            const base = resolver.getOverride(slug) ??
+                conn?.manifest ?? {
+                version: 1,
+                slug,
+                enforcement: "l1-process",
+                env: { allow: [], inheritDefaults: true },
+                network: { mode: "none", allow: [] },
+                filesystem: { read: [], write: [] },
+                subprocess: false,
+            };
+            const updated = {
+                ...base,
+                slug,
+                enforcement: params.enforcement ?? base.enforcement,
+                env: {
+                    allow: params.envAllow ?? base.env.allow,
+                    inheritDefaults: base.env.inheritDefaults,
+                },
+                network: {
+                    mode: params.network ?? base.network.mode,
+                    allow: params.networkAllow ?? base.network.allow,
+                },
+                filesystem: {
+                    read: params.fsRead ?? base.filesystem.read,
+                    write: params.fsWrite ?? base.filesystem.write,
+                },
+                subprocess: params.subprocess ?? base.subprocess,
+            };
+            resolver.saveOverride(updated);
+            return text(`## 🛡️ Sandbox override saved for \`${slug}\`\n\n${renderManifest(slug, updated, false)}\n\n_Takes effect on the next connection. Reconnect to apply._`);
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+function renderManifest(slug, manifest, isLive) {
+    const summary = ManifestResolver.summarize(manifest);
+    const lines = [
+        `## 🛡️ Sandbox: \`${slug}\`${isLive ? " (active connection)" : ""}`,
+        `**Enforcement:** ${manifest.enforcement}`,
+        "",
+        "**Grants:**",
+        ...summary.lines.map((l) => `- ${l}`),
+        "",
+        "**Raw manifest:**",
+        "```json",
+        JSON.stringify({
+            enforcement: manifest.enforcement,
+            env: manifest.env,
+            network: manifest.network,
+            filesystem: manifest.filesystem,
+            subprocess: manifest.subprocess,
+        }, null, 2),
+        "```",
+    ];
+    return lines.join("\n");
+}
+function text(t) {
+    return { content: [{ type: "text", text: t }] };
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/meta-tools/sandbox.js.map

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

package/dist/meta-tools/server-info.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConnectionManager } from "../connection/connection-manager.js";
+import type { RegistryClient } from "../registry/registry-client.js";
+export declare function registerServerInfo(server: McpServer, connectionManager: ConnectionManager, registryClient: RegistryClient): void;

package/dist/meta-tools/server-info.js

@@ -0,0 +1,156 @@
+import { z } from "zod";
+import { TRUST_LABELS } from "../permissions/trust-tiers.js";
+import { namespaceTool } from "../proxy/tool-router.js";
+import { detectLiveUi } from "../proxy/ui-detect.js";
+import { toolError } from "../utils/errors.js";
+export function registerServerInfo(server, connectionManager, registryClient) {
+    server.tool("mcp_server_info", "Get detailed information about an MCP server from the registry or a currently connected server.", {
+        slug: z
+            .string()
+            .describe("Server slug (from registry or connected server)"),
+    }, async ({ slug }) => {
+        try {
+            // Check if it's a connected server first
+            const connected = connectionManager.getConnection(slug);
+            const lines = [];
+            // Fetch registry data
+            let registryData;
+            try {
+                registryData = await registryClient.getServer(slug);
+            }
+            catch {
+                // Registry unreachable — that's okay if we have a live connection
+            }
+            if (!connected && !registryData) {
+                return toolError(`Server "${slug}" not found in registry and not currently connected.`);
+            }
+            // Header
+            const name = connected?.displayName || registryData?.name || slug;
+            lines.push(`## ${name}`, "");
+            // Connection status
+            if (connected) {
+                const tierLabel = TRUST_LABELS[connected.trustTier];
+                lines.push(`**Status:** 🟢 Connected · **Trust:** [${tierLabel}]`);
+                if (connected.serverInfo) {
+                    lines.push(`**Server:** ${connected.serverInfo.name} v${connected.serverInfo.version}`);
+                }
+                lines.push("");
+            }
+            else {
+                lines.push("**Status:** ⚪ Not connected", "");
+            }
+            // Registry info
+            if (registryData) {
+                const tier = (await import("../registry/registry-client.js")).RegistryClient.determineTrustTier(registryData);
+                const tierLabel = TRUST_LABELS[tier];
+                const score = registryData.qualityScore ?? 0;
+                const breakdown = registryData.metadata?.scoreBreakdown;
+                lines.push("### Registry Info");
+                lines.push(`**Quality Score:** ${score}/100 · **Trust:** [${tierLabel}]`);
+                if (breakdown) {
+                    lines.push(`**Breakdown:** Popularity ${Math.round(breakdown.popularity ?? 0)} · ` +
+                        `Freshness ${Math.round(breakdown.freshness ?? 0)} · ` +
+                        `Completeness ${Math.round(breakdown.completeness ?? 0)} · ` +
+                        `MCP Compliance ${Math.round(breakdown.mcpCompliance ?? 0)} · ` +
+                        `Community ${Math.round(breakdown.community ?? 0)}`);
+                }
+                if (registryData.description) {
+                    lines.push(`**Description:** ${registryData.description}`);
+                }
+                if (registryData.author) {
+                    lines.push(`**Author:** ${registryData.author}`);
+                }
+                if (registryData.category) {
+                    lines.push(`**Category:** ${registryData.category.name}`);
+                }
+                const stats = [];
+                if (registryData.stars)
+                    stats.push(`${registryData.stars.toLocaleString()} ★`);
+                if (registryData.weeklyDownloads)
+                    stats.push(`${registryData.weeklyDownloads.toLocaleString()} downloads/wk`);
+                if (registryData.supportsDiscovery)
+                    stats.push("✓ .well-known/mcp");
+                // Heuristic UI capability from the registry ("detected").
+                if (registryData.supportsUi) {
+                    const uiType = registryData.uiType;
+                    stats.push(`🖼️ UI-capable (detected${uiType ? `: ${uiType}` : ""})`);
+                }
+                if (stats.length > 0) {
+                    lines.push(`**Stats:** ${stats.join(" · ")}`);
+                }
+                if (registryData.installCommand) {
+                    lines.push(`**Install:** \`${registryData.installCommand}\``);
+                }
+                // Auth requirements
+                const requiresAuth = registryData.requiresAuth || registryData.metadata?.requiresAuth;
+                if (requiresAuth) {
+                    lines.push("");
+                    lines.push("### Authentication Required");
+                    const authEnvVars = registryData.authDetails?.envVars || registryData.metadata?.authEnvVars || [];
+                    if (authEnvVars.length > 0) {
+                        lines.push("Environment variables needed:");
+                        for (const ev of authEnvVars) {
+                            lines.push(`- \`${ev.name}\`${ev.description ? `: ${ev.description}` : ""}`);
+                        }
+                    }
+                    const authSchemes = registryData.authDetails?.schemes || registryData.metadata?.authSchemes || [];
+                    if (authSchemes.length > 0) {
+                        lines.push(`**Auth schemes:** ${authSchemes.join(", ")}`);
+                    }
+                }
+                lines.push("");
+            }
+            // Live tools (from connection or registry)
+            const tools = connected
+                ? [...connected.tools.values()]
+                : registryData?.tools || [];
+            if (tools.length > 0) {
+                lines.push(`### Tools (${tools.length})`);
+                for (const tool of tools) {
+                    const nsName = connected
+                        ? `\`${namespaceTool(slug, tool.name)}\``
+                        : `\`${tool.name}\``;
+                    lines.push(`- ${nsName}: ${tool.description || "_No description_"}`);
+                }
+                lines.push("");
+            }
+            // Authoritative UI capability (live connection only) — inspect actual
+            // tool _meta.ui.resourceUri and ui:// resources. This confirms (or
+            // refutes) the registry's heuristic "detected" flag.
+            if (connected) {
+                const liveUi = detectLiveUi(connected.tools.values(), connected.resources.values());
+                if (liveUi.supportsUi) {
+                    lines.push("### 🖼️ Interactive UI (confirmed live)");
+                    if (liveUi.uiTools.length > 0) {
+                        lines.push(`**UI tools:** ${liveUi.uiTools.map((t) => `\`${t}\``).join(", ")}`);
+                    }
+                    if (liveUi.uiResources.length > 0) {
+                        lines.push(`**UI resources:** ${liveUi.uiResources.map((u) => `\`${u}\``).join(", ")}`);
+                    }
+                    lines.push("");
+                }
+            }
+            // Action suggestions
+            if (!connected) {
+                if (registryData?.installCommand) {
+                    lines.push(`→ Connect: \`mcp_connect({slug: "${slug}"})\``);
+                }
+                else {
+                    lines.push("⚠️ No install command available. You can connect manually:", `\`mcp_connect({command: "npx", args: ["-y", "package-name"]})\``);
+                }
+            }
+            else {
+                lines.push(`→ Disconnect: \`mcp_disconnect({slug: "${slug}"})\``);
+            }
+            return {
+                content: [
+                    { type: "text", text: lines.join("\n") },
+                ],
+            };
+        }
+        catch (err) {
+            return toolError(`Failed to get server info: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
+//# sourceMappingURL=server-info.js.map

package/dist/meta-tools/server-info.js.map

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

package/dist/meta-tools/usage.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { UsageTracker } from "../analytics/usage-tracker.js";
+/**
+ * Register the `mcp_usage` meta-tool for viewing usage analytics.
+ */
+export declare function registerUsage(server: McpServer, usageTracker: UsageTracker): void;

package/dist/meta-tools/usage.js

@@ -0,0 +1,149 @@
+import { z } from "zod";
+import { toolError } from "../utils/errors.js";
+/**
+ * Register the `mcp_usage` meta-tool for viewing usage analytics.
+ */
+export function registerUsage(server, usageTracker) {
+    server.tool("mcp_usage", "View usage analytics for connected MCP servers — call counts, latency, error rates, and recent activity.", {
+        slug: z
+            .string()
+            .optional()
+            .describe("Filter stats to a specific server slug. Omit for global stats."),
+        action: z
+            .enum(["stats", "recent", "slow", "reset"])
+            .optional()
+            .describe("Action: stats (default — summary), recent (recent calls), slow (slow calls), reset (clear all data)"),
+        limit: z
+            .number()
+            .optional()
+            .describe("Limit number of results for 'recent' and 'slow' actions (default: 20)"),
+        threshold: z
+            .number()
+            .optional()
+            .describe("Latency threshold in ms for 'slow' action (default: 5000)"),
+    }, async ({ slug, action = "stats", limit = 20, threshold = 5000 }) => {
+        try {
+            switch (action) {
+                case "stats": {
+                    const stats = usageTracker.getStats(slug);
+                    if (stats.totalCalls === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: slug
+                                        ? `No usage data recorded for **${slug}** yet.`
+                                        : "No usage data recorded yet. Start calling tools to see analytics.",
+                                },
+                            ],
+                        };
+                    }
+                    const lines = [
+                        slug ? `## Usage Stats: ${slug}` : "## Global Usage Stats",
+                        "",
+                        `**Total calls:** ${stats.totalCalls}`,
+                        `**Total errors:** ${stats.totalErrors} (${((stats.totalErrors / stats.totalCalls) * 100).toFixed(1)}%)`,
+                        `**Avg latency:** ${stats.avgLatencyMs.toFixed(0)}ms`,
+                        "",
+                    ];
+                    // Top tools by calls
+                    if (stats.topToolsByCalls.length > 0) {
+                        lines.push("### Most Used Tools");
+                        for (const tool of stats.topToolsByCalls.slice(0, 5)) {
+                            const errorRate = tool.callCount > 0
+                                ? ((tool.errorCount / tool.callCount) * 100).toFixed(1)
+                                : "0.0";
+                            lines.push(`- **${tool.key}**: ${tool.callCount} calls, ${tool.avgLatencyMs.toFixed(0)}ms avg, p95 ${tool.p95LatencyMs.toFixed(0)}ms, ${errorRate}% errors`);
+                        }
+                        lines.push("");
+                    }
+                    // Slowest tools
+                    if (stats.slowestTools.length > 0) {
+                        lines.push("### Slowest Tools (≥5 calls)");
+                        for (const tool of stats.slowestTools.slice(0, 5)) {
+                            lines.push(`- **${tool.key}**: ${tool.avgLatencyMs.toFixed(0)}ms avg, p95 ${tool.p95LatencyMs.toFixed(0)}ms (${tool.callCount} calls)`);
+                        }
+                        lines.push("");
+                    }
+                    // Per-server breakdown
+                    if (stats.perServer.length > 0) {
+                        lines.push("### Per-Server Breakdown");
+                        for (const srv of stats.perServer) {
+                            const errorRate = srv.totalCalls > 0
+                                ? ((srv.totalErrors / srv.totalCalls) * 100).toFixed(1)
+                                : "0.0";
+                            lines.push(`- **${srv.slug}**: ${srv.totalCalls} calls, ${srv.avgLatencyMs.toFixed(0)}ms avg, ${errorRate}% errors`);
+                        }
+                        lines.push("");
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                    };
+                }
+                case "recent": {
+                    const recent = usageTracker.getRecentCalls(limit);
+                    if (recent.length === 0) {
+                        return {
+                            content: [
+                                { type: "text", text: "No recent tool calls recorded." },
+                            ],
+                        };
+                    }
+                    const lines = [
+                        `## Recent Tool Calls (${recent.length})`,
+                        "",
+                    ];
+                    for (const call of recent) {
+                        const status = call.success ? "✅" : "❌";
+                        const time = new Date(call.startedAt).toISOString().slice(11, 19);
+                        lines.push(`${status} \`${call.slug}::${call.toolName}\` — ${call.durationMs}ms [${time}]${call.error ? ` — ${call.error}` : ""}`);
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                    };
+                }
+                case "slow": {
+                    const slowCalls = usageTracker.getSlowCalls(threshold);
+                    if (slowCalls.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: `No tool calls exceeded the ${threshold}ms threshold.`,
+                                },
+                            ],
+                        };
+                    }
+                    const sorted = [...slowCalls]
+                        .sort((a, b) => b.durationMs - a.durationMs)
+                        .slice(0, limit);
+                    const lines = [
+                        `## Slow Tool Calls (>${threshold}ms) — ${sorted.length} results`,
+                        "",
+                    ];
+                    for (const call of sorted) {
+                        const status = call.success ? "✅" : "❌";
+                        lines.push(`${status} \`${call.slug}::${call.toolName}\` — **${call.durationMs}ms**`);
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                    };
+                }
+                case "reset": {
+                    usageTracker.reset();
+                    return {
+                        content: [
+                            { type: "text", text: "✅ Usage analytics data has been reset." },
+                        ],
+                    };
+                }
+                default:
+                    return toolError(`Unknown action: ${action}`);
+            }
+        }
+        catch (err) {
+            return toolError(err instanceof Error ? err.message : String(err));
+        }
+    });
+}
+//# sourceMappingURL=usage.js.map

package/dist/meta-tools/usage.js.map

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

package/dist/permissions/permission-manager.d.ts

@@ -0,0 +1,26 @@
+import type { GatewayConfig } from "../config/types.js";
+import type { TrustTier } from "../registry/types.js";
+export interface ServerPermissions {
+    slug: string;
+    trustTier: TrustTier;
+    allowedTools: string[] | "all";
+    blockedTools: string[];
+    autoConnect: boolean;
+}
+/**
+ * Manages per-server permissions with file-based persistence.
+ *
+ * In Phase 1 this is primarily informational — the host client's
+ * built-in HITL confirmation (tool call approval dialog) serves as
+ * the primary permission gate.
+ */
+export declare class PermissionManager {
+    private permissions;
+    private readonly filePath;
+    constructor(config: GatewayConfig);
+    getPermissions(slug: string, trustTier: TrustTier): ServerPermissions;
+    setPermissions(slug: string, perms: ServerPermissions): void;
+    isToolAllowed(slug: string, toolName: string): boolean;
+    private loadFromDisk;
+    private saveToDisk;
+}

package/dist/permissions/permission-manager.js

@@ -0,0 +1,73 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { log } from "../utils/logger.js";
+/**
+ * Manages per-server permissions with file-based persistence.
+ *
+ * In Phase 1 this is primarily informational — the host client's
+ * built-in HITL confirmation (tool call approval dialog) serves as
+ * the primary permission gate.
+ */
+export class PermissionManager {
+    permissions = new Map();
+    filePath;
+    constructor(config) {
+        this.filePath = config.permissionsPath;
+        this.loadFromDisk();
+    }
+    getPermissions(slug, trustTier) {
+        const existing = this.permissions.get(slug);
+        if (existing)
+            return existing;
+        // Return defaults for this trust tier
+        return {
+            slug,
+            trustTier,
+            allowedTools: "all",
+            blockedTools: [],
+            autoConnect: trustTier === "verified" || trustTier === "trusted",
+        };
+    }
+    setPermissions(slug, perms) {
+        this.permissions.set(slug, perms);
+        this.saveToDisk();
+    }
+    isToolAllowed(slug, toolName) {
+        const perms = this.permissions.get(slug);
+        if (!perms)
+            return true; // No restrictions stored → allow
+        if (perms.blockedTools.includes(toolName))
+            return false;
+        if (perms.allowedTools === "all")
+            return true;
+        return perms.allowedTools.includes(toolName);
+    }
+    loadFromDisk() {
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const raw = readFileSync(this.filePath, "utf-8");
+            const data = JSON.parse(raw);
+            for (const [slug, perms] of Object.entries(data.servers || {})) {
+                this.permissions.set(slug, { slug, ...perms });
+            }
+            log.debug("Loaded permissions", { count: this.permissions.size });
+        }
+        catch {
+            log.warn("Failed to load permissions file, using defaults");
+        }
+    }
+    saveToDisk() {
+        const data = { servers: {} };
+        for (const [slug, perms] of this.permissions) {
+            const { slug: _slug, ...rest } = perms;
+            data.servers[slug] = rest;
+        }
+        try {
+            writeFileSync(this.filePath, JSON.stringify(data, null, 2), "utf-8");
+        }
+        catch (err) {
+            log.warn("Failed to save permissions", { error: String(err) });
+        }
+    }
+}
+//# sourceMappingURL=permission-manager.js.map

package/dist/permissions/permission-manager.js.map

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

package/dist/permissions/trust-tiers.d.ts

@@ -0,0 +1,18 @@
+import type { TrustTier } from "../registry/types.js";
+/** Human-readable label for tool description prefixes */
+export declare const TRUST_LABELS: Record<TrustTier, string>;
+/** Default max concurrent tool calls per trust tier */
+export declare const DEFAULT_MAX_CONCURRENT: Record<TrustTier, number>;
+/** Policy controlling connection behavior per trust tier */
+export interface TrustPolicy {
+    /** Must the user explicitly confirm before connecting? */
+    requiresConfirmation: boolean;
+    /** Can this server be connected at all? */
+    allowByDefault: boolean;
+    /** Description shown to user in confirmation warnings */
+    description: string;
+}
+/** Default trust policies per tier */
+export declare const DEFAULT_TRUST_POLICIES: Record<TrustTier, TrustPolicy>;
+/** Get the trust policy for a given tier */
+export declare function getTrustPolicy(tier: TrustTier): TrustPolicy;

package/dist/permissions/trust-tiers.js

@@ -0,0 +1,42 @@
+/** Human-readable label for tool description prefixes */
+export const TRUST_LABELS = {
+    verified: "Verified",
+    trusted: "Trusted",
+    community: "Community",
+    unknown: "Unverified",
+};
+/** Default max concurrent tool calls per trust tier */
+export const DEFAULT_MAX_CONCURRENT = {
+    verified: 10,
+    trusted: 5,
+    community: 3,
+    unknown: 1,
+};
+/** Default trust policies per tier */
+export const DEFAULT_TRUST_POLICIES = {
+    verified: {
+        requiresConfirmation: false,
+        allowByDefault: true,
+        description: "Verified server — high quality, officially reviewed.",
+    },
+    trusted: {
+        requiresConfirmation: false,
+        allowByDefault: true,
+        description: "Trusted server — good quality with repository and install command.",
+    },
+    community: {
+        requiresConfirmation: true,
+        allowByDefault: true,
+        description: "Community server — listed in registry with basic quality. User confirmation recommended.",
+    },
+    unknown: {
+        requiresConfirmation: true,
+        allowByDefault: true,
+        description: "Unverified server — unknown origin. User confirmation required.",
+    },
+};
+/** Get the trust policy for a given tier */
+export function getTrustPolicy(tier) {
+    return DEFAULT_TRUST_POLICIES[tier];
+}
+//# sourceMappingURL=trust-tiers.js.map