docs: document tool support (#498)
Document tool support, and tweak the wording for prompts. For #442
This commit is contained in:
Robert Findley
GitHub
parent
28753c9f12
commit
5985a7cbba
1 changed files with 358 additions and 56 deletions
|
|
@ -4,25 +4,32 @@
|
|||
|
||||
## Prompts
|
||||
|
||||
**Server-side**:
|
||||
MCP servers can provide LLM prompt templates (called simply _prompts_) to clients.
|
||||
Every prompt has a required name which identifies it, and a set of named arguments, which are strings.
|
||||
Construct a prompt with a name and descriptions of its arguments.
|
||||
Associated with each prompt is a handler that expands the template given values for its arguments.
|
||||
Use [`Server.AddPrompt`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server.AddPrompt)
|
||||
to add a prompt along with its handler.
|
||||
If `AddPrompt` is called before a server is connected, the server will have the `prompts` capability.
|
||||
If all prompts are to be added after connection, set [`ServerOptions.HasPrompts`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.HasPrompts)
|
||||
to advertise the capability.
|
||||
MCP servers can provide LLM prompt templates (called simply
|
||||
[_prompts_](https://modelcontextprotocol.io/specification/2025-06-18/server/prompts))
|
||||
to clients. Every prompt has a required name which identifies it, and a set of
|
||||
named arguments, which are strings.
|
||||
|
||||
**Client-side**:
|
||||
To list the server's prompts, call
|
||||
Call [`ClientSession.Prompts`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Prompts) to get an iterator.
|
||||
If needed, you can use the lower-level
|
||||
[`ClientSession.ListPrompts`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.ListPrompts) to list the server's prompts.
|
||||
Call [`ClientSession.GetPrompt`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.GetPrompt) to retrieve a prompt by name, providing
|
||||
arguments for expansion.
|
||||
Set [`ClientOptions.PromptListChangedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.PromptListChangedHandler) to be notified of changes in the list of prompts.
|
||||
**Client-side**: To list the server's prompts, use the
|
||||
[`ClientSession.Prompts`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Prompts)
|
||||
iterator, or the lower-level
|
||||
[`ClientSession.ListPrompts`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.ListPrompts)
|
||||
(see [pagination](#pagination) below). Set
|
||||
[`ClientOptions.PromptListChangedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.PromptListChangedHandler)
|
||||
to be notified of changes in the list of prompts.
|
||||
|
||||
Call
|
||||
[`ClientSession.GetPrompt`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.GetPrompt)
|
||||
to retrieve a prompt by name, providing arguments for expansion.
|
||||
|
||||
**Server-side**: Use
|
||||
[`Server.AddPrompt`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server.AddPrompt)
|
||||
to add a prompt to the server along with its handler.
|
||||
The server will have the `prompts` capability if any prompt is added before the
|
||||
server is connected to a client, or if
|
||||
[`ServerOptions.HasPrompts`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.HasPrompts)
|
||||
is explicitly set. When a prompt is added, any clients already connected to the
|
||||
server will be notified via a `notifications/prompts/list_changed`
|
||||
notification.
|
||||
|
||||
%include ../../mcp/server_example_test.go prompts -
|
||||
|
||||
|
|
@ -32,7 +39,107 @@ Set [`ClientOptions.PromptListChangedHandler`](https://pkg.go.dev/github.com/mod
|
|||
|
||||
## Tools
|
||||
|
||||
<!-- TODO -->
|
||||
MCP servers can provide
|
||||
[tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools)
|
||||
to allow clients to interact with external systems or functionality. Tools are
|
||||
effectively remote function calls, and the Go SDK provides mechanisms to bind
|
||||
them to ordinary Go functions.
|
||||
|
||||
**Client-side**: To list the server's tools, use the
|
||||
[`ClientSession.Tools`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.Tools)
|
||||
iterator, or the lower-level
|
||||
[`ClientSession.ListTools`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.ListTools)
|
||||
(see [pagination](#pagination)). Set
|
||||
[`ClientOptions.ToolListChangedHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientOptions.ToolListChangedHandler)
|
||||
to be notified of changes in the list of tools.
|
||||
|
||||
To call a tool, use
|
||||
[`ClientSession.CallTool`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ClientSession.CallTool)
|
||||
with `CallToolParams` holding the name and arguments of the tool to call.
|
||||
|
||||
```go
|
||||
res, err := session.CallTool(ctx, &mcp.CallToolParams{
|
||||
Name: "my_tool",
|
||||
Arguments: map[string]any{"name": "user"},
|
||||
})
|
||||
```
|
||||
|
||||
Arguments may be any value that can be marshaled to JSON.
|
||||
|
||||
**Server-side**: the basic API for adding a tool is symmetrical with the API
|
||||
for prompts or resources:
|
||||
[`Server.AddTool`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Server.AddTool)
|
||||
adds a
|
||||
[`Tool`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Tool) to
|
||||
the server along with its
|
||||
[`ToolHandler`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ToolHandler)
|
||||
to handle it. The server will have the `tools` capability if any tool is added
|
||||
before the server is connected to a client, or if
|
||||
[`ServerOptions.HasTools`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#ServerOptions.HasPrompts)
|
||||
is explicitly set. When a tool is added, any clients already connected to the
|
||||
server will be notified via a `notifications/tools/list_changed` notification.
|
||||
|
||||
However, the `Server.AddTool` API leaves it to the user to implement the tool
|
||||
handler correctly according to the spec, providing very little out of the box.
|
||||
In order to implement a tool, the user must do all of the following:
|
||||
|
||||
- Provide a tool input and output schema.
|
||||
- Validate the tool arguments against its input schema.
|
||||
- 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.
|
||||
- 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.`
|
||||
|
||||
For this reason, the SDK provides a generic
|
||||
[`AddTool`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#AddTool)
|
||||
function that handles this for you. It can bind a tool to any function with the
|
||||
following shape:
|
||||
|
||||
```go
|
||||
func(_ context.Context, request *CallToolRequest, input In) (result *CallToolResult, output Out, _ error)
|
||||
```
|
||||
|
||||
This is like a `ToolHandler`, but with an extra arbitrary `In` input parameter,
|
||||
and `Out` output parameter.
|
||||
|
||||
Such a function can then be bound to the server using `AddTool`:
|
||||
|
||||
```go
|
||||
mcp.AddTool(server, &mcp.Tool{Name: "my_tool"}, handler)
|
||||
```
|
||||
|
||||
This does the following automatically:
|
||||
|
||||
- If `Tool.InputSchema` or `Tool.OutputSchema` are unset, the input and output
|
||||
schemas are inferred from the `In` type, which must be a struct or map.
|
||||
Optional `jsonschema` struct tags provide argument descriptions.
|
||||
- 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`.
|
||||
- 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`.
|
||||
|
||||
In fact, under ordinary circumstances, the user can ignore `CallToolRequest`
|
||||
and `CallToolResult`.
|
||||
|
||||
For a more realistic example, consider a tool that retrieves the weather:
|
||||
|
||||
%include ../../mcp/tool_example_test.go weathertool -
|
||||
|
||||
In this case, we want to customize part of the inferred schema, though we can
|
||||
still infer the rest. Since we want to control the inference ourselves, we set
|
||||
the `Tool.InputSchema` explicitly:
|
||||
|
||||
%include ../../mcp/tool_example_test.go customschemas -
|
||||
|
||||
_See [mcp/tool_example_test.go](../mcp/tool_example_test.go) for the full
|
||||
example, or [examples/server/toolschemas](examples/server/toolschemas/main.go)
|
||||
for more examples of customizing tool schemas._
|
||||
|
||||
## Utilities
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue