mcp-resend 1.0.0-1

package/dist/services/tool-registry.js

@@ -0,0 +1,459 @@
+/**
+ * Tool Registry for Dynamic MCP Tool Discovery
+ *
+ * Manages tool loading/unloading by tier and scope, enabling dynamic tool discovery
+ * and permission-based access control.
+ *
+ * @module services/tool-registry
+ */
+// NOTE: Use console.error for logging - stdout is reserved for MCP protocol
+const log = (message) => console.error(`[tool-registry] ${message}`);
+// ============================================================================
+// Module-Level State
+// ============================================================================
+/**
+ * All registered tools, indexed by name.
+ */
+const registeredTools = new Map();
+/**
+ * Currently enabled tool names.
+ */
+const enabledTools = new Set();
+/**
+ * MCP Server reference for notifications.
+ */
+let serverInstance = null;
+/**
+ * Tools organized by tier for efficient loading.
+ */
+const toolsByTier = {
+    core: [],
+    secondary: [],
+    tertiary: [],
+};
+// NOTE: Tool tier arrays define which tools belong to each tier
+// These are populated by registerTool() calls during initialization
+/**
+ * Core tools - essential functionality (always available).
+ */
+export const CORE_TOOLS = [
+    "send_email",
+    "get_email",
+    "list_emails",
+    "list_domains",
+    "search_resend_documentation",
+];
+/**
+ * Secondary tools - commonly used features.
+ */
+export const SECONDARY_TOOLS = [
+    // Domain
+    "get_domain",
+    "create_domain",
+    "update_domain",
+    "verify_domain",
+    // Email
+    "update_email",
+    "cancel_email",
+    // Contact
+    "list_contacts",
+    "create_contact",
+    "get_contact",
+    "update_contact",
+    // Template
+    "list_templates",
+    "create_template",
+    "get_template",
+    "update_template",
+    "publish_template",
+    "duplicate_template",
+    // Webhook
+    "list_webhooks",
+    "create_webhook",
+    "get_webhook",
+    "update_webhook",
+    // Audience
+    "list_audiences",
+    "create_audience",
+    "get_audience",
+];
+/**
+ * Tertiary tools - advanced/admin features.
+ * NOTE: API key operations are EXCLUDED for security reasons.
+ */
+export const TERTIARY_TOOLS = [
+    // Destructive Operations
+    "delete_domain",
+    "delete_contact",
+    "delete_template",
+    "delete_topic",
+    "delete_webhook",
+    "delete_segment",
+    "delete_broadcast",
+    "delete_contact_property",
+    // Batch Operations
+    "send_batch_emails",
+    // Broadcast Operations
+    "list_broadcasts",
+    "create_broadcast",
+    "get_broadcast",
+    "update_broadcast",
+    "send_broadcast",
+    // Segment Operations
+    "list_segments",
+    "create_segment",
+    "get_segment",
+    "add_contact_to_segment",
+    "remove_contact_from_segment",
+    // Contact Property Operations
+    "list_contact_properties",
+    "create_contact_property",
+    "get_contact_property",
+    "update_contact_property",
+    // Inbound Email Operations
+    "list_received_emails",
+    "get_received_email",
+    "list_received_email_attachments",
+    "get_received_email_attachment",
+    // Sent Email Attachment Operations
+    "list_email_attachments",
+    "get_email_attachment",
+    // Topic Advanced Operations
+    "get_topic",
+    "update_topic",
+    "get_contact_topics",
+    "update_contact_topics",
+    // Contact Segment Operations
+    "list_contact_segments",
+];
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Initialize the tool registry with an MCP server instance.
+ *
+ * @param server - MCP Server instance for notifications
+ * @param tools - Initial tools to register
+ *
+ * @example
+ * ```typescript
+ * const server = new Server({ name: "resend-mcp" }, { capabilities: { tools: {} } });
+ * initializeRegistry(server, [sendEmailTool, listDomainsTool]);
+ * ```
+ */
+export function initializeRegistry(server, tools = []) {
+    serverInstance = server;
+    // Register all provided tools
+    for (const tool of tools) {
+        registerTool(tool);
+    }
+    log(`Registry initialized with ${tools.length} tools`);
+}
+/**
+ * Register a tool in the registry.
+ *
+ * @param tool - Tool definition to register
+ */
+export function registerTool(tool) {
+    if (registeredTools.has(tool.name)) {
+        log(`Warning: Overwriting existing tool '${tool.name}'`);
+    }
+    registeredTools.set(tool.name, tool);
+    toolsByTier[tool.tier].push(tool.name);
+    log(`Registered tool: ${tool.name} (tier: ${tool.tier})`);
+}
+/**
+ * Unregister a tool from the registry.
+ *
+ * @param name - Tool name to unregister
+ */
+export function unregisterTool(name) {
+    const tool = registeredTools.get(name);
+    if (!tool) {
+        return;
+    }
+    registeredTools.delete(name);
+    enabledTools.delete(name);
+    // Remove from tier list
+    const tierTools = toolsByTier[tool.tier];
+    const index = tierTools.indexOf(name);
+    if (index >= 0) {
+        tierTools.splice(index, 1);
+    }
+    log(`Unregistered tool: ${name}`);
+}
+/**
+ * Load all tools of a specific tier (and lower tiers).
+ *
+ * @param tier - Tier to load (includes all lower tiers)
+ *
+ * @example
+ * ```typescript
+ * loadTier("secondary"); // Loads core + secondary tools
+ * ```
+ */
+export async function loadTier(tier) {
+    const previousCount = enabledTools.size;
+    // Always include core tools
+    for (const name of toolsByTier.core) {
+        if (registeredTools.has(name)) {
+            enabledTools.add(name);
+        }
+    }
+    // Include secondary tools if tier is secondary or tertiary
+    if (tier === "secondary" || tier === "tertiary") {
+        for (const name of toolsByTier.secondary) {
+            if (registeredTools.has(name)) {
+                enabledTools.add(name);
+            }
+        }
+    }
+    // Include tertiary tools if tier is tertiary
+    if (tier === "tertiary") {
+        for (const name of toolsByTier.tertiary) {
+            if (registeredTools.has(name)) {
+                enabledTools.add(name);
+            }
+        }
+    }
+    const newCount = enabledTools.size;
+    log(`Loaded tier '${tier}': ${newCount} tools enabled (was ${previousCount})`);
+    // Notify server of tool list change
+    await notifyToolsChanged();
+}
+/**
+ * Unload all tools of a specific tier (keeps lower tiers).
+ *
+ * @param tier - Tier to unload
+ *
+ * @example
+ * ```typescript
+ * unloadTier("tertiary"); // Removes only tertiary tools
+ * ```
+ */
+export async function unloadTier(tier) {
+    const previousCount = enabledTools.size;
+    // Unload specified tier
+    for (const name of toolsByTier[tier]) {
+        enabledTools.delete(name);
+    }
+    // If unloading secondary, also unload tertiary
+    if (tier === "secondary") {
+        for (const name of toolsByTier.tertiary) {
+            enabledTools.delete(name);
+        }
+    }
+    // If unloading core, unload everything
+    if (tier === "core") {
+        for (const name of toolsByTier.secondary) {
+            enabledTools.delete(name);
+        }
+        for (const name of toolsByTier.tertiary) {
+            enabledTools.delete(name);
+        }
+    }
+    const newCount = enabledTools.size;
+    log(`Unloaded tier '${tier}': ${newCount} tools enabled (was ${previousCount})`);
+    // Notify server of tool list change
+    await notifyToolsChanged();
+}
+/**
+ * Load tools by scope(s).
+ *
+ * @param scopes - Scopes to enable
+ *
+ * @example
+ * ```typescript
+ * loadByScope(["read", "write"]); // Enable tools with read or write scope
+ * ```
+ */
+export async function loadByScope(scopes) {
+    const previousCount = enabledTools.size;
+    const scopeSet = new Set(scopes);
+    // Enable tools that have at least one matching scope
+    for (const [name, tool] of registeredTools) {
+        const hasMatchingScope = tool.scopes.some((s) => scopeSet.has(s));
+        if (hasMatchingScope) {
+            enabledTools.add(name);
+        }
+    }
+    const newCount = enabledTools.size;
+    log(`Loaded scopes [${scopes.join(", ")}]: ${newCount} tools enabled (was ${previousCount})`);
+    // Notify server of tool list change
+    await notifyToolsChanged();
+}
+/**
+ * Unload tools by scope(s).
+ *
+ * @param scopes - Scopes to disable
+ */
+export async function unloadByScope(scopes) {
+    const previousCount = enabledTools.size;
+    const scopeSet = new Set(scopes);
+    // Disable tools that have ALL scopes in the provided list
+    for (const [name, tool] of registeredTools) {
+        const allScopesMatch = tool.scopes.every((s) => scopeSet.has(s));
+        if (allScopesMatch) {
+            enabledTools.delete(name);
+        }
+    }
+    const newCount = enabledTools.size;
+    log(`Unloaded scopes [${scopes.join(", ")}]: ${newCount} tools enabled (was ${previousCount})`);
+    // Notify server of tool list change
+    await notifyToolsChanged();
+}
+/**
+ * Get all currently enabled tools as MCP tool definitions.
+ *
+ * @returns Array of MCP tool definitions
+ */
+export function getEnabledTools() {
+    const tools = [];
+    for (const name of enabledTools) {
+        const tool = registeredTools.get(name);
+        if (tool) {
+            tools.push({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                annotations: tool.annotations,
+            });
+        }
+    }
+    return tools;
+}
+/**
+ * Check if a tool is currently enabled.
+ *
+ * @param name - Tool name to check
+ * @returns True if tool is enabled
+ */
+export function isToolEnabled(name) {
+    return enabledTools.has(name);
+}
+/**
+ * Get a tool definition by name.
+ *
+ * @param name - Tool name
+ * @returns Tool definition or undefined
+ */
+export function getTool(name) {
+    return registeredTools.get(name);
+}
+/**
+ * Get a tool's execute function if the tool is enabled.
+ *
+ * @param name - Tool name
+ * @returns Execute function or undefined
+ */
+export function getToolExecutor(name) {
+    if (!enabledTools.has(name)) {
+        return undefined;
+    }
+    return registeredTools.get(name)?.execute;
+}
+/**
+ * Get registry statistics for debugging.
+ *
+ * @returns Registry statistics
+ */
+export function getRegistryStats() {
+    const stats = {
+        totalRegistered: registeredTools.size,
+        totalEnabled: enabledTools.size,
+        byTier: {
+            core: toolsByTier.core.length,
+            secondary: toolsByTier.secondary.length,
+            tertiary: toolsByTier.tertiary.length,
+        },
+        enabledByTier: {
+            core: 0,
+            secondary: 0,
+            tertiary: 0,
+        },
+        enabledTools: [],
+    };
+    // Count enabled by tier
+    for (const name of enabledTools) {
+        const tool = registeredTools.get(name);
+        if (tool) {
+            stats.enabledByTier[tool.tier]++;
+            stats.enabledTools.push(name);
+        }
+    }
+    return stats;
+}
+/**
+ * Reset the registry to initial state.
+ * Useful for testing or reconfiguration.
+ */
+export function resetRegistry() {
+    registeredTools.clear();
+    enabledTools.clear();
+    toolsByTier.core = [];
+    toolsByTier.secondary = [];
+    toolsByTier.tertiary = [];
+    serverInstance = null;
+    log("Registry reset");
+}
+/**
+ * Enable a specific tool by name.
+ *
+ * @param name - Tool name to enable
+ * @returns True if tool was enabled
+ */
+export async function enableTool(name) {
+    if (!registeredTools.has(name)) {
+        log(`Cannot enable unknown tool: ${name}`);
+        return false;
+    }
+    if (enabledTools.has(name)) {
+        return true; // Already enabled
+    }
+    enabledTools.add(name);
+    log(`Enabled tool: ${name}`);
+    await notifyToolsChanged();
+    return true;
+}
+/**
+ * Disable a specific tool by name.
+ *
+ * @param name - Tool name to disable
+ * @returns True if tool was disabled
+ */
+export async function disableTool(name) {
+    if (!enabledTools.has(name)) {
+        return true; // Already disabled
+    }
+    enabledTools.delete(name);
+    log(`Disabled tool: ${name}`);
+    await notifyToolsChanged();
+    return true;
+}
+// ============================================================================
+// Internal Helpers
+// ============================================================================
+/**
+ * Send notification that tool list has changed.
+ * MCP clients should re-fetch the tool list.
+ */
+async function notifyToolsChanged() {
+    if (!serverInstance) {
+        log("Warning: No server instance for notification");
+        return;
+    }
+    try {
+        // NOTE: MCP SDK may require specific notification format
+        // The notification name follows MCP spec: "notifications/tools/list_changed"
+        await serverInstance.notification({
+            method: "notifications/tools/list_changed",
+        });
+        log("Sent tools/list_changed notification");
+    }
+    catch (error) {
+        // Notification failures are non-fatal
+        const message = error instanceof Error ? error.message : String(error);
+        log(`Warning: Failed to send notification: ${message}`);
+    }
+}
+//# sourceMappingURL=tool-registry.js.map

