mcpargs

Documentation

Overview

Package mcpargs provides utilities for working with argument marshaling and unmarshaling in MCP (Multipurpose Control Protocol) tools. It simplifies the process of converting between Go structs and MCP tool options/arguments.

The package offers two main capabilities:

1. Marshaling Go structs to MCP tool options for tool definition:

• Use the Marshal function to convert a struct into MCP tool options
• Use NewTool as a convenient wrapper around mcp.NewTool for automatic marshaling
• Implement the Marshaler interface for custom type handling
• Fields are automatically converted from CamelCase to snake_case
• Supported struct tags:
• mcp_desc: Required. Provides field description
• mcp_required: Optional. Set to "true" if the field is required
• mcp_enum: Optional. For string fields, comma-separated list of allowed values

2. Unmarshaling MCP arguments back to Go structs:

• Use the Unmarshal function to populate a struct from an arguments map
• Implement the Unmarshaler interface for custom unmarshaling logic
• Automatic type conversions between common Go types

Example usage:

// Define a struct with appropriate tags
type UserArgs struct {
  UserID    string `mcp_desc:"The ID or username of the user" mcp_required:"false"`
  MaxItems  int    `mcp_desc:"Maximum number of items to return" mcp_required:"false"`
  SortOrder string `mcp_desc:"Sort order for results" mcp_enum:"asc,desc"`
}

// For defining a tool:
func NewUserTool() mcp.Tool {
  return mcpargs.NewTool("get_user", UserArgs{},
    mcp.WithDescription("Get information about a user"))
}

// Or using Marshal directly:
opts, err := mcpargs.Marshal(UserArgs{})
tool := mcp.NewTool("get_user",
  append([]mcp.ToolOption{mcp.WithDescription("...")}, opts...)...)

// For handling tool invocation:
func handleUser(args map[string]any) (any, error) {
  var userArgs UserArgs
  if err := mcpargs.Unmarshal(args, &userArgs); err != nil {
    return nil, err
  }
  // Use userArgs...
}

// For custom type handling, implement Marshaler and/or Unmarshaler:
type CustomType string

func (c CustomType) Marshal() mcpargs.MCPType {
  return mcpargs.TypeString
}

func (c *CustomType) Unmarshal(v any) error {
  str, ok := v.(string)
  if !ok {
    return fmt.Errorf("expected string, got %T", v)
  }
  *c = CustomType(str)
  return nil
}

Index

• Variables
• func Marshal(v any) ([]mcp.ToolOption, error)
• func NewTool(name string, v any, opts ...mcp.ToolOption) mcp.Tool
• func Unmarshal(arguments map[string]any, v any) error
• type ID
  • func (id ID) IsZero() bool
  • func (ID) Marshal() MCPType
  • func (id *ID) Unmarshal(v any) error
  • func (id ID) Value() any
• type MCPType
• type Marshaler
• type OptionalBool
  • func (OptionalBool) Marshal() MCPType
  • func (o OptionalBool) Ptr() *bool
  • func (o *OptionalBool) Unmarshal(v any) error
• type Unmarshaler

Variables

var ErrMarshalArguments = errors.New("failed to marshal arguments")

var ErrUnmarshalArguments = fmt.Errorf("failed to unmarshal arguments")

Functions

func Marshal

func Marshal(v any) ([]mcp.ToolOption, error)

Marshal accepts a struct and returns a slice of MCP tool options based on the struct's fields and tags. Supported fields are string, boolean, int, and float, as well as fields implementing the MCPTyper interface.

Required tags:

• `mcp_desc`: Describes the field and is required.
• `mcp_required`: Indicates if the field is required.
• `mcp_enum`: Specifies allowed values for a string field in a comma-separated list.

func NewTool

func NewTool(name string, v any, opts ...mcp.ToolOption) mcp.Tool

NewTool is a wrapper around mcp.NewTool that automatically marshals the struct to MCP tool options. It panics if the marshaling fails.

func Unmarshal

func Unmarshal(arguments map[string]any, v any) error

Unmarshal populates the struct pointed to by v with values from the arguments map. Field names in the struct are converted to snake_case to match keys in the arguments map.

Types

type ID

type ID struct {
	String  string
	Integer int
}

ID is a type that can represent an ID either as a string or an integer. It implements the Unmarshaler interface to unmarshal from either string or int types.

func (ID) IsZero

func (id ID) IsZero() bool

IsZero returns true if the ID is zero (both String and Integer are zero).

func (ID) Marshal

func (ID) Marshal() MCPType

Marshal implements the Marshaler interface.

func (*ID) Unmarshal

func (id *ID) Unmarshal(v any) error

Unmarshal sets the ID value from a string or integer. It implements the Unmarshaler interface.

func (ID) Value

func (id ID) Value() any

Value returns either the integer or the string value of the ID.

type MCPType

type MCPType int

MCPType specifies which MCP type a field should be mapped to.

const (
	TypeString MCPType = iota
	TypeNumber
	TypeBoolean
)

type Marshaler

type Marshaler interface {
	Marshal() MCPType
}

Marshaler is an interface for types that can return their MCPType. This allows the type to be identified without requiring knowledge of the specific type. In particular, it allows MCP tool parameters to work with composite types. Typically used in combination with the Unmarshaler interface.

type OptionalBool

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

OptionalBool is an optional boolean type. It supports three states: true, false, and "not set". The zero value is "not set".

func (OptionalBool) Marshal

func (OptionalBool) Marshal() MCPType

func (OptionalBool) Ptr

func (o OptionalBool) Ptr() *bool

func (*OptionalBool) Unmarshal

func (o *OptionalBool) Unmarshal(v any) error

Unmarshal sets the OptionalBool value from a string or bool.

type Unmarshaler

type Unmarshaler interface {
	Unmarshal(v any) error
}

Unmarshaler is the interface implemented by types that can unmarshal an MCP argument themselves. Typically used in combination with the Marshaler interface.