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:
Dinesh
GitHub
parent
f36591bf8a
commit
1209861858
10 changed files with 624 additions and 42 deletions
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 -->
|
||||
# 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).
|
||||
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 -->
|
||||
# Backwards compatibility and MCPGODEBUG
|
||||
# Backwards compatibility and MCPGODEBUG
|
||||
|
||||
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
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@
|
|||
1. [Security](#security)
|
||||
1. [Confused Deputy](#confused-deputy)
|
||||
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. [Utilities](#utilities)
|
||||
1. [Cancellation](#cancellation)
|
||||
|
|
@ -218,7 +218,7 @@ to see the logical session
|
|||
> modelcontextprotocol/modelcontextprotocol#1372, or
|
||||
> 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
|
||||
multiple processes._
|
||||
|
||||
|
|
@ -230,7 +230,7 @@ by implementing the
|
|||
[`Transport`](https://pkg.go.dev/github.com/modelcontextprotocol/go-sdk/mcp#Transport)
|
||||
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
|
||||
|
||||
|
|
@ -443,7 +443,7 @@ of tokens and is the responsibility of the
|
|||
provided to
|
||||
[`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:
|
||||
|
||||
|
|
|
|||
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)
|
||||
```
|
||||
|
||||
_See [mcp/tool_example_test.go](../mcp/tool_example_test.go) for the full
|
||||
example, or [examples/server/toolschemas](examples/server/toolschemas/main.go)
|
||||
_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](https://github.com/modelcontextprotocol/go-sdk/blob/main/examples/server/toolschemas/main.go)
|
||||
for more examples of customizing tool schemas._
|
||||
|
||||
**Stateless server deployments:** Some deployments create a new
|
||||
|
|
|
|||
Loading…
Reference in a new issue