README for v0.2.0 (#118)
Preliminary readme for v0.2.0. We will make a GH "release" with the release notes.
This commit is contained in:
Jonathan Amsterdam
GitHub
parent
6c6243c0b0
commit
78a66a438a
4 changed files with 23 additions and 53 deletions
23
README.md
23
README.md
|
|
@ -1,20 +1,11 @@
|
|||
<!-- Autogenerated by weave; DO NOT EDIT -->
|
||||
# MCP Go SDK
|
||||
# MCP Go SDK v0.2.0
|
||||
|
||||
***BREAKING CHANGES***
|
||||
|
||||
The latest version contains breaking changes:
|
||||
|
||||
- Server.AddTools is replaced by Server.AddTool.
|
||||
|
||||
- NewServerTool is replaced by AddTool. AddTool takes a Tool rather than a name and description, so you can
|
||||
set any field on the Tool that you want before associating it with a handler.
|
||||
|
||||
- Tool options have been removed. If you don't want AddTool to infer a JSON Schema for you, you can construct one
|
||||
as a struct literal, or using any other code that suits you.
|
||||
|
||||
- AddPrompts, AddResources and AddResourceTemplates are similarly replaced by singular methods which pair the
|
||||
feature with a handler. The ServerXXX types have been removed.
|
||||
This version contains breaking changes.
|
||||
See the [release notes](
|
||||
https://github.com/modelcontextprotocol/go-sdk/releases/tag/v0.2.0) for details.
|
||||
|
||||
[](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk)
|
||||
|
||||
|
|
@ -41,7 +32,7 @@ open-ended discussion. See CONTRIBUTING.md for details.
|
|||
|
||||
## Package documentation
|
||||
|
||||
The SDK consists of two importable packages:
|
||||
The SDK consists of three importable packages:
|
||||
|
||||
- The
|
||||
[`github.com/modelcontextprotocol/go-sdk/mcp`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp)
|
||||
|
|
@ -51,6 +42,10 @@ The SDK consists of two importable packages:
|
|||
[`github.com/modelcontextprotocol/go-sdk/jsonschema`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonschema)
|
||||
package provides an implementation of [JSON
|
||||
Schema](https://json-schema.org/), used for MCP tool input and output schema.
|
||||
- The
|
||||
[`github.com/modelcontextprotocol/jsonrpc`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonschema) package is for users implementing
|
||||
their own transports.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
|
|
|
|||
|
|
@ -692,13 +692,9 @@ func (cs *ClientSession) CallTool(context.Context, *CallToolParams[json.RawMessa
|
|||
func CallTool[TArgs any](context.Context, *ClientSession, *CallToolParams[TArgs]) (*CallToolResult, error)
|
||||
```
|
||||
|
||||
**Differences from mcp-go**: using variadic options to configure tools was significantly inspired by mcp-go. However, the distinction between `ToolOption` and `SchemaOption` allows for recursive application of schema options. For example, that limitation is visible in [this code](https://github.com/DCjanus/dida365-mcp-server/blob/master/cmd/mcp/tools.go#L315), which must resort to untyped maps to express a nested schema.
|
||||
**Differences from mcp-go**: We provide a full JSON Schema implementation for validating tool input schemas against incoming arguments. The `jsonschema.Schema` type provides exported features for all keywords in the JSON Schema draft2020-12 spec. Tool definers can use it to construct any schema they want. The `jsonschema.For[T]` function can infer a schema from a Go struct. These combined features eliminate the need for variadic arguments to construct tool schemas.
|
||||
|
||||
Additionally, the `NewServerTool` helper provides a means for building a tool from a Go function using reflection, that automatically handles parsing and validation of inputs.
|
||||
|
||||
We provide a full JSON Schema implementation for validating tool input schemas against incoming arguments. The `jsonschema.Schema` type provides exported features for all keywords in the JSON Schema draft2020-12 spec. Tool definers can use it to construct any schema they want, so there is no need to provide options for all of them. When combined with schema inference from input structs, we found that we needed only three options to cover the common cases, instead of mcp-go's 23. For example, we will provide `Enum`, which occurs 125 times in open source code, but not MinItems, MinLength or MinProperties, which each occur only once (and in an SDK that wraps mcp-go).
|
||||
|
||||
For registering tools, we provide only `AddTools`; mcp-go's `SetTools`, `AddTool`, `AddSessionTool`, and `AddSessionTools` are deemed unnecessary. (Similarly for Delete/Remove).
|
||||
For registering tools, we provide only a `Server.AddTool` method; mcp-go's `SetTools`, `AddTool`, `AddSessionTool`, and `AddSessionTools` are deemed unnecessary. (Similarly for Delete/Remove). The `AddTool` generic function combines schema inference with registration, providing a easy way to register many tools.
|
||||
|
||||
### Prompts
|
||||
|
||||
|
|
@ -722,7 +718,7 @@ server.RemovePrompts("code_review")
|
|||
|
||||
Client sessions can call the spec method `ListPrompts` or the iterator method `Prompts` to list the available prompts, and the spec method `GetPrompt` to get one.
|
||||
|
||||
**Differences from mcp-go**: We provide a `NewServerPrompt` helper to bind a prompt handler to a Go function using reflection to derive its arguments. We provide `RemovePrompts` to remove prompts from the server.
|
||||
**Differences from mcp-go**: We provide `RemovePrompts` to remove prompts from the server.
|
||||
|
||||
### Resources and resource templates
|
||||
|
||||
|
|
@ -746,25 +742,9 @@ func (s *Server) RemoveResourceTemplates(uriTemplates ...string)
|
|||
|
||||
The `ReadResource` method finds a resource or resource template matching the argument URI and calls its associated handler.
|
||||
|
||||
To read files from the local filesystem, we recommend using `FileResourceHandler` to construct a handler:
|
||||
|
||||
```go
|
||||
// FileResourceHandler returns a ResourceHandler that reads paths using dir as a root directory.
|
||||
// It protects against path traversal attacks.
|
||||
// It will not read any file that is not in the root set of the client requesting the resource.
|
||||
func (*Server) FileResourceHandler(dir string) ResourceHandler
|
||||
```
|
||||
|
||||
Here is an example:
|
||||
|
||||
```go
|
||||
// Safely read "/public/puppies.txt".
|
||||
s.AddResource(&mcp.Resource{URI: "file:///puppies.txt"}, s.FileReadResourceHandler("/public"))
|
||||
```
|
||||
|
||||
Server sessions also support the spec methods `ListResources` and `ListResourceTemplates`, and the corresponding iterator methods `Resources` and `ResourceTemplates`.
|
||||
|
||||
**Differences from mcp-go**: for symmetry with tools and prompts, we use `AddResources` rather than `AddResource`. Additionally, the `ResourceHandler` returns a `ReadResourceResult`, rather than just its content, for compatibility with future evolution of the spec.
|
||||
**Differences from mcp-go**: The `ResourceHandler` returns a `ReadResourceResult`, rather than just its content, for compatibility with future evolution of the spec.
|
||||
|
||||
#### Subscriptions
|
||||
|
||||
|
|
|
|||
|
|
@ -1,19 +1,10 @@
|
|||
# MCP Go SDK
|
||||
# MCP Go SDK v0.2.0
|
||||
|
||||
***BREAKING CHANGES***
|
||||
|
||||
The latest version contains breaking changes:
|
||||
|
||||
- Server.AddTools is replaced by Server.AddTool.
|
||||
|
||||
- NewServerTool is replaced by AddTool. AddTool takes a Tool rather than a name and description, so you can
|
||||
set any field on the Tool that you want before associating it with a handler.
|
||||
|
||||
- Tool options have been removed. If you don't want AddTool to infer a JSON Schema for you, you can construct one
|
||||
as a struct literal, or using any other code that suits you.
|
||||
|
||||
- AddPrompts, AddResources and AddResourceTemplates are similarly replaced by singular methods which pair the
|
||||
feature with a handler. The ServerXXX types have been removed.
|
||||
This version contains breaking changes.
|
||||
See the [release notes](
|
||||
https://github.com/modelcontextprotocol/go-sdk/releases/tag/v0.2.0) for details.
|
||||
|
||||
[](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk)
|
||||
|
||||
|
|
@ -40,7 +31,7 @@ open-ended discussion. See CONTRIBUTING.md for details.
|
|||
|
||||
## Package documentation
|
||||
|
||||
The SDK consists of two importable packages:
|
||||
The SDK consists of three importable packages:
|
||||
|
||||
- The
|
||||
[`github.com/modelcontextprotocol/go-sdk/mcp`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp)
|
||||
|
|
@ -50,6 +41,10 @@ The SDK consists of two importable packages:
|
|||
[`github.com/modelcontextprotocol/go-sdk/jsonschema`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonschema)
|
||||
package provides an implementation of [JSON
|
||||
Schema](https://json-schema.org/), used for MCP tool input and output schema.
|
||||
- The
|
||||
[`github.com/modelcontextprotocol/jsonrpc`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonschema) package is for users implementing
|
||||
their own transports.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
|
|
|
|||
|
|
@ -388,7 +388,7 @@ func (s *Server) lookupResourceHandler(uri string) (ResourceHandler, string, boo
|
|||
// The dir argument should be a filesystem path. It need not be absolute, but
|
||||
// that is recommended to avoid a dependency on the current working directory (the
|
||||
// check against client roots is done with an absolute path). If dir is not absolute
|
||||
// and the current working directory is unavailable, FileResourceHandler panics.
|
||||
// and the current working directory is unavailable, fileResourceHandler panics.
|
||||
//
|
||||
// Lexical path traversal attacks, where the path has ".." elements that escape dir,
|
||||
// are always caught. Go 1.24 and above also protects against symlink-based attacks,
|
||||
|
|
|
|||
Loading…
Reference in a new issue