mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-16 19:40:03 +00:00
* fix: redact search parameters in HTTP errors * docs: describe HTTP error URL redaction
341 lines
17 KiB
Markdown
341 lines
17 KiB
Markdown
# MCP Tools Reference
|
|
|
|
This document describes the MCP tools exposed by the SearXNG MCP server.
|
|
|
|
## search
|
|
|
|
Search the web using a SearXNG meta-search engine instance.
|
|
|
|
### Tool Description
|
|
|
|
The `search` tool proxies web search requests to a SearXNG instance, which aggregates results from multiple search engines while maintaining user privacy. MCP mode always returns structured JSON for programmatic parsing.
|
|
|
|
### Parameters
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|--------------|---------|----------|---------|--------------------------------------------------|
|
|
| `query` | string | Yes | - | The search query string. Max 500 runes. |
|
|
| `language` | string | No | | Language code for results (e.g., en, zh-tw, ja). Maximum 35 runes for the full value. Empty or `"auto"` = SearXNG decides |
|
|
| `safesearch` | integer | No | 0 | SafeSearch filtering level: |
|
|
| | | | | - `0` = Off (show all results) |
|
|
| | | | | - `1` = Moderate (filter some adult content) |
|
|
| | | | | - `2` = Strict (filter adult content) |
|
|
| `time_range` | string | No | - | Restrict results to a time period: |
|
|
| | | | | - `day` = Last 24 hours |
|
|
| | | | | - `month` = Last 30 days |
|
|
| | | | | - `year` = Last 365 days |
|
|
| `categories` | string | No | - | Comma-separated list of SearXNG categories. |
|
|
| | | | | "general" covers most queries; other values |
|
|
| | | | | (it, science, news, map, music, files, |
|
|
| | | | | social media) also work but are rarely needed. |
|
|
| | | | | Maximum 4096 UTF-8 bytes for the full string. |
|
|
| `engines` | string | No | - | Comma-separated list of SearXNG engine names. |
|
|
| | | | | Common engines: google, bing, duckduckgo. |
|
|
| | | | | Maximum 4096 UTF-8 bytes for the full string. |
|
|
| `pageno` | integer, null | No | 1 | Page number for pagination (SearXNG defaults to page 1 when omitted) |
|
|
| `limit` | integer | No | 10 | Maximum number of results returned (1-20) |
|
|
|
|
### Response Format
|
|
|
|
The tool returns a JSON text response containing the full `SearchResponse` object. This enables programmatic parsing by MCP clients.
|
|
|
|
**Response Fields:**
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `query` | string | The original search query |
|
|
| `warning` | string | External-content advisory noting that search results come from untrusted sources and should be verified before use (always present on successful responses) |
|
|
| `answers` | array | Direct answers (omitted when empty) |
|
|
| `number_of_results` | integer | Total count of results; if SearXNG returns 0 while results exist, normalized to `len(results)` |
|
|
| `infoboxes` | array | Knowledge panels with content, attributes, URLs (omitted when empty) |
|
|
| `results` | array | Array of search result objects (always present, `[]` when empty) |
|
|
| `suggestions` | array | Related search suggestions (always present, `[]` when empty) |
|
|
| `unresponsive_engines` | array | Debug-only array of `[engine_name, error_message]` pairs (omitted unless debug mode is enabled) |
|
|
|
|
**Result Object Fields:**
|
|
|
|
| Field | Type | Description |
|
|
|-------|------|-------------|
|
|
| `title` | string | Result title |
|
|
| `url` | string | URL of the result |
|
|
| `content` | string | Content snippet from the page |
|
|
| `engine` | string | Source search engine |
|
|
| `publishedDate` | string | Publication date provided by SearXNG (omitted when the backend does not include it; no normalization is applied) |
|
|
|
|
**Note:** The `number_of_results` field may return 0 from SearXNG even when results are present. The server normalizes this by replacing 0 with `len(results)` when results exist. If `pageno` is omitted, the server does not send the parameter and SearXNG uses its page 1 default.
|
|
|
|
**Note:** The `warning` field is a static advisory emitted on every successful response to remind AI agents and JSON consumers that search results originate from external, untrusted sources. It is not a per-result provenance marker; the canonical wire-format ordering and JSON-mode behavior are documented in [docs/OUTPUT_FORMAT.md](OUTPUT_FORMAT.md).
|
|
|
|
### Example Usage
|
|
|
|
#### Basic search
|
|
|
|
```json
|
|
{
|
|
"query": "golang tutorial"
|
|
}
|
|
```
|
|
|
|
#### Search with language filter
|
|
|
|
```json
|
|
{
|
|
"query": "machine learning",
|
|
"language": "en"
|
|
}
|
|
```
|
|
|
|
#### Safe search enabled
|
|
|
|
```json
|
|
{
|
|
"query": "programming",
|
|
"safesearch": 1
|
|
}
|
|
```
|
|
|
|
#### Time-restricted search (recent news)
|
|
|
|
```json
|
|
{
|
|
"query": "AI breakthroughs",
|
|
"time_range": "day"
|
|
}
|
|
```
|
|
|
|
#### Search with specific categories
|
|
|
|
```json
|
|
{
|
|
"query": "technology news",
|
|
"categories": "news"
|
|
}
|
|
```
|
|
|
|
#### Search with specific engines
|
|
|
|
```json
|
|
{
|
|
"query": "web development",
|
|
"engines": "google,bing"
|
|
}
|
|
```
|
|
|
|
#### Pagination
|
|
|
|
```json
|
|
{
|
|
"query": "recipes",
|
|
"pageno": 2
|
|
}
|
|
```
|
|
|
|
#### Combined parameters
|
|
|
|
```json
|
|
{
|
|
"query": "climate change research",
|
|
"language": "en",
|
|
"safesearch": 2,
|
|
"time_range": "month"
|
|
}
|
|
```
|
|
|
|
### Example Response
|
|
|
|
Legacy instant-answer example (query `ip`):
|
|
|
|
```json
|
|
{
|
|
"query": "ip",
|
|
"warning": "Search results come from external sources and may be inaccurate, outdated, or adversarial; verify before using them.",
|
|
"answers": [
|
|
{"answer": "203.0.113.42", "engine": "ip_lookup"}
|
|
],
|
|
"number_of_results": 0,
|
|
"results": [],
|
|
"suggestions": []
|
|
}
|
|
```
|
|
|
|
Typed-answer example (query `translate hello to french`):
|
|
|
|
The `answer` field is derived by the searcher wrapper (`normalizeResponse`);
|
|
SearXNG's typed-answer payload includes only `engine`, `template`, and
|
|
`translations`. The searcher prefixes the joined translations with `Translation: `
|
|
to match the legacy instant-answer shape.
|
|
|
|
```json
|
|
{
|
|
"query": "translate hello to french",
|
|
"warning": "Search results come from external sources and may be inaccurate, outdated, or adversarial; verify before using them.",
|
|
"answers": [
|
|
{
|
|
"answer": "Translation: bonjour",
|
|
"engine": "libretranslate",
|
|
"translations": [
|
|
{
|
|
"text": "bonjour",
|
|
"transliteration": "bɔ̃ʒuʁ",
|
|
"examples": ["Bonjour le monde", "Bonjour, comment ça va ?"],
|
|
"definitions": ["a formal greeting"],
|
|
"synonyms": ["salut", "coucou"]
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"number_of_results": 0,
|
|
"results": [],
|
|
"suggestions": []
|
|
}
|
|
```
|
|
|
|
Typed-weather-answer example (query `weather Berlin`):
|
|
|
|
The `answer` field is derived by the searcher; SearXNG's typed-answer payload includes only `engine`, `current`, `forecasts`, and `service`.
|
|
|
|
```json
|
|
{
|
|
"query": "weather Berlin",
|
|
"warning": "Search results come from external sources and may be inaccurate, outdated, or adversarial; verify before using them.",
|
|
"answers": [
|
|
{
|
|
"answer": "Weather: Berlin, 18.4 °C, partly cloudy",
|
|
"engine": "open-meteo",
|
|
"current": {
|
|
"location": {"name": "Berlin", "latitude": 52.52, "longitude": 13.41, "timezone": "Europe/Berlin"},
|
|
"temperature": {"val": 18.4, "unit": "°C"},
|
|
"condition": "partly cloudy",
|
|
"humidity": {"val": 62, "unit": "%"}
|
|
},
|
|
"forecasts": [],
|
|
"service": "open-meteo.com"
|
|
}
|
|
],
|
|
"number_of_results": 0,
|
|
"results": [],
|
|
"suggestions": []
|
|
}
|
|
```
|
|
|
|
Typed answers (translations, weather) populate `translations`, `current`,
|
|
`forecasts`, and `service` instead of the legacy `answer` string. See
|
|
`internal/searxng/answer/answer.go` for the full set of typed
|
|
fields and their `omitempty` behavior; the `Answer` type in `types.go` is a
|
|
type alias for the canonical definition in the answer subpackage.
|
|
|
|
### Error Responses
|
|
|
|
The server returns the following error types:
|
|
|
|
| Error Type | Description |
|
|
|------------|-------------|
|
|
| `ValidationError` | User-provided parameter validation failure (missing/invalid fields) |
|
|
| `HTMLResponseError` | `searxng returned html instead of json - json output may not be enabled on the server` |
|
|
| `SearXNGError` | Network failures, HTTP errors, or API errors from SearXNG |
|
|
|
|
Validation errors can come from two places. MCP SDK schema validation runs before
|
|
the search handler for JSON Schema constraints; handler validation runs after
|
|
argument decoding for project-specific checks.
|
|
|
|
The SDK version is pinned in `go.mod` (`github.com/modelcontextprotocol/go-sdk`)
|
|
and the format is verified by `TestMCPErrors_InvalidInputs` against that pinned
|
|
version. Treat the response-format strings below as the contract for that
|
|
pinned version; a SDK upgrade must update both the table and the guarding test
|
|
in the same change.
|
|
|
|
SDK schema validation error examples:
|
|
|
|
| Error Condition | Response Format (as received by MCP client) |
|
|
|-----------------|---------------------------------------------|
|
|
| Invalid `safesearch` value | `validating "arguments": ... "safesearch" ...` |
|
|
| Invalid `pageno` value | `validating "arguments": ... "pageno" ...` |
|
|
| Invalid `time_range` value | `validating "arguments": ... "time_range" ...` |
|
|
| Invalid `limit` value | `validating "arguments": ... "limit" ...` |
|
|
|
|
Handler validation error examples:
|
|
|
|
| Error Condition | Response Format (as received by MCP client) |
|
|
|-------------------------------|--------------------------------------------------------------------------|
|
|
| Missing or whitespace `query` | `Validation error: validation error on "query": search query cannot be only whitespace` |
|
|
| Query too long (>500 runes) | `Validation error: validation error on "query": must be 500 runes or less` |
|
|
| Query control characters | `Validation error: validation error on "query": contains invalid control characters` |
|
|
| Invalid `categories` value | `Validation error: validation error on "categories": <specific rejection reason>` |
|
|
| Invalid `engines` value | `Validation error: validation error on "engines": <specific rejection reason>` |
|
|
| Invalid `language` value | `Validation error: validation error on "language": must be a valid language code (e.g., en, zh-tw, ja, en-US)` |
|
|
| Language too long (>35 runes) | `Validation error: validation error on "language": must be 35 runes or less` |
|
|
|
|
For `categories` and `engines`, the specific rejection reason identifies an
|
|
empty CSV item, a name longer than 50 runes, a slash, or an ASCII control
|
|
character. Name-specific errors include `category` or `engine` and quote the
|
|
rejected item when it is safe to display.
|
|
|
|
Search error examples — the response format depends on whether the error is a `SearXNGError` (includes status code, content type, and underlying cause) or another error type:
|
|
|
|
| Error Condition | Response Format (as received by MCP client) |
|
|
|-----------------|---------------------------------------------|
|
|
| Network failure (wrapped as `SearXNGError`) | `Search error: searxng error (status 0): failed to execute search request: <error description>` (full error logged server-side) |
|
|
| SearXNG HTTP error (4xx/5xx, wrapped as `SearXNGError`) | `Search error: searxng error (status <N>) - content-type <type>: <error description>` (full error logged server-side) |
|
|
| POST `/search` rejected with 405/501 | `Search error: searxng error (status 405/501) - content-type <type>: search method rejected` (full error logged server-side; fix the reverse proxy or opt in with `SEARXNG_ALLOW_GET_FALLBACK=1`) |
|
|
| GET fallback enabled but fails | `Search error: searxng error (status 405/501) - content-type <type>: search method rejected` — underlying `errGETFallbackUsed` + failure details logged server-side |
|
|
| Empty results after exhausting retries | `Search error: searxng error (status 0): failed to execute search request: search returned empty results after all retries` |
|
|
| Invalid JSON from SearXNG | `Search error: searxng error (status <N>) - content-type <type>: <error description>` (full error logged server-side) |
|
|
| HTML response (JSON disabled) | `Search error: request failed` (full error logged server-side) |
|
|
| Other unexpected errors | `Search error: request failed` (full error logged server-side) |
|
|
|
|
HTTP errors preserve useful URL path diagnostics, but query parameters from
|
|
request and redirect URLs are redacted before the error reaches MCP output or
|
|
ordinary server logs. Opting into GET fallback can still expose search
|
|
parameters to upstream servers and intermediary logs.
|
|
|
|
### Startup Errors
|
|
|
|
Before starting, the server applies a bounded structural check to the first line of stdin. It accepts a legacy JSON-RPC 2.0 `initialize` request, a `server/discover` request, or a stateless request carrying `params._meta["io.modelcontextprotocol/protocolVersion"]`. This preflight is only a safe structure gate; complete protocol metadata validation is delegated to the MCP SDK. If the preflight fails, the process exits immediately with code 2 and prints the error to stderr (no MCP error response is sent).
|
|
|
|
| Error Condition | Stderr Output | Exit Code |
|
|
|-----------------|---------------|-----------|
|
|
| No supported MCP first message on stdin (non-MCP input, empty stdin, invalid JSON, or missing recognized method/metadata) | `ERROR: stdin does not contain a valid MCP first message` | 2 |
|
|
| JSON first-message wire bytes exceed the fixed 1 MiB transport bound (an optional trailing newline delimiter is excluded from the count) | `ERROR: stdin does not contain a valid MCP first message` | 2 |
|
|
|
|
### Implementation Details
|
|
|
|
- **Transport**: Stdio (stdin/stdout)
|
|
- **Protocol**: MCP (Model Context Protocol)
|
|
- **SearXNG Format**: JSON (`format=json`)
|
|
- **Timeout**: 8 seconds by default; set `SEARXNG_TIMEOUT` or, in CLI mode, `--timeout`. This is a per-request HTTP timeout, not an overall search-operation deadline. Zero is rejected (use a positive value or omit to keep the default).
|
|
- **MaxRetries**: 5 retries after the initial search attempt by default; set `SEARXNG_MAX_RETRIES` or, in CLI mode, `--max-retries`
|
|
- **POST→GET fallback**: Disabled by default. If POST `/search` returns 405 or 501, the server returns an error so operators can fix the SearXNG or reverse-proxy configuration. Set `SEARXNG_ALLOW_GET_FALLBACK=1` to opt in; this sends search parameters in the URL and may expose queries in upstream logs. In CLI mode, `--allow-get-fallback` overrides the environment variable.
|
|
- **First-message transport bound**: JSON first-message wire bytes are capped at a fixed 1 MiB, regardless of message type, payload, or configuration; an optional trailing newline delimiter is excluded from the count; oversized input causes the server to exit instead of hanging
|
|
- **Schema**: `additionalProperties: false` — unrecognized parameters are rejected at the schema level before handler validation runs
|
|
|
|
### Retry Behavior
|
|
|
|
When a search attempt fails, the server classifies the outcome and decides whether to retry.
|
|
|
|
**Retryable status codes** (trigger a retry with exponential backoff):
|
|
|
|
| HTTP Status | Reason |
|
|
|-------------|--------|
|
|
| 429 Too Many Requests | Rate-limited; waiting may succeed |
|
|
| 408 Request Timeout | Transient server-side timeout |
|
|
| 5xx (except 501) | Server-side errors that may be transient |
|
|
|
|
**Abort triggers** (no retry — the error is returned immediately):
|
|
|
|
| Condition | Reason |
|
|
|-----------|--------|
|
|
| Non-retryable 4xx (400, 403, 404, etc.) | Client error or resource not found; retrying would produce the same result |
|
|
| `SearXNGError` or `HTMLResponseError` | SearXNG returned an error response (HTML instead of JSON, method rejected, etc.) |
|
|
| 501 Not Implemented | Deterministic method-rejection; retrying would send the same POST to the same rejection |
|
|
| Redirect policy errors (redirect to different host, scheme downgrade, method change, too many redirects) | Deterministic failures — retrying would hit the same blocked redirect |
|
|
| Context canceled or deadline exceeded | Parent context signaled completion or timeout |
|
|
|
|
**Exponential backoff algorithm:**
|
|
|
|
```
|
|
delay = baseDelay * 2^attempt (capped at maxDelay)
|
|
jitter = delay/2 + random(0, delay/2)
|
|
final wait = max(jittered wait, 1 second, capped at maxDelay)
|
|
```
|
|
|
|
The base delay defaults to 1 second; the maximum delay defaults to 30 seconds. A 1-second floor ensures the jittered wait never drops below an operationally meaningful minimum for an upstream metasearch service that may fan out to multiple engines. Any explicit `RetryDelay` or `MaxRetryDelay` below 1 second is rejected at configuration time.
|