erosolar-cli 1.4.7 → 1.5.1

package/dist/tools/emailTools.js

@@ -0,0 +1,445 @@
+/**
+ * Email Tools - SMTP email sending capabilities
+ *
+ * Supports Gmail, Outlook, and custom SMTP servers with app password authentication.
+ * Users configure their email credentials via /secrets or environment variables.
+ */
+import * as nodemailer from 'nodemailer';
+// SMTP provider presets
+const SMTP_PRESETS = {
+    gmail: {
+        host: 'smtp.gmail.com',
+        port: 587,
+        secure: false, // Uses STARTTLS
+    },
+    outlook: {
+        host: 'smtp.office365.com',
+        port: 587,
+        secure: false,
+    },
+    hotmail: {
+        host: 'smtp.office365.com',
+        port: 587,
+        secure: false,
+    },
+    yahoo: {
+        host: 'smtp.mail.yahoo.com',
+        port: 587,
+        secure: false,
+    },
+    icloud: {
+        host: 'smtp.mail.me.com',
+        port: 587,
+        secure: false,
+    },
+    zoho: {
+        host: 'smtp.zoho.com',
+        port: 587,
+        secure: false,
+    },
+};
+function getEmailConfig() {
+    // Check for provider-specific config first
+    const provider = (process.env['SMTP_PROVIDER'] || 'gmail').toLowerCase();
+    const user = process.env['SMTP_USER'] || process.env['EMAIL_USER'];
+    const password = process.env['SMTP_PASSWORD'] || process.env['EMAIL_APP_PASSWORD'] || process.env['SMTP_APP_PASSWORD'];
+    if (!user || !password) {
+        return null;
+    }
+    // Get preset or custom config
+    const preset = SMTP_PRESETS[provider];
+    return {
+        provider,
+        host: process.env['SMTP_HOST'] || preset?.host || 'smtp.gmail.com',
+        port: parseInt(process.env['SMTP_PORT'] || String(preset?.port || 587), 10),
+        secure: process.env['SMTP_SECURE'] === 'true' || preset?.secure || false,
+        user,
+        password,
+        fromName: process.env['SMTP_FROM_NAME'] || process.env['EMAIL_FROM_NAME'],
+    };
+}
+async function createTransporter(config) {
+    const transporter = nodemailer.createTransport({
+        host: config.host,
+        port: config.port,
+        secure: config.secure,
+        auth: {
+            user: config.user,
+            pass: config.password,
+        },
+        tls: {
+            // Allow self-signed certificates for custom SMTP servers
+            rejectUnauthorized: process.env['SMTP_REJECT_UNAUTHORIZED'] !== 'false',
+        },
+    });
+    // Verify connection
+    await transporter.verify();
+    return transporter;
+}
+export function createEmailTools() {
+    return [
+        {
+            name: 'send_email',
+            description: `Send an email via SMTP. Supports Gmail, Outlook, Yahoo, iCloud, Zoho, and custom SMTP servers.
+
+Configuration (set via /secrets or environment variables):
+- SMTP_USER or EMAIL_USER: Your email address
+- SMTP_PASSWORD or EMAIL_APP_PASSWORD: Your app password (NOT your regular password)
+- SMTP_PROVIDER: gmail, outlook, yahoo, icloud, zoho (default: gmail)
+- SMTP_FROM_NAME: Display name for sent emails (optional)
+
+For Gmail:
+1. Enable 2-Factor Authentication
+2. Go to https://myaccount.google.com/apppasswords
+3. Generate an app password for "Mail"
+4. Use that app password as SMTP_PASSWORD
+
+For Outlook/Hotmail:
+1. Go to https://account.live.com/proofs/AppPassword
+2. Generate an app password
+3. Use that as SMTP_PASSWORD
+
+Use cases:
+- Send notifications, reports, or alerts
+- Automated outreach (investors, leads, contacts)
+- Send formatted HTML emails with attachments
+- Batch email campaigns with personalization`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    to: {
+                        type: 'string',
+                        description: 'Recipient email address(es). For multiple recipients, use comma-separated values.',
+                    },
+                    subject: {
+                        type: 'string',
+                        description: 'Email subject line',
+                    },
+                    body: {
+                        type: 'string',
+                        description: 'Email body content. Can be plain text or HTML.',
+                    },
+                    html: {
+                        type: 'boolean',
+                        description: 'Set to true if body contains HTML content (default: false)',
+                    },
+                    cc: {
+                        type: 'string',
+                        description: 'CC recipient(s), comma-separated (optional)',
+                    },
+                    bcc: {
+                        type: 'string',
+                        description: 'BCC recipient(s), comma-separated (optional)',
+                    },
+                    reply_to: {
+                        type: 'string',
+                        description: 'Reply-To address (optional)',
+                    },
+                    attachments: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                filename: { type: 'string' },
+                                path: { type: 'string', description: 'File path to attach' },
+                                content: { type: 'string', description: 'Base64 encoded content (alternative to path)' },
+                            },
+                        },
+                        description: 'Array of attachments (optional)',
+                    },
+                },
+                required: ['to', 'subject', 'body'],
+            },
+            handler: async (args) => {
+                const config = getEmailConfig();
+                if (!config) {
+                    return `Email not configured. Please set up SMTP credentials:
+
+Required environment variables:
+- SMTP_USER or EMAIL_USER: Your email address
+- SMTP_PASSWORD or EMAIL_APP_PASSWORD: Your app password
+
+Optional:
+- SMTP_PROVIDER: gmail, outlook, yahoo, icloud, zoho (default: gmail)
+- SMTP_FROM_NAME: Display name for sent emails
+
+For Gmail, create an app password at: https://myaccount.google.com/apppasswords
+For Outlook, create an app password at: https://account.live.com/proofs/AppPassword
+
+Use /secrets to configure these values.`;
+                }
+                const to = args['to'];
+                const subject = args['subject'];
+                const body = args['body'];
+                const isHtml = args['html'] === true;
+                const cc = args['cc'];
+                const bcc = args['bcc'];
+                const replyTo = args['reply_to'];
+                const attachments = args['attachments'];
+                if (!to || !subject || !body) {
+                    return 'Error: to, subject, and body are required parameters.';
+                }
+                try {
+                    const transporter = await createTransporter(config);
+                    const fromAddress = config.fromName
+                        ? `"${config.fromName}" <${config.user}>`
+                        : config.user;
+                    const mailOptions = {
+                        from: fromAddress,
+                        to,
+                        subject,
+                        ...(isHtml ? { html: body } : { text: body }),
+                        ...(cc && { cc }),
+                        ...(bcc && { bcc }),
+                        ...(replyTo && { replyTo }),
+                        ...(attachments && {
+                            attachments: attachments.map(att => ({
+                                filename: att.filename,
+                                ...(att.path ? { path: att.path } : {}),
+                                ...(att.content ? { content: att.content, encoding: 'base64' } : {}),
+                            })),
+                        }),
+                    };
+                    const info = await transporter.sendMail(mailOptions);
+                    return `✅ Email sent successfully!
+
+To: ${to}
+Subject: ${subject}
+Message ID: ${info.messageId}
+Provider: ${config.provider}
+${cc ? `CC: ${cc}` : ''}
+${bcc ? `BCC: ${bcc}` : ''}
+${attachments?.length ? `Attachments: ${attachments.length} file(s)` : ''}
+
+Response: ${info.response || 'Accepted'}`;
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    // Provide helpful error messages
+                    if (errorMessage.includes('Invalid login') || errorMessage.includes('authentication')) {
+                        return `❌ Authentication failed.
+
+Error: ${errorMessage}
+
+Common fixes:
+1. Make sure you're using an APP PASSWORD, not your regular password
+2. For Gmail: https://myaccount.google.com/apppasswords
+3. For Outlook: https://account.live.com/proofs/AppPassword
+4. Ensure 2-Factor Authentication is enabled on your account
+5. Check that SMTP_USER matches the email account`;
+                    }
+                    if (errorMessage.includes('ENOTFOUND') || errorMessage.includes('ECONNREFUSED')) {
+                        return `❌ Could not connect to SMTP server.
+
+Error: ${errorMessage}
+
+Current config:
+- Host: ${config.host}
+- Port: ${config.port}
+- Provider: ${config.provider}
+
+Try setting SMTP_HOST and SMTP_PORT manually if using a custom server.`;
+                    }
+                    return `❌ Failed to send email: ${errorMessage}`;
+                }
+            },
+        },
+        {
+            name: 'verify_email_config',
+            description: 'Verify that email/SMTP configuration is correct and can connect to the mail server.',
+            parameters: {
+                type: 'object',
+                properties: {},
+            },
+            handler: async () => {
+                const config = getEmailConfig();
+                if (!config) {
+                    return `❌ Email not configured.
+
+Required environment variables:
+- SMTP_USER or EMAIL_USER
+- SMTP_PASSWORD or EMAIL_APP_PASSWORD
+
+Optional:
+- SMTP_PROVIDER: gmail, outlook, yahoo, icloud, zoho
+- SMTP_HOST, SMTP_PORT: For custom SMTP servers
+- SMTP_FROM_NAME: Display name
+
+Use /secrets to configure these values.`;
+                }
+                try {
+                    await createTransporter(config);
+                    return `✅ Email configuration verified!
+
+Provider: ${config.provider}
+Host: ${config.host}
+Port: ${config.port}
+User: ${config.user}
+Secure: ${config.secure ? 'Yes (SSL/TLS)' : 'No (STARTTLS)'}
+From Name: ${config.fromName || '(not set)'}
+
+SMTP connection successful. You can now use send_email to send emails.`;
+                }
+                catch (error) {
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    return `❌ Email configuration verification failed.
+
+Provider: ${config.provider}
+Host: ${config.host}
+Port: ${config.port}
+User: ${config.user}
+
+Error: ${errorMessage}
+
+Common issues:
+1. Wrong app password (must use app password, not regular password)
+2. 2FA not enabled on email account
+3. Wrong SMTP provider selected
+4. Network/firewall blocking SMTP ports`;
+                }
+            },
+        },
+        {
+            name: 'send_batch_emails',
+            description: `Send personalized emails to multiple recipients in batch.
+
+Useful for:
+- Investor outreach campaigns
+- Lead nurturing sequences
+- Newsletter distribution
+- Bulk notifications with personalization
+
+Supports template variables: {{name}}, {{company}}, {{custom_field}}`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    recipients: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                email: { type: 'string', description: 'Recipient email' },
+                                name: { type: 'string', description: 'Recipient name for personalization' },
+                                company: { type: 'string', description: 'Company name (optional)' },
+                                custom: {
+                                    type: 'object',
+                                    description: 'Custom fields for template substitution',
+                                },
+                            },
+                            required: ['email'],
+                        },
+                        description: 'Array of recipients with personalization data',
+                    },
+                    subject_template: {
+                        type: 'string',
+                        description: 'Subject line template with {{variables}}',
+                    },
+                    body_template: {
+                        type: 'string',
+                        description: 'Email body template with {{variables}}',
+                    },
+                    html: {
+                        type: 'boolean',
+                        description: 'Set to true if body contains HTML (default: false)',
+                    },
+                    delay_ms: {
+                        type: 'number',
+                        description: 'Delay between emails in milliseconds (default: 1000). Helps avoid rate limits.',
+                    },
+                },
+                required: ['recipients', 'subject_template', 'body_template'],
+            },
+            handler: async (args) => {
+                const config = getEmailConfig();
+                if (!config) {
+                    return 'Email not configured. Use /secrets to set SMTP_USER and SMTP_PASSWORD.';
+                }
+                const recipients = args['recipients'];
+                const subjectTemplate = args['subject_template'];
+                const bodyTemplate = args['body_template'];
+                const isHtml = args['html'] === true;
+                const delayMs = args['delay_ms'] || 1000;
+                if (!recipients?.length || !subjectTemplate || !bodyTemplate) {
+                    return 'Error: recipients, subject_template, and body_template are required.';
+                }
+                try {
+                    const transporter = await createTransporter(config);
+                    const fromAddress = config.fromName
+                        ? `"${config.fromName}" <${config.user}>`
+                        : config.user;
+                    const results = [];
+                    for (let i = 0; i < recipients.length; i++) {
+                        const recipient = recipients[i];
+                        if (!recipient)
+                            continue;
+                        // Apply template substitution
+                        const personalizedSubject = applyTemplate(subjectTemplate, recipient);
+                        const personalizedBody = applyTemplate(bodyTemplate, recipient);
+                        try {
+                            await transporter.sendMail({
+                                from: fromAddress,
+                                to: recipient.email,
+                                subject: personalizedSubject,
+                                ...(isHtml ? { html: personalizedBody } : { text: personalizedBody }),
+                            });
+                            results.push({ email: recipient.email, success: true });
+                        }
+                        catch (error) {
+                            results.push({
+                                email: recipient.email,
+                                success: false,
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                        // Delay between emails (except for last one)
+                        if (i < recipients.length - 1 && delayMs > 0) {
+                            await new Promise(resolve => setTimeout(resolve, delayMs));
+                        }
+                    }
+                    const successful = results.filter(r => r.success).length;
+                    const failed = results.filter(r => !r.success);
+                    let summary = `📧 Batch Email Results
+
+Total: ${recipients.length}
+Sent: ${successful}
+Failed: ${failed.length}
+Provider: ${config.provider}
+`;
+                    if (failed.length > 0) {
+                        summary += '\n❌ Failed emails:\n';
+                        for (const f of failed) {
+                            summary += `- ${f.email}: ${f.error}\n`;
+                        }
+                    }
+                    return summary;
+                }
+                catch (error) {
+                    return `❌ Batch email failed: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            },
+        },
+    ];
+}
+function applyTemplate(template, data) {
+    let result = template;
+    // Standard fields
+    result = result.replace(/\{\{email\}\}/gi, data.email);
+    result = result.replace(/\{\{name\}\}/gi, data.name || '');
+    result = result.replace(/\{\{company\}\}/gi, data.company || '');
+    // First name extraction
+    const firstName = data.name?.split(' ')[0] || '';
+    result = result.replace(/\{\{first_name\}\}/gi, firstName);
+    result = result.replace(/\{\{firstName\}\}/gi, firstName);
+    // Custom fields
+    if (data.custom) {
+        for (const [key, value] of Object.entries(data.custom)) {
+            const regex = new RegExp(`\\{\\{${key}\\}\\}`, 'gi');
+            result = result.replace(regex, value);
+        }
+    }
+    // Clean up any remaining unmatched placeholders
+    result = result.replace(/\{\{[^}]+\}\}/g, '');
+    return result;
+}
+export { getEmailConfig };
+//# sourceMappingURL=emailTools.js.map

package/dist/tools/emailTools.js.map

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

package/dist/tools/webTools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webTools.d.ts","sourceRoot":"","sources":["../../src/tools/webTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D,wBAAgB,cAAc,IAAI,cAAc,EAAE,CA0IjD"}
+{"version":3,"file":"webTools.d.ts","sourceRoot":"","sources":["../../src/tools/webTools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAI7D,wBAAgB,cAAc,IAAI,cAAc,EAAE,CAgPjD"}

package/dist/tools/webTools.js

@@ -12,7 +12,7 @@ export function createWebTools() {
 - Use this tool when you need to retrieve and analyze web content
 
 Usage notes:
-  - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions
+  - IMPORTANT: If TAVILY_API_KEY is set, use WebExtract instead for better content extraction
   - The URL must be a fully-formed valid URL
   - HTTP URLs will be automatically upgraded to HTTPS
   - The prompt should describe what information you want to extract from the page
@@ -62,6 +62,95 @@ Summary: This is the content fetched from the URL. In a full implementation, thi
                 }
             },
         },
+        {
+            name: 'WebExtract',
+            description: `- Extracts clean, structured content from one or more URLs using Tavily Extract API
+- Superior to WebFetch for content extraction when TAVILY_API_KEY is available
+- Returns raw text content optimized for LLM consumption
+- Supports batch extraction of up to 20 URLs in a single call
+
+Usage notes:
+  - Requires TAVILY_API_KEY environment variable
+  - Best for extracting article content, documentation, blog posts
+  - Returns clean text without HTML artifacts
+  - More reliable than basic HTML parsing for complex pages
+  - Use for deep content extraction when you need full page text`,
+            parameters: {
+                type: 'object',
+                properties: {
+                    urls: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Array of URLs to extract content from (max 20)',
+                    },
+                },
+                required: ['urls'],
+            },
+            handler: async (args) => {
+                const urls = args['urls'];
+                if (!urls || !Array.isArray(urls) || urls.length === 0) {
+                    return 'Error: urls parameter is required and must be a non-empty array.';
+                }
+                if (urls.length > 20) {
+                    return 'Error: Maximum 20 URLs allowed per request.';
+                }
+                const tavilyKey = process.env['TAVILY_API_KEY']?.trim();
+                if (!tavilyKey) {
+                    return [
+                        'WebExtract requires TAVILY_API_KEY to be set.',
+                        'Get your API key at: https://tavily.com',
+                        '',
+                        'Falling back to WebFetch for basic extraction is available as an alternative.',
+                    ].join('\n');
+                }
+                try {
+                    const response = await fetch('https://api.tavily.com/extract', {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                        },
+                        body: JSON.stringify({
+                            api_key: tavilyKey,
+                            urls: urls,
+                        }),
+                    });
+                    if (!response.ok) {
+                        const errorText = await response.text().catch(() => '');
+                        throw new Error(`Tavily Extract returned HTTP ${response.status}: ${errorText}`);
+                    }
+                    const payload = (await response.json());
+                    const results = payload.results || [];
+                    const failedUrls = payload.failed_results || [];
+                    if (results.length === 0 && failedUrls.length === urls.length) {
+                        return `Failed to extract content from all ${urls.length} URLs. This may be due to access restrictions or invalid URLs.`;
+                    }
+                    let output = `Extracted content from ${results.length}/${urls.length} URLs:\n\n`;
+                    for (const result of results) {
+                        output += `--- ${result.url} ---\n`;
+                        if (result.raw_content) {
+                            // Truncate very long content
+                            const content = result.raw_content.length > 10000
+                                ? result.raw_content.slice(0, 10000) + '\n\n... (content truncated)'
+                                : result.raw_content;
+                            output += `${content}\n\n`;
+                        }
+                        else {
+                            output += '(No content extracted)\n\n';
+                        }
+                    }
+                    if (failedUrls.length > 0) {
+                        output += `\nFailed URLs (${failedUrls.length}):\n`;
+                        for (const failed of failedUrls) {
+                            output += `- ${failed.url}: ${failed.error || 'Unknown error'}\n`;
+                        }
+                    }
+                    return output.trim();
+                }
+                catch (error) {
+                    return `Error extracting content: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            },
+        },
         {
             name: 'WebSearch',
             description: `- Allows Claude to search the web and use the results to inform responses
@@ -109,8 +198,12 @@ Usage notes:
                     const provider = resolveSearchProvider();
                     if (!provider) {
                         return [
-                            'WebSearch requires either BRAVE_SEARCH_API_KEY or SERPAPI_API_KEY.',
+                            'WebSearch requires TAVILY_API_KEY (recommended), BRAVE_SEARCH_API_KEY, or SERPAPI_API_KEY.',
                             'Run /secrets (or set the environment variables directly) to configure an API key.',
+                            '',
+                            'Get your Tavily API key at: https://tavily.com (recommended)',
+                            'Get your Brave Search API key at: https://brave.com/search/api/',
+                            'Get your SerpAPI key at: https://serpapi.com/',
                         ].join('\n');
                     }
                     const results = await provider.search({
@@ -132,6 +225,15 @@ Usage notes:
     ];
 }
 function resolveSearchProvider() {
+    // Tavily is the preferred search provider
+    const tavilyKey = process.env['TAVILY_API_KEY']?.trim();
+    if (tavilyKey) {
+        return {
+            id: 'tavily',
+            label: 'Tavily Search',
+            search: (params) => performTavilySearch(params, tavilyKey),
+        };
+    }
     const braveKey = process.env['BRAVE_SEARCH_API_KEY']?.trim();
     if (braveKey) {
         return {
@@ -199,6 +301,42 @@ async function performSerpApiSearch(params, apiKey) {
         .filter((result) => Boolean(result.url));
     return applyDomainFilters(mapped, params.allowedDomains, params.blockedDomains).slice(0, params.maxResults);
 }
+async function performTavilySearch(params, apiKey) {
+    const response = await fetch('https://api.tavily.com/search', {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            api_key: apiKey,
+            query: params.query,
+            search_depth: 'advanced',
+            include_answer: true,
+            include_raw_content: false,
+            max_results: Math.min(params.maxResults * 2, 10),
+            include_domains: params.allowedDomains.length ? params.allowedDomains : undefined,
+            exclude_domains: params.blockedDomains.length ? params.blockedDomains : undefined,
+        }),
+    });
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => '');
+        throw new Error(`Tavily Search returned HTTP ${response.status}: ${errorText}`);
+    }
+    const payload = (await response.json());
+    const entries = Array.isArray(payload?.results) ? payload.results : [];
+    const mapped = entries
+        .map((entry) => ({
+        title: entry.title || entry.url,
+        url: entry.url,
+        snippet: entry.content || '',
+        source: safeHostname(entry.url) || undefined,
+        published: entry.published_date,
+        score: entry.score,
+    }))
+        .filter((result) => Boolean(result.url));
+    // Tavily already handles domain filtering via include_domains/exclude_domains
+    return mapped.slice(0, params.maxResults);
+}
 function parseDomainList(value) {
     if (!Array.isArray(value)) {
         return [];