package/dist/services/tool-registry.js.map

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

package/dist/tools/docs/embeddings-loader.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Lazy loader for pre-computed embeddings.
+ * Loads embeddings from data/embeddings.json on first access and caches them.
+ * Uses ES module path resolution for compatibility with both dev (tsx) and production (node).
+ */
+/** Expected schema version - must match build-embeddings.ts INDEX_VERSION */
+export declare const EXPECTED_SCHEMA_VERSION = "1.0.0";
+/** Expected embedding dimensions for Xenova/all-MiniLM-L6-v2 */
+export declare const EXPECTED_DIMENSIONS = 384;
+/**
+ * Structure of the embeddings index file.
+ * Mirrors the EmbeddingsIndex from scripts/types.ts but defined here
+ * to avoid importing build-time dependencies at runtime.
+ */
+export interface EmbeddingsIndex {
+    version: string;
+    model: string;
+    dimensions: number;
+    generatedAt: string;
+    sourceHash: string;
+    chunks: EmbeddingChunk[];
+}
+/**
+ * A single chunk with its embedding vector.
+ */
+export interface EmbeddingChunk {
+    id: string;
+    section: string;
+    content: string;
+    tokenCount: number;
+    embedding: number[];
+    sourceUrl?: string;
+}
+/**
+ * Load embeddings asynchronously with caching.
+ * Safe to call multiple times; will return cached data after first load.
+ * Concurrent calls will share the same loading promise.
+ *
+ * @returns Promise resolving to the embeddings index
+ * @throws Error if embeddings file is missing or invalid
+ */
+export declare function loadEmbeddings(): Promise<EmbeddingsIndex>;
+/**
+ * Get cached embeddings synchronously.
+ * Returns null if embeddings haven't been loaded yet.
+ * Use loadEmbeddings() for guaranteed access.
+ *
+ * @returns The cached embeddings index, or null if not loaded
+ */
+export declare function getLoadedEmbeddings(): EmbeddingsIndex | null;
+/**
+ * Clear the embeddings cache.
+ * Primarily for testing purposes.
+ */
+export declare function clearEmbeddingsCache(): void;
+/**
+ * Get the freshness warning message if embeddings are stale.
+ * Returns null if embeddings are fresh or not yet loaded.
+ *
+ * @returns Freshness warning message, or null
+ */
+export declare function getFreshnessWarning(): string | null;
+/**
+ * Check if embeddings are currently loaded.
+ *
+ * @returns true if embeddings are cached
+ */
+export declare function isEmbeddingsLoaded(): boolean;
+//# sourceMappingURL=embeddings-loader.d.ts.map

package/dist/tools/docs/embeddings-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings-loader.d.ts","sourceRoot":"","sources":["../../../src/tools/docs/embeddings-loader.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAWH,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,UAAU,CAAC;AAE/C,gEAAgE;AAChE,eAAO,MAAM,mBAAmB,MAAM,CAAC;AAQvC;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,cAAc,EAAE,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0LD;;;;;;;GAOG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,eAAe,CAAC,CAwB/D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,eAAe,GAAG,IAAI,CAE5D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,IAAI,CAK3C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,GAAG,IAAI,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C"}