From 75c8478e45ad3975416ae31ae207015943732a2b Mon Sep 17 00:00:00 2001 From: Jonathan Amsterdam Date: Wed, 25 Jun 2025 15:07:13 -0400 Subject: [PATCH] mcp: fix some documentation - Add some doc strings. - Remove markdown-like notations. --- mcp/protocol.go | 54 ++++++++++++++++++++++++------------------------- mcp/shared.go | 10 ++++++++- 2 files changed, 36 insertions(+), 28 deletions(-) diff --git a/mcp/protocol.go b/mcp/protocol.go index 439d07a0..9b152431 100644 --- a/mcp/protocol.go +++ b/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. // @@ -133,12 +133,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"` } @@ -168,21 +168,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"` } @@ -236,7 +236,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"` } @@ -254,11 +254,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"` } @@ -424,12 +424,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"` @@ -444,7 +444,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 { @@ -453,10 +453,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. @@ -536,7 +536,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"` @@ -609,7 +609,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. @@ -647,7 +647,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 @@ -757,9 +757,9 @@ 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. @@ -767,14 +767,14 @@ 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"` diff --git a/mcp/shared.go b/mcp/shared.go index 07ea5dff..b7954eac 100644 --- a/mcp/shared.go +++ b/mcp/shared.go @@ -242,9 +242,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" @@ -269,7 +273,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) } @@ -288,7 +294,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) }