Skip to content

Commit 642c114

Browse files
wd041216-bitclaude
wd041216-bit
and
claude
committed
feat: v22.0.0 — WebFetch optimizations + multi-agent integration
browse_page improvements: - HTML-to-Markdown conversion via markdownify (format=markdown default) - LRU response cache (15-min TTL, 50MB cap) for browse and search - Prompt-based extraction passthrough for calling agents - Increased default max_chars from 10K to 50K - PDF text extraction (optional, requires pypdf) - Cross-host redirect blocking (same-host only, max 10 hops) - Domain allowlist/blocklist via env vars - Proper truncation markers with total length MCP server additions: - browse_page: format, prompt params - clear_cache tool for manual cache invalidation - Cache stats in list_providers output Multi-agent integration: - .hermes/ plugin + MCP server config - .openclaw/ skill with SKILL.md + openclaw.json - .nanobot/ nanobot.yaml + researcher agent Dependencies: added markdownify, optional pypdf Version: 21.0.0 → 22.0.0 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 455e8ce commit 642c114

15 files changed

Lines changed: 898 additions & 104 deletions

File tree

‎.hermes/mcp-servers.yaml‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Hermes MCP Server Configuration for zero-api-key-web-search
2+
# Add this to your ~/.hermes/config.yaml under mcp_servers:
3+
4+
mcp_servers:
5+
zero-search:
6+
command: "zero-mcp"
7+
args: []
8+
enabled: true
9+
timeout: 120

‎.hermes/plugins/zero-api-key-web-search/__init__.py‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
"""Hermes plugin registration for zero-api-key-web-search.
2+
3+
This plugin connects to the zero-mcp MCP server which provides
4+
all search, browse, verification, and report tools.
5+
"""
6+
7+
8+
def register(ctx):
9+
"""Register the zero-api-key-web-search plugin with Hermes."""
10+
# The MCP server provides all tools via the stdio protocol.
11+
# Hermes will auto-discover tools from the MCP server config.
12+
# No manual tool registration needed — the MCP server handles it.
13+
ctx.register_skill(
14+
"web-search",
15+
Path(__file__).parent.parent.parent.parent / "zero_api_key_web_search" / "skills" / "SKILL.md",
16+
)
17+
18+
19+
from pathlib import Path

‎.hermes/plugins/zero-api-key-web-search/plugin.yaml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
name: zero-api-key-web-search
2+
version: 1.0.0
3+
description: Free web search with evidence verification and source citations for AI agents
4+
provides_tools:
5+
- search_web
6+
- browse_page
7+
- verify_claim
8+
- evidence_report
9+
- llm_context
10+
- list_providers
11+
- clear_cache

