mcp

Documentation

Overview

Package mcp provides a minimal Model Context Protocol server implementation for building AI tool integrations with Claude Desktop and other MCP clients.

Index

• Constants
• Variables
• type Capabilities
• type ContentBlock
  • func NewTextContent(text string) ContentBlock
• type Implementation
• type InitializeParams
• type InitializeResult
• type InputSchema
  • func NewObjectSchema(properties map[string]Property, required []string) InputSchema
• type Property
  • func NewBooleanProperty(description string) Property
  • func NewNumberProperty(description string) Property
  • func NewStringProperty(description string) Property
• type Request
• type Response
  • func NewErrorResponse(id json.RawMessage, code int, message string) Response
  • func NewResponse(id json.RawMessage, result any) Response
• type ResponseError
• type Server
  • func NewServer(name, version string) *Server
  • func NewServerWithIO(name, version string, reader io.Reader, writer io.Writer) *Server
  • func (a *Server) Name() string
  • func (a *Server) RegisterTool(tool Tool)
  • func (a *Server) Serve(ctx context.Context) error
  • func (a *Server) Tools() []Tool
  • func (a *Server) Version() string
• type Tool
  • func NewTool(name, description string, schema InputSchema, handler ToolHandler) Tool
• type ToolDefinition
• type ToolHandler
• type ToolsCallParams
• type ToolsCallResult
• type ToolsCapability
• type ToolsListResult

Constants

const (
	ErrorCodeInternal       = -32603
	ErrorCodeInvalidParams  = -32602
	ErrorCodeInvalidRequest = -32600
	ErrorCodeMethodNotFound = -32601
	ErrorCodeParse          = -32700
)

JSON-RPC 2.0 standard error codes.

Variables

var (
	ErrMCPInvalidToolParams = errors.New("invalid tool parameters")
	ErrMCPNotInitialized    = errors.New("server not initialized")
	ErrMCPToolNotFound      = errors.New("tool not found")
	ErrMCPTransportClosed   = errors.New("transport closed")
)

MCP-specific errors.

Types

type Capabilities

type Capabilities struct {
	Tools *ToolsCapability `json:"tools,omitempty"`
}

Capabilities represents MCP capabilities.

type ContentBlock

type ContentBlock struct {
	Type string `json:"type"`
	Text string `json:"text,omitempty"`
}

ContentBlock represents a content block in tool results.

func NewTextContent

func NewTextContent(text string) ContentBlock

NewTextContent creates a text content block.

type Implementation

type Implementation struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

Implementation represents server or client implementation info.

type InitializeParams

type InitializeParams struct {
	ProtocolVersion string         `json:"protocolVersion"`
	Capabilities    Capabilities   `json:"capabilities"`
	ClientInfo      Implementation `json:"clientInfo"`
}

InitializeParams represents the parameters for the initialize method.

type InitializeResult

type InitializeResult struct {
	ProtocolVersion string         `json:"protocolVersion"`
	Capabilities    Capabilities   `json:"capabilities"`
	ServerInfo      Implementation `json:"serverInfo"`
}

InitializeResult represents the result of the initialize method.

type InputSchema

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

InputSchema represents the JSON Schema for tool input.

func NewObjectSchema

func NewObjectSchema(properties map[string]Property, required []string) InputSchema

NewObjectSchema creates an object input schema.

type Property

type Property struct {
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
}

Property represents a JSON Schema property.

func NewBooleanProperty

func NewBooleanProperty(description string) Property

NewBooleanProperty creates a boolean property.

func NewNumberProperty

func NewNumberProperty(description string) Property

NewNumberProperty creates a number property.

func NewStringProperty

func NewStringProperty(description string) Property

NewStringProperty creates a string property.

type Request

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id,omitempty"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Request represents a JSON-RPC 2.0 request.

type Response

type Response struct {
	Result  any             `json:"result,omitempty"`
	Error   *ResponseError  `json:"error,omitempty"`
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id,omitempty"`
}

Response represents a JSON-RPC 2.0 response.

func NewErrorResponse

func NewErrorResponse(id json.RawMessage, code int, message string) Response

NewErrorResponse creates a JSON-RPC 2.0 error response.

func NewResponse

func NewResponse(id json.RawMessage, result any) Response

NewResponse creates a successful JSON-RPC 2.0 response.

type ResponseError

type ResponseError struct {
	Data    any    `json:"data,omitempty"`
	Message string `json:"message"`
	Code    int    `json:"code"`
}

ResponseError represents a JSON-RPC 2.0 error object.

type Server

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

Server is an MCP server that handles JSON-RPC requests over STDIO.

func NewServer

func NewServer(name, version string) *Server

NewServer creates a new MCP server with the given name and version.

func NewServerWithIO

func NewServerWithIO(name, version string, reader io.Reader, writer io.Writer) *Server

NewServerWithIO creates a new MCP server with custom IO (for testing).

func (*Server) Name

func (a *Server) Name() string

Name returns the server name.

func (*Server) RegisterTool

func (a *Server) RegisterTool(tool Tool)

RegisterTool registers a tool with the server.

func (*Server) Serve

func (a *Server) Serve(ctx context.Context) error

Serve starts the server and processes requests until context is canceled.

func (*Server) Tools

func (a *Server) Tools() []Tool

Tools returns all registered tools.

func (*Server) Version

func (a *Server) Version() string

Version returns the server version.

type Tool

type Tool struct {
	Handler    ToolHandler
	Definition ToolDefinition
}

Tool represents a registered tool with its definition and handler.

func NewTool

func NewTool(name, description string, schema InputSchema, handler ToolHandler) Tool

NewTool creates a new tool with the given definition and handler.

type ToolDefinition

type ToolDefinition struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	InputSchema InputSchema `json:"inputSchema"`
}

ToolDefinition describes a tool's metadata for tools/list.

type ToolHandler

type ToolHandler service.Function[ToolsCallParams, ToolsCallResult]

ToolHandler is a function that handles tool calls. It follows the cloud-native-utils Function pattern.

type ToolsCallParams

type ToolsCallParams struct {
	Arguments map[string]any `json:"arguments,omitempty"`
	Name      string         `json:"name"`
}

ToolsCallParams represents the parameters for tools/call.

type ToolsCallResult

type ToolsCallResult struct {
	Content []ContentBlock `json:"content"`
	IsError bool           `json:"isError,omitempty"`
}

ToolsCallResult represents the result of tools/call.

type ToolsCapability

type ToolsCapability struct {
	ListChanged bool `json:"listChanged,omitempty"`
}

ToolsCapability represents tools capability.

type ToolsListResult

type ToolsListResult struct {
	Tools []ToolDefinition `json:"tools"`
}

ToolsListResult represents the result of tools/list.