@nghyane/arcane 0.1.0

package/src/exa/search.ts

@@ -0,0 +1,330 @@
+/**
+ * Exa Search Tools
+ *
+ * Basic neural/keyword search, deep research, code search, and URL crawling.
+ */
+import { StringEnum } from "@nghyane/arcane-ai";
+import { Type } from "@sinclair/typebox";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import { callExaTool, findApiKey, formatSearchResults, isSearchResponse } from "./mcp-client";
+import type { ExaRenderDetails } from "./types";
+
+/** exa_search - Basic neural/keyword search */
+const exaSearchTool: CustomTool<any, ExaRenderDetails> = {
+	name: "exa_search",
+	label: "Exa Search",
+	description: `Search the web using Exa's neural or keyword search.
+
+Returns structured search results with optional text content and highlights.
+
+Parameters:
+- query: Search query (required)
+- type: Search type - "neural" (semantic), "keyword" (exact), or "auto" (default: auto)
+- include_domains: Array of domains to include in results
+- exclude_domains: Array of domains to exclude from results
+- start_published_date: Filter results published after this date (ISO 8601)
+- end_published_date: Filter results published before this date (ISO 8601)
+- use_autoprompt: Let Exa optimize your query automatically (default: true)
+- text: Include page text content in results (default: false, costs more)
+- highlights: Include highlighted relevant snippets (default: false)
+- num_results: Maximum number of results to return (default: 10, max: 100)`,
+
+	parameters: Type.Object({
+		query: Type.String({ description: "Search query" }),
+		type: Type.Optional(
+			StringEnum(["keyword", "neural", "auto"], {
+				description: "Search type - neural (semantic), keyword (exact), or auto",
+			}),
+		),
+		include_domains: Type.Optional(
+			Type.Array(Type.String(), {
+				description: "Only include results from these domains",
+			}),
+		),
+		exclude_domains: Type.Optional(
+			Type.Array(Type.String(), {
+				description: "Exclude results from these domains",
+			}),
+		),
+		start_published_date: Type.Optional(
+			Type.String({
+				description: "Filter results published after this date (ISO 8601 format)",
+			}),
+		),
+		end_published_date: Type.Optional(
+			Type.String({
+				description: "Filter results published before this date (ISO 8601 format)",
+			}),
+		),
+		use_autoprompt: Type.Optional(
+			Type.Boolean({
+				description: "Let Exa optimize your query automatically (default: true)",
+			}),
+		),
+		text: Type.Optional(
+			Type.Boolean({
+				description: "Include page text content in results (costs more, default: false)",
+			}),
+		),
+		highlights: Type.Optional(
+			Type.Boolean({
+				description: "Include highlighted relevant snippets (default: false)",
+			}),
+		),
+		num_results: Type.Optional(
+			Type.Number({
+				description: "Maximum number of results to return (default: 10, max: 100)",
+				minimum: 1,
+				maximum: 100,
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		try {
+			const apiKey = await findApiKey();
+			if (!apiKey) {
+				return {
+					content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
+					details: { error: "EXA_API_KEY not found", toolName: "exa_search" },
+				};
+			}
+			const response = await callExaTool("web_search_exa", params, apiKey);
+
+			if (isSearchResponse(response)) {
+				const formatted = formatSearchResults(response);
+				return {
+					content: [{ type: "text" as const, text: formatted }],
+					details: { response, toolName: "exa_search" },
+				};
+			}
+
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+				details: { raw: response, toolName: "exa_search" },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text" as const, text: `Error: ${message}` }],
+				details: { error: message, toolName: "exa_search" },
+			};
+		}
+	},
+};
+
+/** exa_search_deep - AI-synthesized deep research */
+const exaSearchDeepTool: CustomTool<any, ExaRenderDetails> = {
+	name: "exa_search_deep",
+	label: "Exa Deep Search",
+	description: `Perform AI-synthesized deep research using Exa.
+
+Returns comprehensive research with synthesized answers and multiple sources.
+
+Similar parameters to exa_search, optimized for research depth.`,
+
+	parameters: Type.Object({
+		query: Type.String({ description: "Research query" }),
+		type: Type.Optional(
+			StringEnum(["keyword", "neural", "auto"], {
+				description: "Search type - neural (semantic), keyword (exact), or auto",
+			}),
+		),
+		include_domains: Type.Optional(
+			Type.Array(Type.String(), {
+				description: "Only include results from these domains",
+			}),
+		),
+		exclude_domains: Type.Optional(
+			Type.Array(Type.String(), {
+				description: "Exclude results from these domains",
+			}),
+		),
+		start_published_date: Type.Optional(
+			Type.String({
+				description: "Filter results published after this date (ISO 8601 format)",
+			}),
+		),
+		end_published_date: Type.Optional(
+			Type.String({
+				description: "Filter results published before this date (ISO 8601 format)",
+			}),
+		),
+		use_autoprompt: Type.Optional(
+			Type.Boolean({
+				description: "Let Exa optimize your query automatically (default: true)",
+			}),
+		),
+		text: Type.Optional(
+			Type.Boolean({
+				description: "Include page text content in results (costs more, default: false)",
+			}),
+		),
+		highlights: Type.Optional(
+			Type.Boolean({
+				description: "Include highlighted relevant snippets (default: false)",
+			}),
+		),
+		num_results: Type.Optional(
+			Type.Number({
+				description: "Maximum number of results to return (default: 10, max: 100)",
+				minimum: 1,
+				maximum: 100,
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		try {
+			const apiKey = await findApiKey();
+			if (!apiKey) {
+				return {
+					content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
+					details: { error: "EXA_API_KEY not found", toolName: "exa_search_deep" },
+				};
+			}
+			const args = { ...params, type: "deep" };
+			const response = await callExaTool("web_search_exa", args, apiKey);
+
+			if (isSearchResponse(response)) {
+				const formatted = formatSearchResults(response);
+				return {
+					content: [{ type: "text" as const, text: formatted }],
+					details: { response, toolName: "exa_search_deep" },
+				};
+			}
+
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+				details: { raw: response, toolName: "exa_search_deep" },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text" as const, text: `Error: ${message}` }],
+				details: { error: message, toolName: "exa_search_deep" },
+			};
+		}
+	},
+};
+
+/** exa_search_code - Code-focused search */
+const exaSearchCodeTool: CustomTool<any, ExaRenderDetails> = {
+	name: "exa_search_code",
+	label: "Exa Code Search",
+	description: `Search for code examples and technical documentation using Exa.
+
+Optimized for finding code snippets, API documentation, and technical content.
+
+Parameters:
+- query: Code or technical search query (required)
+- code_context: Additional context about what you're looking for`,
+
+	parameters: Type.Object({
+		query: Type.String({ description: "Code or technical search query" }),
+		code_context: Type.Optional(
+			Type.String({
+				description: "Additional context about what you're looking for",
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		try {
+			const apiKey = await findApiKey();
+			if (!apiKey) {
+				return {
+					content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
+					details: { error: "EXA_API_KEY not found", toolName: "exa_search_code" },
+				};
+			}
+			const response = await callExaTool("get_code_context_exa", params, apiKey);
+
+			if (isSearchResponse(response)) {
+				const formatted = formatSearchResults(response);
+				return {
+					content: [{ type: "text" as const, text: formatted }],
+					details: { response, toolName: "exa_search_code" },
+				};
+			}
+
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+				details: { raw: response, toolName: "exa_search_code" },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text" as const, text: `Error: ${message}` }],
+				details: { error: message, toolName: "exa_search_code" },
+			};
+		}
+	},
+};
+
+/** exa_crawl - URL content extraction */
+const exaCrawlTool: CustomTool<any, ExaRenderDetails> = {
+	name: "exa_crawl",
+	label: "Exa Crawl",
+	description: `Extract content from a specific URL using Exa.
+
+Returns the page content with optional text and highlights.
+
+Parameters:
+- url: URL to crawl (required)
+- text: Include full page text content (default: false)
+- highlights: Include highlighted relevant snippets (default: false)`,
+
+	parameters: Type.Object({
+		url: Type.String({ description: "URL to crawl and extract content from" }),
+		text: Type.Optional(
+			Type.Boolean({
+				description: "Include full page text content (default: false)",
+			}),
+		),
+		highlights: Type.Optional(
+			Type.Boolean({
+				description: "Include highlighted relevant snippets (default: false)",
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, _onUpdate, _ctx, _signal) {
+		try {
+			const apiKey = await findApiKey();
+			if (!apiKey) {
+				return {
+					content: [{ type: "text" as const, text: "Error: EXA_API_KEY not found" }],
+					details: { error: "EXA_API_KEY not found", toolName: "exa_crawl" },
+				};
+			}
+			const response = await callExaTool("crawling", params, apiKey);
+
+			if (isSearchResponse(response)) {
+				const formatted = formatSearchResults(response);
+				return {
+					content: [{ type: "text" as const, text: formatted }],
+					details: { response, toolName: "exa_crawl" },
+				};
+			}
+
+			return {
+				content: [{ type: "text" as const, text: JSON.stringify(response, null, 2) }],
+				details: { raw: response, toolName: "exa_crawl" },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text" as const, text: `Error: ${message}` }],
+				details: { error: message, toolName: "exa_crawl" },
+			};
+		}
+	},
+};
+
+export const searchTools: CustomTool<any, ExaRenderDetails>[] = [
+	exaSearchTool,
+	exaSearchDeepTool,
+	exaSearchCodeTool,
+	exaCrawlTool,
+];

package/src/exa/types.ts

@@ -0,0 +1,166 @@
+/**
+ * Exa MCP Types
+ *
+ * Types for the Exa MCP client and tool implementations.
+ */
+import type { TSchema } from "@sinclair/typebox";
+
+/** MCP endpoint URLs */
+export const EXA_MCP_URL = "https://mcp.exa.ai/mcp";
+export const WEBSETS_MCP_URL = "https://websetsmcp.exa.ai/mcp";
+
+/** MCP tool definition from server */
+export interface MCPTool {
+	name: string;
+	description: string;
+	inputSchema: TSchema;
+}
+
+/** Tool wrapper config for dynamic MCP tool creation */
+export interface MCPToolWrapperConfig {
+	/** Our tool name (e.g., "exa_search") */
+	name: string;
+	/** Display label for UI */
+	label: string;
+	/** MCP tool name to call (e.g., "web_search_exa") */
+	mcpToolName: string;
+	/** Whether this is a websets tool (uses different MCP endpoint) */
+	isWebsetsTool?: boolean;
+}
+
+/** MCP tools/list response */
+export interface MCPToolsResponse {
+	result?: {
+		tools: MCPTool[];
+	};
+	error?: {
+		code: number;
+		message: string;
+	};
+}
+
+/** MCP tools/call response */
+export interface MCPCallResponse {
+	result?: {
+		content?: Array<{ type: string; text?: string }>;
+	};
+	error?: {
+		code: number;
+		message: string;
+	};
+}
+
+/** Search result from Exa */
+export interface ExaSearchResult {
+	id?: string;
+	title?: string;
+	url?: string;
+	author?: string;
+	publishedDate?: string;
+	text?: string;
+	highlights?: string[];
+	image?: string;
+	favicon?: string;
+}
+
+/** Search response from Exa */
+export interface ExaSearchResponse {
+	results?: ExaSearchResult[];
+	statuses?: Array<{ id: string; status: string; source?: string }>;
+	costDollars?: { total: number };
+	searchTime?: number;
+	requestId?: string;
+}
+
+/** Researcher task status */
+export interface ResearcherStatus {
+	id: string;
+	status: "pending" | "running" | "completed" | "failed";
+	result?: string;
+	error?: string;
+}
+
+/** Webset definition */
+export interface Webset {
+	id: string;
+	name: string;
+	description?: string;
+	createdAt?: string;
+	updatedAt?: string;
+}
+
+/** Webset item */
+export interface WebsetItem {
+	id: string;
+	websetId: string;
+	url: string;
+	title?: string;
+	content?: string;
+	metadata?: Record<string, unknown>;
+}
+
+/** Webset search */
+export interface WebsetSearch {
+	id: string;
+	websetId: string;
+	query: string;
+	status: "pending" | "running" | "completed" | "cancelled";
+	resultCount?: number;
+}
+
+/** Webset enrichment */
+export interface WebsetEnrichment {
+	id: string;
+	websetId: string;
+	name: string;
+	prompt: string;
+	status: "pending" | "running" | "completed" | "cancelled";
+}
+
+/** Tool name mappings: MCP name -> our tool name */
+export const EXA_TOOL_MAPPINGS = {
+	// Search tools
+	web_search_exa: "exa_search",
+	get_code_context_exa: "exa_search_code",
+	crawling: "exa_crawl",
+	// LinkedIn
+	linkedin_search: "exa_linkedin",
+	// Company
+	company_research: "exa_company",
+	// Researcher
+	deep_researcher_start: "exa_researcher_start",
+	deep_researcher_check: "exa_researcher_poll",
+} as const;
+
+export const WEBSETS_TOOL_MAPPINGS = {
+	create_webset: "webset_create",
+	list_websets: "webset_list",
+	get_webset: "webset_get",
+	update_webset: "webset_update",
+	delete_webset: "webset_delete",
+	list_webset_items: "webset_items_list",
+	get_item: "webset_item_get",
+	create_search: "webset_search_create",
+	get_search: "webset_search_get",
+	cancel_search: "webset_search_cancel",
+	create_enrichment: "webset_enrichment_create",
+	get_enrichment: "webset_enrichment_get",
+	update_enrichment: "webset_enrichment_update",
+	delete_enrichment: "webset_enrichment_delete",
+	cancel_enrichment: "webset_enrichment_cancel",
+	create_monitor: "webset_monitor_create",
+} as const;
+
+export type ExaMcpToolName = keyof typeof EXA_TOOL_MAPPINGS;
+export type WebsetsMcpToolName = keyof typeof WEBSETS_TOOL_MAPPINGS;
+export type ExaToolName = (typeof EXA_TOOL_MAPPINGS)[ExaMcpToolName];
+export type WebsetsToolName = (typeof WEBSETS_TOOL_MAPPINGS)[WebsetsMcpToolName];
+
+/** Render details for TUI */
+export interface ExaRenderDetails {
+	response?: ExaSearchResponse;
+	error?: string;
+	toolName?: string;
+	/** Raw result for non-search responses */
+	raw?: unknown;
+}