‎.hermes/plugins/zero-api-key-web-search/schemas.py‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
"""Tool schemas for zero-api-key-web-search Hermes plugin.
2+
3+
These schemas describe the tools available via the MCP server.
4+
Hermes uses these for tool discovery when the MCP server is not reachable.
5+
"""
6+
7+
SEARCH_WEB = {
8+
"name": "search_web",
9+
"description": "Search the web for real-time information, news, images, books, or videos.",
10+
"parameters": {
11+
"type": "object",
12+
"properties": {
13+
"query": {"type": "string", "description": "The search query."},
14+
"type": {"type": "string", "enum": ["text", "news", "images", "videos", "books"], "description": "Type of search. Default: text."},
15+
"region": {"type": "string", "description": "Region code (default: wt-wt)."},
16+
"timelimit": {"type": "string", "enum": ["d", "w", "m", "y", ""], "description": "Time limit for results."},
17+
"providers": {"type": "array", "items": {"type": "string"}, "description": "Provider list, e.g. ['ddgs', 'searxng', 'brightdata']."},
18+
"profile": {"type": "string", "enum": ["free", "default", "free-verified", "production", "max-evidence"]},
19+
"goggles": {"type": "string", "description": "Goggles preset for reranking."},
20+
},
21+
"required": ["query"],
22+
},
23+
}
24+
25+
BROWSE_PAGE = {
26+
"name": "browse_page",
27+
"description": "Fetch and extract content from a URL. Returns Markdown by default.",
28+
"parameters": {
29+
"type": "object",
30+
"properties": {
31+
"url": {"type": "string", "description": "The URL to read."},
32+
"max_chars": {"type": "integer", "description": "Max characters to extract (default: 50000)."},
33+
"format": {"type": "string", "enum": ["markdown", "text"], "description": "Output format (default: markdown)."},
34+
"prompt": {"type": "string", "description": "Optional extraction hint for the agent's LLM."},
35+
},
36+
"required": ["url"],
37+
},
38+
}
39+
40+
VERIFY_CLAIM = {
41+
"name": "verify_claim",
42+
"description": "Evaluate whether a factual claim is supported, contested, or under-evidenced.",
43+
"parameters": {
44+
"type": "object",
45+
"properties": {
46+
"claim": {"type": "string", "description": "The factual claim to verify."},
47+
"region": {"type": "string", "description": "Region code (default: wt-wt)."},
48+
"timelimit": {"type": "string", "enum": ["d", "w", "m", "y", ""]},
49+
"providers": {"type": "array", "items": {"type": "string"}},
50+
"profile": {"type": "string", "enum": ["free", "default", "free-verified", "production", "max-evidence"]},
51+
"goggles": {"type": "string"},
52+
"with_pages": {"type": "boolean", "description": "Fetch top pages for deeper analysis."},
53+
"deep": {"type": "boolean", "description": "Alias for with_pages."},
54+
"max_pages": {"type": "integer", "description": "Max pages to fetch (default: 3)."},
55+
},
56+
"required": ["claim"],
57+
},
58+
}
59+
60+
EVIDENCE_REPORT = {
61+
"name": "evidence_report",
62+
"description": "Generate a citation-ready evidence report combining search, verification, and analysis.",
63+
"parameters": {
64+
"type": "object",
65+
"properties": {
66+
"query": {"type": "string", "description": "Search query to gather evidence."},
67+
"claim": {"type": "string", "description": "Optional explicit claim to verify."},
68+
"region": {"type": "string"},
69+
"timelimit": {"type": "string", "enum": ["d", "w", "m", "y", ""]},
70+
"providers": {"type": "array", "items": {"type": "string"}},
71+
"profile": {"type": "string"},
72+
"goggles": {"type": "string"},
73+
"with_pages": {"type": "boolean"},
74+
"deep": {"type": "boolean"},
75+
"max_pages": {"type": "integer"},
76+
"max_sources": {"type": "integer", "description": "Max sources in report digest (default: 5)."},
77+
},
78+
"required": ["query"],
79+
},
80+
}
81+
82+
LLM_CONTEXT = {
83+
"name": "llm_context",
84+
"description": "Build compact, citation-ready Markdown context for LLMs.",
85+
"parameters": {
86+
"type": "object",
87+
"properties": {
88+
"query": {"type": "string", "description": "Search query to ground."},
89+
"type": {"type": "string", "enum": ["text", "news", "images", "videos", "books"]},
90+
"region": {"type": "string"},
91+
"timelimit": {"type": "string"},
92+
"providers": {"type": "array", "items": {"type": "string"}},
93+
"profile": {"type": "string"},
94+
"goggles": {"type": "string"},
95+
"max_sources": {"type": "integer", "description": "Max sources (default: 8)."},
96+
"include_verification": {"type": "boolean", "description": "Include evidence verification (default: true)."},
97+
},
98+
"required": ["query"],
99+
},
100+
}
101+
102+
LIST_PROVIDERS = {
103+
"name": "list_providers",
104+
"description": "List available search providers, profiles, goggles presets, and cache stats.",
105+
"parameters": {"type": "object", "properties": {}},
106+
}
107+
108+
CLEAR_CACHE = {
109+
"name": "clear_cache",
110+
"description": "Clear the response cache for fresh results.",
111+
"parameters": {"type": "object", "properties": {}},
112+
}

