searxng-mcp-go/docs/INSTALL.md
XLion d6cf967473
fix: redact search parameters in HTTP errors (#577)
* fix: redact search parameters in HTTP errors

* docs: describe HTTP error URL redaction
2026-08-12 23:57:32 +08:00

241 lines
10 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Installation and Configuration Guide
## User Installation
### Homebrew (Linux, recommended)
```bash
brew install --cask xlionjuan/tap/searxng-mcp-go
```
*Currently supports Linux only (x86_64 and arm64). macOS is not yet supported.*
After installation, find the binary's absolute path — MCP clients often don't inherit your shell PATH:
```bash
which searxng-mcp-go
```
### Manual (Download from GitHub Releases)
1. Visit the [Releases page](https://github.com/xlionjuan/searxng-mcp-go/releases)
2. Download the tarball matching your architecture:
- Linux amd64: `searxng-mcp-go_v<VERSION>_linux_amd64.tar.zst`
- Linux arm64: `searxng-mcp-go_v<VERSION>_linux_arm64.tar.zst`
3. Extract and install:
```bash
tar --zstd -xvf searxng-mcp-go_v<VERSION>_linux_amd64.tar.zst
mkdir -p ~/.local/bin && mv searxng-mcp-go ~/.local/bin/
```
### Verify Installation
```bash
searxng-mcp-go --version
```
---
## Configuration
### SearXNG Instance
A SearXNG instance URL is **required** — there is no default. Set it via the `SEARXNG_URL` environment variable or `--searxng-url` CLI flag.
```bash
export SEARXNG_URL=https://your-searxng-instance.example.com
```
> **Warning:** Using `http://` for a non-private SearXNG host triggers a non-suppressible warning on every invocation: *"Using HTTP for non-private host. Search queries may be transmitted in clear text. Search results could be intercepted and modified by a MITM attacker."*
>
> A host is considered private only if it matches one of the following RFC-grounded criteria (see [ADR-003](https://github.com/xlionjuan/searxng-mcp-go/blob/main/docs/adr/003-http-warning-for-non-private-hosts.md)):
> - Hostname: `localhost` or any subdomain of `localhost` (e.g., `something.localhost`)
> - IPv4 address in: `0.0.0.0/8`, `10.0.0.0/8`, `100.64.0.0/10`, `127.0.0.0/8`, `169.254.0.0/16`, `172.16.0.0/12`, `192.0.0.0/24`, `192.0.2.0/24`, `192.88.99.0/24`, `192.168.0.0/16`, `198.18.0.0/15`, `198.51.100.0/24`, `203.0.113.0/24`, `224.0.0.0/4`, `255.255.255.255/32`
> - IPv6 address in: `::`, `::1`, `fc00::/7`, `fe80::/10`, `ff00::/8`
>
> Prefer HTTPS unless the SearXNG instance is on a private/local network.
>
> **Note:** The warning suppression is based on syntactic host matching only and does not imply confidentiality for cleartext HTTP.
### Max Retries
The default retry count is 5 retries after the initial search attempt. Set `SEARXNG_MAX_RETRIES` to a non-negative integer (maximum 20); in CLI mode, `--max-retries` overrides the environment variable. Use `--max-retries=0` to disable retries in CLI mode.
### Timeout
The default per-request HTTP timeout is 8 seconds. Set `SEARXNG_TIMEOUT` to a Go duration such as `8s`; in CLI mode, `--timeout` overrides the environment variable. The timeout applies to each individual HTTP request attempt, not to the overall search operation including retries. Zero is rejected (use a positive value or omit to keep the default).
### HTTP Proxy
The server honours the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables (and their lowercase equivalents). When running behind a corporate or egress proxy, set these variables in the environment:
```bash
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
export NO_PROXY=localhost,127.0.0.1,.internal.example.com
```
These are cached after the first proxy evaluation; changing them at runtime has no effect.
In MCP client configuration, add the proxy variables to the `env` block:
```json
{
"mcpServers": {
"searxng": {
"command": "/home/linuxbrew/.linuxbrew/bin/searxng-mcp-go",
"env": {
"SEARXNG_URL": "https://your-searxng-instance.example.com",
"HTTP_PROXY": "http://proxy.example.com:8080",
"HTTPS_PROXY": "http://proxy.example.com:8080",
"NO_PROXY": "localhost,127.0.0.1"
}
}
}
}
```
### POST to GET Fallback
Search requests use POST by default. If POST `/search` returns
`405 Method Not Allowed` or `501 Not Implemented`, the server returns an
actionable error by default instead of silently retrying with GET.
Set `SEARXNG_ALLOW_GET_FALLBACK=1` only when you need compatibility with a
deployment that rejects POST and you accept the risk: GET sends search
parameters in the URL, so queries may be recorded by SearXNG, reverse proxies,
CDNs, or access logs. When enabled, the server logs a warning on startup and
again whenever the fallback is used. In CLI mode, `--allow-get-fallback`
overrides the environment variable.
### Invalid Environment Variable Values
`SEARXNG_TIMEOUT`, `SEARXNG_MAX_RETRIES`, and
`SEARXNG_ALLOW_GET_FALLBACK` accept fixed formats (a Go duration, an
integer in the range 0–20, and `0`/`1`, respectively). When a value is set to
something the server cannot parse — for example `SEARXNG_TIMEOUT=abc`,
`SEARXNG_MAX_RETRIES=abc`, or `SEARXNG_ALLOW_GET_FALLBACK=true` — the server
writes a warning line to stderr that names the offending variable and value,
and then the server falls back to whichever value takes precedence:
if a corresponding CLI flag is set (e.g. `--timeout 30s`,
`--max-retries 10`, `--allow-get-fallback`), that value is used;
otherwise the built-in default is used. The process
**continues running** and does not exit. In MCP stdio mode, most MCP clients do
not surface the stderr stream, so end users typically do not see the warning at
all.
Values that parse successfully but fall outside the documented range (for
example `SEARXNG_MAX_RETRIES=-1`) are **not** treated this way — they are
rejected as a hard startup error, as described below.
If you need strict validation (for example in CI), prefer the
`--timeout` and `--max-retries` CLI flags instead of the environment
variables. Invalid CLI values follow two distinct paths depending on
where they are rejected:
- **Flag parse errors** — values the command-line parser cannot
interpret at all (for example `--timeout=abc`) are caught before
any search flow runs. The error is reported on stderr, the CLI help
is printed, and the process exits with a non-zero status. No search
request is issued.
- **Semantic validation errors** — values that parse successfully but
fall outside the documented range (for example `--max-retries=-1`,
or a value above the maximum allowed retries) are accepted by the
parser and only fail later, during configuration validation inside
the CLI search flow. The error is reported on stderr, the process
exits with a non-zero status, and **no CLI help is printed**. No
search request is issued.
When these values are set via environment variables (e.g.,
`SEARXNG_TIMEOUT=0`), they are also **rejected with a clear error**
— the server exits on startup to prevent silent misconfiguration.
> **Note:** If you provide a custom `HTTPClient` (for example, when using the library programmatically), the `Timeout` setting is ignored and the provided client is used as-is. Either set `Timeout` or supply a custom `HTTPClient`, not both.
---
## MCP Server Configuration
### Basic Execution
In MCP mode, `searxng-mcp-go` is meant to be launched by an MCP client host (such as an AI agent framework), not run directly in a terminal. The client provides the configured environment variables, starts the process, and sends an MCP JSON-RPC first message on stdin before tool calls are available. The first message may be a legacy `initialize` request, a `server/discover` request, or a stateless request carrying `params._meta["io.modelcontextprotocol/protocolVersion"]`.
The server uses stdio transport, meaning it communicates via stdin/stdout after the MCP client starts it.
#### Stdin Validation
The server reads the first line of stdin and performs a bounded structural MCP check before starting. It accepts the legacy JSON-RPC 2.0 `initialize` request, the `server/discover` request, or a stateless request carrying `params._meta["io.modelcontextprotocol/protocolVersion"]`. This preflight is only a safe structure gate; the MCP SDK performs complete protocol metadata validation:
- **Invalid input** (non-MCP input, empty stdin, malformed JSON, or no supported first-message shape): the server prints `ERROR: stdin does not contain a valid MCP first message` to stderr and exits with code 2.
- **Oversized input** (the JSON first-message wire bytes exceed the fixed 1 MiB transport bound; an optional trailing newline delimiter is not counted): treated as invalid — same error and exit code 2.
MCP clients that correctly send any supported first message are not affected.
### MCP Client Configuration
Configure the MCP server by adding it to your client's `mcpServers`. Use the **absolute path** to the binary — MCP clients often don't inherit your shell PATH.
```bash
which searxng-mcp-go
```
```json
{
"mcpServers": {
"searxng": {
"command": "/home/linuxbrew/.linuxbrew/bin/searxng-mcp-go",
"env": {
"SEARXNG_URL": "https://your-searxng-instance.example.com",
"SEARXNG_TIMEOUT": "8s",
"SEARXNG_MAX_RETRIES": "5"
}
}
}
}
```
Add `"SEARXNG_ALLOW_GET_FALLBACK": "1"` only as a temporary compatibility
escape hatch for a deployment that rejects POST `/search`.
#### Debug Mode (opt-in, do not enable by default)
> **Warning:** Debug mode writes HTTP request and response details, including
> the full query text, to stderr in plain text. Do not enable it for production
> use, shared hosts, or any workload where queries may be sensitive.
To enable debug logging temporarily for troubleshooting, add `"DEBUG": "1"` to
the `env` block above. Remove it once the issue is diagnosed.
### CLI Mode Configuration
When running in CLI mode (with a query argument), command-line flags can be used directly:
```bash
# Custom SearXNG server via flag
searxng-mcp-go "query" --searxng-url=https://your-searxng-instance.example.com
# Debug mode via flag
searxng-mcp-go "query" --debug
# HTTP timeout and retry tuning via flags
searxng-mcp-go "query" --timeout=8s --max-retries=5
# GET fallback opt-in via flag
searxng-mcp-go "query" --allow-get-fallback
```
Set `NO_COLOR` to any non-empty value, or set `TERM=dumb`, to print errors
without ANSI color escape sequences.
> **Note:** Observable HTTP error messages preserve useful URL path diagnostics
> but redact URL query parameters to `[REDACTED]`. This applies to rejected
> redirects and failed GET fallback requests. Enabling GET fallback can still
> expose search parameters to upstream servers and intermediary logs.
---
## Related Documentation
- [README.md](../README.md) — Quick start and usage overview
- [MCP Tools Reference](MCP_TOOLS.md) — Full tool parameters and response format