modelcontextprotocol/go-sdk
Watch
1
0
Fork
You've already forked go-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1

internal/mcp: update CONTRIBUTING.md and README.md for the official SDK

Browse source 
Change CONTRIBUTING.md and README.md to reflect that the MCP SDK is
being moved to github.com/modelcontextprotocol/go-sdk, and to include
content from the 'Governance' section of the design doc. Also, include
the antitrust policy as a section in CONTRIBUTING.md.

Change-Id: I46784d8e57b2a2cab8895593f633d20a2e15c8ba
Reviewed-on: https://go-review.googlesource.com/c/tools/+/682976
Reviewed-by: Sam Thanawalla <samthanawalla@google.com>
Auto-Submit: Robert Findley <rfindley@google.com>
Reviewed-by: Alan Donovan <adonovan@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
This commit is contained in:
Rob Findley 2025-06-20 18:34:41 +00:00 • committed by Gopher Robot
commit f4ed9b5904
1 changed files with 408 additions and 109 deletions
Download patch file Download diff file Expand all files Collapse all files

129
README.md
View file

@ -1,32 +1,43 @@
<!-- Autogenerated by weave; DO NOT EDIT -->
# MCP Go SDK
# MCP SDK prototype
<!-- TODO: update pkgsite links here to point to the modelcontextprotocol
module, once it exists. -->
[![PkgGoDev](https://pkg.go.dev/badge/golang.org/x/tools)](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp)
[![PkgGoDev](https://pkg.go.dev/badge/golang.org/x/tools)](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk)
# Contents
This repository contains an implementation of the official Go software
development kit (SDK) for the Model Context Protocol (MCP).
1. [Installation](#installation)
1. [Quickstart](#quickstart)
1. [Design](#design)
1. [Testing](#testing)
1. [Code of Conduct](#code-of-conduct)
1. [License](#license)
**WARNING**: The SDK is currently unstable and subject to breaking changes.
Please test it out and file bug reports or API proposals. The [TODO](#todo)
section below outlines outstanding release blockers. We aim to release a stable
version of the SDK in mid July, 2025.
The mcp package provides a software development kit (SDK) for writing clients
and servers of the [model context
protocol](https://modelcontextprotocol.io/introduction). It is unstable, and
will change in breaking ways in the future. As of writing, it is a prototype to
explore the design space of client/server transport and binding.
1. [Package documentation](#package-documentation)
1. [Example](#example)
1. [TODO](#todo)
1. [Design](#design)
1. [Acknowledgements](#acknowledgements)
1. [License](#license)
# Installation
## Package documentation
The mcp package is currently internal and cannot be imported using `go get`.
The SDK consists of two importable packages:
# Quickstart
- The
[`github.com/modelcontextprotocol/go-sdk/mcp`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp)
package defines the primary APIs for constructing and using MCP clients and
servers.
- The
[`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.
Here's an example that creates a client that talks to an MCP server running
as a sidecar process:
## Example
In this example, an MCP client communicates with an MCP server running in a
sidecar process:
```go
package main
@ -41,8 +52,10 @@ import (
func main() {
ctx := context.Background()
// Create a new client, with no features.
client := mcp.NewClient("mcp-client", "v1.0.0", nil)
// Connect to a server over stdin/stdout
transport := mcp.NewCommandTransport(exec.Command("myserver"))
session, err := client.Connect(ctx, transport)
@ -50,31 +63,34 @@ func main() {
log.Fatal(err)
}
defer session.Close()
// Call a tool on the server.
params := &mcp.CallToolParams{
Name: "greet",
Arguments: map[string]any{"name": "you"},
}
if res, err := session.CallTool(ctx, params); err != nil {
log.Printf("CallTool failed: %v", err)
} else {
if res.IsError {
log.Print("tool failed")
}
for _, c := range res.Content {
log.Print(c.Text)
}
res, err := session.CallTool(ctx, params)
if err != nil {
log.Fatalf("CallTool failed: %v", err)
}
if res.IsError {
log.Fatal("tool failed")
}
for _, c := range res.Content {
log.Print(c.Text)
}
}
```
Here is an example of the corresponding server, connected over stdin/stdout:
Here's an example of the corresponding server component, which communicates
with its client over stdin/stdout:
```go
package main
import (
"context"
"log"
"github.com/modelcontextprotocol/go-sdk/mcp"
)
@ -83,8 +99,8 @@ type HiParams struct {
Name string `json:"name"`
}
func SayHi(ctx context.Context, cc *mcp.ServerSession, params *mcp.CallToolParamsFor[HiParams]) (*mcp.CallToolResultFor[string], error) {
return &mcp.CallToolResultFor[string]{
func SayHi(ctx context.Context, cc *mcp.ServerSession, params *mcp.CallToolParamsFor[HiParams]) (*mcp.CallToolResultFor[any], error) {
return &mcp.CallToolResultFor[any]{
Content: []*mcp.Content{mcp.NewTextContent("Hi " + params.Name)},
}, nil
}
@ -94,35 +110,46 @@ func main() {
server := mcp.NewServer("greeter", "v1.0.0", nil)
server.AddTools(mcp.NewServerTool("greet", "say hi", SayHi))
// Run the server over stdin/stdout, until the client disconnects
_ = server.Run(context.Background(), mcp.NewStdIOTransport())
if err := server.Run(context.Background(), mcp.NewStdIOTransport()); err != nil {
log.Fatal(err)
}
}
```
# Design
The `examples/` directory contains more example clients and servers.
See [design.md](./design/design.md) for the SDK design. That document is
canonical: given any divergence between the design doc and this prototype, the
doc reflects the latest design.
## TODO
# Testing
The following TODOs block the release of this SDK:
To test your client or server using stdio transport, you can use an in-memory
transport. See [example](server_example_test.go).
- Better support for resumability in the Streamable HTTP transport: a
server-side event store and client-side retry configuration.
- OAuth support (or examples of implementing OAuth using middleware).
- Support for the changes in the
[2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18/changelog)
version of the MCP spec.
- More examples and documentation.
To test your client or server using sse transport, you can use the [httptest](https://pkg.go.dev/net/http/httptest)
package. See [example](sse_example_test.go).
## Design
# Code of Conduct
The design doc for this SDK is at [design.md](./design/design.md), which was
initially reviewed at
[modelcontextprotocol/discussions/364](https://github.com/orgs/modelcontextprotocol/discussions/364).
This project follows the [Go Community Code of Conduct](https://go.dev/conduct).
If you encounter a conduct-related issue, please mail conduct@golang.org.
Further design discussion should occur in GitHub issues. See CONTRIBUTING.md
for details.
# License
## Acknowledgements
Unless otherwise noted, the Go source files are distributed under the BSD-style
license found in the [LICENSE](../../LICENSE) file.
Several existing Go MCP SDKs inspired the development and design of this
official SDK, notably [mcp-go](https://github.com/mark3labs/mcp-go), authored
by Ed Zynda. We are grateful to Ed as well as the other contributors to mcp-go,
and to authors and contributors of other SDKs such as
[mcp-golang](https://github.com/metoro-io/mcp-golang) and
[go-mcp](https://github.com/ThinkInAIXYZ/go-mcp). Thanks to their work, there
is a thriving ecosystem of Go MCP clients and servers.
Upon a potential move to the
[modelcontextprotocol](https://github.com/modelcontextprotocol) organization,
the license will be updated to the MIT License, and the license header will
reflect the Go MCP SDK Authors.
## License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE)
file for details.