‎.hermes/plugins/zero-api-key-web-search/tools.py‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
"""Hermes tool handlers for zero-api-key-web-search.
2+
3+
Delegates all calls to the MCP server via the hermes MCP integration.
4+
When running through Hermes, tools are auto-discovered from the MCP server
5+
configured in .hermes/mcp-servers.yaml. This module provides fallback
6+
handlers for direct invocation.
7+
"""
8+
9+
import json
10+
11+
12+
def search_web(args: dict, **kwargs) -> str:
13+
"""Search the web. Delegates to MCP server."""
14+
# When running through Hermes MCP, tools are auto-discovered.
15+
# This handler is a fallback for direct plugin invocation.
16+
from zero_api_key_web_search.core import UltimateSearcher
17+
searcher = UltimateSearcher()
18+
answer = searcher.search(
19+
query=args["query"],
20+
search_type=args.get("type", "text"),
21+
region=args.get("region", "wt-wt"),
22+
timelimit=args.get("timelimit"),
23+
providers=args.get("providers"),
24+
profile=args.get("profile"),
25+
goggles=args.get("goggles"),
26+
)
27+
return json.dumps({
28+
"query": answer.query,
29+
"answer": answer.answer,
30+
"sources": [{"title": s.title, "url": s.url, "snippet": s.snippet} for s in answer.sources[:10]],
31+
}, ensure_ascii=False)
32+
33+
34+
def browse_page(args: dict, **kwargs) -> str:
35+
"""Browse a page. Delegates to MCP server."""
36+
from zero_api_key_web_search.browse_page import browse
37+
result = browse(
38+
url=args["url"],
39+
max_chars=args.get("max_chars", 50000),
40+
format=args.get("format", "markdown"),
41+
prompt=args.get("prompt"),
42+
)
43+
return json.dumps(result, ensure_ascii=False)
44+
45+
46+
def verify_claim(args: dict, **kwargs) -> str:
47+
"""Verify a claim. Delegates to MCP server."""
48+
from zero_api_key_web_search.core import UltimateSearcher
49+
searcher = UltimateSearcher()
50+
v = searcher.verify_claim(
51+
claim=args["claim"],
52+
region=args.get("region", "wt-wt"),
53+
timelimit=args.get("timelimit"),
54+
providers=args.get("providers"),
55+
profile=args.get("profile"),
56+
goggles=args.get("goggles"),
57+
include_pages=args.get("with_pages", False) or args.get("deep", False),
58+
deep=args.get("deep", False),
59+
max_pages=args.get("max_pages", 3),
60+
)
61+
return json.dumps({
62+
"claim": v.claim,
63+
"verdict": v.verdict,
64+
"confidence": v.confidence,
65+
"summary": v.summary,
66+
}, ensure_ascii=False)

‎.nanobot/agents/researcher.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
name: Research Agent
3+
mcpServers:
4+
- zero-search
5+
---
6+
7+
You are a research agent with access to web search and evidence verification tools.
8+
9+
## Available Tools
10+
11+
- **search_web**: Search for real-time information, news, images, books, or videos
12+
- **browse_page**: Fetch and extract content from URLs (Markdown or text format)
13+
- **verify_claim**: Evaluate whether a factual claim is supported or contested
14+
- **evidence_report**: Generate a comprehensive citation-ready evidence report
15+
- **llm_context**: Build compact, citation-ready context for grounded responses
16+
- **list_providers**: Check available search providers and cache status
17+
- **clear_cache**: Clear the response cache for fresh results
18+
19+
## Usage Guidelines
20+
21+
1. Start with `search_web` for broad queries
22+
2. Use `browse_page` to read full page content from search results
23+
3. Use `verify_claim` to fact-check specific claims
24+
4. Use `evidence_report` for comprehensive research with citations
25+
5. Use `llm_context` when you need compact, grounded context
26+
27+
## Best Practices
28+
29+
- Use `format: markdown` (default) for structured content, `format: text` for plain text
30+
- Use the `prompt` parameter on `browse_page` to specify what information to focus on
31+
- Set `with_pages: true` on `verify_claim` for deeper analysis
32+
- Use `goggles: research` for academic/institutional sources
33+
- Use `goggles: docs-first` for official documentation

