Skip to main content
Glama
Windrunner20

AllSearch MCP

by Windrunner20
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

AllSearch MCP

面向 AI Agent 的 Grok-first 多源搜索 MCP：先用 Grok 建立答案与引用基线，再按任务需要调用 Tavily、AnySearch 和 Firecrawl 补充证据。

AllSearch 适合接入 Pi、OpenClaw 或其他 MCP Host。它提供统一的搜索结果结构、Provider 路由记录、引用去重、垂直领域检索和网页正文抓取，并附带一个防止搜索结果撑爆上下文的 Pi Extension。

项目状态： v0.2.0，已完成真实 Provider 与 MCP stdio 调用验证，适合本地使用和边用边调。搜索质量策略仍会继续迭代。

它解决什么问题

一个 Agent 的外部搜索通常不是“选一个搜索 API”这么简单：

  • Grok 擅长搜索、理解问题并生成带引用的初步答案；

  • Tavily 适合补充网页结果和做独立交叉验证；

  • AnySearch 对 CVE、金融、学术、法律等垂直领域更有结构化优势；

  • Firecrawl 适合在已经发现 URL 后抓取完整正文。

AllSearch 将这些能力收进一个 MCP，并保持明确的优先级：

flowchart LR
    A[Agent / MCP Host] --> B[AllSearch search]
    B --> C[Grok primary search]
    C --> D{Coverage & query signals}
    D -->|Need web corroboration| E[Tavily]
    D -->|Vertical domain| F[AnySearch]
    C --> G[Merge, rank, deduplicate]
    E --> G
    F --> G
    G --> H{Need full content?}
    H -->|Yes| I[Firecrawl]
    H -->|No| J[Structured evidence]
    I --> J

Provider 职责

Provider

在 AllSearch 中的职责

Grok / xAI-compatible Responses

默认主搜索、答案与引用基线

Tavily

网页补充、官方来源发现、verify / deep 交叉验证

AnySearch

CVE、金融、学术、法律、健康、代码等垂直领域检索

Firecrawl

已知 URL 的正文抓取，不作为默认发现引擎

Related MCP server: websearch-skill

快速开始

1. 安装

要求：

  • Python 3.11+

  • 至少一个支持 web_search 的 OpenAI Responses-compatible Grok 端点

  • Tavily、AnySearch、Firecrawl 按需配置

git clone https://github.com/Windrunner20/allsearch.git
cd allsearch

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'

cp .env.example .env
chmod 600 .env

2. 配置 Provider

编辑 .env。下面是最常用的配置项：

# Grok primary search
ALLSEARCH_XAI_API_KEY=
ALLSEARCH_XAI_BASE_URL=https://your-responses-compatible-endpoint/v1
ALLSEARCH_XAI_RESPONSES_PATH=/responses
ALLSEARCH_XAI_MODEL=grok-4.5
# Optional same-endpoint model fallback. Set to none to go straight to the
# endpoint-level fallback below when the primary model fails.
ALLSEARCH_XAI_FALLBACK_MODELS=grok-4.3
ALLSEARCH_XAI_REASONING_EFFORT=low
ALLSEARCH_XAI_MAX_TOOL_CALLS=4
# Optional endpoint-level fallback (OpenAI-compatible chat gateway; used on 402/429/5xx).
# protocol is openai-only (chat completions); the "responses" protocol is rejected at load.
# ALLSEARCH_XAI_FALLBACK_BASE_URL=https://fallback.example/v1
# ALLSEARCH_XAI_FALLBACK_API_KEY=
# ALLSEARCH_XAI_FALLBACK_MODEL=grok-4.3-fast
# ALLSEARCH_XAI_FALLBACK_PROTOCOL=openai

# Supplements
ALLSEARCH_TAVILY_API_KEY=
# Optional Tavily key pool (comma-separated extra keys; round-robin + quota failover):
# ALLSEARCH_TAVILY_API_KEYS=key2,key3,key4
ALLSEARCH_ANYSEARCH_API_KEY=
ALLSEARCH_FIRECRAWL_API_KEY=

.env.example 包含所有可配置项。进程或 MCP Host 注入的环境变量优先于 .env。

官方 xAI：

ALLSEARCH_XAI_BASE_URL=https://api.x.ai/v1

使用其他 OpenAI Responses-compatible 网关时，只需替换 base URL、模型名称和 API key：

