@sendinel/mcp-server 1.0.81 → 1.0.83

package/build/tools/contacts.js

@@ -1140,7 +1140,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             idempotentHint: false,
             openWorldHint: false,
         },
-        description: 'Add a contact and subscribe them to a site',
+        description: 'Add a contact and subscribe them to a site. Existing contacts keep their source and stored fields; the response includes existing: true.',
         inputSchema: {
             email: z.string().email(),
             site_id: z.string().uuid(),
@@ -1157,6 +1157,7 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
             utm_term: z.string().optional(),
         },
     }, async ({ email, site_id, first_name, last_name, company_id, company_name, company_domain, source, utm_source, utm_medium, utm_campaign, utm_content, utm_term }) => {
+        email = email.trim().toLowerCase();
         const projectId = getProjectId();
         const embedOk = await hasCompaniesEmbed(projectId);
         const resolvedCompanyId = await resolveCompanyId(projectId, { company_id, company_name, company_domain });
@@ -1174,23 +1175,30 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
         // Check if site requires double opt-in
         const { data: siteInfo } = await db().from('sites').select('double_opt_in').eq('id', site_id).maybeSingle();
         const needsConfirm = siteInfo?.double_opt_in === true;
-        const { data: existingContact } = await db()
+        let { data: existingContact, error: lookupError } = await db()
             .from('subscribers')
-            .select('id')
+            .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
             .eq('project_id', projectId)
             .eq('email', email)
             .maybeSingle();
-        const row = { project_id: projectId, email, first_name, last_name, company_id: resolvedCompanyId, source, source_site: site_id };
+        if (lookupError)
+            return txt(`Error looking up contact: ${lookupError.message}`);
+        let customProperties;
         if (company_name || company_domain) {
             const orgId = await getProjectOrgId(projectId);
-            row.custom_properties = await normalizeMcpContactPropertyPatch({
+            customProperties = await normalizeMcpContactPropertyPatch({
                 ...(company_name ? { company_name } : {}),
                 ...(company_domain ? { company_domain: company_domain.trim().toLowerCase() } : {}),
             }, { orgId, projectId });
         }
-        if (!needsConfirm)
-            row.opted_in_at = new Date().toISOString();
+        const selection = embedOk ? '*, company:companies(id, name, domain)' : '*';
+        let contact;
         if (!existingContact) {
+            const row = { project_id: projectId, email, first_name, last_name, company_id: resolvedCompanyId, source, source_site: site_id };
+            if (customProperties)
+                row.custom_properties = customProperties;
+            if (!needsConfirm)
+                row.opted_in_at = new Date().toISOString();
             if (utm_source)
                 row.utm_source = utm_source;
             if (utm_medium)
@@ -1201,30 +1209,76 @@ Requirements: urgency without desperation, acknowledge the gap, one clear CTA, v
                 row.utm_content = utm_content;
             if (utm_term)
                 row.utm_term = utm_term;
+            const { data, error } = await db().from('subscribers')
+                .upsert(row, { onConflict: 'project_id,email', ignoreDuplicates: true })
+                .select(selection).maybeSingle();
+            if (error)
+                return txt(`Error creating contact: ${error.message}`);
+            contact = data;
+            if (!contact) {
+                // A concurrent add won the unique key; its provenance belongs to that insert.
+                const result = await db().from('subscribers')
+                    .select('id, source, first_name, last_name, company_id, custom_properties, opted_in_at')
+                    .eq('project_id', projectId).eq('email', email).single();
+                if (result.error)
+                    return txt(`Error looking up contact: ${result.error.message}`);
+                existingContact = result.data;
+            }
         }
-        const { data: contact, error: cErr } = await db()
-            .from('subscribers')
-            .upsert(row, { onConflict: 'project_id,email' })
-            .select(embedOk ? '*, company:companies(id, name, domain)' : '*')
-            .single();
-        if (cErr)
-            return { content: [{ type: 'text', text: `Error creating contact: ${cErr.message}` }] };
+        const existing = !!existingContact;
+        if (existingContact) {
+            const empty = (value) => value == null || value === '';
+            const row = {};
+            for (const [key, value] of Object.entries({ first_name, last_name, company_id: resolvedCompanyId })) {
+                if (empty(existingContact[key]) && !empty(value))
+                    row[key] = value;
+            }
+            if (!needsConfirm && existingContact.opted_in_at == null)
+                row.opted_in_at = new Date().toISOString();
+            const missingProperties = Object.fromEntries(Object.entries(customProperties ?? {})
+                .filter(([key]) => !Object.hasOwn(existingContact.custom_properties ?? {}, key)));
+            if (Object.keys(missingProperties).length) {
+                row.custom_properties = { ...(existingContact.custom_properties ?? {}), ...missingProperties };
+            }
+            if (Object.keys(row).length) {
+                let update = db().from('subscribers').update(row)
+                    .eq('id', existingContact.id).eq('project_id', projectId);
+                // The stored values must still match: a concurrent edit always wins over a re-add.
+                for (const key of Object.keys(row)) {
+                    const previous = existingContact[key];
+                    update = previous == null ? update.is(key, null)
+                        : update.eq(key, key === 'custom_properties' ? JSON.stringify(previous) : previous);
+                }
+                const { error } = await update;
+                if (error)
+                    return txt(`Error updating contact: ${error.message}`);
+            }
+            const result = await db().from('subscribers').select(selection)
+                .eq('id', existingContact.id).eq('project_id', projectId).single();
+            if (result.error)
+                return txt(`Error reading contact: ${result.error.message}`);
+            contact = result.data;
+        }
+        const existingMessage = existing ? { message: 'Contact already existed; source and existing fields were not changed.' } : {};
         const { error: subErr } = await db()
             .from('site_subscriptions')
             .upsert({ contact_id: contact.id, site_id, subscribed: !needsConfirm }, { onConflict: 'contact_id,site_id' });
         if (subErr)
             return { content: [{ type: 'text', text: `Contact created but subscription failed: ${subErr.message}` }] };
+        if (existing)
+            logAudit({ action: 'contact.readded', resourceType: 'contact', resourceId: contact.id, details: { email, requested_source: source, existing: true } });
         if (needsConfirm) {
             // Create opt-in token (confirmation email must be sent externally in MCP context)
             await db().from('opt_in_tokens').insert({ contact_id: contact.id, site_id });
             await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
             logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_pending_double_opt_in' });
-            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.' }, null, 2) }] };
+            return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, confirmation: 'pending', message: 'Double opt-in required. Confirmation token created.', ...existingMessage }, null, 2) }] };
         }
         await writeBackMcpContact(projectId, contact, { email, first_name: contact.first_name ?? null, last_name: contact.last_name ?? null });
         logConsent({ contactId: contact.id, siteId: site_id, action: 'grant', consentType: 'email_marketing', source: 'mcp_add_subscriber' });
