mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-17 04:17:51 +00:00
* 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]>
269 lines
8.5 KiB
Go
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: ¶mDefaultLanguage,
|
|
},
|
|
{
|
|
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)
|
|
}
|