mcp

package
v1.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 22, 2025 License: Apache-2.0 Imports: 1 Imported by: 0

Documentation

Overview

Package mcp provides core Model Context Protocol types and interfaces.

This package implements the Model Context Protocol (MCP) specification version 2025-03-26, enabling communication between LLM applications (hosts) and context providers (servers).

The MCP follows a client-server architecture where:

  • Hosts are LLM applications that initiate connections
  • Clients maintain 1:1 connections with servers inside the host application
  • Servers provide context, tools, and prompts to clients

All communication uses JSON-RPC 2.0 over various transport mechanisms.

Index

Constants

View Source 
const (
	// ProtocolVersion defines the MCP protocol version this implementation supports.
	ProtocolVersion = "2025-03-26"

	// JSONRPCVersion defines the JSON-RPC version used for all MCP communications.
	JSONRPCVersion = "2.0"
)
View Source 
const (
	// ErrorCodeParseError indicates invalid JSON was received.
	ErrorCodeParseError = -32700

	// ErrorCodeInvalidRequest indicates the JSON sent is not a valid Request object.
	ErrorCodeInvalidRequest = -32600

	// ErrorCodeMethodNotFound indicates the method does not exist or is not available.
	ErrorCodeMethodNotFound = -32601

	// ErrorCodeInvalidParams indicates invalid method parameter(s).
	ErrorCodeInvalidParams = -32602

	// ErrorCodeInternalError indicates internal JSON-RPC error.
	ErrorCodeInternalError = -32603
)

Standard JSON-RPC 2.0 error codes as defined in the specification.