-        logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
-        return { content: [{ type: 'text', text: JSON.stringify(contact, null, 2) }] };
+        if (!existing)
+            logAudit({ action: 'contact.created', resourceType: 'contact', resourceId: contact.id, details: { email, source } });
+        return { content: [{ type: 'text', text: JSON.stringify({ ...contact, existing, ...existingMessage }, null, 2) }] };
     });
     server.registerTool('import_subscribers', {
         title: 'Import Subscribers',

package/build/tools/gateway.d.ts

@@ -4,11 +4,11 @@ export interface GatewayOptions {
     toolGroups?: string[];
 }
 /**
- * Plain words people use for a tool, so search_tools finds "send email", "welcome" or
- * "last campaign" (#3669). Matched alongside name, group and description.
+ * Plain words people use for a tool (#3669, #4059). The map lives in tool-search.ts so how_to can
+ * share it; re-exported under its original name for compatibility.
  */
 export declare const INTENT_ALIASES: Record<string, string[]>;
-/** Every word of the query must appear somewhere in the tool's text (name, group, description, aliases). */
+/** True when the tool scores above zero for the query (OR semantics; empty query matches everything). */
 export declare function matchesToolQuery(entry: {
     name: string;
     group: string;

package/build/tools/gateway.js

@@ -3,6 +3,7 @@ import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { getRegisteredToolGroups, registerAllTools } from '../server.js';
+import { rankTools, scoreTool, TOOL_ALIASES, tokenize } from './tool-search.js';
 const textResult = (text) => ({ content: [{ type: 'text', text }] });
 const jsonResult = (data) => textResult(JSON.stringify(data, null, 2));
 const notFound = (message) => ({
@@ -10,28 +11,17 @@ const notFound = (message) => ({
     content: [{ type: 'text', text: message }],
 });
 /**
- * Plain words people use for a tool, so search_tools finds "send email", "welcome" or
- * "last campaign" (#3669). Matched alongside name, group and description.
+ * Plain words people use for a tool (#3669, #4059). The map lives in tool-search.ts so how_to can
+ * share it; re-exported under its original name for compatibility.
  */
-export const INTENT_ALIASES = {
-    send_broadcast: ['send email', 'send an email', 'email blast', 'blast', 'newsletter', 'announce', 'announcement', 'one-off email'],
-    list_campaigns: ['last campaign', 'latest campaign', 'recent campaign', 'my campaigns'],
-    get_campaign: ['last campaign', 'campaign details', 'campaign results'],
-    create_campaign: ['welcome', 'welcome email', 'onboarding', 'drip', 'sequence', 'triggered email'],
-    add_campaign_step: ['welcome', 'onboarding', 'follow up email', 'next email in sequence'],
-};
-/** Every word of the query must appear somewhere in the tool's text (name, group, description, aliases). */
+export const INTENT_ALIASES = TOOL_ALIASES;
+/** True when the tool scores above zero for the query (OR semantics; empty query matches everything). */
 export function matchesToolQuery(entry, query) {
-    const q = query.trim().toLowerCase();
-    if (!q)
+    if (!query.trim())
         return true;
-    const haystack = [entry.name, entry.name.replace(/_/g, ' '), entry.group, entry.description, ...(INTENT_ALIASES[entry.name] ?? [])]
-        .join(' \n ')
-        .toLowerCase();
-    if (haystack.includes(q))
-        return true;
-    return q.split(/\s+/).filter(Boolean).every((token) => haystack.includes(token));
+    return scoreTool(entry, tokenize(query), query) > 0;
 }
+const SEARCH_LIMIT = 10;
 async function buildCatalog(options) {
     const innerServer = new McpServer({ name: 'sendinel-gateway-inner', version: '1.0.0' });
     registerAllTools(innerServer, { scopes: options.scopes, toolGroups: options.toolGroups });
@@ -101,14 +91,27 @@ export function registerGatewayTools(server, options) {
         const catalog = await getCatalog();
         const q = query?.trim().toLowerCase() ?? '';
         const requestedGroup = group?.trim();
-        const results = catalog.entries.filter((tool) => {
-            if (requestedGroup && tool.group !== requestedGroup)
-                return false;
-            return matchesToolQuery(tool, q);
-        });
+        const scoped = catalog.entries.filter((tool) => !requestedGroup || tool.group === requestedGroup);
+        const summarize = ({ name, group, description }) => ({ name, group, description });
+        if (!q) {
+            return jsonResult({ tools: scoped.map(summarize), total: scoped.length });
+        }
+        const { matches, nearest } = rankTools(scoped, q);
+        if (matches.length === 0) {
+            return jsonResult({
+                tools: [],
+                total: 0,
+                none_matched: true,
+                nearest: nearest.map(({ entry }) => summarize(entry)),
+                hint: 'No tool matched that phrasing. The nearest tools are listed; try a shorter keyword, or browse with the group filter.',
+            });
+        }
+        const top = matches.slice(0, SEARCH_LIMIT);
         return jsonResult({
-            tools: results.map(({ name, group, description }) => ({ name, group, description })),
-            total: results.length,
+            tools: top.map(({ entry }) => summarize(entry)),
+            total: matches.length,
+            ranked: true,
+            ...(matches.length > top.length ? { truncated: true } : {}),
         });
     });
     server.registerTool('describe_tool', {

package/build/tools/tool-search.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Ranked plain-language tool search (#4059). Shared by search_tools today and by how_to later:
+ * tokenize -> drop stopwords -> stem simple plurals -> score (OR semantics) -> rank.
+ */
+export interface SearchableTool {
+    name: string;
+    group: string;
+    description: string;
+}
+export interface ScoredTool<T extends SearchableTool = SearchableTool> {
+    entry: T;
+    score: number;
+}
+export interface RankResult<T extends SearchableTool = SearchableTool> {
+    /** Every tool with score > 0, best first (not truncated). */
+    matches: ScoredTool<T>[];
+    /** Closest tools when nothing matched; empty only when `entries` is empty. */
+    nearest: ScoredTool<T>[];
+}
+/** Exactly the list from #4059. */
+export declare const STOPWORDS: ReadonlySet<string>;
+/**
+ * Plain words people use for a tool (#3669, #4059). One map, shared with how_to's recipe synonyms.
+ * Only tools that exist in the registry belong here.
+ */
+export declare const TOOL_ALIASES: Record<string, string[]>;
+/** Simple plurals only; leaves the word alone when stripping would leave fewer than 4 characters. */
+export declare function stem(token: string): string;
+/** Lowercase, split, drop stopwords, stem. A query made only of stopwords keeps them so it still searches. */
+export declare function tokenize(query: string): string[];
+/**
+ * Tiers are strictly ordered: exact name > alias phrase > per-token hits (name > alias > group >
+ * description, best tier per token, summed: OR semantics). 0 means no match.
+ */
+export declare function scoreTool(entry: SearchableTool, queryTokens: string[], rawQuery: string, aliases?: Record<string, string[]>): number;
+export declare function rankTools<T extends SearchableTool>(entries: T[], query: string, options?: {
+    limit?: number;
+    aliases?: Record<string, string[]>;
+    nearestLimit?: number;
+}): RankResult<T>;

package/build/tools/tool-search.js

@@ -0,0 +1,140 @@
+/**
+ * Ranked plain-language tool search (#4059). Shared by search_tools today and by how_to later:
+ * tokenize -> drop stopwords -> stem simple plurals -> score (OR semantics) -> rank.
+ */
+/** Exactly the list from #4059. */
+export const STOPWORDS = new Set([
+    'how', 'do', 'does', 'i', 'my', 'me', 'a', 'an', 'the', 'to', 'of', 'for',
+    'why', 'can', 'what', 'is', 'did', 'get', 'please',
+]);
+/**
+ * Plain words people use for a tool (#3669, #4059). One map, shared with how_to's recipe synonyms.
+ * Only tools that exist in the registry belong here.
+ */
+export const TOOL_ALIASES = {
+    send_broadcast: [
+        'send email', 'send an email', 'email blast', 'blast', 'newsletter', 'announce', 'announcement', 'one-off email',
+        'email my list', 'send to my list', 'email to my list', 'email my subscribers',
+    ],
+    list_campaigns: ['last campaign', 'latest campaign', 'recent campaign', 'my campaigns'],
+    get_campaign: [
+        'last campaign', 'campaign details', 'campaign results',
+        'opened', 'opens', 'open rate', 'results', 'stats',
+    ],
+    get_stats: ['opened', 'opens', 'open rate', 'click rate', 'email stats', 'how many opened', 'performance', 'results'],
+    create_campaign: [
+        'welcome', 'welcome email', 'onboarding', 'drip', 'sequence', 'triggered email',
+        'launch', 'welcome sequence', 'new signups', 'signup email',
+    ],
+    add_campaign_step: [
+        'welcome', 'onboarding', 'follow up email', 'next email in sequence',
+        'welcome sequence', 'new signups', 'launch',
+    ],
+    diagnose_delivery_issue: [
+        'bounce', 'bounced', 'bounces', 'why did my email bounce', 'not delivered', 'delivery problem',
+        'delivery issue', 'spam folder', 'email not arriving',
+    ],
+    list_email_log: ['bounce', 'bounced', 'email log', 'delivery status', 'delivery events', 'sent emails'],
+    add_subscriber: ['add a contact', 'add contact', 'new contact', 'add person', 'add a person', 'new subscriber'],
+    import_subscribers: ['import contacts', 'upload list', 'upload contacts', 'csv', 'import list'],
+};
+/** Simple plurals only; leaves the word alone when stripping would leave fewer than 4 characters. */
+export function stem(token) {
+    let out = token;
+    if (token.endsWith('ies'))
+        out = `${token.slice(0, -3)}y`;
+    else if (token.endsWith('sses'))
+        out = token.slice(0, -2);
+    else if (token.endsWith('s') && !/(ss|us|is)$/.test(token))
+        out = token.slice(0, -1);
+    return out.length >= 4 ? out : token;
+}
+function splitWords(text) {
+    return text.toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+/** Lowercase, split, drop stopwords, stem. A query made only of stopwords keeps them so it still searches. */
+export function tokenize(query) {
+    const words = splitWords(query);
+    const kept = words.filter((w) => !STOPWORDS.has(w));
+    return (kept.length > 0 ? kept : words).map(stem);
+}
+const normalizePhrase = (text) => ` ${splitWords(text).join(' ')} `;
+const SCORE_EXACT_NAME = 100;
+const SCORE_ALIAS_PHRASE = 60;
+const SCORE_NAME_TOKEN = 10;
+const SCORE_ALIAS_TOKEN = 8;
+const SCORE_GROUP_TOKEN = 3;
+const SCORE_DESCRIPTION_TOKEN = 2;
+function toolTokens(entry, aliases) {
+    return {
+        name: new Set(splitWords(entry.name).map(stem)),
+        alias: new Set((aliases[entry.name] ?? []).flatMap((a) => splitWords(a)).map(stem)),
+        group: new Set(splitWords(entry.group).map(stem)),
+        description: new Set(splitWords(entry.description).filter((w) => !STOPWORDS.has(w)).map(stem)),
+    };
+}
+/**
+ * Tiers are strictly ordered: exact name > alias phrase > per-token hits (name > alias > group >
+ * description, best tier per token, summed: OR semantics). 0 means no match.
+ */
+export function scoreTool(entry, queryTokens, rawQuery, aliases = TOOL_ALIASES) {
+    const normalized = normalizePhrase(rawQuery);
+    if (normalized.trim() === '')
+        return 0;
+    if (normalized.trim().replace(/ /g, '_') === entry.name)
+        return SCORE_EXACT_NAME;
+    let score = 0;
+    if ((aliases[entry.name] ?? []).some((phrase) => normalized.includes(normalizePhrase(phrase)))) {
+        score += SCORE_ALIAS_PHRASE;
+    }
+    const tokens = toolTokens(entry, aliases);
+    for (const token of new Set(queryTokens)) {
+        if (tokens.name.has(token))
+            score += SCORE_NAME_TOKEN;
+        else if (tokens.alias.has(token))
+            score += SCORE_ALIAS_TOKEN;
+        else if (tokens.group.has(token))
+            score += SCORE_GROUP_TOKEN;
+        else if (tokens.description.has(token))
+            score += SCORE_DESCRIPTION_TOKEN;
+    }
+    return score;
+}
+/** Prefix-match fallback (>= 3 chars) used only to pick "nearest" tools when nothing scored. */
+function fuzzyScore(entry, queryTokens, aliases) {
+    const tokens = toolTokens(entry, aliases);
+    const pools = [tokens.name, tokens.alias, tokens.group, tokens.description];
+    let score = 0;
+    for (const token of new Set(queryTokens)) {
+        if (token.length < 3)
+            continue;
+        for (const pool of pools) {
+            if ([...pool].some((w) => w.startsWith(token) || (w.length >= 3 && token.startsWith(w)))) {
+                score += 1;
+                break;
+            }
+        }
+    }
+    return score;
+}
+const byScoreThenName = (a, b) => b.score - a.score || a.entry.name.localeCompare(b.entry.name);
+export function rankTools(entries, query, options = {}) {
+    const aliases = options.aliases ?? TOOL_ALIASES;
+    const nearestLimit = options.nearestLimit ?? 5;
+    const queryTokens = tokenize(query);
+    const matches = entries
+        .map((entry) => ({ entry, score: scoreTool(entry, queryTokens, query, aliases) }))
+        .filter((s) => s.score > 0)
+        .sort(byScoreThenName);
+    if (matches.length > 0) {
+        return { matches: options.limit ? matches.slice(0, options.limit) : matches, nearest: [] };
+    }
+    const fuzzy = entries
+        .map((entry) => ({ entry, score: fuzzyScore(entry, queryTokens, aliases) }))
+        .filter((s) => s.score > 0)
+        .sort(byScoreThenName);
+    const nearest = fuzzy.length > 0
+        ? fuzzy
+        : entries.slice(0, nearestLimit).map((entry) => ({ entry, score: 0 }));
+    return { matches: [], nearest: nearest.slice(0, nearestLimit) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.81",
+  "version": "1.0.83",
   "description": "AI-controlled email operations control plane for campaigns, contacts, segments, analytics, and multi-provider sending via MCP.",
   "mcpName": "ai.sendinel/mcp-server",
   "type": "module",