searxng-mcp-go/main.go
2026-10-30 00:08:19 +08:00

562 lines
17 KiB
Go

// Package main implements a SearXNG MCP server and CLI tool
// that provides web search capabilities via the SearXNG meta-search engine.
package main
import (
"errors"
"flag"
"fmt"
"io"
"log/slog"
"os"
"strconv"
"strings"
"time"
"searxng-mcp-go/internal/searxng"
)
var (
version = "v1.8.3"
commit = "none"
date = "unknown"
)
var (
errArgumentParseFailed = errors.New("failed to parse arguments")
errSearXNGURLRequiredCLI = errors.New(
"SearXNG_URL is required: set SEARXNG_URL environment variable or --searxng-url flag",
)
errSearXNGURLRequiredMCP = errors.New(
"SearXNG_URL is required: set SEARXNG_URL environment variable",
)
errUnexpectedFlagType = errors.New("registered search flag has unexpected type")
)
// Process exit codes. CLI failures exit with exitCodeCLIError; MCP mode
// failures (stdin validation, server startup/run) exit with exitCodeMCPError
// to match the documented contract in cli.go's "EXIT CODES" section.
const (
exitCodeCLIError = 1
exitCodeMCPError = 2
)
// CLI flag names that are referenced both at registration time
// (registerFlags) and by the data-driven config table (configSources), so the
// flag name is single-sourced instead of a duplicated literal.
const (
flagNameTimeout = "timeout"
flagNameMaxRetries = "max-retries"
flagNameAllowGETFallback = "allow-get-fallback"
)
// ============================================================================
// errParamDefaultNotInt is the sentinel error wrapped into the panic value
// raised when a ParamDef declares GoType "int" with a Default string that
// does not parse as an integer. Defaults are compile-time constants today,
// so a non-int default indicates a programming error; failing fast at
// flag-registration time is preferable to silently using 0 (which would be
// a surprise at runtime). Wrapping keeps the panic value errors.Is-checkable.
var errParamDefaultNotInt = errors.New("registerFlags: ParamDef has unparseable int default")
// CLIFlags holds parsed CLI flag values.
type CLIFlags struct {
Query string
JSON bool
Help bool
Version bool
SearXNGURL string
Language string
SafeSearch int
TimeRange string
Categories string
Engines string
Pageno *int
Limit *int
Debug bool
Timeout *time.Duration
MaxRetries *int
AllowGETFallback bool
AllowGETFallbackExplicit bool
}
type registeredFlags struct {
jsonOut *bool
help *bool
version *bool
searxngURL *string
debug *bool
timeout *time.Duration
maxRetries *int
allowGETFallback *bool
// Search parameters are registered generically from the shared
// searxng.SearchParams table and stored in searchFlags. Each value is
// either *string or *int matching the ParamDef.GoType.
searchFlags map[string]any
}
// parseArgs parses command-line arguments and returns the mode, flags, and positional arguments.
// Any supplied arguments route the process into CLI mode; otherwise the server runs in MCP mode.
// Flags are accepted anywhere before or after positional args, matching the current CLI behavior.
func parseArgs(args []string) (bool, *CLIFlags, []string, error) {
// Build the FlagSet first so we can use Lookup to determine whether a
// flag takes a value (via the IsBoolFlag interface) during the
// interleaved scan, avoiding the need to hard-code a parallel map.
fs, registered := registerFlags()
flagArgs, positionalArgs := extractPositionalArgs(args, fs)
err := fs.Parse(flagArgs)
if err != nil {
return false, nil, nil, fmt.Errorf("%w: %w", errArgumentParseFailed, err)
}
// Use flag.Visit with a symmetric data-driven pattern to populate *T
// optional fields. Only flags that were explicitly set get a non-nil
// pointer; unset flags remain nil so downstream code (getConfig) can
// distinguish "not provided" from "provided-but-equal-to-default".
opts := collectOptionalFlags(registered, fs)
searchVals, err := collectSearchFlagValues(registered)
if err != nil {
return false, nil, nil, err
}
limitPtr := opts.limit
if limitPtr == nil {
defaultLimit := searxng.DefaultResultLimit
limitPtr = &defaultLimit
}
flags := CLIFlags{
Query: searchVals.query,
JSON: *registered.jsonOut,
Help: *registered.help,
Version: *registered.version,
SearXNGURL: *registered.searxngURL,
Language: searchVals.language,
SafeSearch: searchVals.safeSearch,
TimeRange: searchVals.timeRange,
Categories: searchVals.categories,
Engines: searchVals.engines,
Pageno: opts.pageno,
Limit: limitPtr,
Debug: *registered.debug,
Timeout: opts.timeout,
MaxRetries: opts.maxRetries,
AllowGETFallback: *registered.allowGETFallback,
AllowGETFallbackExplicit: opts.allowGETFallbackExplicit,
}
isCLIMode := len(args) > 0 || flags.Help || flags.Version || flags.Query != "" || flags.JSON || len(positionalArgs) > 0
return isCLIMode, &flags, positionalArgs, nil
}
// optionalFlagValues captures the explicitly-set optional flags observed
// during flag.Visit, mirroring the "set vs unset" semantics downstream code
// relies on.
type optionalFlagValues struct {
pageno *int
limit *int
timeout *time.Duration
maxRetries *int
allowGETFallbackExplicit bool
}
// collectOptionalFlags visits the flags that were explicitly set and returns
// pointers to their values. Only explicitly-provided flags get a non-nil
// pointer; unset flags remain nil.
func collectOptionalFlags(registered registeredFlags, fs *flag.FlagSet) optionalFlagValues {
var vals optionalFlagValues
fs.Visit(func(f *flag.Flag) {
switch f.Name {
case "pageno":
if ptr, ok := registered.searchFlags["pageno"].(*int); ok {
vals.pageno = ptr
}
case "limit":
if ptr, ok := registered.searchFlags["limit"].(*int); ok {
vals.limit = ptr
}
case flagNameTimeout:
val := *registered.timeout
vals.timeout = &val
case flagNameMaxRetries:
val := *registered.maxRetries
vals.maxRetries = &val
case flagNameAllowGETFallback:
vals.allowGETFallbackExplicit = true
}
})
return vals
}
// searchFlagValues holds the typed values of the search parameters registered
// from the shared searxng.SearchParams table.
type searchFlagValues struct {
query string
language string
safeSearch int
timeRange string
categories string
engines string
}
// collectSearchFlagValues reads the typed pointer for each search parameter
// and dereferences it into a searchFlagValues struct.
func collectSearchFlagValues(registered registeredFlags) (searchFlagValues, error) {
queryPtr, err := searchFlagPtr[string](registered.searchFlags, "query")
if err != nil {
return searchFlagValues{}, err
}
languagePtr, err := searchFlagPtr[string](registered.searchFlags, "language")
if err != nil {
return searchFlagValues{}, err
}
safeSearchPtr, err := searchFlagPtr[int](registered.searchFlags, "safesearch")
if err != nil {
return searchFlagValues{}, err
}
timeRangePtr, err := searchFlagPtr[string](registered.searchFlags, "time_range")
if err != nil {
return searchFlagValues{}, err
}
categoriesPtr, err := searchFlagPtr[string](registered.searchFlags, "categories")
if err != nil {
return searchFlagValues{}, err
}
enginesPtr, err := searchFlagPtr[string](registered.searchFlags, "engines")
if err != nil {
return searchFlagValues{}, err
}
return searchFlagValues{
query: *queryPtr,
language: *languagePtr,
safeSearch: *safeSearchPtr,
timeRange: *timeRangePtr,
categories: *categoriesPtr,
engines: *enginesPtr,
}, nil
}
func registerFlags() (*flag.FlagSet, registeredFlags) {
fs := flag.NewFlagSet("searxng-mcp-go", flag.ContinueOnError)
fs.SetOutput(io.Discard)
fs.Usage = func() {}
reg := registeredFlags{
jsonOut: fs.Bool("json", false, "Output results as JSON (CLI mode)"),
help: fs.Bool("help", false, "Show this help message"),
version: fs.Bool("version", false, "Show version information"),
searxngURL: fs.String("searxng-url", "", "SearXNG URL (can also be set via SEARXNG_URL env var)"),
debug: fs.Bool("debug", false,
"Enable verbose HTTP request/response logging (can also be set via DEBUG=1 env var)"),
timeout: fs.Duration(
flagNameTimeout,
searxng.DefaultTimeout,
"HTTP client timeout (e.g., 8s); must be positive; overrides SEARXNG_TIMEOUT env var",
),
maxRetries: fs.Int(
flagNameMaxRetries,
searxng.DefaultMaxRetries,
"Max retries after initial search attempt; overrides SEARXNG_MAX_RETRIES env var",
),
allowGETFallback: fs.Bool(
flagNameAllowGETFallback,
false,
"Enable POST→GET fallback for 405/501 responses (CLI mode); overrides SEARXNG_ALLOW_GET_FALLBACK env var",
),
searchFlags: make(map[string]any),
}
// Register search parameters from the shared table.
// Note: "query" is also used as a positional argument in CLI mode.
for _, param := range searxng.SearchParams {
defaultVal, err := param.FlagDefault()
if err != nil {
panic(fmt.Errorf("%w (name=%q goType=%q default=%q): %w",
errParamDefaultNotInt, param.Name, param.GoType, param.Default, err))
}
switch val := defaultVal.(type) {
case string:
reg.searchFlags[param.Name] = fs.String(param.Name, val, param.Description)
case int:
reg.searchFlags[param.Name] = fs.Int(param.Name, val, param.Description)
default:
panic(fmt.Errorf("%w: %s has unexpected default type %T",
errUnexpectedFlagType, param.Name, val))
}
}
return fs, reg
}
func searchFlagPtr[T any](searchFlags map[string]any, name string) (*T, error) {
ptr, ok := searchFlags[name].(*T)
if !ok {
return nil, fmt.Errorf("%w: %s", errUnexpectedFlagType, name)
}
return ptr, nil
}
func extractPositionalArgs(args []string, fs *flag.FlagSet) ([]string, []string) {
// Interleaved scan: extract flag tokens (with their values) while
// collecting positional args. Flags are accepted before or after
// positional arguments and are passed to fs.Parse() afterwards.
flagArgs := make([]string, 0, len(args))
positionalArgs := make([]string, 0, len(args))
for idx := 0; idx < len(args); idx++ {
arg := args[idx]
if arg == "--" {
// Everything after -- is positional (standard convention).
positionalArgs = append(positionalArgs, args[idx+1:]...)
break
}
if !strings.HasPrefix(arg, "-") {
positionalArgs = append(positionalArgs, arg)
continue
}
flagArgs = append(flagArgs, arg)
// Consult the FlagSet to decide whether this flag expects a value.
// Bool flags (--help, --json, --version, --debug) do not consume
// the next token; all other flags do.
name := strings.TrimLeft(arg, "-")
if fl := fs.Lookup(name); fl != nil {
if _, isBool := fl.Value.(interface{ IsBoolFlag() bool }); !isBool {
if idx+1 < len(args) {
idx++
flagArgs = append(flagArgs, args[idx])
}
}
}
}
return flagArgs, positionalArgs
}
// ============================================================================
// Main Entry Point
// ============================================================================
// printError writes an error with ANSI color unless the environment requests plain output.
func printError(err error, out io.Writer) {
if os.Getenv("NO_COLOR") != "" || os.Getenv("TERM") == "dumb" {
fmt.Fprintf(out, "ERROR: %v\n", err) //nolint:errcheck // best-effort write to stderr
return
}
fmt.Fprintf(out, "\033[31mERROR: %v\033[0m\n", err) //nolint:errcheck // best-effort write to stderr
}
// printParseError writes an error message followed by CLI help text to w.
func printParseError(err error, w io.Writer) {
printError(err, w)
fmt.Fprintln(w) //nolint:errcheck // best-effort write to stderr
printCLIHelp(w)
}
func main() {
isCLIMode, flags, positionalArgs, err := parseArgs(os.Args[1:])
if err != nil {
printParseError(err, os.Stderr)
os.Exit(exitCodeCLIError)
}
// Enable debug mode via --debug flag or DEBUG=1 env var
debug := flags.Debug || os.Getenv("DEBUG") == "1"
if debug {
slog.SetLogLoggerLevel(slog.LevelDebug)
slog.Debug("debug mode enabled", "version", version)
slog.Warn("debug mode logs search queries and HTTP requests in plain text; avoid sensitive searches")
}
if isCLIMode {
err = runCLIMode(debug, flags, positionalArgs)
if err != nil {
slog.Error("CLI error", "error", err)
os.Exit(exitCodeCLIError)
}
return
}
mcpStdin, err := prepareMCPStdin(os.Stdin)
if err != nil {
printError(err, os.Stderr)
os.Exit(exitCodeMCPError)
}
err = runMCPMode(debug, flags, mcpStdin)
if err != nil {
slog.Error("MCP server error", "error", err)
os.Exit(exitCodeMCPError)
}
}
// configSource represents one configurable setting with env-var fallback and
// CLI-flag override. Each source is a row in a single loop inside getConfig;
// adding a new configurable field means one new row, not branches in three
// places. The shared warn-and-ignore handler is warnInvalidConfigEntry.
type configSource[T any] struct {
envVar string
flagName string
getFlag func(*CLIFlags) *T
parseEnv func(string) (T, error)
setValue func(*searxng.Config, T) error
}
func (cs configSource[T]) apply(cfg *searxng.Config, flags *CLIFlags) error {
// Phase 1: environment variable.
if envStr, ok := os.LookupEnv(cs.envVar); ok {
val, err := cs.parseEnv(envStr)
if err != nil {
warnInvalidConfigEntry(cs.envVar, envStr, err)
} else {
err = cs.setValue(cfg, val)
if err != nil {
return fmt.Errorf("invalid %s value %q: %w", cs.envVar, envStr, err)
}
}
}
// Phase 2: CLI flag override (takes precedence over env var).
if ptr := cs.getFlag(flags); ptr != nil {
err := cs.setValue(cfg, *ptr)
if err != nil {
return fmt.Errorf("invalid --%s value: %w", cs.flagName, err)
}
}
return nil
}
func warnInvalidConfigEntry[T any](source string, value T, err error) {
slog.Warn("invalid configuration value from "+source+", ignoring",
"value", value, "error", err)
}
var errMustBe01 = errors.New("must be 0 or 1")
// intFromString parses an integer from an environment variable string.
// Negative values and values exceeding the maximum are validated by
// SetMaxRetries, which returns a hard error.
func intFromString(s string) (int, error) {
n, err := strconv.Atoi(s)
if err != nil {
return 0, err
}
return n, nil
}
// boolFromString parses a boolean from "1"/"0" environment variable string.
func boolFromString(s string) (bool, error) {
switch s {
case "1":
return true, nil
case "0":
return false, nil
default:
return false, errMustBe01
}
}
// configSources is the single loop table for getConfig. Each row wires one
// configurable setting: env var → parse → apply → flag override.
var configSources = []func(*searxng.Config, *CLIFlags) error{
configSource[time.Duration]{
envVar: "SEARXNG_TIMEOUT",
flagName: flagNameTimeout,
getFlag: func(f *CLIFlags) *time.Duration { return f.Timeout },
parseEnv: time.ParseDuration,
setValue: (*searxng.Config).SetTimeout,
}.apply,
configSource[int]{
envVar: "SEARXNG_MAX_RETRIES",
flagName: flagNameMaxRetries,
getFlag: func(f *CLIFlags) *int { return f.MaxRetries },
parseEnv: intFromString,
setValue: (*searxng.Config).SetMaxRetries,
}.apply,
configSource[bool]{
envVar: "SEARXNG_ALLOW_GET_FALLBACK",
flagName: flagNameAllowGETFallback,
getFlag: allowGetFallbackFlagPtr,
parseEnv: boolFromString,
setValue: func(cfg *searxng.Config, v bool) error {
cfg.AllowGETFallback = v
return nil
},
}.apply,
}
func allowGetFallbackFlagPtr(flags *CLIFlags) *bool {
if flags.AllowGETFallbackExplicit {
return &flags.AllowGETFallback
}
return nil
}
// getConfig builds a Config from defaults, env vars, and CLI flags.
// Precedence: default → env var → CLI flag override.
func getConfig(flags *CLIFlags, isCLIMode bool) (*searxng.Config, error) {
cfg := searxng.DefaultConfig()
// URL is handled separately because it is required and has no
// per-env-var setter (it is a plain string assignment).
searxngURL := flags.SearXNGURL
if searxngURL == "" {
searxngURL = os.Getenv("SEARXNG_URL")
}
if searxngURL == "" {
if isCLIMode {
return nil, errSearXNGURLRequiredCLI
}
return nil, errSearXNGURLRequiredMCP
}
cfg.SearXNGURL = searxngURL
// Apply the data-driven config sources (env → flag override).
var errs error
for _, apply := range configSources {
errs = errors.Join(errs, apply(cfg, flags))
}
if errs != nil {
return nil, errs
}
// Lightweight final validation. By this point each setter has already
// rejected invalid individual values, so Validate primarily serves as a
// cross-field consistency check (none today) and a safety net.
err := cfg.Validate()
if err != nil {
return nil, fmt.Errorf("invalid configuration: %w", err)
}
return cfg, nil
}