mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-16 19:40:03 +00:00
562 lines
17 KiB
Go
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
|
|
}
|