WebSearch Integration
Relevant source files
The following files were used as context for generating this wiki page:
WebSearch Integration is a core feature of the CCS (Claude Code Switch) project designed to provide managed web lookup capabilities for AI runtimes. It allows the system to provision local tools like WebSearch for third-party launches, ensuring that AI agents have access to current web information without requiring manual tool wiring.
The system acts as a bridge, enabling search providers such as Exa, Tavily, Brave Search, and SearXNG. It integrates directly into the Claude environment via hooks and Model Context Protocol (MCP) servers, allowing runtimes like Claude Code or Codex to execute web queries through a unified interface.
Sources: README.md:144-149, tests/unit/hooks/ccs-websearch-mcp-server.test.ts:145-151
Architecture and Components
The WebSearch integration consists of three primary layers: the configuration/API layer, the Hook injection system, and the MCP server.
Component Overview
| Component | Description |
|---|---|
| MCP Server | Implements the Model Context Protocol to expose a WebSearch tool to AI clients. |
| Hook Manager | Injects PreToolUse hooks into the Claude settings.json to intercept and manage tool calls. |
| WebSearch API | Provides REST endpoints for the dashboard to manage API keys and provider settings. |
| Providers | Integration points for search engines (Exa, Tavily, Brave, SearXNG, DuckDuckGo). |
Sources: src/utils/websearch/hook-config.ts:13-20, tests/unit/web-server/websearch-routes.test.ts:24-30, tests/unit/mcp-manager.test.ts:21-30
Logic Flow: Provider Selection
The system uses an "auto" selection logic or specific manual overrides to determine which search provider to use based on available API keys and configuration settings.
Sources: tests/unit/mcp-manager.test.ts:31-68
Model Context Protocol (MCP) Server
The ccs-websearch-server.cjs is an MCP-compliant server that exposes the WebSearch tool. It handles the initialize, tools/list, and tools/call methods.
Tool Definition
The server exposes a tool named WebSearch (with a legacy alias search).
- Description: A third-party WebSearch replacement for CCS-managed Claude launches.
- Input Schema: An object with a required
querystring property. - Provider Priority: Exa > Tavily > Brave Search > SearXNG > DuckDuckGo.
Sources: tests/unit/hooks/ccs-websearch-mcp-server.test.ts:143-162, tests/unit/hooks/ccs-websearch-mcp-server.test.ts:221-230
Server Interaction Flow
The following sequence shows how a client interacts with the WebSearch MCP server to perform a lookup.
Hook Configuration and Injection
CCS manages web search integration by modifying the Claude settings.json file. This is handled by the hook-config.ts module, which ensures a PreToolUse hook is correctly registered.
Hook Mechanism
The hook is registered as a command type that executes a node script: node "/path/to/websearch-transformer.cjs".
- Matcher: The hook specifically targets the
WebSearchmatcher. - Timeout Calculation: The timeout is dynamically calculated as the maximum timeout of all enabled providers plus a 30-second buffer.
- Default Timeout: If no specific timeouts are configured, it defaults to a minimum of 60 seconds (calculated as
MIN_HOOK_TIMEOUT+HOOK_TIMEOUT_BUFFER).
Sources: src/utils/websearch/hook-config.ts:35-64
Hook Management Functions
| Function | Purpose |
|---|---|
getWebSearchHookConfig() | Generates the JSON structure for the hook, including path and computed timeout. |
ensureHookConfig() | Idempotently writes the hook to ~/.claude/settings.json, cleaning up duplicates. |
removeHookConfig() | Safely removes CCS-managed hooks while preserving user-defined hooks. |
Sources: src/utils/websearch/hook-config.ts:41-45, src/utils/websearch/hook-config.ts:70-75, src/utils/websearch/hook-config.ts:167-172
API and Configuration
The websearch-routes.ts module defines the REST API used by the dashboard to configure the service.
Endpoints
- GET
/api/websearch: Returns the current configuration and masked API key state. - GET
/api/websearch/status: Returns readiness state and specific provider availability. - PUT
/api/websearch: Updates provider settings (e.g.,max_results,enabled) and persists API keys to the global environment.
Sources: tests/unit/web-server/websearch-routes.test.ts:133-145, tests/unit/web-server/websearch-routes.test.ts:153-170
Provider-Specific Validation: SearXNG
The system includes specific logic for SearXNG:
- URL Normalization: Clamps URLs to base paths (e.g.,
.../search/becomes.../custom). - Credential Sanitization: Rejects or sanitizes URLs containing credentials, queries, or hashes.
- Result Clamping: Clamps
max_resultsto a maximum of 10.
Sources: tests/unit/web-server/websearch-routes.test.ts:241-260, tests/unit/web-server/websearch-routes.test.ts:223-233
Summary
WebSearch Integration in CCS provides a robust, provider-agnostic way for AI agents to perform web lookups. By combining Model Context Protocol servers with automated configuration of Claude hooks, CCS abstracts the complexity of managing multiple search APIs and ensuring they are correctly exposed to different AI runtimes. The system prioritizes security by sanitizing credentials and ensures reliability through dynamic timeout management and fallback provider logic.
Sources: README.md:144-149, src/utils/websearch/hook-config.ts:35-64, tests/unit/mcp-manager.test.ts:31-68