server

Documentation

Overview

Package server provides a high-level wrapper around mcp-go, making it easy to build MCP servers with typed tool registration, JSON-file-based tool definitions, and both SSE and Stdio transports.

Index

• func ArgBool(req mcpproto.CallToolRequest, key string) (bool, bool)
• func ArgFloat(req mcpproto.CallToolRequest, key string) (float64, bool)
• func ArgString(req mcpproto.CallToolRequest, key string) (string, bool)
• func ArgStringRequired(req mcpproto.CallToolRequest, key string) (string, *mcpproto.CallToolResult)
• func ResultError(msg string, err error) *mcpproto.CallToolResult
• func ResultErrorMsg(msg string) *mcpproto.CallToolResult
• func ResultJSON(v any) *mcpproto.CallToolResult
• func ResultText(text string) *mcpproto.CallToolResult
• type JSONSchema
• type JSONSchemaProperty
• type MCPServer
  • func NewMCPServer(srvName, srvVersion string) *MCPServer
  • func (s *MCPServer) AddTool(def ToolDefinition, handler ToolHandler) error
  • func (s *MCPServer) AddToolFromFile(path string, handler ToolHandler) error
  • func (s *MCPServer) AddToolFromJSON(data []byte, handler ToolHandler) error
  • func (s *MCPServer) AddToolFunc(name, description string, schema JSONSchema, handler ToolHandler) error
  • func (s *MCPServer) Shutdown(ctx context.Context) error
  • func (s *MCPServer) Start(ctx context.Context, addr string) error
  • func (s *MCPServer) StartStdio(ctx context.Context) error
• type ToolDefinition
  • func ParseToolDefinition(data []byte) (ToolDefinition, error)
  • func (d ToolDefinition) SchemaBytes() ([]byte, error)
  • func (d ToolDefinition) Validate() error
• type ToolHandler

Functions

func ArgBool

func ArgBool(req mcpproto.CallToolRequest, key string) (bool, bool)

ArgBool extracts a bool argument from a CallToolRequest by key.

func ArgFloat

func ArgFloat(req mcpproto.CallToolRequest, key string) (float64, bool)

ArgFloat extracts a float64 argument from a CallToolRequest by key.

func ArgString

func ArgString(req mcpproto.CallToolRequest, key string) (string, bool)

ArgString extracts a string argument from a CallToolRequest by key. Returns ("", false) if the key is absent or the value is not a string.

func ArgStringRequired

func ArgStringRequired(req mcpproto.CallToolRequest, key string) (string, *mcpproto.CallToolResult)

ArgStringRequired extracts a required string argument. Returns ("", errResult) if absent or wrong type — intended for use inside handlers that want early returns on missing args.

func ResultError

func ResultError(msg string, err error) *mcpproto.CallToolResult

ResultError wraps an error message into an MCP error result.

func ResultErrorMsg

func ResultErrorMsg(msg string) *mcpproto.CallToolResult

ResultErrorMsg wraps a plain string message into an MCP error result.

func ResultJSON

func ResultJSON(v any) *mcpproto.CallToolResult

ResultJSON serializes v to JSON and returns a structured MCP tool result. Falls back to a text result containing the raw JSON string if marshalling fails (so handlers never need to handle the error themselves).

func ResultText

func ResultText(text string) *mcpproto.CallToolResult

ResultText returns a plain-text MCP tool result.

Types

type JSONSchema

type JSONSchema struct {
	Type       string                        `json:"type"`
	Properties map[string]JSONSchemaProperty `json:"properties,omitempty"`
	Required   []string                      `json:"required,omitempty"`
}

JSONSchema is the input schema attached to an MCP tool. It follows the JSON Schema draft-07 "object" convention.

type JSONSchemaProperty

type JSONSchemaProperty struct {
	Type        string              `json:"type"`
	Description string              `json:"description,omitempty"`
	Enum        []string            `json:"enum,omitempty"`
	Items       *JSONSchemaProperty `json:"items,omitempty"` // for type=array
	Default     any                 `json:"default,omitempty"`
}

JSONSchemaProperty describes a single property inside a JSON Schema object.

type MCPServer

type MCPServer struct {
	// contains filtered or unexported fields
}

MCPServer exposes AI-agent tools via the Model Context Protocol.

func NewMCPServer

func NewMCPServer(srvName, srvVersion string) *MCPServer

NewMCPServer creates a new MCPServer with the given name and version.

srv := mcpserver.NewMCPServer("my-agent", "1.0.0")

func (*MCPServer) AddTool

func (s *MCPServer) AddTool(def ToolDefinition, handler ToolHandler) error

AddTool registers a tool using an explicit ToolDefinition and a handler. This is the lowest-level registration method — all other Add* methods ultimately call this one.

func (*MCPServer) AddToolFromFile

func (s *MCPServer) AddToolFromFile(path string, handler ToolHandler) error

AddToolFromFile loads a ToolDefinition from a JSON file on disk and registers it with the provided handler.

The JSON file must match the ToolDefinition struct:

{
  "name":        "search",
  "description": "Search the web",
  "schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Search query" }
    },
    "required": ["query"]
  }
}

func (*MCPServer) AddToolFromJSON

func (s *MCPServer) AddToolFromJSON(data []byte, handler ToolHandler) error

AddToolFromJSON parses a ToolDefinition from raw JSON bytes and registers the tool with the provided handler.

func (*MCPServer) AddToolFunc

func (s *MCPServer) AddToolFunc(name, description string, schema JSONSchema, handler ToolHandler) error

AddToolFunc registers a tool using individual fields plus a handler. schema must be a valid JSON Schema object (type/properties/required).

err := srv.AddToolFunc("search", "Search the web", schema, myHandler)

func (*MCPServer) Shutdown

func (s *MCPServer) Shutdown(ctx context.Context) error

Shutdown gracefully stops the SSE server. No-op if SSE was never started.

func (*MCPServer) Start

func (s *MCPServer) Start(ctx context.Context, addr string) error

Start starts the SSE (HTTP) transport on the given address (e.g. ":8080"). It blocks until the context is cancelled or a fatal error occurs.

func (*MCPServer) StartStdio

func (s *MCPServer) StartStdio(ctx context.Context) error

StartStdio starts the Stdio transport, reading from os.Stdin and writing to os.Stdout. Blocks until ctx is cancelled or an error occurs.

type ToolDefinition

type ToolDefinition struct {
	Name        string     `json:"name"`
	Description string     `json:"description"`
	Schema      JSONSchema `json:"schema"`
}

ToolDefinition is the full description of a tool that will be registered in the MCP server. It can be built in code or loaded from a JSON file.

func ParseToolDefinition

func ParseToolDefinition(data []byte) (ToolDefinition, error)

ParseToolDefinition deserializes a ToolDefinition from raw JSON bytes.

func (ToolDefinition) SchemaBytes

func (d ToolDefinition) SchemaBytes() ([]byte, error)

SchemaBytes returns the JSON-encoded schema, ready to be passed to mcpproto.NewToolWithRawSchema.

func (ToolDefinition) Validate

func (d ToolDefinition) Validate() error

Validate checks that the minimum required fields are present.

type ToolHandler

type ToolHandler func(ctx context.Context, req mcpproto.CallToolRequest) (*mcpproto.CallToolResult, error)

ToolHandler is the function signature for tool handlers. req carries the full MCP CallToolRequest (name + arguments).