mirror of
https://github.com/xlionjuan/searxng-mcp-go.git
synced 2026-11-16 19:40:03 +00:00
405 lines
12 KiB
Go
405 lines
12 KiB
Go
package main
|
|
|
|
import (
|
|
"bytes"
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"io"
|
|
"log/slog"
|
|
"os"
|
|
"os/signal"
|
|
"syscall"
|
|
|
|
"github.com/modelcontextprotocol/go-sdk/mcp"
|
|
|
|
"searxng-mcp-go/internal/searxng"
|
|
)
|
|
|
|
// buildSearchSchema generates the JSON Schema for the search tool input from
|
|
// the centralized SearchParams table.
|
|
func buildSearchSchema() (json.RawMessage, error) {
|
|
props := make(map[string]any)
|
|
|
|
var required []string
|
|
|
|
for _, p := range searxng.SearchParams {
|
|
props[p.Name] = p.JSONSchema()
|
|
|
|
if p.Required {
|
|
required = append(required, p.Name)
|
|
}
|
|
}
|
|
|
|
schema := map[string]any{
|
|
"type": "object",
|
|
"properties": props,
|
|
"additionalProperties": false,
|
|
}
|
|
if len(required) > 0 {
|
|
schema["required"] = required
|
|
}
|
|
|
|
data, err := json.Marshal(schema)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("marshal search schema: %w", err)
|
|
}
|
|
|
|
return json.RawMessage(data), nil
|
|
}
|
|
|
|
// buildToolDescription returns a concise tool-level description for the MCP search tool.
|
|
// Detailed parameter descriptions live in the structured inputSchema; this
|
|
// description provides context at the tool level only.
|
|
func buildToolDescription() string {
|
|
return "Search the web using SearXNG meta-search engine. " +
|
|
"Returns web results with titles, URLs, summaries, published dates, and engine source information."
|
|
}
|
|
|
|
// newSearchTool creates the search tool definition with annotations marking it
|
|
// as read-only and open-world, signaling to clients that it does not modify
|
|
// state and returns untrusted external content.
|
|
func newSearchTool(schema json.RawMessage) *mcp.Tool {
|
|
openWorldHint := true
|
|
|
|
return &mcp.Tool{
|
|
Name: "search",
|
|
Description: buildToolDescription(),
|
|
InputSchema: schema,
|
|
Annotations: &mcp.ToolAnnotations{
|
|
ReadOnlyHint: true,
|
|
OpenWorldHint: &openWorldHint,
|
|
},
|
|
}
|
|
}
|
|
|
|
// mcpFirstMessage is the JSON-RPC envelope of the first message an MCP client
|
|
// sends over stdin to start a session.
|
|
type mcpFirstMessage struct {
|
|
JSONRPC string `json:"jsonrpc"`
|
|
Method string `json:"method"`
|
|
Params json.RawMessage `json:"params"`
|
|
}
|
|
|
|
const (
|
|
// mcpFirstMessageMaxBytes is the fixed transport bound, in bytes, for the
|
|
// first newline-delimited JSON message read from stdin. The trailing
|
|
// newline delimiter is allowed in addition to this bound. It is deliberately
|
|
// a transport limit, independent of any search payload limits.
|
|
mcpFirstMessageMaxBytes = 1 << 20
|
|
|
|
// mcpFirstMessageReadChunkSize keeps the incremental preflight reader's
|
|
// buffer small while still allowing ordinary MCP messages to be read with
|
|
// few underlying calls.
|
|
mcpFirstMessageReadChunkSize = 32 << 10
|
|
|
|
// mcpFirstMessageMaxDelimiterBytes permits either an LF or CRLF delimiter
|
|
// in addition to the JSON transport bound.
|
|
mcpFirstMessageMaxDelimiterBytes = len("\r\n")
|
|
|
|
mcpMethodInitialize = "initialize"
|
|
mcpMethodDiscover = "server/discover"
|
|
|
|
// metaKeyProtocolVersion marks a request that uses the stateless MCP
|
|
// protocol introduced in 2026-07-28. The SDK validates the complete
|
|
// metadata object after this transport gate accepts the message.
|
|
metaKeyProtocolVersion = "io.modelcontextprotocol/protocolVersion"
|
|
)
|
|
|
|
var (
|
|
errInvalidMCPFirstMessage = errors.New("stdin does not contain a valid MCP first message")
|
|
errMCPFirstMessageTooLong = errors.New("MCP first message exceeds the transport limit")
|
|
errInvalidMCPFirstMessageReaderResult = errors.New("invalid MCP stdin reader result")
|
|
)
|
|
|
|
// prepareMCPStdin reads the first line of stdin to verify it starts a valid
|
|
// MCP session (legacy "initialize", "server/discover", or a stateless request
|
|
// carrying protocol metadata), preventing the MCP server from hanging when
|
|
// piped non-MCP input.
|
|
func prepareMCPStdin(stdin io.Reader) (io.Reader, error) {
|
|
firstLine, leftover, err := readFirstLine(stdin, mcpFirstMessageMaxBytes)
|
|
if err != nil || !isValidMCPFirstMessage(firstLine) {
|
|
return nil, errInvalidMCPFirstMessage
|
|
}
|
|
|
|
return io.MultiReader(
|
|
bytes.NewReader(firstLine),
|
|
bytes.NewReader(leftover),
|
|
stdin,
|
|
), nil
|
|
}
|
|
|
|
// readFirstLine incrementally reads through the first newline, retaining any
|
|
// bytes read after that newline as leftover. The reader never consumes more
|
|
// than maxBytes plus the longest supported delimiter (CRLF), so an oversized
|
|
// first line is rejected without buffering attacker-controlled input or
|
|
// allocating the entire transport bound up front. A line ending at EOF is
|
|
// accepted for JSON validation by the caller.
|
|
func readFirstLine(reader io.Reader, maxBytes int) ([]byte, []byte, error) {
|
|
if reader == nil || maxBytes < 1 {
|
|
return nil, nil, errMCPFirstMessageTooLong
|
|
}
|
|
|
|
// The fixed transport bound used by prepareMCPStdin makes this addition
|
|
// safe. Keep the helper defensive for direct tests and future callers.
|
|
maxInt := int(^uint(0) >> 1)
|
|
if maxBytes > maxInt-mcpFirstMessageMaxDelimiterBytes {
|
|
return nil, nil, errMCPFirstMessageTooLong
|
|
}
|
|
|
|
readLimit := maxBytes + mcpFirstMessageMaxDelimiterBytes
|
|
chunk := make([]byte, mcpFirstMessageReadChunkSize)
|
|
lineCapacity := min(maxBytes, len(chunk))
|
|
line := make([]byte, 0, lineCapacity)
|
|
|
|
consumed := 0
|
|
for consumed < readLimit {
|
|
readSize := min(len(chunk), readLimit-consumed)
|
|
|
|
nRead, readErr := reader.Read(chunk[:readSize])
|
|
if nRead < 0 || nRead > readSize {
|
|
return nil, nil, errInvalidMCPFirstMessageReaderResult
|
|
}
|
|
|
|
if nRead == 0 {
|
|
if readErr == nil {
|
|
return nil, nil, io.ErrNoProgress
|
|
}
|
|
|
|
return mcpFirstMessageReadError(line, readErr, maxBytes)
|
|
}
|
|
|
|
consumed += nRead
|
|
|
|
chunkLine, leftover, complete := consumeMCPFirstLineChunk(line, chunk[:nRead])
|
|
line = chunkLine
|
|
|
|
if complete {
|
|
return mcpFirstMessageLineResult(line, leftover, maxBytes)
|
|
}
|
|
|
|
if readErr != nil {
|
|
return mcpFirstMessageReadError(line, readErr, maxBytes)
|
|
}
|
|
}
|
|
|
|
return nil, nil, errMCPFirstMessageTooLong
|
|
}
|
|
|
|
func mcpFirstMessageReadError(line []byte, err error, maxBytes int) ([]byte, []byte, error) {
|
|
if errors.Is(err, io.EOF) {
|
|
return mcpFirstMessageLineResult(line, nil, maxBytes)
|
|
}
|
|
|
|
return nil, nil, err
|
|
}
|
|
|
|
func mcpFirstMessageLineResult(line, leftover []byte, maxBytes int) ([]byte, []byte, error) {
|
|
if mcpFirstMessagePayloadLength(line) > maxBytes {
|
|
return nil, nil, errMCPFirstMessageTooLong
|
|
}
|
|
|
|
return line, leftover, nil
|
|
}
|
|
|
|
func mcpFirstMessagePayloadLength(line []byte) int {
|
|
payloadLength := len(line)
|
|
if payloadLength == 0 || line[payloadLength-1] != '\n' {
|
|
return payloadLength
|
|
}
|
|
|
|
payloadLength--
|
|
if payloadLength > 0 && line[payloadLength-1] == '\r' {
|
|
payloadLength--
|
|
}
|
|
|
|
return payloadLength
|
|
}
|
|
|
|
func consumeMCPFirstLineChunk(line, data []byte) ([]byte, []byte, bool) {
|
|
newline := bytes.IndexByte(data, '\n')
|
|
if newline < 0 {
|
|
return append(line, data...), nil, false
|
|
}
|
|
|
|
line = append(line, data[:newline+1]...)
|
|
leftover := append([]byte(nil), data[newline+1:]...)
|
|
|
|
return line, leftover, true
|
|
}
|
|
|
|
// isValidMCPFirstMessage checks whether the given byte slice is a valid JSON-RPC
|
|
// 2.0 message that can start an MCP session: the legacy "initialize" handshake,
|
|
// the stateless "server/discover" RPC, or any request carrying the per-request
|
|
// protocol metadata. Full protocol validation remains the SDK's responsibility.
|
|
func isValidMCPFirstMessage(line []byte) bool {
|
|
if len(bytes.TrimSpace(line)) == 0 {
|
|
return false
|
|
}
|
|
|
|
var msg mcpFirstMessage
|
|
|
|
err := json.Unmarshal(line, &msg)
|
|
if err != nil {
|
|
return false
|
|
}
|
|
|
|
if msg.JSONRPC != "2.0" {
|
|
return false
|
|
}
|
|
|
|
if msg.Method == mcpMethodInitialize || msg.Method == mcpMethodDiscover {
|
|
return true
|
|
}
|
|
|
|
return msg.hasStatelessProtocolMeta()
|
|
}
|
|
|
|
// hasStatelessProtocolMeta reports whether the first message carries the
|
|
// stateless protocol-version metadata key. The SDK performs all further
|
|
// validation, including value type, supported version, and required peer
|
|
// capability metadata.
|
|
func (m mcpFirstMessage) hasStatelessProtocolMeta() bool {
|
|
if len(m.Params) == 0 {
|
|
return false
|
|
}
|
|
|
|
var params struct {
|
|
//nolint:tagliatelle // matches the wire key "_meta"
|
|
Meta map[string]json.RawMessage `json:"_meta"`
|
|
}
|
|
|
|
err := json.Unmarshal(m.Params, ¶ms)
|
|
if err != nil {
|
|
return false
|
|
}
|
|
|
|
_, ok := params.Meta[metaKeyProtocolVersion]
|
|
|
|
return ok
|
|
}
|
|
|
|
// runMCPMode starts the MCP stdio server, registers the search tool, and
|
|
// blocks until a signal (SIGINT/SIGTERM) is received or the server exits.
|
|
// It returns an error on failure so that main can handle exit codes and
|
|
// deferred cleanup (searcher.Close) runs correctly.
|
|
func runMCPMode(debug bool, flags *CLIFlags, stdin io.Reader) error {
|
|
cfg, err := getConfig(flags, false)
|
|
if err != nil {
|
|
return fmt.Errorf("configuration error: %w", err)
|
|
}
|
|
|
|
searcher, err := searxng.NewSearXNGSearcher(cfg, debug)
|
|
if err != nil {
|
|
return fmt.Errorf("failed to create searcher: %w", err)
|
|
}
|
|
|
|
defer func() { _ = searcher.Close() }() //nolint:errcheck // cleanup in defer; error is non-actionable
|
|
|
|
schema, err := buildSearchSchema()
|
|
if err != nil {
|
|
return fmt.Errorf("failed to build search schema: %w", err)
|
|
}
|
|
|
|
server := mcp.NewServer(&mcp.Implementation{
|
|
Name: "searxng-mcp-go",
|
|
Version: version,
|
|
}, nil)
|
|
|
|
mcp.AddTool(server, newSearchTool(schema), NewSearchToolHandler(searcher))
|
|
|
|
slog.Info("starting SearXNG MCP server")
|
|
|
|
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
|
|
defer stop()
|
|
|
|
err = server.Run(ctx, &mcp.IOTransport{
|
|
Reader: io.NopCloser(stdin),
|
|
Writer: os.Stdout,
|
|
MaxLineLength: 0, // Use the SDK's default frame limit.
|
|
})
|
|
if err != nil {
|
|
// SIGINT/SIGTERM cancels the context; a normal shutdown should
|
|
// not be reported as a server failure.
|
|
if errors.Is(err, context.Canceled) {
|
|
return nil
|
|
}
|
|
|
|
return fmt.Errorf("server failed: %w", err)
|
|
}
|
|
|
|
return nil
|
|
}
|
|
|
|
// searcher is the minimal interface the MCP handler needs from a search provider.
|
|
type searcher interface {
|
|
Search(ctx context.Context, args *searxng.SearchArgs) (*searxng.SearchResponse, error)
|
|
}
|
|
|
|
var _ searcher = (*searxng.SearXNGSearcher)(nil)
|
|
|
|
// NewSearchToolHandler creates an MCP tool handler function that performs SearXNG searches.
|
|
// It returns a function suitable for use as an mcp.ToolHandler, which validates the search
|
|
// arguments, executes the search, and returns the formatted results.
|
|
func NewSearchToolHandler(searcher searcher) func(
|
|
context.Context, *mcp.CallToolRequest, searxng.SearchArgs,
|
|
) (*mcp.CallToolResult, any, error) {
|
|
return func(ctx context.Context, _ *mcp.CallToolRequest, args searxng.SearchArgs) (*mcp.CallToolResult, any, error) {
|
|
normalized, err := prepareAndValidate(args)
|
|
if err != nil {
|
|
return mcpErrorResult("Validation error: " + err.Error()), nil, nil //nolint:nilerr // error in CallToolResult
|
|
}
|
|
|
|
return searchAndBuildResult(ctx, searcher, normalized)
|
|
}
|
|
}
|
|
|
|
// mcpErrorResult builds an MCP tool error result with the given text.
|
|
func mcpErrorResult(text string) *mcp.CallToolResult {
|
|
return &mcp.CallToolResult{
|
|
Content: []mcp.Content{
|
|
&mcp.TextContent{Text: text},
|
|
},
|
|
IsError: true,
|
|
}
|
|
}
|
|
|
|
// mcpSuccessResult builds an MCP tool success result from marshaled JSON bytes.
|
|
func mcpSuccessResult(data []byte) *mcp.CallToolResult {
|
|
return &mcp.CallToolResult{
|
|
Content: []mcp.Content{
|
|
&mcp.TextContent{Text: string(data)},
|
|
},
|
|
}
|
|
}
|
|
|
|
// prepareAndValidate applies defaults and validates search arguments.
|
|
func prepareAndValidate(args searxng.SearchArgs) (*searxng.SearchArgs, error) {
|
|
args.ApplyDefaults()
|
|
|
|
normalized, err := searxng.ValidateSearchArgs(&args)
|
|
if err != nil {
|
|
return nil, err
|
|
}
|
|
|
|
return normalized, nil
|
|
}
|
|
|
|
// searchAndBuildResult performs the search and builds the MCP result.
|
|
func searchAndBuildResult(ctx context.Context, s searcher, args *searxng.SearchArgs) (*mcp.CallToolResult, any, error) {
|
|
resp, err := s.Search(ctx, args)
|
|
if err != nil {
|
|
slog.Error("search failed", "error", err)
|
|
|
|
if searxngErr, ok := errors.AsType[*searxng.SearXNGError](err); ok {
|
|
return mcpErrorResult("Search error: " + searxngErr.Error()), nil, nil
|
|
}
|
|
|
|
return mcpErrorResult("Search error: request failed"), nil, nil
|
|
}
|
|
|
|
jsonBytes, _ := json.Marshal(resp) //nolint:errcheck,errchkjson // all concrete types; cannot fail
|
|
|
|
return mcpSuccessResult(jsonBytes), nil, nil
|
|
}
|