feat: Add Support for mkdocs

.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

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

docs/CNAME

@@ -0,0 +1 @@
+go.sdk.modelcontextprotocol.io

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

docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"

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

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:
 

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.

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

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

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.
 //

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