{
  "markdown": "# Agent Search MCP: Free-first Web Search with Inspectable Evidence\n\n**A Node.js MCP server and CLI for English and Chinese web search.**\n\nAgent Search MCP starts without an API key. It returns compact multi-source\nevidence, records provider failures, and bounds work with request and evidence\nbudgets. Paid providers run only when policy and credentials allow.\n\n[![npm version](https://img.shields.io/npm/v/agent-search-mcp)](https://www.npmjs.com/package/agent-search-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/agent-search-mcp)](https://www.npmjs.com/package/agent-search-mcp)\n[![GitHub stars](https://img.shields.io/github/stars/lennney/agent-search-mcp)](https://github.com/lennney/agent-search-mcp/stargazers)\n[![CI](https://github.com/lennney/agent-search-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/lennney/agent-search-mcp/actions)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)\n[![Glama](https://glama.ai/mcp/servers/lennney/agent-search-mcp/badges/score.svg)](https://glama.ai/mcp/servers/lennney/agent-search-mcp)\n\n[中文文档](README_zh.md) · [Product page](https://take-a-deep-breath0.com/en/agent-search-mcp) · [Benchmarks](./benchmarks/) · [Architecture](./docs/architecture.md) · [CHANGELOG](./CHANGELOG.md)\n\n---\n\n## Install\n\n```bash\nnpx -y agent-search-mcp\n```\n\nRequires Node.js >= 18.17. The default runtime does not require a browser,\ndatabase, Python, or a search API account.\n\n### Connect an MCP client\n\nUse this stdio configuration in MCP clients that accept `mcpServers` JSON,\nincluding Claude Desktop, Cursor, VS Code, and Windsurf:\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-search\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agent-search-mcp\"]\n    }\n  }\n}\n```\n\nClaude Code and Codex can register the same `npx -y agent-search-mcp` stdio\ncommand through their MCP settings.\n\n### Add the optional Agent Skill\n\nAfter connecting the MCP server, Agent Skills-compatible clients can install\nthe repository-owned routing guide:\n\n```bash\nnpx skills add lennney/agent-search-mcp --skill agent-search\n```\n\nInvoke it with a request such as `Use $agent-search to verify this claim with\nofficial sources.` The [Agent Search Skill](./skills/agent-search/SKILL.md)\nchooses one of four bounded paths: quick discovery, stricter verification,\nChinese-source search, or extraction of a selected URL. It checks that the\nneeded MCP tool exists and asks before any install or configuration change.\nInstalling the Skill does not start or configure the MCP server.\n\n### Example: inspect a bounded search result\n\nAfter building the local package, run a CLI query without adding a provider key:\n\n```bash\nnpm run build\nfasm search \"MCP server without an API key\" --json\n```\n\nThe response contract keeps result evidence, `meta.execution`, and\n`partialFailures` separate. A provider timeout or challenge remains visible to\nthe agent instead of being converted into an unexplained empty result. This is\na contract example, not a live availability or search-quality benchmark.\n\nAfter a global install, check the local runtime without making a search request:\n\n```bash\nnpm install -g agent-search-mcp\nfasm doctor\n```\n\n## Why Agent Search MCP\n\n| Need | Product behavior |\n|---|---|\n| Free web search | Zero-key sources work without an API account |\n| Provider cost control | Paid providers run only under an explicit routing policy |\n| Token cost control | Compact output and one evidence budget bound response size |\n| Multi-source evidence | Results retain provenance, relevance, provider-family count, and partial failures |\n| Chinese web search | Sogou and Baidu handle Chinese queries without a translation layer |\n| Lightweight self-hosting | Pure Node.js runtime with stdio, Streamable HTTP, and CLI access |\n\n### The difference from a plain multi-engine wrapper\n\n| Plain multi-engine aggregation | Agent Search MCP |\n|---|---|\n| Returns N deduplicated results | Returns results plus the number of **independent sources** (provider families, not adapter names) |\n| A provider failure quietly drops some results | Every failure stays in `partialFailures` (timeout, rate limit, challenge, permission, budget) |\n| Stops when the result count looks sufficient | Stops only after a quality gate (count, relevance, confidence, source coverage) and returns the `stop_reason` |\n| Fixed-size output | One shared evidence budget bounds response tokens; compact text keeps provenance |\n| One adapter counts as one source | The same upstream through several adapters never inflates `source_count` |\n\nThe one-minute offline demo replays these differences through the production\nevidence scorer and formatter:\n\n### Inspect the search evidence\n\nEach JSON response includes one Search Evidence Packet. It answers the routing\nquestions an agent needs before it uses a result:\n\n| Question | Response field |\n|---|---|\n| Which adapters ran? | `meta.execution.searched_engines` |\n| Why did the router stop? | `meta.execution.stop_reason` and `meta.execution.quality_gate` |\n| Did the request hit a work limit? | `meta.execution.budget` |\n| Was evidence truncated? | `meta.evidence_budget` |\n| Did an upstream provider fail? | `partialFailures` |\n| Do multiple adapters represent independent sources? | `results[].source_count` counts provider families, not adapter names |\n\nRun the one-minute offline contract demo:\n\n```bash\nnpm run demo:evidence\nnpm run demo:evidence -- --json\n```\n\nIt replays three synthetic scenarios through the production evidence scorer,\nformatter, and MCP output helper: same-family adapter overlap, visible fallback\nfailure, and a bounded quality-gate stop. It makes no live availability or\nsearch-quality claim and performs no network request.\n\nThe default `free_first` policy never spends a configured API credential.\n`free_only` blocks paid providers. `quality_escalation` can call one configured\npaid provider after free evidence misses the quality gate, while `paid_first`\ntries that provider before the free fallback.\n\nRequest budgets cap adapter attempts, elapsed time, and admitted results.\nThe evidence budget caps query-relevant passages across the complete response.\nCompact mode keeps full detail for the first results and reduces later entries\nto source-preserving references.\n\n### Measured token reduction\n\nThe checked-in bilingual fixture measures formatting with a locked tokenizer:\n\n| Output | Average tokens per query | Savings vs normal |\n|---|---:|---:|\n| Normal | 2396.0 | |\n| Compact | 1650.1 | 31.1% |\n| Compact+ | 1633.0 | 31.8% |\n\nThis fixture verifies output formatting and evidence-packet behavior. It does\nnot measure live engine availability or search quality. See the\n[benchmark method and limitations](./benchmarks/#reproducible-fixture-replay).\n\n## How the search router works\n\n```mermaid\nflowchart LR\n    A[\"AI agent\"] --> M[\"MCP search tools\"]\n    M --> P[\"Provider and request policy\"]\n    P --> F[\"Zero-key sources\"]\n    P --> O[\"Optional paid provider\"]\n    F --> E[\"Deduplicate, rank, and preserve failures\"]\n    O --> E\n    E --> B[\"Evidence and token budget\"]\n    B --> R[\"Compact multi-source result\"]\n```\n\nThe router evaluates each search batch against separate result, relevance,\nconfidence, and provider-family gates. It stops after the evidence passes those\ngates and exposes the decision in `meta.execution`. Provider failures stay\nvisible in `partialFailures`, so an empty result cannot hide an upstream error.\n\nThe [competitive landscape (2026-08-07)](./docs/research/2026-08-07-competitive-landscape-and-product-gaps.md)\nmaps the crowded baseline and the product gaps. It records source dates and\nfixed commits for facts that can change. The\n[2026-08-10 update](./docs/research/2026-08-10-competitive-landscape-update.md)\nadds competitor activity since then: direct local competitors are dormant, and\ntoken-efficient evidence is becoming an industry-explicit lever. The earlier\n[source-level product comparison](./docs/research/2026-07-26-agent-search-product-architecture.md)\ncontains the architecture-specific evidence.\n\n---\n\n<!-- BEGIN GENERATED CAPABILITY MATRIX -->\n## Engines\n\nThe runtime registers 16 adapters: 9 zero-key adapters and 7 optional API adapters.\n\n| Engine | Access | Languages | Role |\n|---|---|---|---|\n| DuckDuckGo | Zero-key | en | General Web Search |\n| Sogou Search | Zero-key | zh | Chinese Web Search |\n| Bing | Zero-key | en, zh | Multilingual Web Search |\n| Baidu | Zero-key | zh | Chinese Web Search |\n| Wikipedia | Zero-key | en, zh, ja, de, fr, es, auto | Encyclopedic references |\n| Startpage | Zero-key | en, auto | Privacy-oriented Web Search |\n| Yandex | Zero-key | ru, en, auto | Russian and international Web Search |\n| Mojeek | Zero-key | en, auto | Independent privacy-oriented index |\n| Wiby | Zero-key | en | Independent small-Web index |\n| Brave Search | `BRAVE_API_KEY` | en, zh | Optional commercial Web Search |\n| Tavily Search | `TAVILY_API_KEY` | en, zh | Optional agent-oriented Search |\n| Exa Search | `EXA_API_KEY` | en, zh | Optional neural Search |\n| You.com Search | `YDC_API_KEY` | en, zh | Optional commercial Web Search |\n| Tencent Web Search API | `TENCENT_WSA_API_KEY` | zh | Optional official Chinese Web Search |\n| Bocha Web Search | `BOCHA_API_KEY` | zh, en | Optional Chinese-first AI Search |\n| Serper Google Search | `SERPER_API_KEY` | en, zh, auto | Optional Google SERP Search |\n\n## Tools\n\n| Tool | Description | Best for |\n|---|---|---|\n| `free_search` | Multi-engine Web Search with bounded fallback | Quick facts and general discovery |\n| `free_search_advanced` | Filtered waterfall search and optional enrichment | Domain policy and progressive verification |\n| `free_extract` | Extract a URL as clean Markdown | Reading complete source pages |\n| `fetch_github_readme` | Fetch a public GitHub repository README | Project documentation |\n| `fetch_csdn_article` | Fetch a CSDN article | Chinese technical articles |\n| `fetch_juejin_article` | Fetch a Juejin article | Chinese developer articles |\n| `search_with_synthesis` | Search evidence with an LLM synthesis hint | Agent-authored answers from cited evidence |\n\n### Capability controls\n\n| Environment | Default | Purpose |\n|---|---|---|\n| `ENABLED_TOOLS / DISABLED_TOOLS` | all / none | Tool registration allowlist and denylist; deny wins |\n| `ALLOWED_ENGINES / DENIED_ENGINES` | all / none | Engine execution allowlist and denylist; deny wins |\n| `SEARCH_PROVIDER_MODE` | free_first | Default routing: free_first, quality_escalation, paid_first, or free_only |\n| `PAID_ENGINE_ORDER` | brave,exa,tavily,youcom,tencent_wsa,bocha,serper | Selects the first configured optional provider; not a quality claim |\n| `SEARCH_BUDGET_MAX_CALLS` | 16 | Adapter-attempt budget |\n| `SEARCH_BUDGET_MAX_ELAPSED_MS` | 30000 | End-to-end elapsed-time budget |\n| `SEARCH_BUDGET_MAX_RESULTS` | 100 | Admitted raw-result budget |\n| `EVIDENCE_BUDGET_CHARS` | 1200 | Evidence-character budget |\n<!-- END GENERATED CAPABILITY MATRIX -->\n\n`search_with_synthesis` uses the same canonical `structuredContent` evidence\npacket as the primary search tools and adds `prompt_hint`; its text content is\nonly a compact compatibility view. Execution metadata distinguishes scheduled\nadapters from retry-inclusive adapter attempts. `http_requests` is `null` until\nall adapter transports can report it without false precision.\n\nWiby is a genuine zero-key source backed by its official JSON API and is used\nlate in the free waterfall as an independent small-Web supplement. Optional\nproviders require user credentials; any signup credit or trial quota is\nprovider-controlled and is not treated as permanent free access.\n\nAll tools are read-only and idempotent. Search cancellation reaches rate-limit\nwaits, retries, provider requests, and optional enrichment. Enrichment can\nimprove a snippet but cannot increase source confidence or independent source\ncount.\n\n`free_search_advanced.time_range` remains in the compatibility schema. The\nserver returns `UNSUPPORTED_FILTER` before searching because the general web\nproviders do not share one enforceable recency contract.\n\n---\n\n## Configuration\n\nThe generated capability table above lists the default request budgets. These\nsettings cover the common deployment choices:\n\n| Goal | Environment variables |\n|---|---|\n| Add an optional provider | `BRAVE_API_KEY`, `TAVILY_API_KEY`, `EXA_API_KEY`, `YDC_API_KEY`, `TENCENT_WSA_API_KEY`, `BOCHA_API_KEY`, or `SERPER_API_KEY` |\n| Choose spend policy | `SEARCH_PROVIDER_MODE`, `PAID_ENGINE_ORDER` |\n| Reduce response tokens | `OUTPUT_STYLE=compact`, `MAX_FULL_RESULTS`, `SNIPPET_LENGTH`, `EVIDENCE_BUDGET_CHARS` |\n| Restrict tools or engines | `ENABLED_TOOLS`, `DISABLED_TOOLS`, `ALLOWED_ENGINES`, `DENIED_ENGINES` |\n| Use an explicit proxy | `DUCKDUCKGO_PROXY_URL`, `SOGOU_PROXY_URL`, `MOJEEK_PROXY_URL`, `WIBY_PROXY_URL`, or `USE_PROXY=true` with `PROXY_URL` |\n| Use a user-owned proxy pool | `DUCKDUCKGO_PROXY_URLS`, `SOGOU_PROXY_URLS`, `MOJEEK_PROXY_URLS`, or `WIBY_PROXY_URLS` as a JSON array of 2-16 HTTP(S) proxy URLs |\n| Persist the exact-result cache | `SEARCH_CACHE_DIRECTORY`, `SEARCH_CACHE_TTL_MS`, `SEARCH_CACHE_MAX_ENTRIES` |\n| Enable optional semantic processing | `SEMANTIC_DEDUP`, `SEMANTIC_RERANK`, `DEDUP_THRESHOLD`, `RERANK_TOP_K` |\n\nAdding an API key does not authorize paid traffic. The routing policy controls\nprovider use. The default exact-result cache stays in memory; setting\n`SEARCH_CACHE_DIRECTORY` opts into local persistence. Semantic processing is\nthe only optional feature that uses Python and Model2Vec.\n\nProxy pools select a deterministic first exit from the logical query and keep\nmulti-step provider requests sticky. Only a transport failure can move to the\nnext configured exit; a failed transport is cooled for 60 seconds. HTTP\nresponses, including 403, 429, and challenge pages, never trigger proxy\nswitching and continue through the provider's existing cooldown contract.\nEngine-specific single-proxy variables take precedence over their pool. Proxy\ncredentials are never printed by `fasm doctor`.\n\n### HTTP deployment\n\nHTTP mode requires `HTTP_AUTH_TOKEN` unless you set\n`HTTP_ALLOW_UNAUTHENTICATED=true`. Browser requests with an `Origin` header must\nmatch `ALLOWED_ORIGINS`. See the [HTTP deployment guide](./docs/http-deployment.md)\nfor TLS termination, token rotation, and reverse-proxy examples.\n\n---\n\n## CLI\n\nThe package includes the `fasm` CLI:\n\n```bash\nfasm search \"TypeScript MCP server\"\nfasm search \"query\" --count 5 --engines bing,baidu,youcom --json\nfasm extract \"https://example.com\"\nfasm extract \"https://example.com\" --json\nfasm doctor\nfasm doctor --json\nHTTP_AUTH_TOKEN=change-me MODE=http npx agent-search-mcp\n```\n\n`fasm doctor` reads local configuration without network probes and never prints\ncredential or proxy values.\n\n---\n\n## Documentation and evidence\n\n| Document | Contents |\n|---|---|\n| [System architecture](./docs/architecture.md) | Routing, evidence, provider families, and configuration |\n| [Competitive landscape (2026-08-10)](./docs/research/2026-08-10-competitive-landscape-update.md) | Competitor activity through 2026-08-10, positioning, and improvement priorities |\n| [Competitive landscape (2026-08-07)](./docs/research/2026-08-07-competitive-landscape-and-product-gaps.md) | Baseline competitors, expectations, and product gaps snapshot |\n| [Product comparison](./docs/research/2026-07-26-agent-search-product-architecture.md) | Source-level review of Agent search products |\n| [Benchmarks](./benchmarks/) | Token fixture, live-run scope, and quality evaluation method |\n| [v3.2.0 release notes](./docs/releases/v3.2.0.md) | Provider policy, budgets, and migration notes |\n| [Earlier release candidate evidence](./docs/evidence/2026-07-26-release-candidate-smoke.md) | Pre-expansion packed-install matrix and limitations |\n| [MCP 2026 readiness](./docs/plans/2026-07-25-mcp-ecosystem-and-2026-readiness.md) | Isolated protocol experiment and remaining gates |\n\n## Companion: Slim Guard\n\nAgent Search controls retrieval work and compresses search evidence.\n[mcp-slim-guard](https://github.com/lennney/mcp-slim-guard) sits between an\nagent and MCP servers to handle tool-schema compression and security policy.\n\n```bash\nnpm install -g mcp-slim-guard\n```\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/lennney/agent-search-mcp.git\ncd agent-search-mcp\nnpm install\nnpm run build\nnpm test\nnpm run dev        # stdio mode\nnpm run dev:http   # HTTP mode (port 3000)\n```\n\nThe stable package supports Node.js 18, 20, and 22. The isolated MCP 2026\nexperiment requires Node.js 20 or newer.\n\n---\n\n## License\n\n[Apache 2.0](LICENSE)\n\nBased on [open-websearch](https://github.com/Aas-ee/open-websearch) by Aas-ee.\n\nIf Agent Search MCP helps your agent, [star the repository](https://github.com/lennney/agent-search-mcp)\nso other developers can find the project.\n",
  "bytes": 16823,
  "sha": "7c9d33ba61a8ba11d01858d9b7ad5750489eae04d936f66d97e208852035cae2",
  "repo_slug": "lennney/agent-search-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lennney_agent_search_mcp_ada6e329/readme"
}