Skip to content

Commit 78a66a4

Browse files
jbajba
authored
README for v0.2.0 (#118)
Preliminary readme for v0.2.0. We will make a GH "release" with the release notes.
1 parent 6c6243c commit 78a66a4

File tree

4 files changed

+23
-53
lines changed

4 files changed

+23
-53
lines changed

‎README.md

Lines changed: 9 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,11 @@
11
<!-- Autogenerated by weave; DO NOT EDIT -->
2-
# MCP Go SDK
2+
# MCP Go SDK v0.2.0
33

44
***BREAKING CHANGES***
55

6-
The latest version contains breaking changes:
7-
8-
- Server.AddTools is replaced by Server.AddTool.
9-
10-
- NewServerTool is replaced by AddTool. AddTool takes a Tool rather than a name and description, so you can
11-
set any field on the Tool that you want before associating it with a handler.
12-
13-
- Tool options have been removed. If you don't want AddTool to infer a JSON Schema for you, you can construct one
14-
as a struct literal, or using any other code that suits you.
15-
16-
- AddPrompts, AddResources and AddResourceTemplates are similarly replaced by singular methods which pair the
17-
feature with a handler. The ServerXXX types have been removed.
6+
This version contains breaking changes.
7+
See the [release notes](
8+
https://github.com/modelcontextprotocol/go-sdk/releases/tag/v0.2.0) for details.
189

1910
[![PkgGoDev](https://pkg.go.dev/badge/github.com/modelcontextprotocol/go-sdk)](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk)
2011

@@ -41,7 +32,7 @@ open-ended discussion. See CONTRIBUTING.md for details.
4132

4233
## Package documentation
4334

44-
The SDK consists of two importable packages:
35+
The SDK consists of three importable packages:
4536

4637
- The
4738
[`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:
5142
[`github.com/modelcontextprotocol/go-sdk/jsonschema`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonschema)
5243
package provides an implementation of [JSON
5344
Schema](https://json-schema.org/), used for MCP tool input and output schema.
45+
- The
46+
[`github.com/modelcontextprotocol/jsonrpc`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonschema) package is for users implementing
47+
their own transports.
48+
5449

5550
## Example
5651

‎design/design.md

Lines changed: 4 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -692,13 +692,9 @@ func (cs *ClientSession) CallTool(context.Context, *CallToolParams[json.RawMessa
692692
func CallTool[TArgs any](context.Context, *ClientSession, *CallToolParams[TArgs]) (*CallToolResult, error)
693693
```
694694
695-
**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.
695+
**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.
696696
697-
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.
698-
699-
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).
700-
701-
For registering tools, we provide only `AddTools`; mcp-go's `SetTools`, `AddTool`, `AddSessionTool`, and `AddSessionTools` are deemed unnecessary. (Similarly for Delete/Remove).
697+
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.
702698
703699
### Prompts
704700
@@ -722,7 +718,7 @@ server.RemovePrompts("code_review")
722718
723719
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.
724720
725-
**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.
721+
**Differences from mcp-go**: We provide `RemovePrompts` to remove prompts from the server.
726722
727723
### Resources and resource templates
728724
@@ -746,25 +742,9 @@ func (s *Server) RemoveResourceTemplates(uriTemplates ...string)
746742
747743
The `ReadResource` method finds a resource or resource template matching the argument URI and calls its associated handler.
748744
749-
To read files from the local filesystem, we recommend using `FileResourceHandler` to construct a handler:
750-
751-
```go
752-
// FileResourceHandler returns a ResourceHandler that reads paths using dir as a root directory.
753-
// It protects against path traversal attacks.
754-
// It will not read any file that is not in the root set of the client requesting the resource.
755-
func (*Server) FileResourceHandler(dir string) ResourceHandler
756-
```
757-
758-
Here is an example:
759-
760-
```go
761-
// Safely read "/public/puppies.txt".
762-
s.AddResource(&mcp.Resource{URI: "file:///puppies.txt"}, s.FileReadResourceHandler("/public"))
763-
```
764-
765745
Server sessions also support the spec methods `ListResources` and `ListResourceTemplates`, and the corresponding iterator methods `Resources` and `ResourceTemplates`.
766746
767-
**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.
747+
**Differences from mcp-go**: The `ResourceHandler` returns a `ReadResourceResult`, rather than just its content, for compatibility with future evolution of the spec.
768748
769749
#### Subscriptions
770750

‎internal/readme/README.src.md

Lines changed: 9 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,10 @@
1-
# MCP Go SDK
1+
# MCP Go SDK v0.2.0
22

33
***BREAKING CHANGES***
44

5-
The latest version contains breaking changes:
6-
7-
- Server.AddTools is replaced by Server.AddTool.
8-
9-
- NewServerTool is replaced by AddTool. AddTool takes a Tool rather than a name and description, so you can
10-
set any field on the Tool that you want before associating it with a handler.
11-
12-
- Tool options have been removed. If you don't want AddTool to infer a JSON Schema for you, you can construct one
13-
as a struct literal, or using any other code that suits you.
14-
15-
- AddPrompts, AddResources and AddResourceTemplates are similarly replaced by singular methods which pair the
16-
feature with a handler. The ServerXXX types have been removed.
5+
This version contains breaking changes.
6+
See the [release notes](
7+
https://github.com/modelcontextprotocol/go-sdk/releases/tag/v0.2.0) for details.
178

189
[![PkgGoDev](https://pkg.go.dev/badge/github.com/modelcontextprotocol/go-sdk)](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk)
1910

@@ -40,7 +31,7 @@ open-ended discussion. See CONTRIBUTING.md for details.
4031

4132
## Package documentation
4233

43-
The SDK consists of two importable packages:
34+
The SDK consists of three importable packages:
4435

4536
- The
4637
[`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:
5041
[`github.com/modelcontextprotocol/go-sdk/jsonschema`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonschema)
5142
package provides an implementation of [JSON
5243
Schema](https://json-schema.org/), used for MCP tool input and output schema.
44+
- The
45+
[`github.com/modelcontextprotocol/jsonrpc`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonschema) package is for users implementing
46+
their own transports.
47+
5348

5449
## Example
5550

‎mcp/server.go

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -388,7 +388,7 @@ func (s *Server) lookupResourceHandler(uri string) (ResourceHandler, string, boo
388388
// The dir argument should be a filesystem path. It need not be absolute, but
389389
// that is recommended to avoid a dependency on the current working directory (the
390390
// check against client roots is done with an absolute path). If dir is not absolute
391-
// and the current working directory is unavailable, FileResourceHandler panics.
391+
// and the current working directory is unavailable, fileResourceHandler panics.
392392
//
393393
// Lexical path traversal attacks, where the path has ".." elements that escape dir,
394394
// are always caught. Go 1.24 and above also protects against symlink-based attacks,

0 commit comments

Comments
 (0)