ALLSEARCH_XAI_BASE_URL=https://your-gateway.example/v1
ALLSEARCH_XAI_RESPONSES_PATH=/responses
ALLSEARCH_XAI_MODEL=your-primary-model
ALLSEARCH_XAI_FALLBACK_MODELS=your-fallback-model
ALLSEARCH_XAI_REASONING_EFFORT=low

Responses 推理参数使用嵌套格式：

{
  "reasoning": {
    "effort": "low"
  }
}

兼容网关会接收你的查询和凭据。请仅使用你信任的服务，并自行确认其隐私、计费和数据保留政策。

端点级 fallback 仅支持 openai（chat completions）协议；配置为 responses 会在加载配置时直接报错。

3. 运行健康检查

python - <<'PY'
import asyncio
from allsearch.config import load_config
from allsearch.orchestrator import Orchestrator

async def main():
    app = Orchestrator(load_config())
    try:
        health = await app.health()
        for provider in health.providers:
            print(provider.name, provider.configured, provider.state)
    finally:
        await app.aclose()

asyncio.run(main())
PY

预期能看到已配置 Provider，例如：

xai True idle
tavily True idle
anysearch True idle
firecrawl True idle

4. 启动 MCP

stdio：

python -m allsearch --transport stdio

Streamable HTTP：

python -m allsearch \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --path /mcp

MCP Host 的通用 stdio 配置大致如下；配置键名可能因 Host 而异：

{
  "mcpServers": {
    "allsearch": {
      "command": "/absolute/path/to/allsearch/.venv/bin/python",
      "args": ["-m", "allsearch", "--transport", "stdio"],
      "cwd": "/absolute/path/to/allsearch"
    }
  }
}

密钥可以继续留在仓库目录的 gitignored .env 中，不需要复制到 Host 配置文件。

MCP 工具

search

统一搜索入口。

{
  "query": "核实 Python 当前最新稳定版本和发布日期",
  "mode": "auto",
  "depth": "verify",
  "max_results": 8,
  "include_domains": ["python.org"],
  "fresh": true
}

返回包含：

  • answer：Grok 主答案；

  • results / citations：去重后的证据与引用；

  • route.stages：实际调用了哪些 Provider、原因和延迟；

  • evidence：唯一 URL、独立域名、跨 Provider 命中、抓取页数；

  • warnings / errors：模型 fallback、Provider 错误和降级状态。

fetch

通过 Firecrawl 抓取已知公共 URL 的正文，并进行 SSRF 目标检查。

{
  "url": "https://example.com/article",
  "max_chars": 30000,
  "fresh": true
}

health

查看 Provider 配置、熔断和缓存状态，不返回密钥内容。

{
  "probe": false
}

搜索深度

Depth

行为

适合场景

fast

Grok 优先；证据不足时才补 Tavily；不自动抓正文

普通查询、当前版本、低延迟任务

balanced

Grok 优先；按需 Tavily；高置信度垂直问题使用 AnySearch

默认日常研究

verify

Grok 后强制 Tavily 交叉验证；垂直问题加 AnySearch；有限 Firecrawl

事实核验、多个来源、官方依据

deep

更完整的补充搜索与正文抓取

深度研究、需要原文的任务

所有深度都保持 Grok 先执行。Tavily 与 AnySearch 属于后续补充阶段，Firecrawl 只在发现 URL 后工作。

AnySearch 垂直检索

AllSearch 会先读取目标领域的能力目录，再选择 sub_domain 和必填参数。

例如：

CVE-2024-1234 的影响范围和修复建议

会被路由为：

{
  "domain": "security",
  "sub_domain": "security.vuln",
  "sub_domain_params": {
    "type": "cve",
    "value": "CVE-2024-1234"
  }
}

适配器同时兼容 AnySearch 的旧版表格目录和当前分节 Markdown 目录，并会过滤非法 URL。

Pi 集成：防止搜索撑爆上下文

仓库自带 Pi Extension：

mkdir -p ~/.pi/agent/extensions
ln -s "$(pwd)/integrations/pi" ~/.pi/agent/extensions/allsearch

重启 Pi，或在当前会话执行：

/reload

检查状态：

/allsearch-status

Pi 中会出现：

allsearch_search
allsearch_fetch
allsearch_health

上下文预算

Pi Extension 不会把完整 MCP JSON 和网页正文直接放入模型上下文。

工具

单次摘要上限

单轮共享上限

allsearch_search

8KB

16KB

allsearch_fetch