View Source 
const (
	// ResponseSenderKey is the context key for accessing the ResponseSender.
	ResponseSenderKey contextKey = "responseSender"

	// SessionIDKey is the context key for accessing the session identifier.
	SessionIDKey contextKey = "sessionID"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ContentItem 

type ContentItem struct {
	// Type indicates the content type (e.g., "text", "image", "resource").
	Type string `json:"type"`

	// Text contains the text content when Type is "text".
	Text string `json:"text,omitempty"`

	// Data contains the raw data when Type is "image" or other binary content.
	Data string `json:"data,omitempty"`

	// MimeType specifies the MIME type for binary content.
	MimeType string `json:"mimeType,omitempty"`

	// Resource contains a reference to an MCP resource when Type is "resource".
	Resource *ResourceReference `json:"resource,omitempty"`
}

ContentItem represents a piece of content in a tool response.

Content items can be text, images, or other media types. The type field indicates what kind of content this is, and additional fields provide the actual content data.

type ElicitationHandler 

type ElicitationHandler interface {
	// HandleElicitation processes an elicitation request and returns the user's response.
	// The client maintains control over how the request is presented to the user
	// and how the response is collected.
	HandleElicitation(ctx context.Context, req ElicitationRequest) (ElicitationResponse, error)
}

ElicitationHandler defines the interface for handling elicitation requests.

This interface allows servers to request additional information from users during interactions, enabling interactive workflows while maintaining client control over user interactions and data sharing.

type ElicitationRequest 

type ElicitationRequest struct {
	// Prompt is the human-readable request for information.
	Prompt string `json:"prompt"`

	// Schema defines the expected structure of the user's response using JSON Schema.
	Schema map[string]any `json:"schema,omitempty"`

	// Meta contains implementation-specific metadata.
	Meta map[string]any `json:"_meta,omitempty"`
}

ElicitationRequest represents a request from a server to gather additional information from the user.

This allows servers to request structured data from users with JSON schemas to validate responses. Elicitation enables interactive workflows by allowing user input requests to occur nested inside other MCP server features.

type ElicitationResponse 

type ElicitationResponse struct {
	// Data contains the user's structured response.
	Data map[string]any `json:"data"`

	// Meta contains implementation-specific metadata.
	Meta map[string]any `json:"_meta,omitempty"`
}

ElicitationResponse contains the user's response to an elicitation request.

type ErrorResponse 

type ErrorResponse struct {
	// Code is a numeric error code indicating the type of error.
	Code int `json:"code"`

	// Message is a short description of the error.
	Message string `json:"message"`

	// Data provides additional information about the error.
	Data any `json:"data,omitempty"`
}

ErrorResponse represents a JSON-RPC 2.0 error object.

type InitializeResponse 

type InitializeResponse struct {
	// ProtocolVersion is the MCP protocol version the server supports.
	ProtocolVersion string `json:"protocolVersion"`

	// Capabilities describes what the server can do (tools, resources, prompts).
	Capabilities map[string]any `json:"capabilities"`

	// ServerInfo contains metadata about the server.
	ServerInfo ServerInfo `json:"serverInfo"`
}

InitializeResponse is sent by the server in response to an initialize request. It contains the server's protocol version, capabilities, and metadata.

type InputSchema 

type InputSchema struct {
	// Type is typically "object" for tool parameters.
	Type string `json:"type"`

	// Properties defines the individual parameter schemas.
	Properties map[string]any `json:"properties,omitempty"`

	// Required lists the parameter names that must be provided.
	Required []string `json:"required,omitempty"`
}

InputSchema defines the JSON Schema for tool input parameters.

This follows the JSON Schema specification and describes what parameters the tool expects, their types, and which ones are required.

type MessageContent 

type MessageContent struct {
	// Type indicates the content type (typically "text").
	Type string `json:"type"`

	// Text contains the text content when Type is "text".
	Text string `json:"text"`
}

MessageContent contains the actual content of a prompt message.

Content can be text or other media types. The type field indicates what kind of content this is.

type Prompt 

type Prompt struct {
	// Name is the unique identifier for the prompt.
	Name string `json:"name"`

	// Description explains what the prompt does and when to use it.
	Description string `json:"description"`

	// Arguments defines the parameters this prompt accepts.
	Arguments []PromptArgument `json:"arguments,omitempty"`
}

Prompt represents a template for generating structured LLM interactions.

Prompts help standardize common use cases by providing templates that can be customized with arguments. They generate messages ready for use with language models.

type PromptArgument 

type PromptArgument struct {
	// Name is the parameter name.
	Name string `json:"name"`

	// Description explains what this argument is used for.
	Description string `json:"description"`

	// Required indicates whether this argument must be provided.
	Required bool `json:"required,omitempty"`
}

PromptArgument defines a parameter that can be passed to a prompt.

Arguments allow prompts to be customized for different contexts while maintaining a consistent structure and behavior.

type PromptHandler 

type PromptHandler interface {
	// ListPrompts returns all available prompt templates.
	// Prompts should include their name, description, and expected arguments.
	ListPrompts(ctx context.Context) ([]Prompt, error)

	// GetPrompt generates a prompt with the given parameters.
	// It returns formatted messages ready for use with a language model.
	GetPrompt(ctx context.Context, params PromptParams) (PromptResponse, error)
}

PromptHandler defines the interface for handling MCP prompt operations.

Prompts are templates that can be used to generate structured interactions with language models, helping to standardize common use cases.

type PromptMessage 

type PromptMessage struct {
	// Role indicates who is speaking ("user", "assistant", "system").
	Role string `json:"role"`

	// Content contains the message content.
	Content MessageContent `json:"content"`
}

PromptMessage represents a single message in a generated prompt.

Messages follow the standard conversation format with roles like "user", "assistant", or "system" and contain the actual message content.

type PromptParams 

type PromptParams struct {
	// Name is the name of the prompt to generate.
	Name string `json:"name"`

	// Arguments contains the values for the prompt parameters.
	Arguments map[string]any `json:"arguments,omitempty"`
}

PromptParams contains the parameters for generating a prompt.

type PromptResponse 

type PromptResponse struct {
	// Messages contains the generated conversation messages.
	Messages []PromptMessage `json:"messages"`
}

PromptResponse contains the generated prompt messages.

The response contains a sequence of messages that form a conversation template ready for use with a language model.

type Request 

type Request struct {
	// JSONRPC must be exactly "2.0" to indicate JSON-RPC 2.0.
	JSONRPC string `json:"jsonrpc"`

	// Method is the name of the method to be invoked.
	Method string `json:"method"`

	// ID is the request identifier. Must be string, number, or null.
	// For MCP, ID MUST NOT be null per specification.
	ID any `json:"id"`

	// Params contains the parameter values to be used during method invocation.
	Params any `json:"params,omitempty"`
}

Request represents a JSON-RPC 2.0 request message.

type Resource 

type Resource struct {
	// URI is the unique identifier for the resource.
	// It should follow a consistent scheme (e.g., "file://", "db://").
	URI string `json:"uri"`

	// Name is a human-readable name for the resource.
	Name string `json:"name"`
}

Resource represents a piece of data or content that can be read by the client.

Resources provide contextual information that can be used by LLMs. They are identified by URIs and can contain various types of content such as text, structured data, or references to external systems.

type ResourceContent 

type ResourceContent struct {
	// URI identifies which resource this content belongs to.
	URI string `json:"uri"`

	// Text contains the textual content of the resource.
	Text string `json:"text"`
}

ResourceContent contains the actual content of a resource.

When a resource is read, the server returns the content along with the URI for identification. Content can be text, structured data, or other formats.

type ResourceHandler 

type ResourceHandler interface {
	// ListResources returns all available resources that can be read.
	// Resources should include their URI and human-readable name.
	ListResources(ctx context.Context) ([]Resource, error)

	// ReadResource reads the content of a specific resource identified by URI.
	// It returns the resource content or an error if the resource cannot be read.
	ReadResource(ctx context.Context, params ResourceParams) (ResourceResponse, error)

	// ListResourceTemplates returns all available resource templates.
	// Resource templates define parameterized resources using URI templates.
	ListResourceTemplates(ctx context.Context) ([]ResourceTemplate, error)
}

ResourceHandler defines the interface for handling MCP resource operations.

Resources represent data or content that can be read by the client. They provide contextual information that can be used by LLMs.

type ResourceParams 

type ResourceParams struct {
	// URI identifies the resource to read.
	URI string `json:"uri"`
}

ResourceParams contains the parameters for reading a resource.

type ResourceReference 

type ResourceReference struct {
	// URI identifies the resource being referenced.
	URI string `json:"uri"`

	// Type indicates the type of resource reference.
	Type string `json:"type,omitempty"`
}

ResourceReference represents a reference to an MCP resource in tool output.

This allows tools to link to resources that provide additional context or data related to the tool's execution.

type ResourceResponse 

type ResourceResponse struct {
	// Contents contains the resource content items.
	Contents []ResourceContent `json:"contents"`
}

ResourceResponse is the response to a resource read request.

A single resource request can return multiple content items, for example when reading a directory that contains multiple files or entries.

type ResourceTemplate 

type ResourceTemplate struct {
	// URITemplate is the URI template for the resource (e.g., "file:///{path}").
	URITemplate string `json:"uriTemplate"`

	// Name is a human-readable name for the resource template.
	Name string `json:"name"`

	// Description explains what the resource template provides.
	Description string `json:"description,omitempty"`

	// MimeType indicates the MIME type of resources created from this template.
	MimeType string `json:"mimeType,omitempty"`
}

ResourceTemplate represents a parameterized resource using URI templates.

Resource templates allow servers to expose dynamic resources that can be instantiated with different parameters. They use URI templates to define the structure of the resource URIs.

type Response 

type Response struct {
	// JSONRPC must be exactly "2.0" to indicate JSON-RPC 2.0.
	JSONRPC string `json:"jsonrpc"`

	// ID must match the ID of the request being responded to.
	ID any `json:"id"`

	// Result contains the result of the method invocation.
	// This field is required on success and must not exist if there was an error.
	Result any `json:"result,omitempty"`

	// Error contains error information if the method invocation failed.
	// This field is required on error and must not exist if successful.
	Error *ErrorResponse `json:"error,omitempty"`
}

Response represents a JSON-RPC 2.0 response message.

type ResponseSender 

type ResponseSender interface {
	// SendResponse sends a successful JSON-RPC response.
	SendResponse(response Response) error

	// SendError sends a JSON-RPC error response with the specified error details.
	SendError(id any, code int, message string, data any) error
}

ResponseSender defines the interface for sending responses back to clients.

ResponseSender abstracts the transport mechanism, allowing the same server logic to work with different transport layers (stdio, HTTP, etc.).

type Server 

type Server interface {
	// Initialize handles the MCP initialization handshake.
	// It returns the server's protocol version, capabilities, and metadata.
	Initialize(ctx context.Context) (*InitializeResponse, error)

	// HandleRequest processes a JSON-RPC request and sends the appropriate response.
	// The context may contain a ResponseSender for sending responses back to the client.
	HandleRequest(ctx context.Context, req Request) error
}

Server defines the core MCP server interface.

Server implementations handle the MCP initialization handshake and process incoming JSON-RPC requests according to the MCP specification.

type ServerInfo 

type ServerInfo struct {
	// Name is the human-readable name of the server.
	Name string `json:"name"`

	// Version is the version of the server implementation.
	Version string `json:"version"`
}

ServerInfo contains metadata about an MCP server implementation.

type Tool 

type Tool struct {
	// Name is the unique identifier for the tool.
	Name string `json:"name"`

	// Description explains what the tool does and when to use it.
	Description string `json:"description"`

	// InputSchema defines the expected parameters using JSON Schema.
	InputSchema InputSchema `json:"inputSchema"`
}

Tool represents a function that can be called by the MCP client.

Tools are executable functions that allow the client to perform actions in the external system that the MCP server represents. Each tool has a name, description, and JSON schema defining its input parameters.

type ToolCallParams 

type ToolCallParams struct {
	// Name is the name of the tool to call.
	Name string `json:"name"`

	// Arguments contains the parameters to pass to the tool.
	Arguments map[string]any `json:"arguments"`
}

ToolCallParams contains the parameters for calling a tool.

type ToolHandler 

type ToolHandler interface {
	// ListTools returns all available tools that can be called.
	// Tools should include their name, description, and input schema.
	ListTools(ctx context.Context) ([]Tool, error)

	// CallTool executes a tool with the given parameters.
	// It returns the result of the tool execution or an error if the call fails.
	CallTool(ctx context.Context, params ToolCallParams) (ToolResponse, error)
}

ToolHandler defines the interface for handling MCP tool operations.

Tools are functions that the server can execute on behalf of the client. They represent actions that can be taken in the external system.

type ToolResponse 

type ToolResponse struct {
	// Content contains the output of the tool execution.
	Content []ContentItem `json:"content"`
}

ToolResponse contains the result of a tool execution.

The response contains content items that represent the output of the tool. Content can be text, images, or other media types supported by MCP.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.