openclaw-exa-search 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# openclaw-exa-search
+
+Exa AI search plugin for [OpenClaw](https://openclaw.ai). No API key required — uses [Exa's public MCP endpoint](https://mcp.exa.ai).
+
+## Tools
+
+| Tool | Parameters | Description |
+|------|-----------|-------------|
+| `exa_web_search` | `query`, `numResults?`, `type?` (`auto`/`fast`/`deep`), `livecrawl?` (`fallback`/`preferred`) | Neural web search — news, facts, current info. |
+| `exa_code_search` | `query`, `tokensNum?` (1000–50000) | Find code examples, docs, and solutions from GitHub, Stack Overflow, and official documentation. |
+| `exa_company_research` | `companyName`, `numResults?` | Research any company — products, services, recent news, industry position. |
+| `exa_twitter_search` | `query`, `numResults?`, `startPublishedDate?`, `endPublishedDate?` | Search Twitter/X posts and discussions. Filter by date range (ISO 8601). |
+| `exa_people_search` | `query`, `numResults?` | Find people by name, role, company, or expertise. Returns public LinkedIn and professional profiles. |
+| `exa_financial_report_search` | `query`, `numResults?`, `startPublishedDate?`, `endPublishedDate?` | Search SEC filings (10-K, 10-Q), earnings reports, and annual/quarterly financial documents. |
+
+All tools are enabled by default. Requests time out after 30 seconds.
+
+## Install
+
+```bash
+openclaw plugins install openclaw-exa-search
+openclaw plugins enable openclaw-exa-search
+openclaw gateway restart
+```
+
+If you have a `plugins.allow` allowlist configured, add the plugin id:
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-exa-search"]
+  }
+}
+```
+
+Verify:
+
+```bash
+openclaw plugins list | grep openclaw-exa-search
+```
+
+## Examples
+
+- "Search Twitter for what people are saying about GPT-5"
+- "Find the latest Apple 10-Q filing"
+- "Research Anthropic as a company"
+- "Find CTO profiles at YC startups"
+- "Search for React Server Components examples"
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test              # unit tests
+npm run test:integration  # integration tests (hits real Exa endpoint)
+npm run build
+```
+
+## Notes
+
+- This plugin depends on Exa's public MCP endpoint (`mcp.exa.ai`). If Exa adds authentication or rate limiting in the future, the plugin will need updates.
+- Date parameters use ISO 8601 format (e.g., `2024-01-01T00:00:00.000Z`).
+
+## License
+
+MIT
+
+## Acknowledgements
+
+- [exa-mcp-server](https://github.com/exa-labs/exa-mcp-server) — Official Exa MCP server
+- [exa-search](https://github.com/wysh3/exa-search) — Exa search MCP integration

package/dist/exa-mcp-client.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Exa MCP Client — HTTP/SSE communication with Exa hosted MCP endpoint
+ * No API key required; uses mcp.exa.ai with all tools enabled
+ */
+interface ExaSuccessResponse {
+    jsonrpc: "2.0";
+    id: number;
+    result: {
+        content?: Array<{
+            type: string;
+            text: string;
+        }>;
+        tools?: Array<{
+            name: string;
+            description: string;
+            inputSchema: unknown;
+        }>;
+    };
+}
+interface ExaErrorResponse {
+    jsonrpc: "2.0";
+    id: number;
+    error: {
+        code: number;
+        message: string;
+    };
+}
+type ExaResponse = ExaSuccessResponse | ExaErrorResponse;
+/**
+ * Parse SSE response — extract the last complete JSON-RPC message.
+ * Per SSE spec, multiple `data:` lines within one event are joined with "\n",
+ * but Exa sends one JSON object per `data:` line. We take the last `data:` line
+ * that parses as valid JSON to handle both single and multi-event streams.
+ */
+export declare function parseSSEResponse(text: string): string;
+/**
+ * Call an Exa MCP tool
+ */
+export declare function callExa(method: string, params?: Record<string, unknown>, fetchFn?: typeof fetch): Promise<ExaResponse>;
+/**
+ * Extract text content from an Exa response
+ */
+export declare function extractTextContent(response: ExaResponse): string;
+export declare function webSearch(params: {
+    query: string;
+    numResults?: number;
+    type?: "auto" | "fast" | "deep";
+    livecrawl?: "fallback" | "preferred";
+}): Promise<string>;
+export declare function codeSearch(params: {
+    query: string;
+    tokensNum?: number;
+}): Promise<string>;
+export declare function companyResearch(params: {
+    companyName: string;
+    numResults?: number;
+}): Promise<string>;
+export declare function twitterSearch(params: {
+    query: string;
+    numResults?: number;
+    startPublishedDate?: string;
+    endPublishedDate?: string;
+}): Promise<string>;
+export declare function peopleSearch(params: {
+    query: string;
+    numResults?: number;
+}): Promise<string>;
+export declare function financialSearch(params: {
+    query: string;
+    numResults?: number;
+    startPublishedDate?: string;
+    endPublishedDate?: string;
+}): Promise<string>;
+export {};

package/dist/exa-mcp-client.js

@@ -0,0 +1,168 @@
+/**
+ * Exa MCP Client — HTTP/SSE communication with Exa hosted MCP endpoint
+ * No API key required; uses mcp.exa.ai with all tools enabled
+ */
+const EXA_BASE_URL = "https://mcp.exa.ai/mcp";
+const EXA_TOOLS = [
+    "web_search_exa",
+    "web_search_advanced_exa",
+    "get_code_context_exa",
+    "company_research_exa",
+    "people_search_exa",
+].join(",");
+const EXA_URL = `${EXA_BASE_URL}?tools=${EXA_TOOLS}`;
+const REQUEST_TIMEOUT_MS = 30_000;
+let requestIdCounter = 0;
+/**
+ * Parse SSE response — extract the last complete JSON-RPC message.
+ * Per SSE spec, multiple `data:` lines within one event are joined with "\n",
+ * but Exa sends one JSON object per `data:` line. We take the last `data:` line
+ * that parses as valid JSON to handle both single and multi-event streams.
+ */
+export function parseSSEResponse(text) {
+    const lines = text.split("\n");
+    const dataLines = [];
+    for (const line of lines) {
+        if (line.startsWith("data: ")) {
+            dataLines.push(line.substring(6));
+        }
+    }
+    if (dataLines.length === 0) {
+        throw new Error("No data: field found in SSE response");
+    }
+    // Try each data line from last to first — return the first valid JSON
+    for (let i = dataLines.length - 1; i >= 0; i--) {
+        try {
+            JSON.parse(dataLines[i]);
+            return dataLines[i];
+        }
+        catch {
+            // not valid JSON, try next
+        }
+    }
+    // Fallback: join all and let caller handle parse error
+    return dataLines.join("");
+}
+/**
+ * Call an Exa MCP tool
+ */
+export async function callExa(method, params, fetchFn = fetch) {
+    const requestId = ++requestIdCounter;
+    const request = {
+        jsonrpc: "2.0",
+        id: requestId,
+        method,
+        params,
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+    try {
+        const response = await fetchFn(EXA_URL, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Accept: "application/json, text/event-stream",
+            },
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP error: ${response.status} ${response.statusText}`);
+        }
+        const text = await response.text();
+        // Try JSON first, fallback to SSE parsing
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            const jsonData = parseSSEResponse(text);
+            return JSON.parse(jsonData);
+        }
+    }
+    catch (error) {
+        if (error instanceof DOMException && error.name === "AbortError") {
+            throw new Error(`Exa request timed out after ${REQUEST_TIMEOUT_MS / 1000}s`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Extract text content from an Exa response
+ */
+export function extractTextContent(response) {
+    if ("error" in response) {
+        throw new Error(`Exa API error: ${response.error.code} - ${response.error.message}`);
+    }
+    const result = response.result;
+    if (!result?.content) {
+        throw new Error("No content in response");
+    }
+    return result.content
+        .filter((item) => item.type === "text")
+        .map((item) => item.text)
+        .join("\n\n");
+}
+// ─── Tool Functions ────────────────────────────────────────────────
+export async function webSearch(params) {
+    const response = await callExa("tools/call", {
+        name: "web_search_exa",
+        arguments: params,
+    });
+    return extractTextContent(response);
+}
+export async function codeSearch(params) {
+    const response = await callExa("tools/call", {
+        name: "get_code_context_exa",
+        arguments: params,
+    });
+    return extractTextContent(response);
+}
+export async function companyResearch(params) {
+    const response = await callExa("tools/call", {
+        name: "company_research_exa",
+        arguments: params,
+    });
+    return extractTextContent(response);
+}
+export async function twitterSearch(params) {
+    const args = {
+        query: params.query,
+        category: "tweet",
+        numResults: params.numResults ?? 10,
+    };
+    if (params.startPublishedDate !== undefined)
+        args.startPublishedDate = params.startPublishedDate;
+    if (params.endPublishedDate !== undefined)
+        args.endPublishedDate = params.endPublishedDate;
+    const response = await callExa("tools/call", {
+        name: "web_search_advanced_exa",
+        arguments: args,
+    });
+    return extractTextContent(response);
+}
+export async function peopleSearch(params) {
+    const response = await callExa("tools/call", {
+        name: "people_search_exa",
+        arguments: params,
+    });
+    return extractTextContent(response);
+}
+export async function financialSearch(params) {
+    const args = {
+        query: params.query,
+        category: "financial report",
+        numResults: params.numResults ?? 10,
+    };
+    if (params.startPublishedDate !== undefined)
+        args.startPublishedDate = params.startPublishedDate;
+    if (params.endPublishedDate !== undefined)
+        args.endPublishedDate = params.endPublishedDate;
+    const response = await callExa("tools/call", {
+        name: "web_search_advanced_exa",
+        arguments: args,
+    });
+    return extractTextContent(response);
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * OpenClaw Exa Search Plugin
+ *
+ * Registers 6 tools: web_search, code_search, company_research,
+ * twitter_search, people_search, financial_report_search
+ */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    execute: (id: string, params: Record<string, unknown>) => Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+        isError?: boolean;
+    }>;
+}
+interface PluginAPI {
+    registerTool: (tool: ToolDefinition) => void;
+}
+declare const TOOLS: ToolDefinition[];
+export default function (api: PluginAPI): void;
+export { TOOLS };

package/dist/index.js

@@ -0,0 +1,167 @@
+/**
+ * OpenClaw Exa Search Plugin
+ *
+ * Registers 6 tools: web_search, code_search, company_research,
+ * twitter_search, people_search, financial_report_search
+ */
+import { webSearch, codeSearch, companyResearch, twitterSearch, peopleSearch, financialSearch, } from "./exa-mcp-client.js";
+function wrapExecute(fn) {
+    return async (_id, params) => {
+        try {
+            const result = await fn(params);
+            return { content: [{ type: "text", text: result }] };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    };
+}
+const TOOLS = [
+    {
+        name: "exa_web_search",
+        description: "Search the web using Exa AI neural search. Find current information, news, facts, or answer questions about any topic. Returns clean, formatted content ready for LLM use.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Web search query" },
+                numResults: {
+                    type: "number",
+                    description: "Number of search results to return (default: 8)",
+                },
+                type: {
+                    type: "string",
+                    enum: ["auto", "fast", "deep"],
+                    description: "Search type - 'auto': balanced search (default), 'fast': quick results, 'deep': comprehensive research",
+                },
+                livecrawl: {
+                    type: "string",
+                    enum: ["fallback", "preferred"],
+                    description: "Live crawl mode - 'fallback': use live crawling as backup if cached unavailable, 'preferred': prioritize live crawling",
+                },
+            },
+            required: ["query"],
+        },
+        execute: wrapExecute(webSearch),
+    },
+    {
+        name: "exa_code_search",
+        description: "Find code examples, documentation, and programming solutions from GitHub, Stack Overflow, and official docs. Useful for API usage, library examples, code snippets, and debugging help.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query for code context - e.g., 'React useState hook examples', 'Python pandas dataframe filtering'",
+                },
+                tokensNum: {
+                    type: "number",
+                    description: "Number of tokens to return (1000-50000). Lower for focused queries, higher for comprehensive docs (default: 5000)",
+                },
+            },
+            required: ["query"],
+        },
+        execute: wrapExecute(codeSearch),
+    },
+    {
+        name: "exa_company_research",
+        description: "Research any company to get business information, news, and insights. Returns information from trusted business sources about products, services, recent news, or industry position.",
+        parameters: {
+            type: "object",
+            properties: {
+                companyName: {
+                    type: "string",
+                    description: "Name of the company to research",
+                },
+                numResults: {
+                    type: "number",
+                    description: "Number of search results to return (default: 5)",
+                },
+            },
+            required: ["companyName"],
+        },
+        execute: wrapExecute(companyResearch),
+    },
+    {
+        name: "exa_twitter_search",
+        description: "Search Twitter/X posts. Find tweets, discussions, and social commentary on any topic. Useful for tracking public sentiment, announcements, and trending discussions.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query for Twitter/X posts",
+                },
+                numResults: {
+                    type: "number",
+                    description: "Number of tweets to return (default: 10)",
+                },
+                startPublishedDate: {
+                    type: "string",
+                    description: "Filter tweets published after this date (ISO 8601 format, e.g., '2024-01-01T00:00:00.000Z')",
+                },
+                endPublishedDate: {
+                    type: "string",
+                    description: "Filter tweets published before this date (ISO 8601 format)",
+                },
+            },
+            required: ["query"],
+        },
+        execute: wrapExecute(twitterSearch),
+    },
+    {
+        name: "exa_people_search",
+        description: "Find people and their professional profiles. Search for individuals by name, role, company, or expertise. Returns public LinkedIn and professional profile data.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query for people - e.g., 'CTO at Anthropic', 'machine learning researchers Stanford'",
+                },
+                numResults: {
+                    type: "number",
+                    description: "Number of results to return (default: 5)",
+                },
+            },
+            required: ["query"],
+        },
+        execute: wrapExecute(peopleSearch),
+    },
+    {
+        name: "exa_financial_report_search",
+        description: "Search financial reports — 10-K, 10-Q, annual reports, quarterly earnings, and SEC filings for public companies.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query for financial reports - e.g., 'Apple 2024 Q4 earnings', 'Tesla annual report 2024'",
+                },
+                numResults: {
+                    type: "number",
+                    description: "Number of results to return (default: 10)",
+                },
+                startPublishedDate: {
+                    type: "string",
+                    description: "Filter reports published after this date (ISO 8601 format)",
+                },
+                endPublishedDate: {
+                    type: "string",
+                    description: "Filter reports published before this date (ISO 8601 format)",
+                },
+            },
+            required: ["query"],
+        },
+        execute: wrapExecute(financialSearch),
+    },
+];
+export default function (api) {
+    for (const tool of TOOLS) {
+        api.registerTool(tool);
+    }
+}
+export { TOOLS };

package/dist/integration.spec.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Integration tests — hits real Exa MCP endpoint
+ * Run with: npm run test:integration
+ */
+export {};

package/dist/integration.spec.js

@@ -0,0 +1,45 @@
+/**
+ * Integration tests — hits real Exa MCP endpoint
+ * Run with: npm run test:integration
+ */
+import { describe, it, expect } from "vitest";
+import { webSearch, codeSearch, companyResearch, twitterSearch, peopleSearch, financialSearch, } from "./exa-mcp-client.js";
+const TIMEOUT = 30_000;
+describe("integration: Exa MCP endpoint", () => {
+    it("exa_web_search", async () => {
+        const result = await webSearch({ query: "OpenAI latest news", numResults: 3 });
+        expect(result).toBeTruthy();
+        expect(result.length).toBeGreaterThan(50);
+        console.log("[web_search] ✅", result.slice(0, 200), "...");
+    }, TIMEOUT);
+    it("exa_code_search", async () => {
+        const result = await codeSearch({ query: "React useState hook examples", tokensNum: 2000 });
+        expect(result).toBeTruthy();
+        expect(result.length).toBeGreaterThan(50);
+        console.log("[code_search] ✅", result.slice(0, 200), "...");
+    }, TIMEOUT);
+    it("exa_company_research", async () => {
+        const result = await companyResearch({ companyName: "Anthropic", numResults: 3 });
+        expect(result).toBeTruthy();
+        expect(result.length).toBeGreaterThan(50);
+        console.log("[company_research] ✅", result.slice(0, 200), "...");
+    }, TIMEOUT);
+    it("exa_twitter_search", async () => {
+        const result = await twitterSearch({ query: "AI agents", numResults: 5 });
+        expect(result).toBeTruthy();
+        expect(result.length).toBeGreaterThan(50);
+        console.log("[twitter_search] ✅", result.slice(0, 200), "...");
+    }, TIMEOUT);
+    it("exa_people_search", async () => {
+        const result = await peopleSearch({ query: "CTO at Anthropic", numResults: 3 });
+        expect(result).toBeTruthy();
+        expect(result.length).toBeGreaterThan(50);
+        console.log("[people_search] ✅", result.slice(0, 200), "...");
+    }, TIMEOUT);
+    it("exa_financial_search", async () => {
+        const result = await financialSearch({ query: "Apple 2024 annual report", numResults: 3 });
+        expect(result).toBeTruthy();
+        expect(result.length).toBeGreaterThan(50);
+        console.log("[financial_search] ✅", result.slice(0, 200), "...");
+    }, TIMEOUT);
+});

package/openclaw.plugin.json

@@ -0,0 +1,11 @@
+{
+  "id": "openclaw-exa-search",
+  "name": "Exa Search",
+  "version": "1.0.0",
+  "description": "Exa AI search integration for OpenClaw — web search, code search, company research, Twitter/X search, people search, and financial report search. No API key required.",
+  "author": "sawyer0x110",
+  "license": "MIT",
+  "repository": "https://github.com/sawyer0x110/openclaw-exa-search",
+  "keywords": ["search", "exa", "web", "code", "twitter", "financial"],
+  "main": "./dist/index.js"
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "openclaw-exa-search",
+  "version": "1.0.0",
+  "description": "OpenClaw plugin for Exa AI search — web, code, company, Twitter/X, people, and financial report search.",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.integration.config.ts",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": ["openclaw", "openclaw-plugin", "exa", "search", "web-search", "code-search", "company-research", "twitter-search", "people-search", "financial-reports", "ai", "neural-search", "mcp"],
+  "author": "sawyer0x110",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sawyer0x110/openclaw-exa-search"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md"
+  ]
+}