MySearch-Proxy

# MySearch Proxy [English Guide](./README_EN.md) `MySearch Proxy` is a unified search stack designed for AI assistants. It consolidates four previously separate components into a single repository: - `mysearch/` - The actual installable MySearch MCP - `skill/` - Skills and installation instructions for Codex / Claude Code - `openclaw/` - An independent skill bundle for OpenClaw / ClawHub - `proxy/` - A console and proxy layer for team or public deployment Supported search capabilities: - Tavily - Firecrawl - Exa - Optional X / Social The goal is simple: - Let local AI assistants get started quickly - Let OpenClaw install directly - Let teams share a unified search backend - Let callers focus less on underlying provider differences Project entrance: - GitHub: [skernelx/MySearch-Proxy](https://github.com/skernelx/MySearch-Proxy) - Docker Hub: [skernelx/mysearch-proxy](https://hub.docker.com/r/skernelx/mysearch-proxy) - ClawHub: [clawhub.ai/skernelx/mysearch](https://clawhub.ai/skernelx/mysearch)  ## Why Create This Project Many search-related projects only solve a small part of the problem: - Only provide a `web_search` - Only search, no content extraction - Only use official APIs, no self-built gateway support - Only provide prompts, no actual runtime - Only create key panels, no solution for AI invocation `MySearch Proxy` aims to complete the entire chain: ```text Upstream provider / aggregation gateway -> Tavily / Firecrawl / Exa / X / Social MySearch Proxy -> Console, token, quota synchronization, compatible proxy interface MySearch MCP / Codex Skill / OpenClaw Skill -> Directly usable for Codex, Claude Code, OpenClaw, and other agents ``` ## Recommended Architecture The currently recommended architecture is `proxy-first`: ```text Upstream provider -> MySearch Proxy -> Generate MySearch universal token -> MySearch MCP / OpenClaw skill / Other agents ``` The benefits of this approach are: - Clients only need a set of `MYSEARCH_PROXY_*` - Tavily / Firecrawl / Exa are no longer scattered across every machine - Unified management of tokens, call statistics, and quota synchronization - OpenClaw, local Codex, and team proxies can reuse the same configuration If you don't have a Proxy yet, you can also let `mysearch/` or `openclaw/` connect directly to the official provider. ## Latest Optimizations (v0.1.11) This version focuses on improving provider health status from "just checking if there's a key" to "determining if the key is alive," and adding self-protection for failed providers in docs/resource routing. - Configuration entry consolidation: - `MySearch` runtime now prioritizes reading `~/.codex/config.toml` for `mcp_servers.mysearch.env`. - `install.sh` inherits existing host-registered `MYSEARCH_*`, then uses `mysearch/.env` to supplement default values. - OpenClaw wrapper prioritizes reading `openclaw.json` for `skills.entries.mysearch.env`. - `.env` is still supported but only for local single-repository debugging. - Document/resource result reordering: - Blended results for `docs/github/pdf/resource/tutorial` now prioritize official domains and paths. - When `include_domains` is explicitly passed, results are stabilized to prioritize matching domains. - Provider health check and routing self-protection: - `health` now returns each provider's `live_status`, `live_error`, and `last_checked_at`. - For example, if a Tavily key is invalid or disabled, it will be clearly displayed as `auth_error`. ## Getting Started Follow the usage scenario: - Just want to get Codex/Claude Code started locally: See [mysearch/README.md](./mysearch/README.md) - Want AI to automatically understand installation and usage: See [skill/README.md](./skill/README.md) - Want to install an independent search skill for OpenClaw/ClawHub: See [openclaw/README.md](./openclaw/README.md) - Want to deploy a console and manage keys/tokens/quotas: See [proxy/README.md](./proxy/README.md) ## Quick Start in 5 Minutes ### Route A: Directly Install MySearch MCP Locally ```bash cd /path/to/MySearch-Proxy python3 -m venv venv ``` Prioritize placing configuration directly into the host config: - `Codex`: `~/.codex/config.toml` for `mcp_servers.mysearch.env` - `OpenClaw`: `openclaw.json` for `skills.entries.mysearch.env` - `.env`: Only recommended for local single-repository debugging Recommended minimal configuration: ```env MYSEARCH_PROXY_BASE_URL=https://your-mysearch-proxy.example.com MYSEARCH_PROXY_API_KEY=mysp-... ``` Installation: ```bash ./install.sh ``` Verification: ```bash python3 skill/scripts/check_mysearch.py --health-only python3 skill/scripts/check_mysearch.py --web-query "OpenAI latest announcements" ``` ### Route B: Deploy Proxy First, Then Reuse for All Clients ```bash mkdir -p mysearch-proxy-data docker run -d \ --name mysearch-proxy \ --restart unless-stopped \ -p 9874:9874 \ -e ADMIN_PASSWORD=change-me \ -v $(pwd)/mysearch-proxy-data:/app/data \ skernelx/mysearch-proxy:latest ``` After deployment: 1. Log in to the console 2. Add Tavily/Firecrawl/Exa/Social upstream configurations 3. Create a MySearch universal token 4. Fill the token into `mysearch/.env` or OpenClaw skill env ## Directory Explanation ### `mysearch/` The actual runnable MCP service. Provides four tools: - `search` - `extract_url` - `research` - `mysearch_health` Supports: - `stdio` - `streamableHTTP` - `sse` Detailed explanation: [mysearch/README.md](./mysearch/README.md) ### `skill/` This layer is not MCP implementation but installation and usage instructions for AI assistants. Suitable for: - Codex automatic installation - Claude Code connection via README + SKILL Detailed explanation: [skill/README.md](./skill/README.md) ### `openclaw/` An independently packaged OpenClaw skill bundle. Features: - Self-contained runtime - Local installation - Publishable to ClawHub - Recommended injection of `MYSEARCH_PROXY_*` via skill env Detailed explanation: [openclaw/README.md](./openclaw/README.md) ### `proxy/` The console and proxy layer of the entire system. Responsible for: - Provider key pool - MySearch token pool - Call statistics - Official quota synchronization - `/social/search` compatible entry Detailed explanation: [proxy/README.md](./proxy/README.md) ## Routing Strategy MySearch does not default to "send all questions to one provider." Current recommended understanding: - `web/news` - Prioritize Tavily - `docs/github/pdf/pricing/changelog` - Prioritize Firecrawl - General web supplement discovery - Fall back to Exa - `social` - Use xAI or compatible `/social/search` - `extract_url` - Prioritize Firecrawl, fall back to Tavily extract if failed or empty - `research` - Search first, then extract content, and optionally supplement Social/X ## Suitable Scenarios - Default search entry for local development assistants - Default search skill for OpenClaw - A unified search backend shared by multiple agents - You already have Tavily/Firecrawl/xAI upstream and want a unified entrance ## Documentation Map - Overall architecture: [docs/mysearch-architecture.md](./docs/mysearch-architecture.md) - MCP: [mysearch/README.md](./mysearch/README.md) - OpenClaw: [openclaw/README.md](./openclaw/README.md) - Proxy: [proxy/README.md](./proxy/README.md) - Codex/Claude Code skill: [skill/README.md](./skill/README.md) ## Current Public Pages - Docker Hub: [skernelx/mysearch-proxy](https://hub.docker.com/r/skernelx/mysearch-proxy) - ClawHub: [clawhub.ai/skernelx/mysearch](https://clawhub.ai/skernelx/mysearch) The image below is a historical screenshot of public pages; please refer to the live page for the latest status: