search-boost-mcp
Multi-engine web search and page-reading toolkit for AI agents — search the web without API keys, read pages, pull X/Twitter posts, and inspect diagnostics.
fused_search— Parallel multi-engine web search (keyless free pool: Bing, DuckDuckGo, Yahoo, Exa-free, AnySearch; optional API engines: Tavily, Brave, Exa). Supports domain include/exclude, query variants, recency filters, engine/weight overrides, complexity and ranking presets, plus optional X community blending. Returns ranked, deduplicated, scored results with provenance.fetch_page— Read a known HTTP(S) URL without searching again; returns cleaned text or locally extracted PDF text, with optional keywordfocusand offset-based windowing for long pages (continuations served from cache).x_search— Find X/Twitter posts by keyword, semantic topic, user handle, or thread ID; supports author/date filters with verifiable-metadata enforcement; works credential-free with optional auth for better coverage.search_layer— View (default) or persist the compatibility search layer (freekeyless vsapi/hybrid).search_stats— Read-only diagnostics: cache hits/misses, engine configuration readiness, recent searches, and X source status.
All tools are read-only except search_layer when changing defaults; results include warnings and diagnostics, and scores do not verify claims.
Integrates Brave Search via API key, adding it to the parallel search engine pool for web searches.
Provides DuckDuckGo search support for general web searches and domain-restricted queries in the API layer.
Integrates Google News as a free-layer search engine, returning news-oriented results in multi-engine searches.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@search-boost-mcpsearch the web for MCP server security vulnerabilities"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Release & Branch Notice: The formerly standalone pi-search-boost and dsh-search-boost projects are merged into one codebase under lib/. Documented commands specifying @latest retrieve the official published npm package. To test code that is not in a published release, check out the branch or tag you need and follow Installation from Source & Development.
v0.2.4: single-snapshot Jev screening (schema V5), private research save/recovery, bounded PDF text extraction, Desktop integration, and separate package updates / integration management. See the release and migration notes: V3 adaptive inputs/outputs and the
upgradecommand have changed. This source version does not imply npm publication;@latestfollows the published registry.
Table of Contents
Related MCP server: gemini-search-mcp
Key Features
Multi-Engine Parallel Fusion (
fused_search)
Queries multiple search providers in parallel. Features an out-of-the-box keyless free pool (Bing, DuckDuckGo, Yahoo, Exa-free, AnySearch) and a keyed API pool (Tavily, Brave, Exa, AnySearch). Automatically performs cross-engine URL deduplication, domain routing, and relevance re-ranking.Clean Webpage Content Extractor (
fetch_page)
Fetches the origin first for low latency, with optional same-route curl compatibility fallback and Jina Reader backup. Strips CSS, JS, and ad clutter. Supports focused contextual paragraph extraction viafocus, backed by in-memory caching and size limits.X / Twitter Community Intelligence (
x_search)
Retrieves public posts, user timelines, and discussion threads via official xAI API or an anonymous fallback channel. Derives UTC timestamps from verifiable Snowflake post IDs and applies author/date filters only when metadata can be verified. Coverage may be incomplete, stale or empty; a retrieved sample does not establish platform-wide sentiment.Jev Intent-Guided Search (
adaptive_search· Experimental) Supply one full question and a required research intent. One pre-search Jev strategy request selects the fixed ranking preset and (when community is omitted) whether to add the already-wired community branch; one bounded fused snapshot (32 candidates for targets up to 10; larger targets keep the same headroom ratio, at most 160) is then screened with fixed safety, prototype value 3/4/5 and source-discount options. No keyword planning, no constraints gate, no language check, no automatic page read, and no self-set cumulative budget stop; cursor and saved-result pagination only replay stored results. No claim of verified or complete answers.Native Multi-Agent Parallel Research
Bundlessearch-boostandsearch-boost-parallel-researchskills. In hosts supporting subagents (Cursor, Claude Code, Pi, DSH), tasks can be dispatched to parallel Searchers (gathering evidence) and Summarizers (pure synthesis without tools), supporting both Fast and Complex waves.Unified Core Across All Host Ecosystems
A single, host-neutral core runtime powering standard Model Context Protocol (MCP) servers, alongside native extensions for Pi and Cordis plugin bundles for DeepSeek Harness (DSH).Zero-Config Onboarding & Strict Security
Requires zero API keys to start using the free engine pool. Sensitive credentials are stored as plaintext in local private configs with restricted file permissions (POSIX0600); this is not encryption at rest. Uses local networking and proxy DNS, with bounded requests and explicit fallback. Configured credentials are kept out of model prompts and diagnostic output.
System Architecture
SearchBoost follows a "One Core, Three Adapters" architecture. All search logic, content parsing, deduplication algorithms, and network safety mechanisms reside in the shared core:
SearchBoost TUI / CLI
installation · configuration · refresh
│
Shared SearchBoost Core
lib/runtime.mjs facade
search · fetch · X · adaptive evidence
│
┌───────────────┼───────────────┐
│ │ │
MCP Adapter Pi Adapter DSH Adapter
stdio server extension Cordis bundle
│ │ │
┌────────┴────────┐ ▼ ▼
│ Cursor / Claude │ Pi DeepSeek Harness
│ Codex / Grok │
│ Antigravity │
└─────────────────┘Core (
lib/): Host-neutral algorithms, engine orchestration, Jev client protocol, and network safety policies.Adapters (
adapters/): Maps core operations into host-specific protocols (MCP JSON-RPC, Pi Extension API, DSH Cordis lifecycle).Agents (
agents/): Host prompt contracts, workflow templates, and native skill definitions. See the prompt responsibility contract and beta.8 release notes for the Agent-facing routing update.
Supported Hosts Matrix
Host | Integration Type | Files / Mechanism | Capabilities & Notes |
Cursor / Cursor CLI | MCP + Skills |
| Supports CLI auto-approval ( |
Claude Code | MCP + Prompts | Official | Full multi-engine search and page extraction tools with prompt boundaries |
Codex | MCP + Prompts | Host MCP configuration | Seamless access to fused search, X retrieval, and reader tools |
Grok Build | MCP + Plugin | MCP config + bundled plugin | Automatically syncs and installs companion plugin when |
Google Antigravity | MCP + Workspace | Workspace MCP configuration | Per-project workspace guidance and full search tool suite |
Pi | Native Extension |
| Registers native extension, |
DeepSeek Harness | Native Bundle |
| Integrated with Cordis runtime; provides native |
Quick Start (30 Seconds)
Prerequisites
Node.js:
>= 22.13.0Package Manager:
npm(orpnpm)
1. Install & Launch the Dashboard
# Install globally
npm install -g search-boost
# Launch the interactive terminal UI (TUI)
search-boostZero API Keys Required to Start: SearchBoost includes a keyless free pool (Bing, DuckDuckGo, Yahoo, Exa-free, AnySearch). No paid-provider signup is required; availability and result coverage depend on the providers and your network.
2. 3-Step Setup Wizard
Select Setup wizard on the default flat TUI home (folder layout: Installation & integrations → Setup). Configure engine keys (or skip to use free tier) and optional X credentials.
Check the agents you want to integrate (Cursor, Claude Code, Pi, etc.), confirming auto-approval and native search replacement.
Restart or reload your chosen agents, then ask them to research anything in conversation!
Upgrade & Migration Guide
1. Routine Updates: npm First, Then Refresh Integrations
The commands below describe v0.2.4. Before it is published, @latest may still install an older release without refresh or research; use a v0.2.4 source checkout as described below. Use npm to update the package; the TUI no longer updates SearchBoost itself. Installation, refresh and removal live under Manage agent integrations (folder layout: Installation & integrations → Manage agent integrations).
npm install -g search-boost@latest --prefer-online
search-boost
# → Manage agent integrations → Refresh existing integrations → select scopes
# Or refresh all existing integrations:
search-boost refresh -y
# Preview only:
search-boost refresh --dry-runRefresh uses the current package and preserves credentials, permissions, disabled states and unrelated configuration. It does not install unconfigured hosts. Unchecking a target means no operation, not removal. The old upgrade command and --sync-only option are removed.
If a Grok local cache remains stale after native update, fully quit Grok and separately approve data-retaining reconstruction and trust of the displayed source. -y alone is not approval; explicit CLI approval is search-boost refresh -y --repair-grok-cache. This requests native uninstall --keep-data, then install --trust; legacy-name data reuse is not guaranteed. Restart affected hosts afterward. See integration refresh.
2. Migrating from Legacy search-boost-mcp
If you have the old global packagesearch-boost-mcp installed, npm cannot automatically replace the global binary across package renames. Use the one-line npx migration command. The refresh step below requires v0.2.4 or later:
# Execute safe migration via npx
npx --yes --package=search-boost@latest -- search-boost migrate -y
# For v0.2.4 and later, update the package before refreshing integrations:
npm install -g search-boost@latest --prefer-online
search-boost
# -> Manage agent integrations → Refresh existing integrations (or search-boost refresh -y)Interactive Console (TUI)
Launch search-boost without arguments to access the interactive dashboard built with Clack. Manage host integrations, search configuration and credentials here; package updates are handled by npm:
The default flat home lists these actions in order:
Home entries | Behavior |
Setup wizard; Manage agent integrations; Status | Guided setup; install / scoped refresh / confirmed uninstall; read-only status |
Search engine configuration; Default search layer; Tool switches | Choose individual engines; |
X credentials; Jev configuration (experimental) | Masked credential management |
Native web search; Print MCP snippet | Explicit permission choices; read-only snippets |
TUI settings; Exit | Menu layout before display language; close the console |
TUI settings → Menu layout offers flat / folder. Folder mode retains Installation & integrations, Search & tools, Services & credentials and Status. Completed actions return to the same flat home entry or their folder submenu. Escape cancels/navigates back; Ctrl+C exits. A layout switch immediately returns to the new home. Management returns to its own submenu; interactive uninstall and Grok cache reconstruction default to cancel. Partial failures are reported, not styled as success.
Layout and language changes apply immediately and are saved in ~/.search-boost/config/tui.json (or $SEARCH_BOOST_HOME/config/tui.json). Missing layout (including legacy language-only settings) defaults to flat. Without a saved language preference, Chinese system locales select Simplified Chinese; other locales select English. The preference also applies to standalone interactive setup/config commands, not non-interactive CLI output, search results or agent replies. Tool names, commands, paths, MCP snippets and raw upstream errors remain unchanged. Dry-run previews layout/language without saving; malformed settings are warned about, not overwritten. See TUI navigation and language settings.
Tool switches
Open Tool switches (folder layout: Search & tools → Tool switches), toggle with Space, press Enter to review, then confirm. Esc or declining confirmation writes nothing; an empty selection disables all tools. Locked adaptive_search appears struck through in the status panel and is excluded from selectable choices until Jev is configured. Configuring Jev makes it available by default; an explicit OFF preference is preserved.
Preferences are shared through ~/.search-boost/config/tools.json (or $SEARCH_BOOST_HOME/config/tools.json), using atomic, locked writes. No host restart or reinstall is needed once the updated adapters are loaded:
MCP: tool-list updates within approximately 300ms, with
tools/list_changednotification; clients ignoring notifications may need reconnecting.Pi: active tools refresh within approximately 300ms; unrelated and initially excluded tools are preserved. Watchers stop on session shutdown.
DSH: registrations remain present but disabled calls fail immediately; the native search/fetch provider paths obey the same switches.
Every new invocation checks the current preference, including stale tool handles. Existing requests finish normally. Removing Jev credentials locks adaptive calls (including pagination and saved-result recovery); restoring credentials does not override explicit OFF. These are tool-entry switches, not engine permissions: enabled adaptive research screens one internal fused snapshot and does not read pages automatically, and fused community search may still use internal X retrieval. Searcher waves in Pi/DSH also require the shared fused_search and fetch_page entries and DSH scoped tools: disabled dependencies prevent initial dispatch, and are checked again before each child starts. Started children finish normally; tool-free summarizers do not require these entries. Checks never enable tools or expand permissions. Slash commands remain available for recovery. Existing processes running older adapter code require one reload/update first. Hosts sharing these settings must use the same SearchBoost home.
Tool Suite & Usage Guide
When integrated, agents automatically receive standard tool definitions and autonomously determine when to call them.
Tool Responsibilities & Boundaries
Tool | Best Used For | Boundary / Non-Goals |
| Parallel multi-engine querying, deduplication, and diversity re-ranking | A single search step; follow-up decisions remain with the parent agent |
| Reading clean content from public URLs with optional keyword focus | Not an authenticated browser; local network and proxy policy still apply |
| Retrieving public X posts, author timelines, or discussion threads | Does not guarantee exhaustive comment threads or total sentiment sampling |
| Experimental: one bounded fused snapshot + fixed-option Jev screening for one question and a required intent | Selected URLs with reviewed extracts and value labels; targetMet is quantity only, not verified answers |
| Reading engine status, memory cache hits, and recent diagnostic stats | Read-only; configuration readiness does not guarantee active external network reachability |
| Viewing or switching compatibility search layer in MCP |
|
1. fused_search Multi-Engine Search
Dispatches queries across engines concurrently, normalizes URLs, strips redirects, and applies diversity filters.
Tool Arguments Example (JSON):
{
"query": "Node.js 22 built-in WebSocket API guide",
"include_domains": ["nodejs.org", "developer.mozilla.org"],
"engine_pool": "free",
"ranking": "balanced",
"complexity": "simple",
"max_results": 5
}engine_pool:free(keyless Bing, DuckDuckGo, Yahoo, Exa-free, AnySearch),api(configured API engines), orhybrid(both pools). Unavailable or disabled engines are skipped. When omitted, the compatibility layer mapsfreeto the free pool andapito hybrid.ranking: Final engine-weight presets:balanced(default),research, orfresh. They do not change query variants, search depth or recency filters, and do not establish source authority or freshness.complexity:simple(1 query variant),medium(up to 2 variants),complex(up to 3 deep variants).community: Boolean (falseby default). Set totrueto blend real-time X developer discussions into the final result quota.
2. fetch_page Smart Content Reader
Reads webpage content from search URLs. Reads and cleans the origin first; PDFs are extracted to text locally and only fall back to Jina Reader when that fails; curl handles transport compatibility when installed.
Tool Arguments Example:
{
"url": "https://nodejs.org/api/globals.html",
"focus": "AbortSignal.any"
}focus(Optional): Filters and retains paragraphs matching the target keywords.TIPA
focusmiss does not prove the information is absent from the page. If in doubt, re-fetch withoutfocusto inspect the full context.offset(Optional): Long bodies are returned in bounded windows (60,000 characters by default). The result reportstotalCharsand, while more content follows,nextOffset; pass that back asoffsetto continue reading. Continuations are served from the 24h cache without another request.TIPBinary responses (images, archives, PDFs with no extractable text) raise a clear error instead of being returned as page text.
3. x_search X (Twitter) Intelligence
Designed for real-time technical tracking and first-party developer updates. Supports keyword search, author timelines, and thread conversations.
Tool Arguments Example:
{
"query": "Claude 3.7 Sonnet hybrid reasoning from:AnthropicAI",
"type": "keyword",
"max_results": 5
}Timestamp derivation: When a valid Snowflake post ID is available, it can supply a UTC creation timestamp if platform metadata is missing or inconsistent; this does not verify the post text.
Filters: Keyword mode accepts X operators such as
from:username,since:YYYY-MM-DD, anduntil:YYYY-MM-DD. Usefrom_date/to_datefor explicit date bounds; candidates without verifiable author/date metadata are omitted when those filters apply.
4. adaptive_search Jev Intent-Guided Search (Experimental)
Vercel support: in TUI → Jev configuration (folder layout: Services & credentials → Jev configuration), enter https://ai-gateway.vercel.sh/v1 and a Vercel AI Gateway key. SearchBoost selects the official SDK evaluation model typesafe-ai/jev, not chat completions. The default TypeSafe /systemone path remains supported. Both paths use only the canonical user Jev credential, not environment keys, and respect server rate-limit delays.
Supply one question (questions has exactly one item) plus a required research intent and optional soft preferences. Write them in English as a caller instruction: the server never language-checks, rejects or translates them, and any language is searched exactly as written. The original question is the only query — there is no keyword planning and no query expansion. One pre-search Jev strategy request selects the fixed balanced/research/fresh ranking and, when community is omitted, enable/disable/unknown for the already-wired community (X) branch; an explicit community true/false overrides that choice and is never asked back. That single fused call collects a bounded snapshot: 32 candidates for targets up to 10, ceil(max_results×32/10) for larger targets (at most 160) (web and community rows share it), and every declared candidate is screened with fixed options: safety clear/violation/unavailable, prototype value levels 0-5, source discounts from real positive-contribution engines, and one match per preference. Only safe material with an established value 3/4/5 is delivered, ranked by the versioned screening formula; confidence is audit-only. There is no early stop at the first K acceptable links, no automatic page read, and no self-imposed cumulative cost, token, request-count or whole-run time budget — real single-request timeouts, limited retries, authentication/rate-limit failures, safety refusals and explicit cancellation still apply.
{
"questions": ["What are the migration risks from ExampleDB 4.1 to 4.2?"],
"intent": "Find migration steps and concrete incompatibilities, including counterexamples.",
"preferences": ["Official migration guides"],
"max_results": 8,
"page_size": 3
}intentis required (it is no longer filled in from the question) andpreferencesare independent soft ranking bonuses, deduplicated exactly.constraintsis retired as a per-material hard gate: omit it or pass[](adeprecated_constraints_emptywarning); a non-empty array is refused withadaptive_constraints_removedbefore any network call. Keep every direction and condition in the question/intent; for hard domain limits usesite:/-site:or fused_searchinclude_domains/exclude_domains, and verify required document properties by reading.Multi-question lists,
tasks/targets/facts/time_range,keywordsand nested keyword arrays are refused as legacy inputs; independent questions require separate calls.max_resultscaps the selected and saved set (default 10, max 50);page_sizeonly changes the page (default 20, max 50) and never re-orders or re-filters.Results contain selected URLs, titles, reviewed extracts,
valueLevel/valueLabel, rank, real provenance and score components — never generated answers.selection.targetMetmeans quantity only, never research completion or verification;selection.incomplete,diagnostics,stopReason,outsideReviewandunrevieweddisclose what was not finished rather than treating it as low value.run.communityreports the finite community decision and the actual execution status (not_requested/domain_excluded/unavailable/blocked/succeeded/empty/failed/partial/not_run), never model reasoning. A failed or partial community branch keeps valid web results and marks the run incomplete.Read saved pages with
{"cursor":"<s5:…>"}(optionalpage_size) only: no new search, strategy, Jev, community or value call. Default 20/max 50 per page with a byte budget. Cursors last up to 30 minutes/32 recent sets in the current process and are not exhaustive search.With explicit
save_results:true, the complete final selected set plus typed metadata is stored privately under the SearchBoost home (search-boost-research-v2, schema version 5) and you receive asavedResultId. After a restart or cache clear, read{"saved_result_id":"<savedResultId>"}(optionalpage_size) without another search or Jev call. Oldersearch-boost-research-v1files stay readable in a marked read-onlyh1:historical branch (restoration.historical: true, original schema version preserved, no invented v5 fields). Public tool switches and the Jev configuration lock still apply to reads;search-boost research list/research export <id> --output <new-file.json>work offline without Jev. See integration and acceptance boundaries.Thresholds remain uncalibrated engineering starting points. See the contract, budgets and migration notes.
Engine Pools & Scoring Presets
engine_pool selects engines, ranking selects shared cross-pool weights, and complexity controls query breadth and depth, not scoring weights. AnySearch is one logical engine: anonymous in free, key-required in api, and key-preferred in hybrid. Configure ANYSEARCH_API_KEY or config keys --set anysearch=KEY.
Engine | balanced | research | fresh |
bing | 0.957 | 0.927 | 1.020 |
ddg | 0.981 | 0.903 | 0.927 |
yahoo | 0.957 | 0.877 | 0.902 |
exa-free | 1.004 | 1.085 | 0.951 |
tavily | 1.049 | 1.105 | 1.084 |
brave | 1.004 | 0.951 | 1.125 |
exa | 1.049 | 1.146 | 1.063 |
anysearch | 1.004 | 1.042 | 0.951 |
These are uncalibrated cold-start priors, not measured quality rankings. consensus-v2.1 combines original ranks, related-provider discounts and max+log consensus, with metadata adjustments capped at 20%. Quality and list-selection scores stay separate; zero-weight sources cannot vote. Recalibrate old min_score thresholds. See scoring and migration and pool routing.
Parallel Multi-Agent Research Workflows
One shared workflow with three host bindings. The parent agent splits a question into independent tracks; each searcher gathers evidence with fused_search and fetch_page; a tool-less summarizer (or the parent itself) then turns the reports into one answer.
[ Parent Agent ]
splits tracks · owns the answer
│
┌───────────────┴───────────────┐
▼ ▼
[ Searcher A ] [ Searcher B ]
fused_search · fetch_page fused_search · fetch_page
│ │
└───────────────┬───────────────┘
▼
[ Summarizer ]
no tools · synthesis only
▼
[ Parent Report ]Host | Entry point | How children run |
Pi |
| Each searcher is a child process that explicitly loads the SearchBoost Pi extension ( |
DeepSeek Harness | Native | Children spawn on the same Cordis context through the host's subagent service. Searchers receive |
MCP hosts (Cursor, Claude Code, Codex, Grok, Antigravity) | Bundled | The skill embeds the same roles and workflow and runs them through whatever subagent mechanism the host provides. A host without usable delegation falls back to serial research by the parent. |
Installing into an MCP host also installs the companion search-boost router skill for optional workflows. Ordinary tool selection uses the registered descriptions and schemas directly; no skill load is required.
Fast mode: one searcher wave, then parent synthesis — no summarizer and no second wave.
Complex mode: one to three waves with a gap review in between; another wave starts only when a material gap remains, and the run stops early when the evidence is sufficient. These wave limits are workflow instructions, not global quotas enforced across independent tool calls.
Unavailable delegation: the parent may research serially when browsing is allowed and parallelism is not a strict requirement, and discloses that choice. A denied or failed runtime is a blocker, not permission for a silent fallback.
A child returningok means it finished with non-empty text, not that its claims are verified. Failed or partial reports stay visible, but their URLs are excluded from the successful aggregate, and final judgment always belongs to the parent.
For Pi/DSH child-tool loading, stale pi-search-boost references, and the retired deep_research tool, see Subagent tool setup and diagnosis.
Security
Custom search API bases
Open Search engine configuration on the flat TUI home (folder layout: Services & credentials). Each engine shows its masked key and default/custom Base URL. Choose Set / replace Base URL, then keep or edit the key; Restore default Base URL resets only the address. Choose any individual engine without stepping through all credential slots; unrelated keys and routing selections are preserved. Status and config keys --show also show the effective bases. Standalone search-boost config keys and first setup retain the sequential guided wizard.
search-boost config keys --base-url exa=https://gateway.example/exa
search-boost config keys --reset-base-url exaEngine | Default Base URL | Appended path |
Tavily |
|
|
Exa |
|
|
Brave |
|
|
AnySearch |
|
|
Supply an API base, not a full search endpoint; gateway prefixes are preserved. Overrides live in engines.<name>.baseUrl in the keys file; existing key strings and routing flags are unchanged. Use only trusted API-compatible gateways: queries and configured keys are sent there (AnySearch remains anonymous in the free pool). Prefer HTTPS; HTTP is supported for local gateways. Credentials, query strings and fragments in URLs are rejected. Exa-free is unaffected. Changing a base invalidates the search cache partition.
API keys use a credential store this tool owns. They are not written into prompts, tool results or shell profiles:
Private file permissions: keys live in
~/.search-boost/config/keys.json(redirect the root withSEARCH_BOOST_HOME). On POSIX the store directory is0700and the file is0600; a rewrite is built from a fresh0600temporary file rather than written in place, so an existing file is never widened. Backups and upgrade receipts under the same root are0600as well. An env-overridden directory keeps its own mode, while the credential file is still created0600. Windows has no POSIX mode bits — ACL inheritance applies there.Atomic, locked writes: replacement uses an
O_EXCLtemporary file plus rename, so a reader sees either the old or the new file and never a partial one; a failed write cleans up after itself and leaves the previous file untouched. Read-modify-write cycles take an exclusive lock, so two writers cannot silently lose each other's update, and a rejected change does not touch the file at all.Never echoed back: a key is only sent to the engine it belongs to (Tavily, Brave, Exa and AnySearch request parameters/headers). Status output,
search-boost config keys --showand the doctor report print masked values (abcd****wxyz); error messages are tested not to contain credential material, and Jev evaluation payloads deliberately carry no key, masked key or fingerprint. AnySearch uses anonymous quota in free, requires a key in api, and prefers a configured key in hybrid. Its potentially credential-bearing error envelopes are never echoed or persisted.
CLI Command Reference (Headless & CI)
The following CLI reference describes v0.2.4. refresh and research require that version or later; merging source does not publish it to npm. Use a source checkout until the required version is published.
DeepSeek Harness Desktop: interactive installation offers Desktop / CLI / All, then Automatic (default) or Local directory for Desktop. Automatic setup retains bundled-command discovery through Windows installer registry metadata (including custom destinations), default directories and PATH; launch Desktop once, then fully quit it including its tray. Local setup runs last, after all other integrations including Grok, and displays the current durable package directory to paste into the running app's Plugins → Add plugin dialog. The TUI observes saved installation read-only and finishes after stable verification; Escape / Ctrl+C or timeout marks Desktop unfinished while retaining earlier results. Saved installation is not proof of live activation; missing bundled launchers explicitly leave runtime verification unknown. Temporary _npx paths are refused as persistent local links. The app also accepts search-boost for a registry install. Automatic install/update still verifies the owning resolver and rejects shadow copies. Disabled bundles stay disabled unless explicitly requested; local setup with --enable-dsh-bundle waits for the user to enable it in Desktop. See Desktop integration for ownership and validation limits.
# ----------------- Core & Interactive -----------------
search-boost # Launch interactive dashboard (TUI)
search-boost status # Disk/configuration evidence; running host version remains unknown
search-boost status --json # Structured read-only installation evidence
search-boost research list # List opt-in private result snapshots
search-boost research export <id> --output <new-file.json> # Explicit export; never overwrite
search-boost --help # Display full CLI documentation
search-boost refresh --dry-run # Preview refreshing existing integrations
search-boost refresh -y # Refresh all existing integrations from this package
search-boost migrate --dry-run # Preview the legacy global package rename
# ----------------- Headless Installation -----------------
search-boost install -t cursor -y # Install for Cursor with auto-approval
search-boost install -t claude,codex --keep-native # Install while preserving host native search
search-boost install -t antigravity --workspace /path/to/project # Target a specific workspace
search-boost install -t antigravity -y --antigravity-config legacy # Explicit old-client compatibility; modern switches back
search-boost install -t pi -y # Mount Pi extension and prompt templates
search-boost install -t dsh --profile web # Connect to DeepSeek Harness CLI web profile
search-boost install -t dsh --dsh-surface desktop -y # Desktop bundled command + local package
search-boost install -t dsh --dsh-surface all -y # Manage Desktop and CLI independently
# No global search-boost / dsh / pnpm required (Windows, Linux, macOS):
npx --yes search-boost@latest install -t dsh --profile web -y
search-boost install -t cursor --dry-run # Preview installation without writing files
# ----------------- Configuration Management -----------------
search-boost config keys # Manage API keys from CLI
search-boost config keys --set anysearch=KEY # Configure the AnySearch key (ANYSEARCH_API_KEY)
search-boost config layer # Switch default layer (free / api)
search-boost config x --import-grok # Import X credentials from local Grok login
search-boost config jev # Configure Jev endpoint and token
# ----------------- Diagnostics & Health -----------------
search-boost doctor # Run offline diagnostic checks
search-boost doctor --strict # Strict mode (exits non-zero on warnings)
search-boost doctor --json # Output machine-readable JSON report
# ----------------- Uninstall -----------------
search-boost uninstall -t cursor,claude -y # Remove integrations from selected hostsInstallation from Source & Development
Use this path to contribute to SearchBoost, or to test code that is not in a published release yet. Everywhere else, @latest refers to the published package.
Prerequisites
Node.js
>= 22.13.0(matchingpackage.json)git and npm
Optional:
curl, for the same-route transport-compatibility fallback infetch_pageOptional:
pdfjs-dist(optionalDependency) to extract PDF text locally; without it, PDF reads fall back to Jina Reader
Set up a checkout
# 1. Clone the repository
git clone https://github.com/Mr-remon219/search-boost.git
cd search-boost
# 2. Install dependencies exactly as CI does
npm ci
# 3. Regenerate the bundled Grok plugin assets
npm run plugin:sync-grokThe clone lands on the repository's default branch. To test a different branch or tag, check it out before installing dependencies (git checkout BRANCH_OR_TAG).
Run it without a global install
node cli.mjs # interactive TUI straight from the checkout
node cli.mjs status # one-shot status summary
node cli.mjs install -t pi -y # mount the Pi extension from this checkout
node cli.mjs install -t dsh --profile webnode cli.mjs accepts the same commands as the installed search-boost binary. If you want the bare command in your terminal, link the checkout instead of installing from npm:
npm link # or: npm install -g .
search-boostAfter changing adapter or agent assets, re-run the same install command for that host (node cli.mjs install -t HOST) so the host picks up the new files, then restart or reload that host.
Test gates before a PR
Command | What it covers |
| Syntax check across the CLI, core, adapters and scripts |
| Syntax and CI policy checks, exact-lock dependency audit (registry access required), then every isolated regression entrypoint, including generated assets, install / refresh / migration, search, adapters and MCP |
| Proxy retries, curl fallback, request bounds and compatibility regressions |
| MCP, Pi and DSH adapter protocol suites plus Pi subagent settings migration/diagnosis |
| Searcher/summarizer contracts, DSH dispatch preflight, cancellation and tool isolation |
| Single-snapshot V5 screening, capacity boundaries and MCP/Pi/DSH adapter fixtures (not live host sessions) |
| MCP JSON-RPC protocol smoke test |
Regression suites use isolated state, loopback fixtures and process doubles; no engine keys are needed. The dependency audit requires registry access. A green npm run prepublishOnly is the local PR gate, not proof of live host loading, paid-service behaviour or evidence quality.
Friendly Links
License
This project is licensed under the MIT License.
Available Tools
5 toolsfetch_pageFetch PageARead-only
Read a known HTTP(S) URL without searching again. Returns readable HTML or locally extracted PDF text, with retrieval route and any extraction limitations. Long bodies use bounded windows; continue from nextOffset using the cached read, not a new request. A focus miss is not evidence of absence: retry without focus. Binary bodies and PDFs with no extractable text return errors, not page text. Network safety, proxy policy, cancellation and size limits remain enforced through all supported fallbacks. This is not an authenticated browser.
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | http(s) URL to fetch | |
| focus | No | Keep matching paragraphs; omit for the readable body. Output may still be windowed; inspect nextOffset and limitations | |
| offset | No | Character offset into the page body (default 0); pass nextOffset from a previous call to continue a long page from cache |
Output Schema
| Name | Required | Description |
|---|---|---|
| url | Yes | |
| via | Yes | |
| offset | No | |
| tookMs | Yes | |
| content | Yes | |
| focusMiss | No | |
| truncated | No | |
| limitation | No | |
| nextOffset | No | |
| totalChars | No | |
| windowNote | No | |
| word_count | Yes | |
| requestedUrl | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover the safety profile (readOnly, openWorld, non-destructive); the description adds substantial behavior beyond them: binary bodies and text-less PDFs return errors, long bodies are windowed and continued from cache, network safety/proxy/cancellation/size limits persist through fallbacks, and it is explicitly not an authenticated browser. These are exactly the operational caveats an agent needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core action, then dense but purposeful sentences covering return format, pagination, focus retry, error cases, and the auth boundary. No filler and no repetition of the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value documentation is not required, and the description still covers error outcomes, extraction limitations, pagination continuation, and the unauthenticated boundary. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3, but the description adds real semantics: offset continuation should use the cached read rather than a new request, and focus should be dropped on a miss because a miss is not evidence of absence. That goes beyond the schema's parameter descriptions without restating them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The first sentence gives a specific verb (read/fetch) and resource (a known HTTP(S) URL) plus a distinguishing constraint ('without searching again') that separates it from the search siblings. It also states the return shape (readable HTML or locally extracted PDF text with retrieval route). An agent can select this over fused_search or x_search without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly sets the context of use (a URL you already know, avoiding a re-search) and gives concrete recovery guidance: 'A focus miss is not evidence of absence: retry without focus.' It stops short of explicitly naming the search siblings as the alternative when the URL is unknown, so routing is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
fused_searchFused Web SearchARead-only
Use for the vast majority of public-web research tasks, from precise lookups to difficult investigations. This general-purpose multi-engine search does not require Jev. If adaptive_search is unavailable, disabled or Jev is not configured, use enabled fused_search normally; do not delay research or require Jev setup. When both tools are available, choose fused_search for direct retrieval, varied query angles or explicit source control. Prefer adaptive_search for higher-quality intent-guided evidence selection when a medium-to-high difficulty or uncertain question benefits from screening noisy or mixed-relevance results. Choose by the evidence need, not merely by which tools are configured. Returns ranked extracts, source attribution and execution diagnostics, including failures and warnings. Normally omit engines; request-local choices do not change persistent defaults. Add X community voices when relevant; use x_search for X-only tasks. Scores do not verify claims, and multiple engines finding the same page do not independently corroborate it. Use fetch_page to read decisive sources when extracts are insufficient. Optional live status: search-boost://capabilities Resource.
| Name | Required | Description | Default |
|---|---|---|---|
| layer | No | Deprecated compatibility alias: free→free pool, api→hybrid pool; engine_pool takes precedence; not persisted | |
| query | Yes | Search query (site:, -site:, "phrase", A OR B) | |
| engines | No | Optional exact engine selection overriding engine_pool; unavailable or disabled engines are skipped with warnings | |
| queries | No | Distinct query angles, not paraphrases; complexity caps total variants at 1/2/3, including query and OR alternatives | |
| ranking | No | Final engine-weight preset only; default balanced | |
| recency | No | Favor recent dated results; omit for historical or version-pinned documentation | |
| community | No | Add X developer/community voices when relevant; default false; shares final max_results | |
| min_score | No | Minimum consensus-v2 quality score; old thresholds need recalibration, default 0 | |
| complexity | No | Budget, query variants and depth only; default medium | |
| engine_pool | No | Which engines to search. Omitted: compatibility layer free→free, api→hybrid | |
| max_results | No | Max results (default 6) | |
| engine_weights | No | Override preset engine weights; zero still calls the engine. Never enables or selects engines | |
| exclude_domains | No | Exclude these hostnames from results | |
| include_domains | No | Restrict results to these hostnames, e.g. nodejs.org; useful for official sources |
Output Schema
| Name | Required | Description |
|---|---|---|
| tier | Yes | |
| layer | Yes | |
| query | Yes | |
| tookMs | Yes | |
| ranking | Yes | |
| results | Yes | |
| cacheHit | Yes | |
| warnings | No | |
| enginePool | Yes | |
| engineStats | No | |
| enginesUsed | No | |
| resultCount | Yes | |
| scoreVersion | Yes | |
| communityUsed | Yes | |
| effectiveWeights | Yes | |
| enginesRequested | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint, openWorldHint, non-destructive), and the description adds substantial behavior beyond them: returns ranked extracts plus source attribution and execution diagnostics including failures/warnings, scores do not verify claims, agreement across engines is not independent corroboration, request-local choices do not alter persistent defaults, and disabled engines are skipped with warnings.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the primary use case and the routing decision, and most sentences carry distinct information. However, it runs long and contains mild redundancy, e.g. 'do not delay research or require Jev setup' restates the preceding clause and 'choose by the evidence need' restates the routing rule already given.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 14-parameter tool with nested objects, enums, and an output schema, the description covers routing, fallbacks, parameter defaults, return contents, and caveats about interpreting results. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description still adds non-obvious meaning: engines should normally be omitted, request-local selections are not persisted, community adds X voices and shares the final max_results budget, and engine_pool takes precedence over the deprecated layer alias.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('general-purpose multi-engine search') and explicitly distinguishes itself from siblings: x_search for X-only tasks, fetch_page for reading decisive sources, and adaptive_search for intent-guided evidence selection. An agent can route between these without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use ('vast majority of public-web research tasks', 'direct retrieval, varied query angles or explicit source control'), explicit when-to-prefer-the-alternative (adaptive_search for medium-to-high difficulty or noisy results), and explicit fallback behavior if Jev is unavailable. The selection criterion is stated as a principle ('choose by the evidence need') rather than left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_layerSearch LayerA
Inspect the current search layer with layer=show (default, no change). layer=free or api persists a new default: only change it when authorized. free = free — compatibility default engine_pool=free (keyless). api = api — compatibility default engine_pool=hybrid (keyless plus configured APIs). For a single search, use fused_search.engine_pool instead; legacy api maps to hybrid, not the strict api pool.
| Name | Required | Description | Default |
|---|---|---|---|
| layer | No | show (default) reads current state; free/api persist a new default and require authorization |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=false and destructiveHint=false, but the description adds critical behavioral context: layer=show causes no change, while free/api persist a new default and require authorization. It also discloses the compatibility mapping (legacy api maps to hybrid, not strict api pool), which goes beyond the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is dense but mostly earns its length, with the default behavior and key warning front-loaded. The 'free = free' and 'api = api' phrasing is slightly redundant and could be tightened, but it remains efficient and readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter, full schema coverage, and no output schema, the description covers all essential context: default behavior, persistence side effects, authorization requirement, engine_pool mapping, and the alternative tool for single searches. Nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds meaning beyond the enum descriptions by explaining the engine_pool implications of each value: free maps to engine_pool=free (keyless), api maps to engine_pool=hybrid, and legacy api does not map to the strict api pool. This is valuable semantic nuance that the schema alone does not convey.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific resource (the search layer) and a clear action set: inspect with layer=show or persist a new default with free/api. It also explicitly differentiates this tool from fused_search, making its purpose and scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: use layer=show to inspect, only change the default when authorized, and for a single search use fused_search.engine_pool instead. This routes the agent to the correct sibling in the exact condition that matters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_statsSearch StatsARead-only
Read-only search diagnostics: cache activity, engine configuration readiness and recent searches. Inspect result warnings as well; empty results do not prove absence or authorize changing credentials, permissions or defaults.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| layer | Yes | |
| recent | Yes | |
| engines | Yes | |
| xSource | Yes | |
| cacheHits | Yes | |
| startedAt | Yes | |
| xOfficial | Yes | |
| tierCounts | Yes | |
| cacheMisses | Yes | |
| keyedEngines | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false), so the bar is lower. The description adds genuine value beyond them: it discloses the diagnostic surfaces returned and warns that empty results do not authorize changing credentials, permissions, or defaults — a meaningful behavioral caveat for an agent acting on ambiguous results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two front-loaded sentences: the first defines scope, the second carries the caution. No filler, though the second sentence packs three distinct warnings and is slightly dense.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described. With zero parameters and annotations covering the safety profile, the description supplies everything an agent needs to call this correctly, including the caveat about interpreting empty results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate. Baseline of 4 applies; the description neither helps nor hurts parameter understanding.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete resource and enumerates what it exposes: cache activity, engine configuration readiness, and recent searches. It clearly reads as a diagnostics tool, distinct from the search/retrieval siblings (fused_search, fetch_page, search_layer), though it never names an alternative explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives interpretive guidance ('inspect result warnings', 'empty results do not prove absence') but never states when to call this tool versus the search siblings or when not to. Usage is implied by the diagnostics framing rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
x_searchX (Twitter) SearchARead-only
Find X/Twitter posts, account material or available thread content. Credential-free retrieval is supported; configured authentication can improve coverage. Results include source attribution and diagnostics. Author/date filters require verifiable metadata; unverified candidates are omitted. Coverage may be incomplete, stale or empty. A post sample does not establish platform-wide sentiment, and a thread result need not contain the full conversation.
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | Mode: keyword (default) or semantic uses query; user uses username; thread uses post_id | |
| query | No | Search terms and X filters (e.g. from:OpenAI), or a natural-language topic for semantic mode | |
| post_id | No | Real X post ID or status URL for type=thread | |
| to_date | No | Inclusive end date, YYYY-MM-DD (UTC) | |
| username | No | X account handle for type=user | |
| from_date | No | Inclusive start date, YYYY-MM-DD (UTC) | |
| max_results | No | Requested result limit, 1–10 | |
| allowed_x_handles | No | Only these authors; mutually exclusive with excluded_x_handles | |
| excluded_x_handles | No | Exclude these authors; mutually exclusive with allowed_x_handles |
Output Schema
| Name | Required | Description |
|---|---|---|
| via | Yes | |
| note | No | |
| items | Yes | |
| tookMs | Yes | |
| results | Yes | |
| cacheHit | No | |
| inFlight | No | |
| warnings | No | |
| engineStats | No | |
| enginesUsed | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only cover readOnly/openWorld/no-destructive, and the description adds substantial context: credential-free vs authenticated coverage, that results include source attribution and diagnostics, that author/date filters require verifiable metadata and unverified candidates are dropped, and that coverage may be incomplete, stale or empty. It even warns that a sample does not establish platform-wide sentiment. This is exactly the kind of behavior disclosure annotations cannot supply.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Six compact sentences, each carrying distinct information (capability, auth, output, filter constraint, coverage limits, interpretation caveat). Front-loaded with the core capability and free of filler, though the telegraphic style gives it a slightly dense, checklist feel.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description needn't explain return values, and it correctly focuses on credentials, filter constraints and coverage limitations. For a 9-parameter, open-world search tool it covers what an agent needs to call it responsibly, though it never clarifies the division of labor with the sibling search tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter baseline is 3. The description earns above baseline by adding a behavioral constraint on the filter parameters: author/date filters require verifiable metadata and unverified candidates are omitted, which tells the agent those parameters may silently narrow results. It still doesn't add syntax or format detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('Find X/Twitter posts, account material or available thread content'), so an agent immediately knows the domain and operation. It does not, however, distinguish this tool from siblings like fused_search or search_layer, leaving the agent to infer the boundary. Clear but not differentiating.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage context is implied ('Credential-free retrieval is supported; configured authentication can improve coverage') and caveats are given for when filters work, but there is no explicit when-to-use guidance relative to the sibling search tools. The mode selection (keyword/semantic/user/thread) is left entirely to the schema. Adequate but with a clear gap in routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.2.4- Changed
fetch_page7 fields changed- changed
Input schema / properties / focus / descriptionPrevious value: -"Keep paragraphs matching these terms (optional; full page is returned when omitted)"New value: +"Keep matching paragraphs; omit for the readable body. Output may still be windowed; inspect nextOffset and limitations" - added
Input schema / properties / offsetAdded value: +{ + "description": "Character offset into the page body (default 0); pass nextOffset from a previous call to continue a long page from cache", + "minimum": 0, + "type": "integer" +} - added
Output schema / properties / nextOffsetAdded value: +{ + "type": "number" +} - added
Output schema / properties / offsetAdded value: +{ + "type": "number" +} - added
Output schema / properties / requestedUrlAdded value: +{ + "type": "string" +} - added
Output schema / properties / totalCharsAdded value: +{ + "type": "number" +} - added
Output schema / properties / windowNoteAdded value: +{ + "type": "string" +}
- Changed
fused_search2 fields changed- changed
Input schema / properties / engine_weights / descriptionPrevious value: -"Override preset engine weights; never enables or selects engines"New value: +"Override preset engine weights; zero still calls the engine. Never enables or selects engines" - changed
Input schema / properties / queries / descriptionPrevious value: -"Distinct query angles, not paraphrases; use up to 3 variants"New value: +"Distinct query angles, not paraphrases; complexity caps total variants at 1/2/3, including query and OR alternatives"
- Changed
x_search4 fields changed- added
Output schema / properties / engineStatsAdded value: +{ + "additionalProperties": { + "additionalProperties": false, + "properties": { + "attempts": { + "type": "number" + }, + "errors": { + "type": "number" + }, + "note": { + "type": "string" + }, + "successes": { + "type": "number" + }, + "used": { + "type": "boolean" + } + }, + "required": [ + "used", + "errors" + ], + "type": "object" + }, + "type": "object" +} - added
Output schema / properties / enginesUsedAdded value: +{ + "items": { + "type": "string" + }, + "type": "array" +} - added
Output schema / properties / inFlightAdded value: +{ + "type": "boolean" +} - added
Output schema / properties / warningsAdded value: +{ + "items": { + "type": "string" + }, + "type": "array" +}
1 tool update
v0.2.3- Removed
adaptive_search
7 tool updates
v0.2.2- Added
adaptive_search - Removed
deep_research - Changed
fetch_page3 fields changed- changed
Input schema / properties / focus / descriptionPrevious value: -"Keep paragraphs matching these terms (~90% token savings)"New value: +"Keep paragraphs matching these terms (optional; full page is returned when omitted)" - added
Output schema / properties / focusMissAdded value: +{ + "type": "boolean" +} - added
Output schema / properties / limitationAdded value: +{ + "additionalProperties": false, + "properties": { + "kind": { + "type": "string" + }, + "message": { + "type": "string" + } + }, + "required": [ + "kind", + "message" + ], + "type": "object" +}
- Changed
fused_search37 fields changed- added
Input schema / properties / communityAdded value: +{ + "description": "Add X developer/community voices when relevant; default false; shares final max_results", + "type": "boolean" +} - added
Input schema / properties / complexity / descriptionAdded value: +"Budget, query variants and depth only; default medium" - changed
Input schema / properties / complexity / enumPrevious value: -[ - "auto", - "simple", - "medium", - "complex" -]New value: +[ + "simple", + "medium", + "complex" +] - added
Input schema / properties / engine_poolAdded value: +{ + "description": "Which engines to search. Omitted: compatibility layer free→free, api→hybrid", + "enum": [ + "free", + "api", + "hybrid" + ], + "type": "string" +} - added
Input schema / properties / engine_weightsAdded value: +{ + "additionalProperties": false, + "description": "Override preset engine weights; never enables or selects engines", + "properties": { + "anysearch": { + "minimum": 0, + "type": "number" + }, + "bing": { + "minimum": 0, + "type": "number" + }, + "brave": { + "minimum": 0, + "type": "number" + }, + "ddg": { + "minimum": 0, + "type": "number" + }, + "exa": { + "minimum": 0, + "type": "number" + }, + "exa-free": { + "minimum": 0, + "type": "number" + }, + "tavily": { + "minimum": 0, + "type": "number" + }, + "yahoo": { + "minimum": 0, + "type": "number" + } + }, + "type": "object" +} - changed
Input schema / properties / engines / descriptionPrevious value: -"Engine subset override"New value: +"Optional exact engine selection overriding engine_pool; unavailable or disabled engines are skipped with warnings" - changed
Input schema / properties / engines / items / enumPrevious value: -[ - "bing", - "ddg", - "yahoo", - "exa-free", - "antigravity", - "tavily", - "brave", - "exa" -]New value: +[ + "bing", + "ddg", + "yahoo", + "exa-free", + "anysearch", + "tavily", + "brave", + "exa" +] - added
Input schema / properties / engines / minItemsAdded value: +1 - added
Input schema / properties / exclude_domains / descriptionAdded value: +"Exclude these hostnames from results" - added
Input schema / properties / include_domains / descriptionAdded value: +"Restrict results to these hostnames, e.g. nodejs.org; useful for official sources" - added
Input schema / properties / layer / descriptionAdded value: +"Deprecated compatibility alias: free→free pool, api→hybrid pool; engine_pool takes precedence; not persisted" - added
Input schema / properties / min_scoreAdded value: +{ + "description": "Minimum consensus-v2 quality score; old thresholds need recalibration, default 0", + "minimum": 0, + "type": "number" +} - changed
Input schema / properties / queries / descriptionPrevious value: -"Extra query variants (max 3)"New value: +"Distinct query angles, not paraphrases; use up to 3 variants" - added
Input schema / properties / rankingAdded value: +{ + "description": "Final engine-weight preset only; default balanced", + "enum": [ + "balanced", + "research", + "fresh" + ], + "type": "string" +} - added
Input schema / properties / recency / descriptionAdded value: +"Favor recent dated results; omit for historical or version-pinned documentation" - added
Output schema / properties / communityUsedAdded value: +{ + "type": "boolean" +} - added
Output schema / properties / effectiveWeightsAdded value: +{ + "additionalProperties": { + "type": "number" + }, + "type": "object" +} - added
Output schema / properties / enginePoolAdded value: +{ + "enum": [ + "free", + "api", + "hybrid" + ], + "type": "string" +} - added
Output schema / properties / engineStats / additionalProperties / properties / attemptsAdded value: +{ + "type": "number" +} - added
Output schema / properties / engineStats / additionalProperties / properties / successesAdded value: +{ + "type": "number" +} - added
Output schema / properties / rankingAdded value: +{ + "enum": [ + "balanced", + "research", + "fresh" + ], + "type": "string" +} - added
Output schema / properties / results / items / properties / consensusBoostAdded value: +{ + "type": "number" +} - added
Output schema / properties / results / items / properties / contributionsAdded value: +{ + "additionalProperties": { + "type": "number" + }, + "type": "object" +} - added
Output schema / properties / results / items / properties / dateStatusAdded value: +{ + "enum": [ + "known", + "unknown", + "conflicting" + ], + "type": "string" +} - added
Output schema / properties / results / items / properties / engineRanksAdded value: +{ + "additionalProperties": { + "type": "number" + }, + "type": "object" +} - added
Output schema / properties / results / items / properties / evidenceScoreAdded value: +{ + "type": "number" +} - added
Output schema / properties / results / items / properties / idAdded value: +{ + "type": "string" +} - added
Output schema / properties / results / items / properties / kindAdded value: +{ + "enum": [ + "web", + "x" + ], + "type": "string" +} - added
Output schema / properties / results / items / properties / metadataDeltaAdded value: +{ + "type": "number" +} - added
Output schema / properties / results / items / properties / provenanceAdded value: +{ + "items": { + "additionalProperties": false, + "properties": { + "engine": { + "type": "string" + }, + "published": { + "type": [ + "string", + "null" + ] + }, + "rank": { + "type": "number" + }, + "snippet": { + "type": "string" + }, + "title": { + "type": "string" + }, + "url": { + "type": "string" + }, + "variant": { + "type": "string" + } + }, + "required": [ + "engine", + "rank", + "url", + "title", + "snippet", + "published" + ], + "type": "object" + }, + "type": "array" +} - added
Output schema / properties / results / items / properties / rankScoreAdded value: +{ + "type": "number" +} - added
Output schema / properties / results / items / properties / scoreVersionAdded value: +{ + "type": "string" +} - added
Output schema / properties / results / items / properties / selectionScoreAdded value: +{ + "type": "number" +} - added
Output schema / properties / results / items / properties / usernameAdded value: +{ + "type": "string" +} - changed
Output schema / properties / results / items / requiredPrevious value: -[ - "title", - "url", - "domain", - "snippet", - "score", - "engines", - "published" -]New value: +[ + "title", + "url", + "domain", + "snippet", + "score", + "scoreVersion", + "rankScore", + "evidenceScore", + "consensusBoost", + "metadataDelta", + "engineRanks", + "contributions", + "provenance", + "dateStatus", + "engines", + "published" +] - added
Output schema / properties / scoreVersionAdded value: +{ + "type": "string" +} - changed
Output schema / requiredPrevious value: -[ - "query", - "layer", - "tier", - "tookMs", - "cacheHit", - "resultCount", - "results" -]New value: +[ + "scoreVersion", + "query", + "layer", + "tier", + "tookMs", + "cacheHit", + "resultCount", + "enginePool", + "ranking", + "effectiveWeights", + "communityUsed", + "results" +]
- Changed
search_layer1 field changed- added
Input schema / properties / layer / descriptionAdded value: +"show (default) reads current state; free/api persist a new default and require authorization"
- Changed
search_stats2 fields changed- added
Output schema / properties / keyedEnginesAdded value: +{ + "additionalProperties": false, + "properties": { + "configured": { + "type": "number" + }, + "enabled": { + "type": "number" + }, + "enabledNames": { + "items": { + "type": "string" + }, + "type": "array" + }, + "total": { + "type": "number" + } + }, + "required": [ + "configured", + "enabled", + "total", + "enabledNames" + ], + "type": "object" +} - changed
Output schema / requiredPrevious value: -[ - "startedAt", - "layer", - "cacheHits", - "cacheMisses", - "tierCounts", - "engines", - "xOfficial", - "xSource", - "recent" -]New value: +[ + "startedAt", + "layer", + "cacheHits", + "cacheMisses", + "tierCounts", + "keyedEngines", + "engines", + "xOfficial", + "xSource", + "recent" +]
- Changed
x_search10 fields changed- added
Input schema / properties / allowed_x_handlesAdded value: +{ + "description": "Only these authors; mutually exclusive with excluded_x_handles", + "items": { + "type": "string" + }, + "maxItems": 20, + "type": "array" +} - added
Input schema / properties / excluded_x_handlesAdded value: +{ + "description": "Exclude these authors; mutually exclusive with allowed_x_handles", + "items": { + "type": "string" + }, + "maxItems": 20, + "type": "array" +} - changed
Input schema / properties / from_date / descriptionPrevious value: -"YYYY-MM-DD"New value: +"Inclusive start date, YYYY-MM-DD (UTC)" - added
Input schema / properties / max_results / descriptionAdded value: +"Requested result limit, 1–10" - added
Input schema / properties / post_id / descriptionAdded value: +"Real X post ID or status URL for type=thread" - added
Input schema / properties / query / descriptionAdded value: +"Search terms and X filters (e.g. from:OpenAI), or a natural-language topic for semantic mode" - changed
Input schema / properties / to_date / descriptionPrevious value: -"YYYY-MM-DD"New value: +"Inclusive end date, YYYY-MM-DD (UTC)" - added
Input schema / properties / type / descriptionAdded value: +"Mode: keyword (default) or semantic uses query; user uses username; thread uses post_id" - added
Input schema / properties / username / descriptionAdded value: +"X account handle for type=user" - added
Output schema / properties / noteAdded value: +{ + "type": "string" +}
2 tool updates
v0.1.6- Changed
deep_research1 field changed- added
Input schema / properties / roundAdded value: +{ + "description": "Research round number (auto-increments when omitted)", + "minimum": 1, + "type": "integer" +}
- Changed
fused_search4 fields changed- added
Output schema / properties / engineStatsAdded value: +{ + "additionalProperties": { + "additionalProperties": false, + "properties": { + "errors": { + "type": "number" + }, + "note": { + "type": "string" + }, + "used": { + "type": "boolean" + } + }, + "required": [ + "used", + "errors" + ], + "type": "object" + }, + "type": "object" +} - added
Output schema / properties / enginesRequestedAdded value: +{ + "items": { + "type": "string" + }, + "type": "array" +} - added
Output schema / properties / enginesUsedAdded value: +{ + "items": { + "type": "string" + }, + "type": "array" +} - added
Output schema / properties / warningsAdded value: +{ + "items": { + "type": "string" + }, + "type": "array" +}
6 tool updates
v0.1.2- First observed
deep_research - First observed
fetch_page - First observed
fused_search - First observed
search_layer - First observed
search_stats - First observed
x_search
TDQS
Scored across 5 tools
Tools have mostly distinct purposes: fused_search for general web search, x_search for X/Twitter, fetch_page for URL reading, and search_stats/search_layer for diagnostics/configuration. However, search_stats and search_layer both touch engine configuration, and fused_search's description references a non-existent adaptive_search tool, which could cause mild confusion.
All names use snake_case, which is consistent. However, the naming patterns vary: fused_search (adjective_noun), fetch_page (verb_noun), x_search (noun_noun), search_stats (noun_noun), search_layer (noun_noun). There is no single predictable verb_noun convention, though names remain readable.
5 tools is well-scoped for a search server: core search, specialized X search, page fetch, diagnostics, and configuration. Each tool has a clear role without redundancy.
The surface covers general search, X search, page fetch, stats, and layer configuration. However, the descriptions reference an adaptive_search tool for higher-quality intent-guided evidence selection that is not present, indicating a notable gap in the intended tool set.
Maintenance
Related MCP Connectors
Free web search for AI agents. No API key required. Hosted MCP in active development.
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
Scrape, crawl and search the web for AI agents via MCP.
Docs: https://docs.keenable.ai/mcp-server Keenable is a free, remote MCP server that gives agents access to the web index. Search the web with ranked results and date/site filters, then fetch any indexed page as clean markdown. Works out of the box with no account or API key.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server that enables coding agents to search X/Twitter and the web through the local Grok CLI, providing better search results than default Codex or Claude search without requiring an API key.24 npm7MIT
- AlicenseAqualityFmaintenanceMCP server for web search powered by Google AI Mode (Gemini). Enables any AI agent to search the web in real-time for free and without rate limits.2183MIT
- AlicenseNot gradedqualityBmaintenanceA zero-config web search and fetch MCP server for LLM agents, featuring multi-backend metasearch, persistent rolling cache, and structured error envelopes for retry-friendly interactions.MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for multi-engine web search and web page fetching, supporting parallel search, content extraction, and optional LLM-powered search summarization and deep search.5MIT