‎.nanobot/nanobot.yaml‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
mcpServers:
2+
zero-search:
3+
name: "Zero-API-Key Web Search"
4+
shortName: "zsearch"
5+
command: "zero-mcp"
6+
args: []
7+
8+
agents:
9+
researcher:
10+
name: Research Agent
11+
mcpServers: zero-search
12+
tools:
13+
- zero-search
14+
permissions:
15+
'*': allow

‎.openclaw/openclaw.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"mcp": {
3+
"servers": {
4+
"zero-search": {
5+
"command": "zero-mcp",
6+
"args": []
7+
}
8+
}
9+
}
10+
}

‎.openclaw/skills/zero-api-key-web-search/SKILL.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
name: zero-api-key-web-search
3+
description: Free web search with evidence verification and source citations for AI agents
4+
version: 22.0.0
5+
url: https://github.com/wd041216-bit/zero-api-key-web-search
6+
user-invocable: true
7+
command-dispatch: tool
8+
command-tool: search_web
9+
metadata: {"openclaw":{"emoji":"\U0001F50D","requires":{"bins":["zero-mcp"]}}}
10+
---
11+
12+
# Zero-API-Key Web Search
13+
14+
Free web search for AI agents. No API keys required for default usage (DuckDuckGo).
15+
16+
## Available Tools
17+
18+
### search_web
19+
Search the web for real-time information, news, images, books, or videos.
20+
- `query` (required): The search query
21+
- `type`: text, news, images, videos, books (default: text)
22+
- `region`: Region code (default: wt-wt)
23+
- `timelimit`: d (day), w (week), m (month), y (year)
24+
- `providers`: Optional provider list: ddgs, searxng, brightdata
25+
- `profile`: free, default, free-verified, production, max-evidence
26+
- `goggles`: Reranking preset: docs-first, research, news-balanced
27+
28+
### browse_page
29+
Fetch and extract content from a URL. Returns Markdown by default.
30+
- `url` (required): The URL to read
31+
- `max_chars`: Max characters to extract (default: 50000)
32+
- `format`: markdown or text (default: markdown)
33+
- `prompt`: Optional extraction hint for focused retrieval
34+
35+
### verify_claim
36+
Evaluate whether a factual claim is supported, contested, or under-evidenced.
37+
- `claim` (required): The claim to verify
38+
- `with_pages` / `deep`: Fetch top pages for deeper analysis
39+
- `max_pages`: Max pages to fetch (default: 3)
40+
41+
### evidence_report
42+
Generate a citation-ready evidence report combining search + verification.
43+
- `query` (required): Search query to gather evidence
44+
- `claim`: Optional explicit claim to verify
45+
- `max_sources`: Max sources in digest (default: 5)
46+
47+
### llm_context
48+
Build compact, citation-ready Markdown context for LLMs.
49+
- `query` (required): Search query to ground
50+
- `max_sources`: Max sources (default: 8)
51+
- `include_verification`: Include evidence verification (default: true)
52+
53+
### list_providers
54+
List available search providers, profiles, and cache statistics.
55+
56+
### clear_cache
57+
Clear the response cache for fresh results.
58+
59+
## Setup
60+
61+
```bash
62+
pip install zero-api-key-web-search
63+
```
64+
65+
For PDF extraction support:
66+
```bash
67+
pip install zero-api-key-web-search[pdf]
68+
```
69+
70+
## MCP Configuration
71+
72+
Add to your OpenClaw config (`openclaw.json`):
73+
74+
```json
75+
{
76+
"mcp": {
77+
"servers": {
78+
"zero-search": {
79+
"command": "zero-mcp",
80+
"args": []
81+
}
82+
}
83+
}
84+
}
85+
```
86+
87+
## Confidence Levels
88+
89+
| Tool | High Confidence | Medium Confidence | Low Confidence |
90+
|------|---------------|-------------------|---------------|
91+
| search_web | Multiple sources agree | Single authoritative source | Single weak source |
92+
| verify_claim | supported/likely_supported | contested | likely_false/insufficient_evidence |
93+
| browse_page | Official docs, well-structured pages | Blog posts, forums | User-generated, no attribution |

0 commit comments

Comments
 (0)