|
7 | 7 | // The mcp package provides an SDK for writing model context protocol clients |
8 | 8 | // and servers. |
9 | 9 | // |
10 | | -// To get started, create either a [Client] or [Server], and connect it to a |
11 | | -// peer using a [Transport]. The diagram below illustrates how this works: |
| 10 | +// To get started, create either a [Client] or [Server], add features to it |
| 11 | +// using `AddXXX` functions, and connect it to a peer using a [Transport]. |
| 12 | +// |
| 13 | +// For example, to run a simple server on the [StdioTransport]: |
| 14 | +// |
| 15 | +// server := mcp.NewServer(&mcp.Implementation{Name: "greeter"}, nil) |
| 16 | +// |
| 17 | +// // Using the generic AddTool automatically populates the the input and output |
| 18 | +// // schema of the tool. |
| 19 | +// type args struct { |
| 20 | +// Name string `json:"name" jsonschema:"the person to greet"` |
| 21 | +// } |
| 22 | +// mcp.AddTool(server, &mcp.Tool{ |
| 23 | +// Name: "greet", |
| 24 | +// Description: "say hi", |
| 25 | +// }, func(ctx context.Context, req *mcp.CallToolRequest, args args) (*mcp.CallToolResult, any, error) { |
| 26 | +// return &mcp.CallToolResult{ |
| 27 | +// Content: []mcp.Content{ |
| 28 | +// &mcp.TextContent{Text: "Hi " + args.Name}, |
| 29 | +// }, |
| 30 | +// }, nil, nil |
| 31 | +// }) |
| 32 | +// |
| 33 | +// // Run the server on the stdio transport. |
| 34 | +// if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil { |
| 35 | +// log.Printf("Server failed: %v", err) |
| 36 | +// } |
| 37 | +// |
| 38 | +// To connect to this server, use the [CommandTransport]: |
| 39 | +// |
| 40 | +// client := mcp.NewClient(&mcp.Implementation{Name: "mcp-client", Version: "v1.0.0"}, nil) |
| 41 | +// transport := &mcp.CommandTransport{Command: exec.Command("myserver")} |
| 42 | +// session, err := client.Connect(ctx, transport, nil) |
| 43 | +// if err != nil { |
| 44 | +// log.Fatal(err) |
| 45 | +// } |
| 46 | +// defer session.Close() |
| 47 | +// |
| 48 | +// params := &mcp.CallToolParams{ |
| 49 | +// Name: "greet", |
| 50 | +// Arguments: map[string]any{"name": "you"}, |
| 51 | +// } |
| 52 | +// res, err := session.CallTool(ctx, params) |
| 53 | +// if err != nil { |
| 54 | +// log.Fatalf("CallTool failed: %v", err) |
| 55 | +// } |
| 56 | +// |
| 57 | +// # Clients, servers, and sessions |
| 58 | +// |
| 59 | +// In this SDK, both a [Client] and [Server] may handle many concurrent |
| 60 | +// connections. Each time a client or server is connected to a peer using a |
| 61 | +// [Transport], it creates a new session (either a [ClientSession] or |
| 62 | +// [ServerSession]): |
12 | 63 | // |
13 | 64 | // Client Server |
14 | 65 | // ⇅ (jsonrpc2) ⇅ |
15 | 66 | // ClientSession ⇄ Client Transport ⇄ Server Transport ⇄ ServerSession |
16 | 67 | // |
17 | | -// A [Client] is an MCP client, which can be configured with various client |
18 | | -// capabilities. Clients may be connected to a [Server] instance |
19 | | -// using the [Client.Connect] method. |
20 | | -// |
21 | | -// Similarly, a [Server] is an MCP server, which can be configured with various |
22 | | -// server capabilities. Servers may be connected to one or more [Client] |
23 | | -// instances using the [Server.Connect] method, which creates a |
24 | | -// [ServerSession]. |
25 | | -// |
26 | | -// A [Transport] connects a bidirectional [Connection] of jsonrpc2 messages. In |
27 | | -// practice, transports in the MCP spec are are either client transports or |
28 | | -// server transports. For example, the [StdioTransport] is a server transport |
29 | | -// that communicates over stdin/stdout, and its counterpart is a |
30 | | -// [CommandTransport] that communicates with a subprocess over its |
31 | | -// stdin/stdout. |
32 | | -// |
33 | | -// Some transports may hide more complicated details, such as an |
34 | | -// [SSEClientTransport], which reads messages via server-sent events on a |
35 | | -// hanging GET request, and writes them to a POST endpoint. Users of this SDK |
36 | | -// may define their own custom Transports by implementing the [Transport] |
37 | | -// interface. |
| 68 | +// The session types expose an API to interact with its peer. For example, |
| 69 | +// [ClientSession.CallTool] or [ServerSession.ListRoots]. |
| 70 | +// |
| 71 | +// # Adding features |
| 72 | +// |
| 73 | +// Add MCP servers to your Client or Server using AddXXX methods (for example |
| 74 | +// [Client.AddRoot] or [Server.AddPrompt]). If any peers are connected when |
| 75 | +// AddXXX is called, they will receive a corresponding change notification |
| 76 | +// (for example notifications/roots/list_changed). |
| 77 | +// |
| 78 | +// Adding tools is special: tools may be bound to ordinary Go functions by |
| 79 | +// using the top-level generic [AddTool] function, which allows specifying an |
| 80 | +// input and output type. When AddTool is used, the tool's input schema and |
| 81 | +// output schema are automatically populated, and inputs are automatically |
| 82 | +// validated. As a special case, if the output type is 'any', no output schema |
| 83 | +// is generated. |
| 84 | +// |
| 85 | +// func double(_ context.Context, _ *mcp.CallToolRequest, in In) (*mcp.CallToolResponse, Out, error) { |
| 86 | +// return nil, Out{Answer: 2*in.Number}, nil |
| 87 | +// } |
| 88 | +// ... |
| 89 | +// mcp.AddTool(&mcp.Tool{Name: "double", Description: "double a number"}, double) |
38 | 90 | package mcp |
0 commit comments