Add documentation backed by mkdocs (#883)
Affects /docs - (Refined Documentation for deployment and added Some Supporting documentation) Added a github action for deployment Fixes #835 Added Support for mkdocs Example - https://dinesht04.github.io/go-sdk/ Requires Configuration of Github pages as follows:- 1. Enable Github Pages 2. Select gh-pages branch for deployment <img width="1237" height="817" alt="gh-pages" src="https://github.com/user-attachments/assets/01f0b012-d5f3-4011-9af9-7269e657ae6a" /> ## Sources # For mkdocs.yaml 1. https://github.com/modelcontextprotocol/python-sdk/blob/main/mkdocs.yml 2. https://github.com/modelcontextprotocol/java-sdk/blob/main/mkdocs.yml 3. MKDocs official documentation # For Github Action 1. https://github.com/modelcontextprotocol/python-sdk/blob/main/.github/workflows/publish-docs-manually.yml 2. https://github.com/modelcontextprotocol/java-sdk/blob/main/.github/workflows/docs.yml 3. https://github.com/james-willett/material-mkdocs-youtube-2024/blob/main/.github/workflows/ci.yml - From Youtube Tutorial
This commit is contained in:
parent
f36591bf8a
commit
1209861858
21 changed files with 624 additions and 42 deletions
27
.github/workflows/publish-docs.yml
vendored
27
.github/workflows/publish-docs.yml
vendored
|
|
@ -1,4 +1,4 @@
|
||||||
name: Publish Docs to GitHub Pages
|
name: Publish Docs
|
||||||
|
|
||||||
on:
|
on:
|
||||||
release:
|
release:
|
||||||
|
|
@ -13,13 +13,20 @@ jobs:
|
||||||
contents: write
|
contents: write
|
||||||
runs-on: ubuntu-latest
|
runs-on: ubuntu-latest
|
||||||
steps:
|
steps:
|
||||||
- name: Check out code
|
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
||||||
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
|
- name: Configure Git Credentials
|
||||||
- name: Deploy to GitHub Pages
|
run: |
|
||||||
uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
|
git config user.name github-actions[bot]
|
||||||
|
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
|
||||||
|
- uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
|
||||||
with:
|
with:
|
||||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
python-version: 3.x
|
||||||
publish_dir: ./docs
|
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
|
||||||
publish_branch: gh-pages
|
- uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
|
||||||
enable_jekyll: true
|
with:
|
||||||
cname: go.sdk.modelcontextprotocol.io
|
key: mkdocs-material-${{ env.cache_id }}
|
||||||
|
path: .cache
|
||||||
|
restore-keys: |
|
||||||
|
mkdocs-material-
|
||||||
|
- run: pip install mkdocs-material
|
||||||
|
- run: mkdocs gh-deploy --force
|
||||||
|
|
|
||||||
|
|
@ -1,3 +1,4 @@
|
||||||
|
<!-- Autogenerated by weave; DO NOT EDIT -->
|
||||||
# Contributing to the Go MCP SDK
|
# Contributing to the Go MCP SDK
|
||||||
|
|
||||||
Thank you for your interest in contributing! The Go SDK needs active
|
Thank you for your interest in contributing! The Go SDK needs active
|
||||||
|
|
@ -6,11 +7,28 @@ new and emerging use-cases. We welcome all forms of contribution, from filing
|
||||||
and reviewing issues, to contributing fixes, to proposing and implementing new
|
and reviewing issues, to contributing fixes, to proposing and implementing new
|
||||||
features.
|
features.
|
||||||
|
|
||||||
As described in the [design document](./design/design.md), it is important for
|
As described in the [design document](https://github.com/modelcontextprotocol/go-sdk/blob/main/design/design.md), it is important for
|
||||||
the MCP SDK to remain idiomatic, future-proof, and extensible. The process
|
the MCP SDK to remain idiomatic, future-proof, and extensible. The process
|
||||||
described here is intended to ensure that the SDK evolves safely and
|
described here is intended to ensure that the SDK evolves safely and
|
||||||
transparently, while adhering to these goals.
|
transparently, while adhering to these goals.
|
||||||
|
|
||||||
|
1. [Development setup](#development-setup)
|
||||||
|
1. [Conformance tests](#conformance-tests)
|
||||||
|
1. [Filing issues](#filing-issues)
|
||||||
|
1. [Bugs](#bugs)
|
||||||
|
1. [Proposals](#proposals)
|
||||||
|
1. [Design discussion](#design-discussion)
|
||||||
|
1. [Contributing code](#contributing-code)
|
||||||
|
1. [Adding and updating dependencies](#adding-and-updating-dependencies)
|
||||||
|
1. [Updating the README](#updating-the-readme)
|
||||||
|
1. [Timeouts](#timeouts)
|
||||||
|
1. [Code of conduct](#code-of-conduct)
|
||||||
|
1. [Governance](#governance)
|
||||||
|
1. [Working Group meetings](#working-group-meetings)
|
||||||
|
1. [Discord](#discord)
|
||||||
|
1. [Antitrust considerations](#antitrust-considerations)
|
||||||
|
|
||||||
|
|
||||||
## Development setup
|
## Development setup
|
||||||
|
|
||||||
This module can be built and tested using the standard Go toolchain. Run `go
|
This module can be built and tested using the standard Go toolchain. Run `go
|
||||||
|
|
|
||||||
1
docs/CNAME
Normal file
1
docs/CNAME
Normal file
|
|
@ -0,0 +1 @@
|
||||||
|
go.sdk.modelcontextprotocol.io
|
||||||
|
|
@ -1,5 +1,22 @@
|
||||||
<!-- Autogenerated by weave; DO NOT EDIT -->
|
<!-- Autogenerated by weave; DO NOT EDIT -->
|
||||||
# Features
|
# Overview
|
||||||
|
|
||||||
|
The SDK consists of several importable packages:
|
||||||
|
|
||||||
|
- 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/jsonrpc`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonrpc) package is for users implementing
|
||||||
|
their own transports.
|
||||||
|
- The
|
||||||
|
[`github.com/modelcontextprotocol/go-sdk/auth`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth)
|
||||||
|
package provides some primitives for supporting OAuth.
|
||||||
|
- The
|
||||||
|
[`github.com/modelcontextprotocol/go-sdk/oauthex`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/oauthex)
|
||||||
|
package provides extensions to the OAuth protocol, such as ProtectedResourceMetadata.
|
||||||
|
|
||||||
|
|
||||||
These docs mirror the [official MCP spec](https://modelcontextprotocol.io/specification/2025-06-18).
|
These docs mirror the [official MCP spec](https://modelcontextprotocol.io/specification/2025-06-18).
|
||||||
Use the index below to learn how the SDK implements a particular aspect of the
|
Use the index below to learn how the SDK implements a particular aspect of the
|
||||||
|
|
|
||||||
1
docs/contributing.md
Normal file
1
docs/contributing.md
Normal file
|
|
@ -0,0 +1 @@
|
||||||
|
--8<-- "CONTRIBUTING.md"
|
||||||
12
docs/images/logo-dark.svg
Normal file
12
docs/images/logo-dark.svg
Normal file
|
|
@ -0,0 +1,12 @@
|
||||||
|
<svg width="180" height="180" viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||||
|
<g clip-path="url(#clip0_19_13)">
|
||||||
|
<path d="M18 84.8528L85.8822 16.9706C95.2548 7.59798 110.451 7.59798 119.823 16.9706V16.9706C129.196 26.3431 129.196 41.5391 119.823 50.9117L68.5581 102.177" stroke="black" stroke-width="12" stroke-linecap="round"/>
|
||||||
|
<path d="M69.2652 101.47L119.823 50.9117C129.196 41.5391 144.392 41.5391 153.765 50.9117L154.118 51.2652C163.491 60.6378 163.491 75.8338 154.118 85.2063L92.7248 146.6C89.6006 149.724 89.6006 154.789 92.7248 157.913L105.331 170.52" stroke="black" stroke-width="12" stroke-linecap="round"/>
|
||||||
|
<path d="M102.853 33.9411L52.6482 84.1457C43.2756 93.5183 43.2756 108.714 52.6482 118.087V118.087C62.0208 127.459 77.2167 127.459 86.5893 118.087L136.794 67.8822" stroke="black" stroke-width="12" stroke-linecap="round"/>
|
||||||
|
</g>
|
||||||
|
<defs>
|
||||||
|
<clipPath id="clip0_19_13">
|
||||||
|
<rect width="180" height="180" fill="white"/>
|
||||||
|
</clipPath>
|
||||||
|
</defs>
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 973 B |
69
docs/images/logo-light.svg
Normal file
69
docs/images/logo-light.svg
Normal file
|
|
@ -0,0 +1,69 @@
|
||||||
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||||
|
<svg
|
||||||
|
width="180"
|
||||||
|
height="180"
|
||||||
|
viewBox="0 0 180 180"
|
||||||
|
fill="none"
|
||||||
|
version="1.1"
|
||||||
|
id="svg3"
|
||||||
|
sodipodi:docname="Model_Context_Protocol_logo copy 2.svg"
|
||||||
|
inkscape:version="1.3.2 (091e20e, 2023-11-25)"
|
||||||
|
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
|
||||||
|
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
|
||||||
|
xmlns="http://www.w3.org/2000/svg"
|
||||||
|
xmlns:svg="http://www.w3.org/2000/svg">
|
||||||
|
<sodipodi:namedview
|
||||||
|
id="namedview3"
|
||||||
|
pagecolor="#ffffff"
|
||||||
|
bordercolor="#000000"
|
||||||
|
borderopacity="0.25"
|
||||||
|
inkscape:showpageshadow="2"
|
||||||
|
inkscape:pageopacity="0.0"
|
||||||
|
inkscape:pagecheckerboard="0"
|
||||||
|
inkscape:deskcolor="#d1d1d1"
|
||||||
|
inkscape:zoom="1.3111111"
|
||||||
|
inkscape:cx="89.618644"
|
||||||
|
inkscape:cy="89.618644"
|
||||||
|
inkscape:window-width="1728"
|
||||||
|
inkscape:window-height="944"
|
||||||
|
inkscape:window-x="0"
|
||||||
|
inkscape:window-y="38"
|
||||||
|
inkscape:window-maximized="0"
|
||||||
|
inkscape:current-layer="svg3" />
|
||||||
|
<g
|
||||||
|
clip-path="url(#clip0_19_13)"
|
||||||
|
id="g3">
|
||||||
|
<path
|
||||||
|
d="M18 84.8528L85.8822 16.9706C95.2548 7.59798 110.451 7.59798 119.823 16.9706V16.9706C129.196 26.3431 129.196 41.5391 119.823 50.9117L68.5581 102.177"
|
||||||
|
stroke="black"
|
||||||
|
stroke-width="12"
|
||||||
|
stroke-linecap="round"
|
||||||
|
id="path1"
|
||||||
|
style="stroke:#ffffff;stroke-opacity:1" />
|
||||||
|
<path
|
||||||
|
d="M69.2652 101.47L119.823 50.9117C129.196 41.5391 144.392 41.5391 153.765 50.9117L154.118 51.2652C163.491 60.6378 163.491 75.8338 154.118 85.2063L92.7248 146.6C89.6006 149.724 89.6006 154.789 92.7248 157.913L105.331 170.52"
|
||||||
|
stroke="black"
|
||||||
|
stroke-width="12"
|
||||||
|
stroke-linecap="round"
|
||||||
|
id="path2"
|
||||||
|
style="stroke:#ffffff;stroke-opacity:1" />
|
||||||
|
<path
|
||||||
|
d="M102.853 33.9411L52.6482 84.1457C43.2756 93.5183 43.2756 108.714 52.6482 118.087V118.087C62.0208 127.459 77.2167 127.459 86.5893 118.087L136.794 67.8822"
|
||||||
|
stroke="black"
|
||||||
|
stroke-width="12"
|
||||||
|
stroke-linecap="round"
|
||||||
|
id="path3"
|
||||||
|
style="stroke:#ffffff;stroke-opacity:1" />
|
||||||
|
</g>
|
||||||
|
<defs
|
||||||
|
id="defs3">
|
||||||
|
<clipPath
|
||||||
|
id="clip0_19_13">
|
||||||
|
<rect
|
||||||
|
width="180"
|
||||||
|
height="180"
|
||||||
|
fill="white"
|
||||||
|
id="rect3" />
|
||||||
|
</clipPath>
|
||||||
|
</defs>
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 2.3 KiB |
|
|
@ -1,15 +0,0 @@
|
||||||
---
|
|
||||||
---
|
|
||||||
<!DOCTYPE html>
|
|
||||||
<html>
|
|
||||||
<head>
|
|
||||||
<meta charset="utf-8">
|
|
||||||
<title>MCP Go SDK Documentation</title>
|
|
||||||
<meta http-equiv="refresh" content="0; url=https://github.com/modelcontextprotocol/go-sdk/blob/{{ site.github.latest_release.tag_name }}/docs/README.md">
|
|
||||||
<link rel="canonical" href="https://github.com/modelcontextprotocol/go-sdk/blob/{{ site.github.latest_release.tag_name }}/docs/README.md">
|
|
||||||
</head>
|
|
||||||
<body>
|
|
||||||
<p>Redirecting to <a href="https://github.com/modelcontextprotocol/go-sdk/blob/{{ site.github.latest_release.tag_name }}/docs/README.md">MCP Go SDK documentation ({{ site.github.latest_release.tag_name }})</a>...</p>
|
|
||||||
<p>For API reference, see <a href="https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk">pkg.go.dev</a>.</p>
|
|
||||||
</body>
|
|
||||||
</html>
|
|
||||||
|
|
@ -1,5 +1,5 @@
|
||||||
<!-- Autogenerated by weave; DO NOT EDIT -->
|
<!-- Autogenerated by weave; DO NOT EDIT -->
|
||||||
# Backwards compatibility and MCPGODEBUG
|
# Backwards compatibility and MCPGODEBUG
|
||||||
|
|
||||||
According to our compatibility promise, we can't break backward compatibility
|
According to our compatibility promise, we can't break backward compatibility
|
||||||
of the SDK API. However, sometimes we need to change the behavior of the SDK
|
of the SDK API. However, sometimes we need to change the behavior of the SDK
|
||||||
|
|
|
||||||
|
|
@ -13,7 +13,7 @@
|
||||||
1. [Security](#security)
|
1. [Security](#security)
|
||||||
1. [Confused Deputy](#confused-deputy)
|
1. [Confused Deputy](#confused-deputy)
|
||||||
1. [Token Passthrough](#token-passthrough)
|
1. [Token Passthrough](#token-passthrough)
|
||||||
1. [Server-Side Request Forgery (SSRF)](#server-side-request-forgery-(ssrf))
|
1. [Server-Side Request Forgery](#server-side-request-forgery)
|
||||||
1. [Session Hijacking](#session-hijacking)
|
1. [Session Hijacking](#session-hijacking)
|
||||||
1. [Utilities](#utilities)
|
1. [Utilities](#utilities)
|
||||||
1. [Cancellation](#cancellation)
|
1. [Cancellation](#cancellation)
|
||||||
|
|
@ -218,7 +218,7 @@ to see the logical session
|
||||||
> modelcontextprotocol/modelcontextprotocol#1372, or
|
> modelcontextprotocol/modelcontextprotocol#1372, or
|
||||||
> modelcontextprotocol/modelcontextprotocol#1442 for potential refinements.
|
> modelcontextprotocol/modelcontextprotocol#1442 for potential refinements.
|
||||||
|
|
||||||
_See [examples/server/distributed](../examples/server/distributed/main.go) for
|
_See [examples/server/distributed](https://github.com/modelcontextprotocol/go-sdk/blob/main/examples/server/distributed/main.go) for
|
||||||
an example using stateless mode to implement a server distributed across
|
an example using stateless mode to implement a server distributed across
|
||||||
multiple processes._
|
multiple processes._
|
||||||
|
|
||||||
|
|
@ -230,7 +230,7 @@ by implementing the
|
||||||
[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
|
[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
|
||||||
interface: a logical bidirectional stream of JSON-RPC messages.
|
interface: a logical bidirectional stream of JSON-RPC messages.
|
||||||
|
|
||||||
_Full example: [examples/server/custom-transport](../examples/server/custom-transport/main.go)._
|
_Full example: [examples/server/custom-transport](https://github.com/modelcontextprotocol/go-sdk/blob/main//examples/server/custom-transport/main.go)._
|
||||||
|
|
||||||
### Concurrency
|
### Concurrency
|
||||||
|
|
||||||
|
|
@ -443,7 +443,7 @@ of tokens and is the responsibility of the
|
||||||
provided to
|
provided to
|
||||||
[`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
|
[`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
|
||||||
|
|
||||||
### Server-Side Request Forgery (SSRF)
|
### Server-Side Request Forgery
|
||||||
|
|
||||||
The [mitigations](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices#mitigation-3) are as follows:
|
The [mitigations](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices#mitigation-3) are as follows:
|
||||||
|
|
||||||
|
|
|
||||||
105
docs/quick_start.md
Normal file
105
docs/quick_start.md
Normal file
|
|
@ -0,0 +1,105 @@
|
||||||
|
<!-- Autogenerated by weave; DO NOT EDIT -->
|
||||||
|
# Quick Start
|
||||||
|
|
||||||
|
1. [Installation](#installation)
|
||||||
|
1. [Getting started](#getting-started)
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```
|
||||||
|
go get github.com/modelcontextprotocol/go-sdk
|
||||||
|
```
|
||||||
|
|
||||||
|
## Getting started
|
||||||
|
|
||||||
|
To get started creating an MCP server, create an `mcp.Server` instance, add
|
||||||
|
features to it, and then run it over an `mcp.Transport`. For example, this
|
||||||
|
server adds a single simple tool, and then connects it to clients over
|
||||||
|
stdin/stdout:
|
||||||
|
|
||||||
|
```go
|
||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"log"
|
||||||
|
|
||||||
|
"github.com/modelcontextprotocol/go-sdk/mcp"
|
||||||
|
)
|
||||||
|
|
||||||
|
type Input struct {
|
||||||
|
Name string `json:"name" jsonschema:"the name of the person to greet"`
|
||||||
|
}
|
||||||
|
|
||||||
|
type Output struct {
|
||||||
|
Greeting string `json:"greeting" jsonschema:"the greeting to tell to the user"`
|
||||||
|
}
|
||||||
|
|
||||||
|
func SayHi(ctx context.Context, req *mcp.CallToolRequest, input Input) (
|
||||||
|
*mcp.CallToolResult,
|
||||||
|
Output,
|
||||||
|
error,
|
||||||
|
) {
|
||||||
|
return nil, Output{Greeting: "Hi " + input.Name}, nil
|
||||||
|
}
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
// Create a server with a single tool.
|
||||||
|
server := mcp.NewServer(&mcp.Implementation{Name: "greeter", Version: "v1.0.0"}, nil)
|
||||||
|
mcp.AddTool(server, &mcp.Tool{Name: "greet", Description: "say hi"}, SayHi)
|
||||||
|
// Run the server over stdin/stdout, until the client disconnects.
|
||||||
|
if err := server.Run(context.Background(), &mcp.StdioTransport{}); err != nil {
|
||||||
|
log.Fatal(err)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
To communicate with that server, create an `mcp.Client` and connect it to the
|
||||||
|
corresponding server, by running the server command and communicating over its
|
||||||
|
stdin/stdout:
|
||||||
|
|
||||||
|
```go
|
||||||
|
package main
|
||||||
|
|
||||||
|
import (
|
||||||
|
"context"
|
||||||
|
"log"
|
||||||
|
"os/exec"
|
||||||
|
|
||||||
|
"github.com/modelcontextprotocol/go-sdk/mcp"
|
||||||
|
)
|
||||||
|
|
||||||
|
func main() {
|
||||||
|
ctx := context.Background()
|
||||||
|
|
||||||
|
// Create a new client, with no features.
|
||||||
|
client := mcp.NewClient(&mcp.Implementation{Name: "mcp-client", Version: "v1.0.0"}, nil)
|
||||||
|
|
||||||
|
// Connect to a server over stdin/stdout.
|
||||||
|
transport := &mcp.CommandTransport{Command: exec.Command("myserver")}
|
||||||
|
session, err := client.Connect(ctx, transport, nil)
|
||||||
|
if err != nil {
|
||||||
|
log.Fatal(err)
|
||||||
|
}
|
||||||
|
defer session.Close()
|
||||||
|
|
||||||
|
// Call a tool on the server.
|
||||||
|
params := &mcp.CallToolParams{
|
||||||
|
Name: "greet",
|
||||||
|
Arguments: map[string]any{"name": "you"},
|
||||||
|
}
|
||||||
|
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.(*mcp.TextContent).Text)
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The [`examples/`](https://github.com/modelcontextprotocol/go-sdk/tree/main/examples) directory contains more example clients and
|
||||||
|
servers.
|
||||||
|
|
@ -399,8 +399,8 @@ mcp.AddTool(server, &mcp.Tool{
|
||||||
}, WeatherTool)
|
}, WeatherTool)
|
||||||
```
|
```
|
||||||
|
|
||||||
_See [mcp/tool_example_test.go](../mcp/tool_example_test.go) for the full
|
_See [mcp/tool_example_test.go](https://github.com/modelcontextprotocol/go-sdk/blob/main/mcp/tool_example_test.go) for the full
|
||||||
example, or [examples/server/toolschemas](examples/server/toolschemas/main.go)
|
example, or [examples/server/toolschemas](https://github.com/modelcontextprotocol/go-sdk/blob/main/examples/server/toolschemas/main.go)
|
||||||
for more examples of customizing tool schemas._
|
for more examples of customizing tool schemas._
|
||||||
|
|
||||||
**Stateless server deployments:** Some deployments create a new
|
**Stateless server deployments:** Some deployments create a new
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,21 @@
|
||||||
# Features
|
# Overview
|
||||||
|
|
||||||
|
The SDK consists of several importable packages:
|
||||||
|
|
||||||
|
- 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/jsonrpc`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/jsonrpc) package is for users implementing
|
||||||
|
their own transports.
|
||||||
|
- The
|
||||||
|
[`github.com/modelcontextprotocol/go-sdk/auth`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth)
|
||||||
|
package provides some primitives for supporting OAuth.
|
||||||
|
- The
|
||||||
|
[`github.com/modelcontextprotocol/go-sdk/oauthex`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/oauthex)
|
||||||
|
package provides extensions to the OAuth protocol, such as ProtectedResourceMetadata.
|
||||||
|
|
||||||
|
|
||||||
These docs mirror the [official MCP spec](https://modelcontextprotocol.io/specification/2025-06-18).
|
These docs mirror the [official MCP spec](https://modelcontextprotocol.io/specification/2025-06-18).
|
||||||
Use the index below to learn how the SDK implements a particular aspect of the
|
Use the index below to learn how the SDK implements a particular aspect of the
|
||||||
|
|
|
||||||
|
|
@ -10,6 +10,7 @@
|
||||||
//go:generate weave -o ../../docs/troubleshooting.md ./troubleshooting.src.md
|
//go:generate weave -o ../../docs/troubleshooting.md ./troubleshooting.src.md
|
||||||
//go:generate weave -o ../../docs/rough_edges.md ./rough_edges.src.md
|
//go:generate weave -o ../../docs/rough_edges.md ./rough_edges.src.md
|
||||||
//go:generate weave -o ../../docs/mcpgodebug.md ./mcpgodebug.src.md
|
//go:generate weave -o ../../docs/mcpgodebug.md ./mcpgodebug.src.md
|
||||||
|
//go:generate weave -o ../../docs/quick_start.md ./quick_start.src.md
|
||||||
|
|
||||||
// The doc package generates the documentation at /doc, via go:generate.
|
// The doc package generates the documentation at /doc, via go:generate.
|
||||||
//
|
//
|
||||||
|
|
|
||||||
|
|
@ -1,4 +1,4 @@
|
||||||
# Backwards compatibility and MCPGODEBUG
|
# Backwards compatibility and MCPGODEBUG
|
||||||
|
|
||||||
According to our compatibility promise, we can't break backward compatibility
|
According to our compatibility promise, we can't break backward compatibility
|
||||||
of the SDK API. However, sometimes we need to change the behavior of the SDK
|
of the SDK API. However, sometimes we need to change the behavior of the SDK
|
||||||
|
|
|
||||||
|
|
@ -143,7 +143,7 @@ to see the logical session
|
||||||
> modelcontextprotocol/modelcontextprotocol#1372, or
|
> modelcontextprotocol/modelcontextprotocol#1372, or
|
||||||
> modelcontextprotocol/modelcontextprotocol#1442 for potential refinements.
|
> modelcontextprotocol/modelcontextprotocol#1442 for potential refinements.
|
||||||
|
|
||||||
_See [examples/server/distributed](../examples/server/distributed/main.go) for
|
_See [examples/server/distributed](https://github.com/modelcontextprotocol/go-sdk/blob/main/examples/server/distributed/main.go) for
|
||||||
an example using stateless mode to implement a server distributed across
|
an example using stateless mode to implement a server distributed across
|
||||||
multiple processes._
|
multiple processes._
|
||||||
|
|
||||||
|
|
@ -155,7 +155,7 @@ by implementing the
|
||||||
[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
|
[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
|
||||||
interface: a logical bidirectional stream of JSON-RPC messages.
|
interface: a logical bidirectional stream of JSON-RPC messages.
|
||||||
|
|
||||||
_Full example: [examples/server/custom-transport](../examples/server/custom-transport/main.go)._
|
_Full example: [examples/server/custom-transport](https://github.com/modelcontextprotocol/go-sdk/blob/main//examples/server/custom-transport/main.go)._
|
||||||
|
|
||||||
### Concurrency
|
### Concurrency
|
||||||
|
|
||||||
|
|
@ -368,7 +368,7 @@ of tokens and is the responsibility of the
|
||||||
provided to
|
provided to
|
||||||
[`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
|
[`RequireBearerToken`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/auth#RequireBearerToken).
|
||||||
|
|
||||||
### Server-Side Request Forgery (SSRF)
|
### Server-Side Request Forgery
|
||||||
|
|
||||||
The [mitigations](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices#mitigation-3) are as follows:
|
The [mitigations](https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices#mitigation-3) are as follows:
|
||||||
|
|
||||||
|
|
|
||||||
27
internal/docs/quick_start.src.md
Normal file
27
internal/docs/quick_start.src.md
Normal file
|
|
@ -0,0 +1,27 @@
|
||||||
|
# Quick Start
|
||||||
|
|
||||||
|
%toc
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
```
|
||||||
|
go get github.com/modelcontextprotocol/go-sdk
|
||||||
|
```
|
||||||
|
|
||||||
|
## Getting started
|
||||||
|
|
||||||
|
To get started creating an MCP server, create an `mcp.Server` instance, add
|
||||||
|
features to it, and then run it over an `mcp.Transport`. For example, this
|
||||||
|
server adds a single simple tool, and then connects it to clients over
|
||||||
|
stdin/stdout:
|
||||||
|
|
||||||
|
%include ../readme/server/server.go -
|
||||||
|
|
||||||
|
To communicate with that server, create an `mcp.Client` and connect it to the
|
||||||
|
corresponding server, by running the server command and communicating over its
|
||||||
|
stdin/stdout:
|
||||||
|
|
||||||
|
%include ../readme/client/client.go -
|
||||||
|
|
||||||
|
The [`examples/`](https://github.com/modelcontextprotocol/go-sdk/tree/main/examples) directory contains more example clients and
|
||||||
|
servers.
|
||||||
|
|
@ -189,8 +189,8 @@ the `Tool.InputSchema` explicitly:
|
||||||
|
|
||||||
%include ../../mcp/tool_example_test.go customschemas -
|
%include ../../mcp/tool_example_test.go customschemas -
|
||||||
|
|
||||||
_See [mcp/tool_example_test.go](../mcp/tool_example_test.go) for the full
|
_See [mcp/tool_example_test.go](https://github.com/modelcontextprotocol/go-sdk/blob/main/mcp/tool_example_test.go) for the full
|
||||||
example, or [examples/server/toolschemas](examples/server/toolschemas/main.go)
|
example, or [examples/server/toolschemas](https://github.com/modelcontextprotocol/go-sdk/blob/main/examples/server/toolschemas/main.go)
|
||||||
for more examples of customizing tool schemas._
|
for more examples of customizing tool schemas._
|
||||||
|
|
||||||
**Stateless server deployments:** Some deployments create a new
|
**Stateless server deployments:** Some deployments create a new
|
||||||
|
|
|
||||||
222
internal/readme/contributing.src.md
Normal file
222
internal/readme/contributing.src.md
Normal file
|
|
@ -0,0 +1,222 @@
|
||||||
|
# Contributing to the Go MCP SDK
|
||||||
|
|
||||||
|
Thank you for your interest in contributing! The Go SDK needs active
|
||||||
|
contributions to keep up with changes in the MCP spec, fix bugs, and accommodate
|
||||||
|
new and emerging use-cases. We welcome all forms of contribution, from filing
|
||||||
|
and reviewing issues, to contributing fixes, to proposing and implementing new
|
||||||
|
features.
|
||||||
|
|
||||||
|
As described in the [design document](https://github.com/modelcontextprotocol/go-sdk/blob/main/design/design.md), it is important for
|
||||||
|
the MCP SDK to remain idiomatic, future-proof, and extensible. The process
|
||||||
|
described here is intended to ensure that the SDK evolves safely and
|
||||||
|
transparently, while adhering to these goals.
|
||||||
|
|
||||||
|
%toc
|
||||||
|
|
||||||
|
|
||||||
|
## Development setup
|
||||||
|
|
||||||
|
This module can be built and tested using the standard Go toolchain. Run `go
|
||||||
|
test ./...` to run all its tests.
|
||||||
|
|
||||||
|
To test changes to this module against another module that uses the SDK, we
|
||||||
|
recommend using a [`go.work` file](https://go.dev/doc/tutorial/workspaces) to
|
||||||
|
define a multi-module workspace. For example, if your directory contains a
|
||||||
|
`project` directory containing your project, and a `go-sdk` directory
|
||||||
|
containing the SDK, run:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
go work init ./project ./go-sdk
|
||||||
|
```
|
||||||
|
|
||||||
|
### Conformance tests
|
||||||
|
|
||||||
|
The SDK includes a script to run the official MCP conformance tests against the
|
||||||
|
SDK's conformance server:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./scripts/conformance.sh
|
||||||
|
```
|
||||||
|
|
||||||
|
By default, results are cleaned up after the script runs. To save results to a
|
||||||
|
specific directory:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./scripts/conformance.sh --result_dir ./conformance-results
|
||||||
|
```
|
||||||
|
|
||||||
|
To run against a local checkout of the
|
||||||
|
[conformance repo](https://github.com/modelcontextprotocol/conformance) instead
|
||||||
|
of the latest npm release:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
./scripts/conformance.sh --conformance_repo ~/src/conformance
|
||||||
|
```
|
||||||
|
|
||||||
|
Note: you must run `npm install` in the conformance repo first.
|
||||||
|
|
||||||
|
Run `./scripts/conformance.sh --help` for more options.
|
||||||
|
|
||||||
|
## Filing issues
|
||||||
|
|
||||||
|
This project uses the [GitHub issue
|
||||||
|
tracker](https://github.com/modelcontextprotocol/go-sdk/issues) for issues. The
|
||||||
|
process for filing bugs and proposals is described below.
|
||||||
|
|
||||||
|
TODO(rfindley): describe a process for asking general questions in the public
|
||||||
|
MCP discord server.
|
||||||
|
|
||||||
|
### Bugs
|
||||||
|
|
||||||
|
Please [report
|
||||||
|
bugs](https://github.com/modelcontextprotocol/go-sdk/issues/new). If the SDK is
|
||||||
|
not working as you expected, it is likely due to a bug or inadequate
|
||||||
|
documentation, and reporting an issue will help us address this shortcoming.
|
||||||
|
|
||||||
|
When reporting a bug, make sure to answer these five questions:
|
||||||
|
|
||||||
|
1. What did you do?
|
||||||
|
2. What did you see?
|
||||||
|
3. What did you expect to see?
|
||||||
|
4. What version of the Go MCP SDK are you using?
|
||||||
|
5. What version of Go are you using (`go version`)?
|
||||||
|
|
||||||
|
### Proposals
|
||||||
|
|
||||||
|
A proposal is an issue that proposes a new API for the SDK, or a change to the
|
||||||
|
signature or behavior of an existing API. Proposals should be labeled with the
|
||||||
|
'proposal' label, and require an explicit approval from a maintainer before
|
||||||
|
being accepted (indicated by the 'proposal-accepted' label). Proposals must
|
||||||
|
remain open for at least a week to allow discussion before being accepted or
|
||||||
|
declined by a maintainer.
|
||||||
|
|
||||||
|
Proposals that are straightforward and uncontroversial may be approved based on
|
||||||
|
discussion on the issue tracker or in a GitHub Discussion. However, proposals
|
||||||
|
that are deemed to be sufficiently unclear or complicated may be deferred to a
|
||||||
|
regular Working Group meeting (see 'Governance' below).
|
||||||
|
|
||||||
|
This process is similar to the [Go proposal
|
||||||
|
process](https://github.com/golang/proposal), but is necessarily lighter weight
|
||||||
|
to accommodate the greater rate of change expected for the SDK.
|
||||||
|
|
||||||
|
### Design discussion
|
||||||
|
|
||||||
|
For open ended design discussion (anything that doesn't fall into the issue
|
||||||
|
categories above), use [GitHub
|
||||||
|
Discussions](https://github.com/modelcontextprotocol/go-sdk/discussions).
|
||||||
|
Ideally, each discussion should be focused on one aspect of the design. For
|
||||||
|
example: Tool Binding and Session APIs would be two separate discussions.
|
||||||
|
When discussions reach a consensus, they should be promoted into proposals.
|
||||||
|
|
||||||
|
## Contributing code
|
||||||
|
|
||||||
|
The project uses GitHub pull requests (PRs) to review changes.
|
||||||
|
|
||||||
|
Any significant change should be associated with a GitHub issue. Issues that
|
||||||
|
are deemed to be good opportunities for contribution are be labeled ['Help
|
||||||
|
Wanted'](https://github.com/modelcontextprotocol/go-sdk/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22help%20wanted%22).
|
||||||
|
If you want to work on such an issue, please first comment on the issue to say
|
||||||
|
that you're interested in contributing. For issues _not_ labeled 'Help Wanted',
|
||||||
|
it is recommended that you ask (and wait for confirmation) on the issue before
|
||||||
|
contributing, to avoid duplication of effort or wasted work. For nontrivial
|
||||||
|
changes that _don't_ relate to an existing issue, please file an issue first.
|
||||||
|
|
||||||
|
Changes should be high quality and well tested, and should generally follow the
|
||||||
|
[Google Go style guide](https://google.github.io/styleguide/go/). Commit
|
||||||
|
messages should follow the [format used by the Go
|
||||||
|
project](https://go.dev/wiki/CommitMessage).
|
||||||
|
|
||||||
|
Unless otherwise noted, the Go source files are distributed under the license
|
||||||
|
found in the LICENSE file. New contributions are licensed under Apache 2.0. All
|
||||||
|
Go files in the SDK should have a copyright header following the format below:
|
||||||
|
|
||||||
|
```go
|
||||||
|
// Copyright 2025 The Go MCP SDK Authors. All rights reserved.
|
||||||
|
// Use of this source code is governed by the license
|
||||||
|
// that can be found in the LICENSE file.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Adding and updating dependencies
|
||||||
|
|
||||||
|
In general, the SDK tries to use as few dependencies as possible. Each new
|
||||||
|
dependency is a potential source for bugs, churn, and conflicts for our users.
|
||||||
|
Therefore, we require a [proposal](#proposals) for any new module dependency,
|
||||||
|
including upgrading an existing module to a new major version. New dependencies
|
||||||
|
should be evaluated for their stability and security, and should be
|
||||||
|
well-established in the Go ecosystem.
|
||||||
|
|
||||||
|
In general, dependencies should be for internal use by the SDK implementation,
|
||||||
|
or for testing. Do not include types from dependencies in the SDK API.
|
||||||
|
|
||||||
|
On the other hand, updating existing dependencies can be done at any time
|
||||||
|
without a proposal, as long as their major version does not change. Prefer to
|
||||||
|
update dependencies immediately following a release of the SDK, to allow as
|
||||||
|
much time as possible to find issues with the new version.
|
||||||
|
|
||||||
|
After any change to dependencies, run govulncheck to check them for
|
||||||
|
vulnerabilities.
|
||||||
|
|
||||||
|
```
|
||||||
|
go run golang.org/x/vuln/cmd/govulncheck@latest
|
||||||
|
```
|
||||||
|
|
||||||
|
### Updating the README
|
||||||
|
|
||||||
|
The top-level `README.md` file is generated from `internal/readme/README.src.md`
|
||||||
|
and should not be edited directly. To update the README:
|
||||||
|
|
||||||
|
1. Make your changes to `internal/readme/README.src.md`
|
||||||
|
2. Run `go generate ./internal/readme` from the repository root to regenerate `README.md`
|
||||||
|
3. Commit both files together
|
||||||
|
|
||||||
|
The CI system will automatically check that the README is up-to-date by running
|
||||||
|
`go generate ./internal/readme` and verifying no changes result. If you see a CI failure about the
|
||||||
|
README being out of sync, follow the steps above to regenerate it.
|
||||||
|
|
||||||
|
## Timeouts
|
||||||
|
|
||||||
|
If a contributor hasn't responded to issue questions or PR comments in two weeks,
|
||||||
|
the issue or PR may be closed. It can be reopened when the contributor can resume
|
||||||
|
work.
|
||||||
|
|
||||||
|
## Code of conduct
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
## Governance
|
||||||
|
|
||||||
|
Initially, the Go SDK repository will be administered by the Go team and
|
||||||
|
Anthropic, and they will be the approvers (the set of people able to merge PRs
|
||||||
|
to the SDK), also referred to as the 'Working Group'. The policies here are
|
||||||
|
also intended to satisfy necessary constraints of the Go team's participation
|
||||||
|
in the project. This may change in the future: see 'Ongoing Evaluation' below.
|
||||||
|
|
||||||
|
### Working Group meetings
|
||||||
|
|
||||||
|
On a regular basis, the Working Group will host a virtual meeting to discuss
|
||||||
|
outstanding proposals and other changes to the SDK. These meetings and their
|
||||||
|
agendas will be announced in advance, and open to all. The meetings will be
|
||||||
|
recorded, and recordings and meeting notes will be made available afterward.
|
||||||
|
(TODO: decide on a mechanism for tracking these meetings--likely a GitHub
|
||||||
|
issue.)
|
||||||
|
|
||||||
|
This process is similar to the [Go Tools
|
||||||
|
call](https://go.dev/wiki/golang-tools), though it is expected that meetings
|
||||||
|
will at least initially occur on a more frequent basis.
|
||||||
|
|
||||||
|
### Discord
|
||||||
|
|
||||||
|
Discord (either the public or private Anthropic discord servers) should only be
|
||||||
|
used for logistical coordination or answering questions. For transparency and
|
||||||
|
durability, design discussion and decisions should occur in GitHub issues,
|
||||||
|
GitHub discussions, or public steering meetings.
|
||||||
|
|
||||||
|
### Antitrust considerations
|
||||||
|
|
||||||
|
The goal of this repository is to provide a robust and complete Go
|
||||||
|
implementation of the model context protocol, in an open and transparent
|
||||||
|
manner, without bias toward specific integration paths or providers. To that
|
||||||
|
end, the model context protocol organization's [antitrust
|
||||||
|
policy](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/ANTITRUST.md)
|
||||||
|
applies to all participation in this project.
|
||||||
|
|
@ -2,7 +2,9 @@
|
||||||
// Use of this source code is governed by an MIT-style
|
// Use of this source code is governed by an MIT-style
|
||||||
// license that can be found in the LICENSE file.
|
// license that can be found in the LICENSE file.
|
||||||
|
|
||||||
//go:generate go run golang.org/x/example/internal/cmd/weave@latest -o ../../README.md ./README.src.md
|
//go:generate -command weave go run golang.org/x/example/internal/cmd/weave@latest
|
||||||
|
//go:generate weave -o ../../README.md ./README.src.md
|
||||||
|
//go:generate weave -o ../../CONTRIBUTING.md ./contributing.src.md
|
||||||
|
|
||||||
// The readme package is used to generate README.md at the top-level of this
|
// The readme package is used to generate README.md at the top-level of this
|
||||||
// repo. Regenerate the README with go generate.
|
// repo. Regenerate the README with go generate.
|
||||||
|
|
|
||||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue