Exa MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is the Exa MCP Server - a Model Context Protocol (MCP) server that connects AI assistants to Exa AI's search capabilities. The server provides various search and research tools including web search, code search, company research, web crawling, and deep research workflows. ## Development Commands ### Building ```bash # Build for stdio transport (default) npm run build # Build for HTTP transport npm run build:shttp # Build both transports npm run build ``` ### Development ```bash # Start development server with hot reload npm run dev # Watch TypeScript files npm run watch # Run MCP inspector to test tools npm run inspector ``` ### Testing and Publishing ```bash # Prepare for publish (builds stdio version) npm run prepare # Publish to npm (runs prepare automatically) npm publish ``` ## Architecture Overview ### Core Structure - **src/index.ts**: Main server entry point, configures MCP server and registers tools - **src/tools/**: Individual tool implementations (each tool is ~300-400 lines max) - **src/utils/logger.ts**: Logging utilities - **src/types.ts**: TypeScript type definitions - **src/tools/config.ts**: API configuration constants ### Tool System The server uses a modular tool system where each search capability is implemented as a separate tool: - `webSearch.ts`: Real-time web search - `exaCode.ts`: Code context search from GitHub/docs - `companyResearch.ts`: Company website research - `crawling.ts`: URL content extraction - `linkedInSearch.ts`: LinkedIn profile/company search - `deepResearchStart.ts` & `deepResearchCheck.ts`: Asynchronous research workflow ### Configuration Tools can be selectively enabled/disabled via: - Command line: `--tools=web_search_exa,get_code_context_exa` - Environment: `enabledTools` array in config - Remote URL: `enabledTools` query parameter ### Key Dependencies - **@modelcontextprotocol/sdk**: MCP server implementation - **axios**: HTTP client for Exa API calls - **zod**: Runtime type validation - **@smithery/cli**: Build tooling and development server ## Development Guidelines ### Adding New Tools 1. Create tool file in `src/tools/` following existing pattern 2. Export `register[ToolName]Tool` function 3. Add tool to `availableTools` registry in `index.ts` 4. Implement registration logic in main server function ### Tool Implementation Pattern Each tool should: - Accept MCP server and config objects - Use zod schemas for input validation - Return properly formatted MCP responses - Include error handling and logging - Keep under 400 lines (split if needed) ### Configuration Management - Use `config.exaApiKey` for API authentication - Check `config.enabledTools` array before registering - Support `config.debug` flag for verbose logging - Use API_CONFIG constants for endpoint URLs ### Build Process - Smithery CLI handles TypeScript compilation - Outputs to `.smithery/index.cjs` - Creates executable with proper shebang - Supports both stdio and HTTP transports ## Testing Approach Use the MCP inspector to test tools: ```bash npm run inspector ``` This provides a web interface to test tool calls and view responses. ## Deployment ### Local Testing ```bash npx exa-mcp-server --tools=web_search_exa,get_code_context_exa ``` ### Remote Usage Server can be accessed remotely at: `https://mcp.exa.ai/mcp` ### Smithery Integration Server is available on Smithery at: `https://smithery.ai/server/exa`