6KB

16KB

allsearch_health

4KB

16KB

当 Pi 当前上下文使用率超过 75% / 90% 时，单次摘要会自动收紧到 4KB / 2KB。

完整 MCP 响应保存到私有临时文件：

/tmp/pi-allsearch-*/search.json

文件权限为 0600，目录权限为 0700。摘要不足时，Agent 可以通过 read 的 offset / limit 增量查看，而不是一次吞入完整结果。会话关闭时临时文件会自动清理。

Pi Extension 与所有本地 Extension 一样，使用当前用户权限执行。只从你信任的仓库版本加载它。

运行与安全边界

  • .env、虚拟环境、缓存和 Agent 临时文件均被 Git 忽略；

  • Provider 错误在返回给 Agent 前会进行常见密钥模式脱敏；

  • fetch 会拒绝 localhost、私有 IP、嵌入凭据和非 HTTP(S) URL，并且自动抓取（auto-scrape）和显式 fetch 都会对原始 URL 与最终重定向 URL（final_url）做同样的 SSRF 校验；

  • URL 合并会去除常见追踪参数并按规范化 URL 去重；

  • 搜索和网页内容始终被标记为不可信外部数据；

  • 最终的结构化结果、引用与证据会按 include_domains / exclude_domains 做大小写不敏感、真实子域匹配的过滤（exclude 优先）；自然语言 answer 不会被改写；

  • 自动抓取每页正文有内部 30000 字符上限（截断时会加 warning），并拒绝空内容 / 过短 / 反爬壳页面（拒绝的页面不计入 pages_fetched）；

  • 搜索整体受硬总截止时间约束（ALLSEARCH_TOTAL_BUDGET_SECONDS）：超时后不再启动后续阶段并取消未完成任务，超时响应不缓存；若主搜索已完成则返回 partial，严格模式下主搜索未完成则返回 error；

  • health 在 xAI 处于 idle / healthy 时报告 ok，处于 degraded / half_open / open 时报告 degraded（熔断打开时附加 primary_circuit_open warning）；

  • ALLSEARCH_ALLOW_DEGRADED_SEARCH=false 时，Grok 不可用会在任何补充源（Tavily/AnySearch）执行前直接返回明确错误，而不是悄悄改成其他搜索结果。

测试

source .venv/bin/activate
pytest -q

当前测试覆盖（默认全离线，不调用外网 Provider）：

  • Provider 请求与响应契约（respx mock）；

  • Grok 模型 fallback、reasoning 参数和端点级 fallback（OpenAI chat）；

  • Tavily 多 Key 轮换与配额故障切换；

  • AnySearch 两种 Markdown 格式；

  • 路由、合并、缓存、熔断和 SSRF 检查；

  • 严格模式下的主搜索门禁（补充源零调用）、group1 并发与确定顺序、单源失败不阻塞；

  • 硬总截止时间：阶段不悬挂、超时不缓存、不重复报错、取消不触发熔断计数；

  • 最终域过滤（大小写不敏感、真实子域、exclude 优先）；

  • 自动抓取的原 URL / final URL DNS 校验、低质量拒绝与 30000 字符截断；

  • 配置脱敏、fallback 协议校验、Tavily pool-only 配置；

  • health 的熔断到 degraded / primary_circuit_open 映射；

  • MCP 工具注册与 Pi bridge 的严格字节预算和 artifact 路径保留。

真实 Provider 测试只是占位模板，默认不在 CI / 普通测试中运行，以避免消耗额度和依赖外部网络。

已知限制

  • 搜索排序和查询改写仍需要根据真实任务持续调优；

  • Responses-compatible 网关的模型可用性、延迟和计费可能随时变化；

  • 当前缓存仅为进程内存缓存，没有 Redis 或跨进程共享；

  • 搜索整体已有硬总截止时间，但 Provider 内部的重试与响应解析仍可能占用全部预算，极端情况下留给后续阶段的时间会变少；

  • 当前没有 Docker 镜像、管理 UI 或第二次模型综合层。

参与贡献

欢迎提交 Issue 或 Pull Request。涉及 Provider 契约变化时，请附上脱敏后的响应结构或 fixture，不要提交真实 API key、完整私密查询或用户数据。

License

项目元数据当前声明为 MIT。仓库尚未加入独立的 LICENSE 文件；正式分发或二次使用前，请先确认许可证文本。

Available Tools

3 tools
fetchB

