searxng-mcp-go/docs/adr/004-mcp-stdin-env-only.md
xlion-bot-renovate[bot] 5eb419f9e1
fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0 (#542)
* fix(deps): update module github.com/modelcontextprotocol/go-sdk to v1.7.0

* fix: support MCP SDK v1.7 first messages

---------

Co-authored-by: xlion-bot-renovate[bot] <218815870+xlion-bot-renovate[bot]@users.noreply.github.com>
Co-authored-by: XLion <[email protected]>
2026-08-02 22:13:27 +08:00

72 lines
3.7 KiB
Markdown

# ADR-004: MCP Stdin Mode Is Detected From Input
- **Date**: 2026-04-19
- **Status**: Accepted
## Context
The searxng-mcp-go server operates in two modes:
1. **CLI mode**: Interactive command-line usage with flags like `--query`, `--json`, `--searxng-url`, etc.
2. **MCP stdin mode**: Headless operation communicating via stdio with MCP clients (e.g., Claude Desktop).
The server now detects MCP stdin mode by inspecting the first line of stdin for a supported MCP first message. The preflight accepts a legacy `initialize` request, a `server/discover` request, or a stateless request carrying `params._meta["io.modelcontextprotocol/protocolVersion"]`. It is a bounded structural gate; complete protocol metadata validation remains with the MCP SDK. If the process was launched with CLI arguments, it runs in CLI mode instead. This avoids treating normal command-line usage as MCP input and matches the actual startup flow:
## Detection Flow
1. CLI arguments are parsed first.
2. Any argument selects CLI mode, including positional queries, search flags, configuration flags such as `--searxng-url` or `--timeout`, `--debug`, `--help`, and `--version`.
3. Otherwise the process reads the first line of stdin and requires one of the supported MCP first-message shapes: legacy `initialize`, `server/discover`, or stateless protocol-version metadata in `params._meta["io.modelcontextprotocol/protocolVersion"]`.
4. If stdin does not look like MCP input, startup fails with an MCP-specific error.
## Decision
In MCP stdin mode, configuration comes from environment variables and MCP input, not from standalone CLI search flags. The supported environment variables are:
| Environment Variable | Purpose |
|----------------------|---------|
| `SEARXNG_URL` | SearXNG server URL |
| `DEBUG` | Set to `1` for debug logging |
| `SEARXNG_TIMEOUT` | Sets the search timeout (default 8s) |
| `SEARXNG_MAX_RETRIES` | Sets the max retry count (default 5) |
| `SEARXNG_ALLOW_GET_FALLBACK` | Set to `1` to opt in to POST→GET fallback |
`--help` and `--version` trigger CLI mode for informational output. Like every
other CLI flag, they are not accepted in MCP stdin mode.
The JSON first-message wire bytes have a fixed 1 MiB transport bound,
independent of the message type, payload, or configuration. An optional
trailing newline delimiter is excluded from the count. The preflight only
checks safe structure; the MCP SDK validates the complete protocol metadata
after startup.
### Detection Logic
```
MCP stdin mode = no command-line arguments
```
If stdin does not contain a supported MCP first message, the server exits with:
```
stdin does not contain a valid MCP first message
```
### CLI mode is unaffected
All existing CLI flags continue to work normally. Only the MCP stdin code path enforces the stdin protocol check.
## Consequences
### Positive
- **Clear configuration contract**: MCP users know exactly where to configure the server (environment variables only).
- **Predictable behavior**: No silent failures or ignored flags in MCP mode.
- **Better error messages**: Users who accidentally pass flags get an immediate, actionable error instead of silent misconfiguration.
- **Easier debugging**: When troubleshooting MCP issues, the configuration source is unambiguous.
- **Convention compliance**: Aligns with how other MCP servers are typically configured.
### Negative
- **Migration required**: Existing setups that pass CLI flags in MCP mode (e.g., `./searxng-mcp-go --searxng-url https://example.com`) must migrate to environment variables.
- **Less flexible**: Users who preferred CLI flags for MCP configuration lose that option. However, environment variables are equally powerful and more portable across MCP client launchers.