Files
waggle-os/packages/agent/src/connector-search.ts
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
moving
2026-09-02 10:10:29 +02:00

266 lines
9.8 KiB
TypeScript

/**
* Connector Search Tools — give the agent semantic discovery over the
* MCP connector catalog.
*
* Two tools:
* - find_connector(query, limit?, category?)
* Natural-language search over the 148-entry catalog. Returns ranked
* matches with install command, description, and a match score.
* - list_connector_categories()
* Category breakdown of the catalog. Use this first when the user
* asks what kinds of integrations are available.
*
* Uses weighted keyword scoring — no LLM calls, no embeddings, zero
* additional cost. Handles the 90% of queries where the intent is in
* the words. For the edge cases, the agent can iterate by refining
* the query or calling list_connector_categories to orient itself.
*/
import { MCP_CATALOG, MCP_CATEGORIES, type McpServer } from '@waggle/shared';
import type { ToolDefinition } from './tools.js';
/**
* Strip common English suffixes so "automate" also matches "automation",
* "messages" matches "message", "scenarios" matches "scenario", etc.
* Not a real stemmer — just enough to bridge the vocabulary gap between
* user queries and catalog descriptions.
*/
function stem(word: string): string {
if (word.length < 5) return word;
for (const suffix of ['ations', 'ation', 'ings', 'ing', 'ies', 'ed', 'es', 's']) {
if (word.endsWith(suffix)) {
const base = word.slice(0, -suffix.length);
if (base.length >= 3) return base;
}
}
return word;
}
/**
* Domain synonym map — bridges common user vocabulary to the terms our
* catalog descriptions actually use. Keyed by stemmed query word.
* Kept deliberately small: each entry must solve a query where the naive
* substring match misses the obvious answer.
*/
const SYNONYMS: Record<string, string[]> = {
chat: ['message', 'channel', 'communication'],
messag: ['chat', 'channel', 'send'],
automat: ['workflow', 'scenario', 'trigger', 'webhook'],
workflow: ['scenario', 'trigger', 'automat'],
crm: ['salesforce', 'hubspot', 'customer', 'contact', 'deal'],
db: ['database', 'query', 'schema'],
auth: ['identity', 'sso', 'token', 'oauth'],
payment: ['subscription', 'invoice', 'checkout', 'billing'],
invoice: ['billing', 'subscription', 'payment'],
analytic: ['metric', 'event', 'report', 'funnel'],
metric: ['analytic', 'event', 'monitor'],
monitor: ['metric', 'alert', 'observability'],
log: ['observability', 'trace', 'monitor'],
task: ['issue', 'ticket', 'project'],
issue: ['task', 'ticket', 'bug'],
note: ['document', 'page', 'wiki'],
document: ['page', 'file', 'note'],
email: ['send', 'inbox', 'mail'],
sms: ['send', 'text', 'twilio'],
voice: ['call', 'speech', 'audio'],
vector: ['embedding', 'search', 'similarity'],
embedding: ['vector', 'search'],
scrap: ['crawl', 'extract', 'fetch'],
crawl: ['scrap', 'fetch', 'extract'],
};
/**
* Build the expanded word set for a query: the original words, their
* stems, and any synonym expansions. Uses a Set so duplicates don't
* double-score.
*/
function expandQueryWords(words: string[]): string[] {
const expanded = new Set<string>();
for (const word of words) {
if (word.length < 3) continue;
expanded.add(word);
const stemmed = stem(word);
if (stemmed !== word && stemmed.length >= 3) expanded.add(stemmed);
for (const syn of SYNONYMS[stemmed] ?? SYNONYMS[word] ?? []) {
expanded.add(syn);
}
}
return [...expanded];
}
/**
* Score a catalog entry against a natural-language query.
* Higher = better match. Zero means no signal.
*
* Scoring weights (tuned to rank exact-name hits above thematic hits):
* name exact → 20
* name includes → 10
* id includes → 8
* category match → 6 (e.g. "database" surfaces all DB entries)
* description → 5
* capability → 3 each (max 3 hits counted)
* per-word bonus → 1-3 depending on where the word lands
*
* Expanded words (stems + synonyms) only score at half weight so the
* original user vocabulary always wins ties.
*/
function scoreEntry(server: McpServer, query: string, words: string[]): number {
let score = 0;
const name = server.name.toLowerCase();
const id = server.id.toLowerCase();
const desc = server.description.toLowerCase();
const cat = server.category.toLowerCase();
// Whole-query phrase signals
if (name === query) score += 20;
else if (name.includes(query)) score += 10;
if (id.includes(query)) score += 8;
if (cat === query || cat.includes(query)) score += 6;
if (desc.includes(query)) score += 5;
const originalWords = new Set(words);
const allWords = expandQueryWords(words);
let capabilityHits = 0;
for (const word of allWords) {
if (word.length < 3) continue;
const isOriginal = originalWords.has(word);
// Expanded (stem/synonym) hits score at half so originals always rank higher.
const mul = isOriginal ? 1 : 0.5;
if (name.includes(word)) score += 3 * mul;
if (id.includes(word)) score += 2 * mul;
if (desc.includes(word)) score += 2 * mul;
if (cat.includes(word)) score += 1 * mul;
for (const capability of server.capabilities) {
if (capabilityHits >= 3) break;
if (capability.toLowerCase().includes(word)) {
score += 3 * mul;
capabilityHits++;
}
}
}
return score;
}
/** Human-readable compact view of a catalog entry for tool output. */
function formatMatch(server: McpServer, score: number) {
return {
id: server.id,
name: server.name,
category: server.category,
description: server.description,
capabilities: server.capabilities,
installCmd: server.installCmd,
url: server.url,
official: server.official ?? false,
matchScore: score,
};
}
export function createConnectorSearchTools(): ToolDefinition[] {
return [
{
name: 'find_connector',
description: [
'Search the MCP connector catalog by natural-language query to find integrations the user can connect.',
'Returns ranked matches with name, category, description, install command, and a match score.',
'Use this whenever the user mentions connecting, integrating, or plugging in a service — even vaguely.',
'Examples:',
' query="project management" → Linear, Jira, Asana, ClickUp, Todoist...',
' query="team chat" → Slack, Discord, Microsoft Teams, Telegram...',
' query="postgres" → PostgreSQL, Neon, Supabase, PlanetScale...',
' query="analytics" → PostHog, Mixpanel, Amplitude, Google Analytics, Plausible...',
].join(' '),
parameters: {
type: 'object' as const,
required: ['query'],
properties: {
query: {
type: 'string' as const,
description: 'Natural-language description of the integration the user needs.',
},
limit: {
type: 'number' as const,
description: 'Maximum matches to return. Default 10, capped at 30.',
},
category: {
type: 'string' as const,
description: `Optional category filter. One of: ${MCP_CATEGORIES.join(', ')}`,
},
},
},
offlineCapable: true,
execute: async (args: Record<string, unknown>) => {
const rawQuery = String(args.query ?? '').trim();
if (!rawQuery) {
return JSON.stringify({
error: 'query is required',
hint: 'Pass a short description of the integration the user wants.',
});
}
const query = rawQuery.toLowerCase();
const words = query.split(/[^a-z0-9]+/).filter(Boolean);
const limit = Math.min(Math.max(Number(args.limit) || 10, 1), 30);
const categoryFilter = typeof args.category === 'string' ? args.category : undefined;
const scored: Array<{ server: McpServer; score: number }> = [];
for (const server of MCP_CATALOG) {
if (categoryFilter && server.category !== categoryFilter) continue;
const score = scoreEntry(server, query, words);
if (score > 0) scored.push({ server, score });
}
scored.sort((a, b) => b.score - a.score);
const matches = scored.slice(0, limit);
if (matches.length === 0) {
const categoriesList = MCP_CATEGORIES.join(', ');
return JSON.stringify({
query: rawQuery,
matchCount: 0,
hint: `No matches. Try broader terms, or filter by category. Available categories: ${categoriesList}. Call list_connector_categories for counts.`,
});
}
return JSON.stringify({
query: rawQuery,
catalogSize: MCP_CATALOG.length,
matchCount: matches.length,
matches: matches.map(({ server, score }) => formatMatch(server, score)),
});
},
},
{
name: 'list_connector_categories',
description: [
'List every MCP connector category with the number of servers in each.',
'Use this first when the user asks what kinds of integrations are available',
'or wants to browse by type rather than search for a specific tool.',
].join(' '),
parameters: {
type: 'object' as const,
required: [],
properties: {},
},
offlineCapable: true,
execute: async () => {
const counts = new Map<string, number>();
for (const server of MCP_CATALOG) {
counts.set(server.category, (counts.get(server.category) ?? 0) + 1);
}
const categories = [...counts.entries()]
.sort(([, a], [, b]) => b - a)
.map(([category, count]) => ({ category, count }));
const officialCount = MCP_CATALOG.filter((s) => s.official).length;
return JSON.stringify({
totalServers: MCP_CATALOG.length,
officialServers: officialCount,
categoryCount: categories.length,
categories,
});
},
},
];
}