Add documentation backed by mkdocs (#883)

Dinesht04 · web-flow · commit 12098618587b · 2026-04-09T14:25:43.000+02:00
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
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -1,4 +1,4 @@
-name: Publish Docs to GitHub Pages
+name: Publish Docs 
 
 on:
   release:
@@ -13,13 +13,20 @@ jobs:
       contents: write
     runs-on: ubuntu-latest
     steps:
-      - name: Check out code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@4f9cc6602d3f66b9c108549d475ec49e8ef4d45e # v4
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Configure Git Credentials
+        run: |
+          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:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./docs
-          publish_branch: gh-pages
-          enable_jekyll: true
-          cname: go.sdk.modelcontextprotocol.io
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
+      - uses: actions/cache@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5.0.4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip install mkdocs-material 
+      - run: mkdocs gh-deploy --force
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,3 +1,4 @@
+<!-- Autogenerated by weave; DO NOT EDIT -->
 # Contributing to the Go MCP SDK
 
 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
 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
 described here is intended to ensure that the SDK evolves safely and
 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
 
 This module can be built and tested using the standard Go toolchain. Run `go
diff --git a/docs/CNAME b/docs/CNAME
@@ -0,0 +1 @@
+go.sdk.modelcontextprotocol.io
diff --git a/docs/README.md b/docs/README.md
@@ -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
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"
diff --git a/docs/images/logo-dark.svg b/docs/images/logo-dark.svg
@@ -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>
diff --git a/docs/images/logo-light.svg b/docs/images/logo-light.svg
@@ -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>
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/mcpgodebug.md b/docs/mcpgodebug.md
@@ -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
diff --git a/docs/protocol.md b/docs/protocol.md
@@ -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:
 
diff --git a/docs/quick_start.md b/docs/quick_start.md
@@ -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.
diff --git a/docs/server.md b/docs/server.md
@@ -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
diff --git a/internal/docs/README.src.md b/internal/docs/README.src.md
@@ -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).
 Use the index below to learn how the SDK implements a particular aspect of the
diff --git a/internal/docs/doc.go b/internal/docs/doc.go
@@ -10,6 +10,7 @@
 //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/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.
 //
diff --git a/internal/docs/mcpgodebug.src.md b/internal/docs/mcpgodebug.src.md
@@ -1,4 +1,4 @@
- # 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
diff --git a/internal/docs/protocol.src.md b/internal/docs/protocol.src.md
diff --git a/internal/docs/quick_start.src.md b/internal/docs/quick_start.src.md
diff --git a/internal/docs/server.src.md b/internal/docs/server.src.md
diff --git a/internal/readme/contributing.src.md b/internal/readme/contributing.src.md
diff --git a/internal/readme/doc.go b/internal/readme/doc.go
diff --git a/mkdocs.yaml b/mkdocs.yaml
