mcp: fix some documentation (#41)

- Add some doc strings.

- Remove markdown-like notations.

Author: jba

mcp/protocol.go

@@ -22,7 +22,7 @@ type Annotations struct {
 	// Describes who the intended customer of this object or data is.
 	//
 	// It can include multiple entries to indicate content useful for multiple
-	// audiences (e.g., `["user", "assistant"]`).
+	// audiences (e.g., []Role{"user", "assistant"}).
 	Audience []Role `json:"audience,omitempty"`
 	// The moment the resource was last modified, as an ISO 8601 formatted string.
 	//
@@ -70,12 +70,12 @@ type CallToolResult struct {
 	//
 	// If not set, this is assumed to be false (the call was successful).
 	//
-	// Any errors that originate from the tool SHOULD be reported inside the result
-	// object, with `isError` set to true, _not_ as an MCP protocol-level error
+	// Any errors that originate from the tool should be reported inside the result
+	// object, with isError set to true, not as an MCP protocol-level error
 	// response. Otherwise, the LLM would not be able to see that an error occurred
 	// and self-correct.
 	//
-	// However, any errors in _finding_ the tool, an error indicating that the
+	// However, any errors in finding the tool, an error indicating that the
 	// server does not support tool calls, or any other exceptional conditions,
 	// should be reported as an MCP error response.
 	IsError bool `json:"isError,omitempty"`
@@ -115,8 +115,8 @@ type CallToolResultFor[Out any] struct {
 	//
 	// If not set, this is assumed to be false (the call was successful).
 	//
-	// Any errors that originate from the tool SHOULD be reported inside the result
-	// object, with `isError` set to true, not as an MCP protocol-level error
+	// Any errors that originate from the tool should be reported inside the result
+	// object, with isError set to true, not as an MCP protocol-level error
 	// response. Otherwise, the LLM would not be able to see that an error occurred
 	// and self-correct.
 	//
@@ -152,12 +152,12 @@ type CancelledParams struct {
 	// This property is reserved by the protocol to allow clients and servers to
 	// attach additional metadata to their responses.
 	Meta `json:"_meta,omitempty"`
-	// An optional string describing the reason for the cancellation. This MAY be
+	// An optional string describing the reason for the cancellation. This may be
 	// logged or presented to the user.
 	Reason string `json:"reason,omitempty"`
 	// The ID of the request to cancel.
 	//
-	// This MUST correspond to the ID of a request previously issued in the same
+	// This must correspond to the ID of a request previously issued in the same
 	// direction.
 	RequestID any `json:"requestId"`
 }
@@ -187,21 +187,21 @@ type CreateMessageParams struct {
 	// attach additional metadata to their responses.
 	Meta `json:"_meta,omitempty"`
 	// A request to include context from one or more MCP servers (including the
-	// caller), to be attached to the prompt. The client MAY ignore this request.
+	// caller), to be attached to the prompt. The client may ignore this request.
 	IncludeContext string `json:"includeContext,omitempty"`
 	// The maximum number of tokens to sample, as requested by the server. The
-	// client MAY choose to sample fewer tokens than requested.
+	// client may choose to sample fewer tokens than requested.
 	MaxTokens int64              `json:"maxTokens"`
 	Messages  []*SamplingMessage `json:"messages"`
 	// Optional metadata to pass through to the LLM provider. The format of this
 	// metadata is provider-specific.
 	Metadata struct{} `json:"metadata,omitempty"`
-	// The server's preferences for which model to select. The client MAY ignore
+	// The server's preferences for which model to select. The client may ignore
 	// these preferences.
 	ModelPreferences *ModelPreferences `json:"modelPreferences,omitempty"`
 	StopSequences    []string          `json:"stopSequences,omitempty"`
 	// An optional system prompt the server wants to use for sampling. The client
-	// MAY modify or omit this prompt.
+	// may modify or omit this prompt.
 	SystemPrompt string  `json:"systemPrompt,omitempty"`
 	Temperature  float64 `json:"temperature,omitempty"`
 }
@@ -255,7 +255,7 @@ type InitializeParams struct {
 	Capabilities *ClientCapabilities `json:"capabilities"`
 	ClientInfo   *implementation     `json:"clientInfo"`
 	// The latest version of the Model Context Protocol that the client supports.
-	// The client MAY decide to support older versions as well.
+	// The client may decide to support older versions as well.
 	ProtocolVersion string `json:"protocolVersion"`
 }
 
@@ -273,11 +273,11 @@ type InitializeResult struct {
 	//
 	// This can be used by clients to improve the LLM's understanding of available
 	// tools, resources, etc. It can be thought of like a "hint" to the model. For
-	// example, this information MAY be added to the system prompt.
+	// example, this information may be added to the system prompt.
 	Instructions string `json:"instructions,omitempty"`
 	// The version of the Model Context Protocol that the server wants to use. This
 	// may not match the version that the client requested. If the client cannot
-	// support this version, it MUST disconnect.
+	// support this version, it must disconnect.
 	ProtocolVersion string          `json:"protocolVersion"`
 	ServerInfo      *implementation `json:"serverInfo"`
 }
@@ -443,12 +443,12 @@ func (x *LoggingMessageParams) SetProgressToken(t any) { setProgressToken(x, t)
 type ModelHint struct {
 	// A hint for a model name.
 	//
-	// The client SHOULD treat this as a substring of a model name; for example: -
+	// The client should treat this as a substring of a model name; for example: -
 	// `claude-3-5-sonnet` should match `claude-3-5-sonnet-20241022` - `sonnet`
 	// should match `claude-3-5-sonnet-20241022`, `claude-3-sonnet-20240229`, etc. -
 	// `claude` should match any Claude model
 	//
-	// The client MAY also map the string to a different provider's model name or a
+	// The client may also map the string to a different provider's model name or a
 	// different model family, as long as it fills a similar niche; for example: -
 	// `gemini-1.5-flash` could match `claude-3-haiku-20240307`
 	Name string `json:"name,omitempty"`
@@ -463,7 +463,7 @@ type ModelHint struct {
 // on. This interface allows servers to express their priorities across multiple
 // dimensions to help clients make an appropriate selection for their use case.
 //
-// These preferences are always advisory. The client MAY ignore them. It is also
+// These preferences are always advisory. The client may ignore them. It is also
 // up to the client to decide how to interpret these preferences and how to
 // balance them against other considerations.
 type ModelPreferences struct {
@@ -472,10 +472,10 @@ type ModelPreferences struct {
 	CostPriority float64 `json:"costPriority,omitempty"`
 	// Optional hints to use for model selection.
 	//
-	// If multiple hints are specified, the client MUST evaluate them in order (such
+	// If multiple hints are specified, the client must evaluate them in order (such
 	// that the first match is taken).
 	//
-	// The client SHOULD prioritize these hints over the numeric priorities, but MAY
+	// The client should prioritize these hints over the numeric priorities, but may
 	// still use the priorities to select from ambiguous matches.
 	Hints []*ModelHint `json:"hints,omitempty"`
 	// How much to prioritize intelligence and capabilities when selecting a model.
@@ -555,7 +555,7 @@ func (x *PromptListChangedParams) SetProgressToken(t any) { setProgressToken(x,
 
 // Describes a message returned as part of a prompt.
 //
-// This is similar to `SamplingMessage`, but also supports the embedding of
+// This is similar to SamplingMessage, but also supports the embedding of
 // resources from the MCP server.
 type PromptMessage struct {
 	Content Content `json:"content"`
@@ -628,7 +628,7 @@ type Resource struct {
 	// easily understood, even by those unfamiliar with domain-specific terminology.
 	//
 	// If not provided, the name should be used for display (except for Tool, where
-	// `annotations.title` should be given precedence over using `name`, if
+	// Annotations.Title should be given precedence over using name, if
 	// present).
 	Title string `json:"title,omitempty"`
 	// The URI of this resource.
@@ -666,7 +666,7 @@ type ResourceTemplate struct {
 	// easily understood, even by those unfamiliar with domain-specific terminology.
 	//
 	// If not provided, the name should be used for display (except for Tool, where
-	// `annotations.title` should be given precedence over using `name`, if
+	// Annotations.Title should be given precedence over using name, if
 	// present).
 	Title string `json:"title,omitempty"`
 	// A URI template (according to RFC 6570) that can be used to construct resource
@@ -776,24 +776,24 @@ type Tool struct {
 
 // Additional properties describing a Tool to clients.
 //
-// NOTE: all properties in ToolAnnotations are **hints**. They are not
+// NOTE: all properties in ToolAnnotations are hints. They are not
 // guaranteed to provide a faithful description of tool behavior (including
-// descriptive properties like `title`).
+// descriptive properties like title).
 //
 // Clients should never make tool use decisions based on ToolAnnotations
 // received from untrusted servers.
 type ToolAnnotations struct {
 	// If true, the tool may perform destructive updates to its environment. If
 	// false, the tool performs only additive updates.
 	//
-	// (This property is meaningful only when `readOnlyHint == false`)
+	// (This property is meaningful only when ReadOnlyHint == false.)
 	//
 	// Default: true
 	DestructiveHint *bool `json:"destructiveHint,omitempty"`
 	// If true, calling the tool repeatedly with the same arguments will have no
 	// additional effect on the its environment.
 	//
-	// (This property is meaningful only when `readOnlyHint == false`)
+	// (This property is meaningful only when ReadOnlyHint == false.)
 	//
 	// Default: false
 	IdempotentHint bool `json:"idempotentHint,omitempty"`

mcp/shared.go

@@ -236,9 +236,13 @@ func notifySessions[S Session](sessions []S, method string, params Params) {
 	}
 }
 
+// Meta is additional metadata for requests, responses and other types.
 type Meta map[string]any
 
-func (m Meta) GetMeta() map[string]any   { return m }
+// GetMeta returns metadata from a value.
+func (m Meta) GetMeta() map[string]any { return m }
+
+// SetMeta sets the metadata on a value.
 func (m *Meta) SetMeta(x map[string]any) { *m = x }
 
 const progressTokenKey = "progressToken"
@@ -263,7 +267,9 @@ func setProgressToken(p Params, pt any) {
 
 // Params is a parameter (input) type for an MCP call or notification.
 type Params interface {
+	// GetMeta returns metadata from a value.
 	GetMeta() map[string]any
+	// SetMeta sets the metadata on a value.
 	SetMeta(map[string]any)
 }
 
@@ -282,7 +288,9 @@ type RequestParams interface {
 
 // Result is a result of an MCP call.
 type Result interface {
+	// GetMeta returns metadata from a value.
 	GetMeta() map[string]any
+	// SetMeta sets the metadata on a value.
 	SetMeta(map[string]any)
 }