Fetch full content for a known HTTP(S) URL via Firecrawl (post-discovery assist).

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYes
focusNo
freshNo
max_charsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of disclosing behavioral traits. It says 'Fetch full content', which implies a read-only operation, but it does not explicitly confirm non-destructiveness, mention rate limits, authentication requirements, or potential side effects. The description also lacks context on how 'fresh' and 'max_chars' affect the request, leaving behavioral nuances undisclosed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that front-loads the core action ('Fetch full content') and wastes no words. It is appropriately sized for the simplicity of the tool, though it could benefit from a bit more detail without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderate complexity (4 parameters, 1 required), an output schema, and no annotations, the description is too brief to be complete. It does not explain the purpose or semantics of 'focus', 'fresh', or 'max_chars', nor does it provide enough workflow context beyond the vague 'post-discovery assist'. The agent would struggle to invoke the tool optimally without additional information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate for the missing parameter meanings. It only explains the 'url' parameter as 'known HTTP(S) URL' and provides no explanation for 'focus', 'fresh', or 'max_chars'. These names are somewhat self-explanatory, but 'focus' is ambiguous and 'fresh' could be misinterpreted, making the description insufficient for correct parameter usage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool's action: 'Fetch full content for a known HTTP(S) URL'. This specific verb+resource combination distinguishes it from siblings like 'search' (which likely finds URLs) and 'health' (a status check). The parenthetical 'post-discovery assist' adds context, though it does not explicitly name alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'post-discovery assist' implies the tool is intended for use after a discovery step, suggesting when it might be appropriate, but it gives no explicit guidance on when to use it versus alternatives. There are no exclusion criteria or comparisons to sibling tools like 'search'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

healthB

Provider configuration and circuit health. probe=true runs bounded cached probes.

ParametersJSON Schema
NameRequiredDescriptionDefault
probeNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that probes are 'bounded cached', implying safe execution, but does not describe default behavior when probe=false, potential side effects, return format, or whether the operation is read-only. This is minimal behavioral disclosure for a tool with zero annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently front-loads the tool's purpose and then clarifies the parameter behavior. Every word contributes to meaning, with no unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with an output schema, the description covers the core purpose and parameter semantics. However, it lacks explicit usage guidance and default behavior context, making it minimally complete but not thorough.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only defines a 'probe' boolean with a default. The description adds meaning by explaining that setting probe=true triggers 'bounded cached probes', clarifying the effect of the parameter. This goes beyond the schema's bare title and default value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Provider configuration and circuit health', which clearly indicates the tool's purpose as a health-check resource. It differentiates from sibling tools 'search' and 'fetch' by focusing on health rather than data retrieval, though it lacks an explicit verb like 'get' or 'check'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions 'probe=true runs bounded cached probes', which gives guidance on using the optional parameter but does not explicitly state when to use this tool versus alternatives. The usage context is implied as a health check, but no exclusions or alternative tool references are provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.7/5.0
Disambiguation5/5

Each tool has a distinct purpose: health checks service status, search performs web queries, and fetch retrieves a specific URL. No overlap or ambiguity between them.

Naming Consistency5/5

All tool names are single lowercase words (health, search, fetch), following a simple and consistent pattern. Though not verb_noun, the style is uniform across the set.

Tool Count5/5

Three tools is an ideal scope for a search service with a health check and content fetching. Each tool serves a clear, non-redundant role.

Completeness5/5

The tool set covers the full lifecycle of a search workflow: verify service health, execute a search, and fetch full content for follow-up. No obvious missing operations for the stated purpose.

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • grok-build-plugin

    VasiHemanth
    A
    license
    Not graded
    quality
    B
    maintenance
    Live X (Twitter) and web search for any coding agent through your existing Grok subscription. Exposes a grok_search MCP tool, so no X API key or X developer account is needed.
    59
    25
    Apache 2.0

  • qsearch

    theYahia
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to perform web searches with full content retrieval and multi-engine provenance, including trust scoring and local corpus persistence, via MCP integration.
    3
    2
    Apache 2.0

  • MCP Info Gatherer

    ESkuratov
    F
    license
    A
    quality
    B
    maintenance
    Enables searching and gathering information from multiple online sources (web, Twitter/X, Telegram, GitHub, Hugging Face, arXiv) through a unified MCP interface.
    12

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Windrunner20/allsearch'

If you have feedback or need assistance with the MCP directory API, please join our Discord server