@nylas/helix-mcp-server 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * CLI for @nylas/helix-mcp-server.
+ *
+ * Usage:
+ *   npx @nylas/helix-mcp-server --setup   # Interactive setup: device code flow → registers Claude Code over HTTP
+ *   npx @nylas/helix-mcp-server            # Prints migration guidance for legacy stdio setups
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAEA;;;;;;GAMG"}

package/dist/cli.js

@@ -0,0 +1,233 @@
+#!/usr/bin/env node
+/**
+ * CLI for @nylas/helix-mcp-server.
+ *
+ * Usage:
+ *   npx @nylas/helix-mcp-server --setup   # Interactive setup: device code flow → registers Claude Code over HTTP
+ *   npx @nylas/helix-mcp-server            # Prints migration guidance for legacy stdio setups
+ */
+import { execFile } from 'node:child_process';
+const DEFAULT_HELIX_URL = 'https://helix.nylas.com';
+const CONFIGURED_HELIX_URL = process.env.HELIX_URL || DEFAULT_HELIX_URL;
+const HELIX_URL = normalizeHelixUrl(CONFIGURED_HELIX_URL);
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes('--setup')) {
+        await runSetup();
+    }
+    else if (args.includes('--uninstall')) {
+        await runUninstall();
+    }
+    else {
+        console.error('[helix-mcp] Usage:');
+        console.error('  npx @nylas/helix-mcp-server --setup       # Set up Helix MCP in Claude Code');
+        console.error('  npx @nylas/helix-mcp-server --uninstall   # Remove Helix MCP from Claude Code');
+        process.exit(1);
+    }
+}
+async function runSetup() {
+    console.log('');
+    console.log('  Helix MCP Server Setup');
+    console.log('  ──────────────────────');
+    console.log('');
+    if (HELIX_URL !== CONFIGURED_HELIX_URL) {
+        console.log(`  Using ${HELIX_URL} for local auth so dashboard cookies work.`);
+        console.log('');
+    }
+    // Step 1: Register as an OAuth client via DCR
+    console.log('  Registering with Helix...');
+    let clientId = '';
+    try {
+        const registerRes = await fetch(`${HELIX_URL}/oauth/register`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                client_name: 'Claude Code',
+                redirect_uris: ['urn:ietf:wg:oauth:2.0:oob'],
+                grant_types: ['urn:ietf:params:oauth:grant-type:device_code', 'refresh_token'],
+                response_types: ['code'],
+                token_endpoint_auth_method: 'none',
+            }),
+        });
+        if (!registerRes.ok) {
+            const err = await registerRes.text();
+            console.error(`  Failed to register: ${err}`);
+            process.exit(1);
+        }
+        const registration = await registerRes.json();
+        clientId = registration.client_id;
+    }
+    catch (e) {
+        console.error(`  Could not reach ${HELIX_URL}. Is it running?`);
+        process.exit(1);
+    }
+    // Step 2: Request device code
+    console.log('  Requesting device code...');
+    const scope = 'email.read email.send calendar.read calendar.write contacts.read identity.read';
+    const deviceRes = await fetch(`${HELIX_URL}/oauth/device/code`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ client_id: clientId, scope }),
+    });
+    if (!deviceRes.ok) {
+        const err = await deviceRes.text();
+        console.error(`  Failed to get device code: ${err}`);
+        process.exit(1);
+    }
+    const device = await deviceRes.json();
+    // Step 3: Show code and open browser
+    console.log('');
+    console.log(`  Your code:  ${device.user_code}`);
+    console.log('');
+    console.log(`  Opening ${device.verification_uri_complete}`);
+    console.log('  Paste the code above if prompted.');
+    console.log('');
+    openBrowser(device.verification_uri_complete);
+    // Step 4: Poll for approval
+    console.log('  Waiting for approval...');
+    const pollInterval = (device.interval || 5) * 1000;
+    const deadline = Date.now() + device.expires_in * 1000;
+    const tokens = await new Promise((resolve, reject) => {
+        const poll = async () => {
+            if (Date.now() > deadline) {
+                reject(new Error('Device code expired. Run setup again.'));
+                return;
+            }
+            try {
+                const tokenRes = await fetch(`${HELIX_URL}/oauth/token`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                    body: new URLSearchParams({
+                        grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+                        device_code: device.device_code,
+                        client_id: clientId,
+                    }),
+                });
+                if (tokenRes.ok) {
+                    resolve(await tokenRes.json());
+                    return;
+                }
+                const err = await tokenRes.json();
+                if (err.error === 'authorization_pending') {
+                    setTimeout(poll, pollInterval);
+                    return;
+                }
+                if (err.error === 'slow_down') {
+                    setTimeout(poll, pollInterval * 2);
+                    return;
+                }
+                reject(new Error(`Authorization failed: ${err.error}`));
+            }
+            catch (e) {
+                reject(e);
+            }
+        };
+        setTimeout(poll, pollInterval);
+    });
+    // Step 5: Register Claude Code MCP config
+    console.log('  Writing Claude Code config...');
+    const mcpEndpoint = buildMcpEndpoint(HELIX_URL);
+    const manualCommand = buildClaudeCodeRegistrationCommand(mcpEndpoint, tokens.access_token);
+    const registeredWithClaudeCli = await registerWithClaudeCli(mcpEndpoint, tokens.access_token);
+    console.log('');
+    console.log('  Done. Helix is now available in Claude Code.');
+    console.log('');
+    if (registeredWithClaudeCli) {
+        console.log('  Registered via: claude mcp add --transport http -s user helix ...');
+        console.log('  Verify with:   claude mcp get helix');
+    }
+    else {
+        console.log('  Automatic Claude CLI registration failed.');
+        console.log('  Run this command manually:');
+        console.log(`  ${manualCommand}`);
+    }
+    console.log('  Restart Claude Code to activate.');
+    console.log('');
+}
+async function runUninstall() {
+    console.log('');
+    console.log('  Helix MCP Server Uninstall');
+    console.log('  ──────────────────────────');
+    console.log('');
+    try {
+        await execFileAsync('claude', ['mcp', 'remove', 'helix', '-s', 'user']);
+        console.log('  Removed helix MCP server from Claude Code.');
+    }
+    catch {
+        console.log('  helix MCP server was not registered in Claude Code.');
+    }
+    console.log('');
+    console.log('  Done. Restart Claude Code to apply.');
+    console.log('');
+}
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', url] : [url];
+    execFile(cmd, args, (err) => {
+        if (err) {
+            console.log(`  Open this URL in your browser:`);
+            console.log(`  ${url}`);
+        }
+    });
+}
+function buildMcpEndpoint(helixUrl) {
+    return `${helixUrl.replace(/\/+$/, '')}/mcp`;
+}
+function buildClaudeCodeRegistrationCommand(mcpEndpoint, accessToken) {
+    return `claude mcp add --transport http -s user helix ${mcpEndpoint} --header 'Authorization: Bearer ${accessToken}'`;
+}
+async function registerWithClaudeCli(mcpEndpoint, accessToken) {
+    try {
+        await execFileAsync('claude', ['mcp', 'remove', 'helix', '-s', 'user']);
+    }
+    catch {
+        // Ignore; the server may not exist yet.
+    }
+    try {
+        await execFileAsync('claude', [
+            'mcp',
+            'add',
+            '--transport',
+            'http',
+            '-s',
+            'user',
+            'helix',
+            mcpEndpoint,
+            '--header',
+            `Authorization: Bearer ${accessToken}`,
+        ]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function execFileAsync(command, args) {
+    return new Promise((resolve, reject) => {
+        execFile(command, args, (err) => {
+            if (err) {
+                reject(err);
+                return;
+            }
+            resolve();
+        });
+    });
+}
+function normalizeHelixUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.hostname === '127.0.0.1' || parsed.hostname === '[::1]' || parsed.hostname === '::1') {
+            parsed.hostname = 'localhost';
+            return parsed.toString().replace(/\/$/, '');
+        }
+        return parsed.toString().replace(/\/$/, '');
+    }
+    catch {
+        return url.replace(/\/$/, '');
+    }
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/html-to-markdown.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Lightweight HTML email → Markdown converter.
+ *
+ * Applies the same heuristic philosophy as the web reader engine
+ * (noise detection, boilerplate/tracker stripping, signature detection)
+ * but works without a DOM parser so it runs in Node, Deno, and Workers.
+ *
+ * Designed for email HTML — not arbitrary web pages.
+ */
+/**
+ * Convert an HTML email body to clean Markdown.
+ * Returns the original string if it doesn't look like HTML.
+ */
+export declare function htmlToMarkdown(html: string): string;
+//# sourceMappingURL=html-to-markdown.d.ts.map

package/dist/html-to-markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-to-markdown.d.ts","sourceRoot":"","sources":["../src/html-to-markdown.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAyCH;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmJnD"}

package/dist/html-to-markdown.js

@@ -0,0 +1,234 @@
+/**
+ * Lightweight HTML email → Markdown converter.
+ *
+ * Applies the same heuristic philosophy as the web reader engine
+ * (noise detection, boilerplate/tracker stripping, signature detection)
+ * but works without a DOM parser so it runs in Node, Deno, and Workers.
+ *
+ * Designed for email HTML — not arbitrary web pages.
+ */
+// ── Patterns ────────────────────────────────────────────────
+const BLOCK_TAGS = new Set([
+    'p', 'div', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'li', 'tr', 'td', 'th', 'blockquote', 'pre',
+    'ul', 'ol', 'table', 'hr', 'br', 'dt', 'dd',
+    'section', 'article', 'header', 'footer', 'main', 'aside', 'nav',
+]);
+const STRIP_TAGS = new Set([
+    'script', 'style', 'noscript', 'iframe', 'object', 'embed',
+    'svg', 'canvas', 'form', 'input', 'button', 'select', 'textarea',
+    'head', 'meta', 'link', 'template',
+]);
+const BOILERPLATE_PATTERN = /unsubscribe|email.preferences|opt.?out|manage.*subscription|privacy.?policy|view.in.browser|view.this.email|trouble.viewing|add.us.to.your|no.longer.wish|mailing.list|this.email.was.sent|^\s*sent.from.my/i;
+const TRACKER_HOST_PATTERN = /hubspotlinks\.com|hs-analytics\.net|mandrillapp\.com|mailchi\.mp|list-manage\.com|sendgrid\.net|mailgun\.(org|us)|\.click\.|\.trk\./i;
+const SIGNATURE_PATTERN = /^(\-\-\s*$|regards,|best,|thanks,|cheers,|sincerely,|kind regards|sent from my|get outlook)/im;
+const QUOTED_REPLY_PATTERN = /^(on\s.+\swrote:$|from:\s|sent:\s|_{5,}|>{1,}\s)/im;
+/** Entity map for the most common HTML entities */
+const ENTITY_MAP = {
+    '&amp;': '&', '&lt;': '<', '&gt;': '>', '&quot;': '"',
+    '&#39;': "'", '&apos;': "'", '&nbsp;': ' ', '&mdash;': '—',
+    '&ndash;': '–', '&laquo;': '«', '&raquo;': '»', '&hellip;': '…',
+    '&bull;': '•', '&middot;': '·', '&copy;': '©', '&reg;': '®',
+    '&trade;': '™', '&rsquo;': '\u2019', '&lsquo;': '\u2018',
+    '&rdquo;': '\u201D', '&ldquo;': '\u201C',
+};
+// ── Core converter ──────────────────────────────────────────
+/**
+ * Convert an HTML email body to clean Markdown.
+ * Returns the original string if it doesn't look like HTML.
+ */
+export function htmlToMarkdown(html) {
+    const source = html.trim();
+    if (!source)
+        return '';
+    if (!looksLikeHtml(source))
+        return normalizeWhitespace(source);
+    let work = source;
+    // 1. Strip invisible / dangerous tags (with their content)
+    for (const tag of STRIP_TAGS) {
+        work = work.replace(new RegExp(`<${tag}[^>]*>[\\s\\S]*?<\\/${tag}>`, 'gi'), '');
+    }
+    // 2. Strip HTML comments
+    work = work.replace(/<!--[\s\S]*?-->/g, '');
+    // 3. Convert block-level structure to markdown before stripping tags
+    // Headings
+    work = work.replace(/<h([1-6])[^>]*>([\s\S]*?)<\/h\1>/gi, (_m, level, content) => {
+        const text = stripTags(content).trim();
+        if (!text)
+            return '';
+        return `\n${'#'.repeat(Number(level))} ${text}\n`;
+    });
+    // Blockquotes
+    work = work.replace(/<blockquote[^>]*>([\s\S]*?)<\/blockquote>/gi, (_m, content) => {
+        const text = stripTags(content).trim();
+        if (!text)
+            return '';
+        return `\n${text.split('\n').map((line) => `> ${line}`).join('\n')}\n`;
+    });
+    // Preformatted
+    work = work.replace(/<pre[^>]*>([\s\S]*?)<\/pre>/gi, (_m, content) => {
+        const text = decodeEntities(content.replace(/<br\s*\/?>/gi, '\n').replace(/<[^>]+>/g, ''));
+        return `\n\`\`\`\n${text}\n\`\`\`\n`;
+    });
+    // Code (inline)
+    work = work.replace(/<code[^>]*>([\s\S]*?)<\/code>/gi, (_m, content) => {
+        const text = stripTags(content).trim();
+        return text ? `\`${text}\`` : '';
+    });
+    // Lists — ordered
+    work = work.replace(/<ol[^>]*>([\s\S]*?)<\/ol>/gi, (_m, content) => {
+        let idx = 0;
+        return `\n${content.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, (_lm, li) => {
+            idx++;
+            return `${idx}. ${stripTags(li).trim()}\n`;
+        })}`;
+    });
+    // Lists — unordered
+    work = work.replace(/<ul[^>]*>([\s\S]*?)<\/ul>/gi, (_m, content) => {
+        return `\n${content.replace(/<li[^>]*>([\s\S]*?)<\/li>/gi, (_lm, li) => {
+            return `- ${stripTags(li).trim()}\n`;
+        })}`;
+    });
+    // Table rows → pipe-separated (simple)
+    work = work.replace(/<table[^>]*>([\s\S]*?)<\/table>/gi, (_m, content) => {
+        const rows = [];
+        const rowPattern = /<tr[^>]*>([\s\S]*?)<\/tr>/gi;
+        let rowMatch;
+        while ((rowMatch = rowPattern.exec(content)) !== null) {
+            const cells = [];
+            const cellPattern = /<(?:td|th)[^>]*>([\s\S]*?)<\/(?:td|th)>/gi;
+            let cellMatch;
+            const rowContent = rowMatch[1] ?? '';
+            while ((cellMatch = cellPattern.exec(rowContent)) !== null) {
+                cells.push(stripTags(cellMatch[1] ?? '').trim());
+            }
+            if (cells.length > 0 && cells.some(c => c.length > 0)) {
+                rows.push(`| ${cells.join(' | ')} |`);
+            }
+        }
+        if (rows.length === 0)
+            return '';
+        const firstRow = rows[0];
+        // Add separator after first row (treat as header)
+        const sep = `| ${firstRow.split('|').slice(1, -1).map(() => '---').join(' | ')} |`;
+        return `\n${firstRow}\n${sep}\n${rows.slice(1).join('\n')}\n`;
+    });
+    // Horizontal rules
+    work = work.replace(/<hr[^>]*\/?>/gi, '\n---\n');
+    // Line breaks
+    work = work.replace(/<br\s*\/?>/gi, '\n');
+    // Bold / strong
+    work = work.replace(/<(?:strong|b)[^>]*>([\s\S]*?)<\/(?:strong|b)>/gi, (_m, c) => {
+        const t = stripTags(c).trim();
+        return t ? `**${t}**` : '';
+    });
+    // Italic / emphasis
+    work = work.replace(/<(?:em|i)[^>]*>([\s\S]*?)<\/(?:em|i)>/gi, (_m, c) => {
+        const t = stripTags(c).trim();
+        return t ? `*${t}*` : '';
+    });
+    // Strikethrough
+    work = work.replace(/<(?:del|s|strike)[^>]*>([\s\S]*?)<\/(?:del|s|strike)>/gi, (_m, c) => {
+        const t = stripTags(c).trim();
+        return t ? `~~${t}~~` : '';
+    });
+    // Links — preserve href as markdown link
+    work = work.replace(/<a[^>]*href=["']([^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi, (_m, href, content) => {
+        const text = stripTags(content).trim();
+        const cleanHref = decodeEntities(href.trim());
+        if (!text)
+            return '';
+        if (!cleanHref || cleanHref.startsWith('javascript:') || cleanHref.startsWith('data:'))
+            return text;
+        // Skip tracker URLs — just show the link text
+        if (TRACKER_HOST_PATTERN.test(cleanHref))
+            return text;
+        // If text is just the URL, use bare URL
+        if (text === cleanHref || text === cleanHref.replace(/^https?:\/\//, ''))
+            return cleanHref;
+        return `[${text}](${cleanHref})`;
+    });
+    // Images — alt text only (email images are usually decorative)
+    work = work.replace(/<img[^>]*alt=["']([^"']+)["'][^>]*\/?>/gi, (_m, alt) => {
+        const text = alt.trim();
+        return text && text.length > 2 ? `[${text}]` : '';
+    });
+    // Remove remaining images without useful alt
+    work = work.replace(/<img[^>]*\/?>/gi, '');
+    // 4. Insert paragraph breaks for remaining block tags
+    for (const tag of BLOCK_TAGS) {
+        work = work.replace(new RegExp(`<${tag}[^>]*>`, 'gi'), '\n');
+        work = work.replace(new RegExp(`</${tag}>`, 'gi'), '\n');
+    }
+    // 5. Strip any remaining HTML tags
+    work = stripTags(work);
+    // 6. Decode entities
+    work = decodeEntities(work);
+    // 7. Normalize whitespace
+    work = normalizeWhitespace(work);
+    // 8. Apply heuristics — strip boilerplate, signatures, quoted replies
+    work = applyEmailHeuristics(work);
+    return work.trim();
+}
+// ── Heuristics ──────────────────────────────────────────────
+function applyEmailHeuristics(text) {
+    const lines = text.split('\n');
+    const output = [];
+    let hitSignature = false;
+    let hitQuotedReply = false;
+    for (const line of lines) {
+        // Stop at signature boundary
+        if (!hitSignature && SIGNATURE_PATTERN.test(line)) {
+            // Keep the closing line itself (e.g., "Best, Alex") but stop after
+            if (/^(regards,|best,|thanks,|cheers,|sincerely,|kind regards)/i.test(line.trim())) {
+                output.push(line);
+            }
+            hitSignature = true;
+            continue;
+        }
+        if (hitSignature)
+            continue;
+        // Stop at quoted reply boundary
+        if (!hitQuotedReply && QUOTED_REPLY_PATTERN.test(line)) {
+            hitQuotedReply = true;
+            continue;
+        }
+        if (hitQuotedReply)
+            continue;
+        // Skip boilerplate lines
+        if (BOILERPLATE_PATTERN.test(line) && line.trim().length < 400)
+            continue;
+        output.push(line);
+    }
+    return output.join('\n');
+}
+// ── Helpers ─────────────────────────────────────────────────
+function looksLikeHtml(source) {
+    return /<[a-z][\s\S]*?>/i.test(source.slice(0, 1000));
+}
+function stripTags(html) {
+    return decodeEntities(html.replace(/<[^>]+>/g, ''));
+}
+function decodeEntities(text) {
+    let result = text;
+    for (const [entity, char] of Object.entries(ENTITY_MAP)) {
+        result = result.split(entity).join(char);
+    }
+    // Numeric entities
+    result = result.replace(/&#x([0-9a-f]+);/gi, (_m, hex) => String.fromCodePoint(Number.parseInt(hex, 16)));
+    result = result.replace(/&#(\d+);/g, (_m, dec) => String.fromCodePoint(Number(dec)));
+    return result;
+}
+function normalizeWhitespace(text) {
+    return text
+        // Collapse runs of spaces/tabs (not newlines)
+        .replace(/[^\S\n]+/g, ' ')
+        // Collapse 3+ consecutive newlines to 2
+        .replace(/\n{3,}/g, '\n\n')
+        // Trim leading/trailing whitespace per line
+        .split('\n')
+        .map((line) => line.trim())
+        .join('\n')
+        .trim();
+}
+//# sourceMappingURL=html-to-markdown.js.map

package/dist/html-to-markdown.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createMcpServer, type McpContext } from './server.js';
+export { emailTools } from './tools/email.js';
+export { calendarTools } from './tools/calendar.js';
+export { contactsTools } from './tools/contacts.js';
+export { identityTools } from './tools/identity.js';
+export type { ToolDefinition, ToolCategory } from './tools/types.js';
+export type { ResponseDetail, BodyFormat } from './shape-response.js';
+export { htmlToMarkdown } from './html-to-markdown.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,YAAY,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpE,YAAY,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createMcpServer } from './server.js';
+export { emailTools } from './tools/email.js';
+export { calendarTools } from './tools/calendar.js';
+export { contactsTools } from './tools/contacts.js';
+export { identityTools } from './tools/identity.js';
+export { htmlToMarkdown } from './html-to-markdown.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAmB,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAGnD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA"}

package/dist/server.d.ts

@@ -0,0 +1,49 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ToolCategory } from './tools/types.js';
+import { type ResponseDetail, type BodyFormat } from './shape-response.js';
+export interface NylasApiClient {
+    fetch(path: string, init?: RequestInit): Promise<Response>;
+}
+export interface McpContext {
+    userId: string;
+    grantId: string;
+    scopes: string[];
+    nylasApiUrl: string;
+    nylasApiKey: string;
+    /** Resolve the best grant for a capability (falls back from primary to any capable grant). */
+    resolveGrantId?: (capability: string) => Promise<string>;
+    /** Check whether an action requires approval. Returns approved=false if pending. */
+    checkApproval?: (actionType: string, payload: unknown, summary: string) => Promise<{
+        approved: boolean;
+        pendingActionId?: string;
+    }>;
+    /** Log an action to the audit trail. */
+    logAction?: (actionType: string, source: string, summary: string, status: 'success' | 'error' | 'pending_approval') => Promise<void>;
+    /** Log any tool call (reads + writes) to the audit trail. */
+    logToolCall?: (toolName: string, args: Record<string, unknown>, durationMs: number) => Promise<void>;
+    /** Identity data for context-aware responses. */
+    identity?: {
+        displayName: string;
+        tone: string;
+        verbosity: string;
+        customInstructions: string | null;
+        approvalPolicy: string;
+        capabilities: string[];
+        templateId: string | null;
+    };
+    /** Token optimization settings. */
+    tokenOptimization?: {
+        responseDetail: ResponseDetail;
+        enabledTools: ToolCategory[];
+        maxBodyLength?: number;
+        /** Format for email body content: 'html' (raw), 'text' (stripped), 'markdown' (heuristic conversion). Default: 'text'. */
+        bodyFormat?: BodyFormat;
+    };
+}
+/**
+ * Create an MCP server with AI identity tools registered.
+ * The server is stateless — context is provided per-request via the API client.
+ * Tools are filtered by enabledTools and responses shaped by responseDetail.
+ */
+export declare function createMcpServer(getContext: () => Promise<McpContext>): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAA;AAKnE,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAA;AACpE,OAAO,EAAqB,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAE7F,MAAM,WAAW,cAAc;IAC9B,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAC1D;AAED,MAAM,WAAW,UAAU;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;IACnB,8FAA8F;IAC9F,cAAc,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IACxD,oFAAoF;IACpF,aAAa,CAAC,EAAE,CACf,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,MAAM,KACX,OAAO,CAAC;QAAE,QAAQ,EAAE,OAAO,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC7D,wCAAwC;IACxC,SAAS,CAAC,EAAE,CACX,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,kBAAkB,KAC5C,OAAO,CAAC,IAAI,CAAC,CAAA;IAClB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,CACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,UAAU,EAAE,MAAM,KACd,OAAO,CAAC,IAAI,CAAC,CAAA;IAClB,iDAAiD;IACjD,QAAQ,CAAC,EAAE;QACV,WAAW,EAAE,MAAM,CAAA;QACnB,IAAI,EAAE,MAAM,CAAA;QACZ,SAAS,EAAE,MAAM,CAAA;QACjB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAA;QACjC,cAAc,EAAE,MAAM,CAAA;QACtB,YAAY,EAAE,MAAM,EAAE,CAAA;QACtB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KACzB,CAAA;IACD,mCAAmC;IACnC,iBAAiB,CAAC,EAAE;QACnB,cAAc,EAAE,cAAc,CAAA;QAC9B,YAAY,EAAE,YAAY,EAAE,CAAA;QAC5B,aAAa,CAAC,EAAE,MAAM,CAAA;QACtB,0HAA0H;QAC1H,UAAU,CAAC,EAAE,UAAU,CAAA;KACvB,CAAA;CACD;AAQD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,aA8GpE"}