mcp: add docs for tier 1 assessment (#1195)
Closes open points in [comment](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/3220#issuecomment-5373089321)
This commit is contained in:
Guglielmo Colombo
GitHub
parent
6f0a645c20
commit
b8c53fedd6
3 changed files with 1461 additions and 5 deletions
|
|
@ -35,6 +35,16 @@ pattern.
|
|||
|
||||
%include ../../mcp/client_example_test.go roots -
|
||||
|
||||
### Roots list changed
|
||||
|
||||
`Client.AddRoots` and `Client.RemoveRoots` notify every connected server that
|
||||
the list changed. Servers observe this through
|
||||
[`ServerOptions.RootsListChangedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.RootsListChangedHandler);
|
||||
as with the server-side list-changed notifications, it reports only that
|
||||
something changed, so read the list back with `ServerSession.ListRoots`.
|
||||
|
||||
%include ../../mcp/client_example_test.go rootslistchanged -
|
||||
|
||||
## Sampling
|
||||
|
||||
> **Note:** The sampling feature is deprecated as of protocol version
|
||||
|
|
@ -84,6 +94,48 @@ pattern.
|
|||
|
||||
%include ../../mcp/client_example_test.go elicitation -
|
||||
|
||||
### Schema defaults and enums
|
||||
|
||||
`ElicitParams.RequestedSchema` is a flat schema of primitive fields, which the
|
||||
client renders as a form. Two field keywords shape that form.
|
||||
|
||||
A `Default` ([SEP-1034](https://modelcontextprotocol.io/seps/1034)) prefills a
|
||||
field. When the user accepts without supplying it, the SDK fills the field in
|
||||
from the schema before the result reaches either side's caller — the client
|
||||
does so after its elicitation handler returns, and `ServerSession.Elicit` does
|
||||
so again on receipt. This is unconditional; there is no opt-in flag. Marking a
|
||||
defaulted field `Required` defeats it: accepted content is validated against
|
||||
the schema before defaults are applied, so an answer that omits the field is
|
||||
rejected rather than defaulted.
|
||||
|
||||
An `Enum` ([SEP-1330](https://modelcontextprotocol.io/seps/1330)) restricts a
|
||||
field to a fixed set of values, which the client renders as a choice. Enums
|
||||
are supported only on `"string"` fields; declaring one on another type is
|
||||
rejected. To label the choices, set the legacy `enumNames` keyword through
|
||||
`Schema.Extra`, with exactly one name per enum value — a mismatched length is
|
||||
rejected.
|
||||
|
||||
%include ../../mcp/client_example_test.go elicitationschema -
|
||||
|
||||
### Completing a URL elicitation
|
||||
|
||||
In URL mode the user finishes out of band, in a browser, so nothing in the
|
||||
elicitation result tells the client when they are done. The server signals that
|
||||
with
|
||||
[`ServerSession.NotifyElicitationComplete`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerSession.NotifyElicitationComplete),
|
||||
passing the same `ElicitationID` the request carried; the client observes it
|
||||
through
|
||||
[`ClientOptions.ElicitationCompleteHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.ElicitationCompleteHandler).
|
||||
Send it from whatever endpoint the hosted flow redirects back to.
|
||||
|
||||
The notification matters most when a handler rejects a request with
|
||||
[`URLElicitationRequiredError`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#URLElicitationRequiredError):
|
||||
the client parks the original request until a notification names that
|
||||
`ElicitationID`, and then retries it automatically. Until one arrives, the
|
||||
client waits.
|
||||
|
||||
%include ../../mcp/client_example_test.go elicitationcomplete -
|
||||
|
||||
## Multi Round-Trip Requests
|
||||
|
||||
[SEP-2322](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322)
|
||||
|
|
|
|||
|
|
@ -267,6 +267,34 @@ _See [examples/server/distributed](https://github.com/modelcontextprotocol/go-sd
|
|||
an example using stateless mode to implement a server distributed across
|
||||
multiple processes._
|
||||
|
||||
### SSE Transport (legacy)
|
||||
|
||||
Before the streamable transport, the
|
||||
[2024-11-05](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports)
|
||||
spec defined an HTTP transport built from two endpoints: a hanging GET that
|
||||
streams server-to-client messages as server-sent events, and a per-session
|
||||
endpoint the client POSTs its messages to. The SDK still implements it, for
|
||||
talking to peers that predate the streamable transport. New deployments should
|
||||
use the [streamable transport](#streamable-transport) instead.
|
||||
|
||||
It is implemented across three types, mirroring the streamable ones:
|
||||
|
||||
- [`SSEHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#SSEHandler):
|
||||
an `http.Handler` that creates a session per incoming GET and routes POSTs to
|
||||
the right session. Construct it with
|
||||
[`NewSSEHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#NewSSEHandler),
|
||||
which takes a function returning the `Server` to serve a given request.
|
||||
- [`SSEServerTransport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#SSEServerTransport):
|
||||
one such session. Reach for it directly only when serving the two endpoints
|
||||
yourself; `SSEHandler` creates these for you.
|
||||
- [`SSEClientTransport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#SSEClientTransport):
|
||||
the client side, which needs only the `Endpoint` of the GET.
|
||||
|
||||
%include ../../mcp/sse_example_test.go ssehandler -
|
||||
|
||||
_See [examples/server/sse](https://github.com/modelcontextprotocol/go-sdk/blob/main/examples/server/sse/main.go)
|
||||
for a standalone server._
|
||||
|
||||
### Custom transports
|
||||
|
||||
The SDK supports [custom
|
||||
|
|
|
|||
|
|
@ -33,6 +33,24 @@ notification.
|
|||
|
||||
%include ../../mcp/server_example_test.go prompts -
|
||||
|
||||
### Prompt message content
|
||||
|
||||
A
|
||||
[`PromptMessage`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#PromptMessage)
|
||||
has two fields: a `Role`, either `"user"` or `"assistant"`, and a single
|
||||
`Content`. That is the same interface a tool result uses (see [Tool result
|
||||
content](#tool-result-content)), so a prompt message can hold an image, audio,
|
||||
or a resource's contents as readily as text.
|
||||
|
||||
Media on its own says nothing about what the model should do with it, so send a
|
||||
text message alongside it. Embedding a resource puts its contents directly in
|
||||
the message, sparing the client a separate `resources/read`. Note that
|
||||
`ResourceContents.URI` is not checked against the resources the server has
|
||||
registered: it records where the contents came from, so use the URI of a real
|
||||
resource when there is one, as in the example below.
|
||||
|
||||
%include ../../mcp/server_example_test.go promptcontent -
|
||||
|
||||
## Resources
|
||||
|
||||
In MCP terms, a _resource_ is some data referenced by a URI.
|
||||
|
|
@ -94,6 +112,37 @@ notification.
|
|||
|
||||
%include ../../mcp/server_example_test.go resources -
|
||||
|
||||
### Binary resources
|
||||
|
||||
A
|
||||
[`ResourceContents`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ResourceContents)
|
||||
carries its data in either `Text` or `Blob`. Binary data goes in `Blob` as
|
||||
plain bytes — the SDK base64-encodes it on the wire — and leaves `Text` empty,
|
||||
so a client tells the two apart by which field is populated.
|
||||
|
||||
%include ../../mcp/server_example_test.go binaryresource -
|
||||
|
||||
### Resource subscriptions
|
||||
|
||||
A client interested in changes to one resource subscribes to its URI with
|
||||
[`ClientSession.Subscribe`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Subscribe)
|
||||
and stops with
|
||||
[`ClientSession.Unsubscribe`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Unsubscribe).
|
||||
Set
|
||||
[`ServerOptions.SubscribeHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.SubscribeHandler)
|
||||
and
|
||||
[`UnsubscribeHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.UnsubscribeHandler)
|
||||
to track who is listening; setting either one gives the server the
|
||||
`resources.subscribe` capability.
|
||||
|
||||
Publish a change with
|
||||
[`Server.ResourceUpdated`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server.ResourceUpdated),
|
||||
which notifies every session subscribed to that URI. The notification carries
|
||||
only the URI, not the new contents, so a client that wants them reads the
|
||||
resource again.
|
||||
|
||||
%include ../../mcp/server_example_test.go subscribe -
|
||||
|
||||
## Tools
|
||||
|
||||
MCP servers can provide
|
||||
|
|
@ -145,7 +194,7 @@ In order to implement a tool, the user must do all of the following:
|
|||
- Unmarshal the input schema into a Go value
|
||||
- Execute the tool logic.
|
||||
- Marshal the tool's structured output (if any) to JSON, and store it in the
|
||||
result's `StructuredOutput` field as well as the unstructured `Content` field.
|
||||
result's `StructuredContent` field as well as the unstructured `Content` field.
|
||||
- Validate that output JSON against the tool's output schema.
|
||||
- If any tool errors occurred, pack them into the unstructured content and set
|
||||
`IsError` to `true.`
|
||||
|
|
@ -180,7 +229,7 @@ This does the following automatically:
|
|||
- Tool arguments are validated against the input schema.
|
||||
- Tool arguments are marshaled into the `In` value.
|
||||
- Tool output (the `Out` value) is marshaled into the result's
|
||||
`StructuredOutput`, as well as the unstructured `Content`.
|
||||
`StructuredContent`, as well as the unstructured `Content`.
|
||||
- Output is validated against the tool's output schema.
|
||||
- If an ordinary error is returned, it is stored int the `CallToolResult` and
|
||||
`IsError` is set to `true`.
|
||||
|
|
@ -202,6 +251,39 @@ _See [mcp/tool_example_test.go](https://github.com/modelcontextprotocol/go-sdk/b
|
|||
example, or [examples/server/toolschemas](https://github.com/modelcontextprotocol/go-sdk/blob/main/examples/server/toolschemas/main.go)
|
||||
for more examples of customizing tool schemas._
|
||||
|
||||
### Tool result content
|
||||
|
||||
Alongside its structured output, a tool result carries a list of
|
||||
[`Content`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Content)
|
||||
blocks in `CallToolResult.Content`, and may mix as many kinds as it needs:
|
||||
|
||||
| Type | Carries |
|
||||
| --- | --- |
|
||||
| [`TextContent`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#TextContent) | plain text |
|
||||
| [`ImageContent`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ImageContent) | image data, with a MIME type |
|
||||
| [`AudioContent`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#AudioContent) | audio data, with a MIME type |
|
||||
| [`EmbeddedResource`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#EmbeddedResource) | the contents of a resource, inline |
|
||||
| [`ResourceLink`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ResourceLink) | a reference to a resource the client can read separately |
|
||||
|
||||
`ImageContent.Data` and `AudioContent.Data` are plain `[]byte`; the SDK
|
||||
base64-encodes them on the wire, so handlers never encode by hand, and base64
|
||||
carried over from another MCP SDK must be decoded before it is assigned. An
|
||||
`EmbeddedResource` wraps a
|
||||
[`ResourceContents`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ResourceContents),
|
||||
which holds either `Text` or, for binary data, `Blob`. Prefer a `ResourceLink`
|
||||
when the client may not need the contents, since an embedded resource is
|
||||
transferred whether it is used or not.
|
||||
|
||||
When a handler bound with `AddTool` leaves `Content` unset, the SDK fills it
|
||||
with the JSON encoding of the output value; set `Content` explicitly, as below,
|
||||
to return anything else. `StructuredContent` is still populated from the output
|
||||
value either way.
|
||||
|
||||
%include ../../mcp/tool_example_test.go contenttypes -
|
||||
|
||||
`ToolUseContent` and `ToolResultContent` also implement `Content`, but are only
|
||||
valid in sampling messages, not in tool results.
|
||||
|
||||
**Stateless server deployments:** Some deployments create a new
|
||||
[`Server`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server)
|
||||
for each incoming request, re-registering tools every time. To avoid repeated
|
||||
|
|
@ -219,6 +301,26 @@ func handleRequest(w http.ResponseWriter, r *http.Request) {
|
|||
}
|
||||
```
|
||||
|
||||
## List changed notifications
|
||||
|
||||
Adding or removing a feature on a connected server sends the matching
|
||||
`notifications/*/list_changed` to every client, which dispatches it to
|
||||
[`ClientOptions.ToolListChangedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.ToolListChangedHandler),
|
||||
[`PromptListChangedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.PromptListChangedHandler),
|
||||
or
|
||||
[`ResourceListChangedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.ResourceListChangedHandler).
|
||||
A notification reports only that the list changed, so a client that needs the
|
||||
new contents lists them again.
|
||||
|
||||
These notifications ride on capabilities, and capabilities are inferred from
|
||||
what is registered before [`Server.Connect`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server.Connect)
|
||||
(see [Capabilities](#capabilities)). A server that registers its features
|
||||
afterwards, as the example below does, has to declare
|
||||
`ServerOptions.HasTools`, `HasPrompts`, or `HasResources` itself, or the
|
||||
client is never told.
|
||||
|
||||
%include ../../mcp/server_example_test.go listchanged -
|
||||
|
||||
## Multi Round-Trip Requests
|
||||
|
||||
[SEP-2322](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322)
|
||||
|
|
|
|||
Loading…
Reference in a new issue