@sendinel/mcp-server 1.0.80 → 1.0.82

package/build/db.d.ts

@@ -38,6 +38,7 @@ export declare function runWithClient<T>(client: any, fn: () => Promise<T>, requ
     actorType?: string;
     actorId?: string | null;
     oauthTokenId?: string | null;
+    invitationProjectIds?: string[] | null;
     authKind?: string | null;
     oauthClientId?: string | null;
     agentLabel?: string | null;
@@ -58,6 +59,7 @@ export declare function requestContext(): {
     actorType?: string;
     actorId?: string | null;
     oauthTokenId?: string | null;
+    invitationProjectIds?: string[] | null;
     authKind?: string | null;
     oauthClientId?: string | null;
     agentLabel?: string | null;

package/build/db.js

@@ -69,6 +69,7 @@ export function requestContext() {
             actorType: ctx.actorType,
             actorId: ctx.actorId,
             oauthTokenId: ctx.oauthTokenId,
+            invitationProjectIds: ctx.invitationProjectIds,
             authKind: ctx.authKind,
             oauthClientId: ctx.oauthClientId,
             agentLabel: ctx.agentLabel,

package/build/tools/analytics.js

@@ -365,6 +365,8 @@ export function registerAnalyticsTools(server) {
                 return txt(`Error: ${ownedProjectsError.message}`);
             const byId = new Map();
             for (const project of [...(directProjects ?? []), ...(ownedProjects ?? [])]) {
+                if (ctx.invitationProjectIds != null && !ctx.invitationProjectIds.includes(project.id))
+                    continue;
                 byId.set(project.id, project);
             }
             const orgIds = Array.from(new Set(Array.from(byId.values()).map((project) => project.org_id).filter((id) => Boolean(id))));
@@ -450,6 +452,9 @@ export function registerAnalyticsTools(server) {
             return j({ error: accessError.message });
         if (!hasAccess)
             return j({ error: 'You do not have access to this project.', code: 'PROJECT_ACCESS_DENIED' });
+        if (ctx.invitationProjectIds != null && !ctx.invitationProjectIds.includes(project_id.toLowerCase())) {
+            return j({ error: 'You do not have access to this project.', code: 'PROJECT_ACCESS_DENIED' });
+        }
         const previousProjectId = getProjectId();
         const { error: updateError } = await adminDb()
             .from('mcp_oauth_tokens')

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.80",
+  "version": "1.0.82",
   "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",