searxng-mcp-go/internal/searxng/params.go
xlion-bot-renovate[bot] 6e4c553a9e
chore(deps): update dependency go to v1.27.1 (#588)
* chore(deps): update dependency go to v1.27.1

* Fixed all lints; just verify passes.

Co-authored-by: xlionjuan <[email protected]>

* Fixed `.golangci.yml` paths→path; `just verify` passes.

Co-authored-by: xlionjuan <[email protected]>

* Parallelized golden & error-path tests; verify passes.

Co-authored-by: xlionjuan <[email protected]>

* Verify passes; HTTPClient/Logger nil set; exhaustruct covers Config.

Co-authored-by: xlionjuan <[email protected]>

---------

Co-authored-by: xlion-bot-renovate[bot] <218815870+xlion-bot-renovate[bot]@users.noreply.github.com>
Co-authored-by: opencode-agent[bot] <opencode-agent[bot]@users.noreply.github.com>
Co-authored-by: xlionjuan <[email protected]>
2026-09-06 23:14:09 +08:00

269 lines
8.5 KiB
Go

package searxng
import (
"errors"
"fmt"
"strconv"
"strings"
)
// ParamDef describes a single search parameter for use across CLI and MCP layers.
type ParamDef struct {
// Name is the parameter name (flag name, JSON key).
Name string
// GoType is the Go flag type: "string" or "int".
GoType string
// Default is the default value as a string.
Default string
// Description is a general description used as the flag description in
// go's flag package and as the JSON Schema description.
Description string
// CLIHelp is the help text suffix for the CLI --help output (right-hand
// column). It should include default indicators where appropriate.
CLIHelp string
// CLIType is the human-friendly type indicator for CLI help, e.g.
// "string", "LANG", "0-2", "N", "RANGE", "CAT", "ENG".
CLIType string
// MCPType is the JSON Schema type: "string", "integer", or "boolean".
MCPType string
// Nullable indicates that the MCP type allows null (union type).
Nullable bool
// Enum is an optional list of valid values for JSON Schema enum.
Enum []string
// Minimum is an optional JSON Schema minimum constraint.
Minimum *int
// Maximum is an optional JSON Schema maximum constraint.
Maximum *int
// MaxLength is an optional JSON Schema maxLength constraint for strings.
MaxLength *int
// Examples is an optional list of example values for JSON Schema examples.
Examples []string
// DefaultStr is the typed string default for the JSON Schema "default" keyword.
// Populate this when the GoType is "string" and a default exists.
DefaultStr *string
// DefaultInt is the typed integer default for the JSON Schema "default" keyword.
// Populate this when the GoType is "int" and a default exists.
DefaultInt *int
// Required indicates whether the parameter is required.
Required bool
}
var paramDefaultLanguage = ""
// errUnexpectedGoType is a sentinel error for FlagDefault when a ParamDef
// declares an unsupported GoType.
var errUnexpectedGoType = errors.New("unexpected GoType")
// cliHelpPadding is the minimum width reserved for the flag expression
// column in CLI help output, matching the CLI consumer's expectation.
const cliHelpPadding = 18
// Type-name constants shared by the ParamDef metadata table and FlagDefault
// so the canonical Go/JSON-schema types are single-sourced.
const (
goTypeString = "string"
goTypeInt = "int"
mcpTypeInteger = "integer"
)
// SearchParams is the canonical list of all search parameters used by both CLI
// and MCP layers. Adding or changing a parameter here propagates to flag
// registration, help text, and MCP schema generation automatically.
//
// The Minimum, Maximum, MaxLength, and DefaultInt fields reference the same
// package-level variables used by the runtime validators in validation.go,
// making schema/validator consistency structurally guaranteed. The Default
// string and Enum fields are still verified by drift tests in
// params_validation_drift_test.go.
var SearchParams = []ParamDef{
{
Name: "query", GoType: goTypeString, Default: "", Required: true,
Description: "Search query string",
CLIHelp: "Search query string (alternative to positional argument)",
CLIType: goTypeString,
MCPType: goTypeString,
MaxLength: &MaxQueryLength,
},
{
Name: "language", GoType: goTypeString, Default: "",
Description: fmt.Sprintf(
"Language code for results (e.g., en, zh-tw, ja). Maximum %d runes for the full value. "+
"Leave empty or pass \"auto\" to let SearXNG decide",
MaxLanguageLength,
),
// DefaultStr is set only for language because empty string is the
// semantically meaningful "auto-detect" default that schema-aware
// MCP clients should see. Other string params with Default: ""
// (time_range, categories, engines) represent "no filter" which
// is an absence of constraint, not an explicit default.
CLIHelp: fmt.Sprintf(
"Language code for results (e.g., en, zh-tw, ja) [max %d runes] [default: \"\"]",
MaxLanguageLength,
),
CLIType: "LANG",
MCPType: goTypeString,
MaxLength: &MaxLanguageLength,
DefaultStr: &paramDefaultLanguage,
},
{
Name: "safesearch", GoType: goTypeInt, Default: strconv.Itoa(MinSafeSearch),
Description: "SafeSearch level: 0=Off, 1=Moderate, 2=Strict",
CLIHelp: fmt.Sprintf("SafeSearch level: 0=Off, 1=Moderate, 2=Strict [default: %d]", MinSafeSearch),
CLIType: "0-2",
MCPType: mcpTypeInteger,
DefaultInt: &MinSafeSearch,
Minimum: &MinSafeSearch,
Maximum: &MaxSafeSearch,
},
{
Name: "time_range", GoType: goTypeString, Default: "",
Description: "Time range filter: " + strings.Join(ValidTimeRanges(), ", "),
CLIHelp: "Time range filter: " + strings.Join(ValidTimeRanges(), ", "),
CLIType: "RANGE",
MCPType: goTypeString,
// Enum is derived from ValidTimeRanges() plus the empty
// string, which means "no time restriction" and is short-circuited
// by validateTimeRange.
Enum: append([]string{""}, ValidTimeRanges()...),
},
{
Name: "categories", GoType: goTypeString, Default: "",
Description: fmt.Sprintf(
`Comma-separated list of SearXNG categories (CSV format). `+
`Common values: general, news, images, videos, music, files, map, social media, science, it. `+
`"social media" is a single category (with a space); pass it as "social media" in CSV, not "social,media". `+
`Unknown categories are silently ignored by SearXNG. `+
`Maximum %d UTF-8 bytes for the full string.`,
MaxCSVInputBytes,
),
CLIHelp: fmt.Sprintf(
"Comma-separated list of categories to search [max %d bytes]",
MaxCSVInputBytes,
),
CLIType: "CAT",
MCPType: goTypeString,
Examples: []string{"general", "news", "social media", "images,videos"},
},
{
Name: "engines", GoType: goTypeString, Default: "",
Description: fmt.Sprintf(
`Comma-separated list of SearXNG engine names. Common engines: google, bing, duckduckgo. `+
`Maximum %d UTF-8 bytes for the full string.`,
MaxCSVInputBytes,
),
CLIHelp: fmt.Sprintf(
"Comma-separated list of search engines to use [max %d bytes]",
MaxCSVInputBytes,
),
CLIType: "ENG",
MCPType: goTypeString,
Examples: []string{"google", "bing", "duckduckgo"},
},
{
Name: "pageno", GoType: goTypeInt, Default: strconv.Itoa(MinPageno),
Description: "Page number for pagination",
CLIHelp: fmt.Sprintf("Page number for pagination [default: %d]", MinPageno),
CLIType: "N",
MCPType: mcpTypeInteger,
Nullable: true,
DefaultInt: &MinPageno,
Minimum: &MinPageno,
},
{
Name: "limit", GoType: goTypeInt, Default: strconv.Itoa(DefaultResultLimit),
Description: fmt.Sprintf("Maximum number of results to return (%d-%d)", MinResultLimit, MaxResultLimit),
CLIHelp: fmt.Sprintf(
"Maximum number of results to return (%d-%d) [default: %d]",
MinResultLimit, MaxResultLimit, DefaultResultLimit,
),
CLIType: "N",
MCPType: mcpTypeInteger,
DefaultInt: &DefaultResultLimit,
Minimum: &MinResultLimit,
Maximum: &MaxResultLimit,
},
}
// JSONSchema returns the JSON Schema property map for this parameter.
func (p ParamDef) JSONSchema() map[string]any {
prop := map[string]any{
"type": p.MCPType,
}
if p.Description != "" {
prop["description"] = p.Description
}
if p.Enum != nil {
enum := make([]string, len(p.Enum))
copy(enum, p.Enum)
prop["enum"] = enum
}
if p.Minimum != nil {
prop["minimum"] = *p.Minimum
}
if p.Maximum != nil {
prop["maximum"] = *p.Maximum
}
if p.MaxLength != nil {
prop["maxLength"] = *p.MaxLength
}
if len(p.Examples) > 0 {
examples := make([]string, len(p.Examples))
copy(examples, p.Examples)
prop["examples"] = examples
}
if p.DefaultStr != nil {
prop["default"] = *p.DefaultStr
} else if p.DefaultInt != nil {
prop["default"] = *p.DefaultInt
}
if p.Nullable {
prop["type"] = []string{"null", p.MCPType}
}
return prop
}
// FlagDefault returns the parsed default value for use with Go's flag package.
// The returned type matches the ParamDef.GoType: string or int.
// An unparseable int default is treated as a programming error and reported.
func (p ParamDef) FlagDefault() (any, error) {
switch p.GoType {
case goTypeString:
return p.Default, nil
case goTypeInt:
return strconv.Atoi(p.Default)
default:
return nil, fmt.Errorf("%w %q for param %q", errUnexpectedGoType, p.GoType, p.Name)
}
}
// CLIHelpLine returns the formatted CLI help line for this parameter.
func (p ParamDef) CLIHelpLine() string {
flagExpr := "--" + p.Name + " " + p.CLIType
padding := max(cliHelpPadding-len(flagExpr), 1)
return fmt.Sprintf(" %s%s%s", flagExpr, strings.Repeat(" ", padding), p.CLIHelp)
}