Agent Search Mcp
io.github.lennneyPublished by GitHub account lennneyv3.2.1Updated Oct 27, 2026
Free-first Chinese and English web search MCP using zero-key sources and inspectable evidence.
Overview
Free-first English and Chinese web search MCP server that runs locally on Node.js and returns compact, inspectable multi-source evidence.
- What you can do
- Run bounded multi-engine web searches, including a filtered waterfall variant with optional enrichment
- Extract a URL as clean Markdown, and fetch GitHub READMEs, CSDN articles and Juejin articles
- Search with an LLM synthesis hint built on the same cited evidence packet
- Report execution metadata: engines used, stop reason, budgets, evidence truncation and partial provider failures
- Run the same queries from a bundled CLI, including a local configuration check
- When to use it
- Useful when an assistant needs web search in English or Chinese without signing up for a search API, or when you want search results with visible provenance and provider failures rather than a bare list of links. It also suits verification work where bounded, token-efficient evidence matters.
- Requirements
- Node.js 18.17 or newer; runs as a local stdio process, typically via npx. No API key, browser, database or Python is needed for the default zero-key engines. Optional paid engines need their own keys (BRAVE_API_KEY, TAVILY_API_KEY, EXA_API_KEY, YDC_API_KEY, TENCENT_WSA_API_KEY, BOCHA_API_KEY, SERPER_API_KEY). Optional semantic processing uses Python and Model2Vec; HTTP mode requires HTTP_AUTH_TOKEN unless explicitly disabled.
Installation
In SourceWeft
- Open Agent Search Mcp in the dashboard and add it to a workspace.
- Enable the server for the chats that should use its tools.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Other MCP clients
Follow the launch instructions in the repository.
README
Agent Search MCP: Free-first Web Search with Inspectable Evidence
A Node.js MCP server and CLI for English and Chinese web search.
Agent Search MCP starts without an API key. It returns compact multi-source evidence, records provider failures, and bounds work with request and evidence budgets. Paid providers run only when policy and credentials allow.
[npm version] [npm downloads] [GitHub stars] [CI] [License] [Glama]
中文文档 · Product page · Benchmarks · Architecture · CHANGELOG
Install
Requires Node.js >= 18.17. The default runtime does not require a browser, database, Python, or a search API account.
Connect an MCP client
Use this stdio configuration in MCP clients that accept mcpServers JSON,
including Claude Desktop, Cursor, VS Code, and Windsurf:
Claude Code and Codex can register the same npx -y agent-search-mcp stdio
command through their MCP settings.
Add the optional Agent Skill
After connecting the MCP server, Agent Skills-compatible clients can install the repository-owned routing guide:
Invoke it with a request such as Use $agent-search to verify this claim with official sources. The Agent Search Skill
chooses one of four bounded paths: quick discovery, stricter verification,
Chinese-source search, or extraction of a selected URL. It checks that the
needed MCP tool exists and asks before any install or configuration change.
Installing the Skill does not start or configure the MCP server.
Example: inspect a bounded search result
After building the local package, run a CLI query without adding a provider key:
The response contract keeps result evidence, meta.execution, and
partialFailures separate. A provider timeout or challenge remains visible to
the agent instead of being converted into an unexplained empty result. This is
a contract example, not a live availability or search-quality benchmark.
After a global install, check the local runtime without making a search request:
Why Agent Search MCP
The difference from a plain multi-engine wrapper
The one-minute offline demo replays these differences through the production evidence scorer and formatter:
Inspect the search evidence
Each JSON response includes one Search Evidence Packet. It answers the routing questions an agent needs before it uses a result:
Run the one-minute offline contract demo:
It replays three synthetic scenarios through the production evidence scorer, formatter, and MCP output helper: same-family adapter overlap, visible fallback failure, and a bounded quality-gate stop. It makes no live availability or search-quality claim and performs no network request.
The default free_first policy never spends a configured API credential.
free_only blocks paid providers. quality_escalation can call one configured
paid provider after free evidence misses the quality gate, while paid_first
tries that provider before the free fallback.
Request budgets cap adapter attempts, elapsed time, and admitted results. The evidence budget caps query-relevant passages across the complete response. Compact mode keeps full detail for the first results and reduces later entries to source-preserving references.
Measured token reduction
The checked-in bilingual fixture measures formatting with a locked tokenizer:
This fixture verifies output formatting and evidence-packet behavior. It does not measure live engine availability or search quality. See the benchmark method and limitations.
How the search router works
The router evaluates each search batch against separate result, relevance,
confidence, and provider-family gates. It stops after the evidence passes those
gates and exposes the decision in meta.execution. Provider failures stay
visible in partialFailures, so an empty result cannot hide an upstream error.
The competitive landscape (2026-08-07) maps the crowded baseline and the product gaps. It records source dates and fixed commits for facts that can change. The 2026-08-10 update adds competitor activity since then: direct local competitors are dormant, and token-efficient evidence is becoming an industry-explicit lever. The earlier source-level product comparison contains the architecture-specific evidence.
Engines
The runtime registers 16 adapters: 9 zero-key adapters and 7 optional API adapters.
Tools
Capability controls
search_with_synthesis uses the same canonical structuredContent evidence
packet as the primary search tools and adds prompt_hint; its text content is
only a compact compatibility view. Execution metadata distinguishes scheduled
adapters from retry-inclusive adapter attempts. http_requests is null until
all adapter transports can report it without false precision.
Wiby is a genuine zero-key source backed by its official JSON API and is used late in the free waterfall as an independent small-Web supplement. Optional providers require user credentials; any signup credit or trial quota is provider-controlled and is not treated as permanent free access.
All tools are read-only and idempotent. Search cancellation reaches rate-limit waits, retries, provider requests, and optional enrichment. Enrichment can improve a snippet but cannot increase source confidence or independent source count.
free_search_advanced.time_range remains in the compatibility schema. The
server returns UNSUPPORTED_FILTER before searching because the general web
providers do not share one enforceable recency contract.
Configuration
The generated capability table above lists the default request budgets. These settings cover the common deployment choices:
Adding an API key does not authorize paid traffic. The routing policy controls
provider use. The default exact-result cache stays in memory; setting
SEARCH_CACHE_DIRECTORY opts into local persistence. Semantic processing is
the only optional feature that uses Python and Model2Vec.
Proxy pools select a deterministic first exit from the logical query and keep
multi-step provider requests sticky. Only a transport failure can move to the
next configured exit; a failed transport is cooled for 60 seconds. HTTP
responses, including 403, 429, and challenge pages, never trigger proxy
switching and continue through the provider's existing cooldown contract.
Engine-specific single-proxy variables take precedence over their pool. Proxy
credentials are never printed by fasm doctor.
HTTP deployment
HTTP mode requires HTTP_AUTH_TOKEN unless you set
HTTP_ALLOW_UNAUTHENTICATED=true. Browser requests with an Origin header must
match ALLOWED_ORIGINS. See the HTTP deployment guide
for TLS termination, token rotation, and reverse-proxy examples.
CLI
The package includes the fasm CLI:
fasm doctor reads local configuration without network probes and never prints
credential or proxy values.
Documentation and evidence
Companion: Slim Guard
Agent Search controls retrieval work and compresses search evidence. mcp-slim-guard sits between an agent and MCP servers to handle tool-schema compression and security policy.
Development
The stable package supports Node.js 18, 20, and 22. The isolated MCP 2026 experiment requires Node.js 20 or newer.
License
Based on open-websearch by Aas-ee.
If Agent Search MCP helps your agent, star the repository so other developers can find the project.
Source: README.md at commit dd91577
Tools
0Version history
1- v3.2.1LatestSep 16, 2026
Score
50% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
- Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
- Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
- Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
- DescriptionRequired15 pts
- Logo10 pts
- Documentation15 pts
- License10 pts
