docs: improve documentation clarity and client integration steps (#567)

- Fix typo in "TroubleShooting" heading, changing it to
"Troubleshooting"
- Improve CLI usage instructions by formatting commands as code blocks
and marking them with "bash"
- Change "Start the Server" to a third-level heading for clarity
- Add additional code examples for real-world client testing and
interaction steps
- Clarify and condense instructions for adding the tool to a popular MCP
client

---------

Signed-off-by: appleboy <appleboy.tw@gmail.com>
Co-authored-by: Robert Findley <rfindley@google.com>

examples/http/README.md

@@ -10,7 +10,7 @@ The example implements:
 
 ## Usage
 
-Start the Server
+### Start the Server
 
 ```bash
 go run . server
@@ -31,36 +31,40 @@ The client will:
 
 At any given time you can pass a custom URL to the program to run it on a custom host/port:
 
-```
+
+```bash
 go run . -host 0.0.0.0 -port 9000 server
 ```
 
 ## Testing with real-world MCP Clients
 
-Once the server is started, assuming it's the default
-localhost:8080, you can try to add it to a popular MCP client:
+Once the server is started, assuming it's the default localhost:8080, you can try to add it to a popular MCP client:
 
-    claude mcp add -t http timezone http://localhost:8080
+```bash
+claude mcp add -t http timezone http://localhost:8080
+```
 
 Once added, Claude Code will be able to discover and use the `cityTime` tool provided by this server.
 
 In Claude Code:
 
-    > what's the timezone
+```
+> what's the timezone
 
-    ⏺ I'll get the current time in a major US city for you.
+⏺ I'll get the current time in a major US city for you.
 
-    ⏺ timezone - cityTime (MCP)(city: "nyc")
-      ⎿ The current time in New York City is 7:30:16 PM EDT on Wedn
-        esday, July 23, 2025
+⏺ timezone - cityTime (MCP)(city: "nyc")
+  ⎿ The current time in New York City is 7:30:16 PM EDT on Wedn
+    esday, July 23, 2025
 
 
-    ⏺ The current timezone is EDT (Eastern Daylight Time), and it's
-       7:30 PM on Wednesday, July 23, 2025.
+⏺ The current timezone is EDT (Eastern Daylight Time), and it's
+   7:30 PM on Wednesday, July 23, 2025.
 
-    > what timezones do you support?
+> what timezones do you support?
 
-    ⏺ The timezone tool supports three US cities:
-      - NYC (Eastern Time)
-      - SF (Pacific Time)
-      - Boston (Eastern Time)
+⏺ The timezone tool supports three US cities:
+  - NYC (Eastern Time)
+  - SF (Pacific Time)
+  - Boston (Eastern Time)
+```

examples/server/auth-middleware/README.md

@@ -154,12 +154,12 @@ server := mcp.NewServer(&mcp.Implementation{Name: "authenticated-mcp-server"}, n
 
 // Create authentication middleware
 authMiddleware := auth.RequireBearerToken(verifier, &auth.RequireBearerTokenOptions{
-    Scopes: []string{"read", "write"},
+	Scopes: []string{"read", "write"},
 })
 
 // Create MCP handler
 handler := mcp.NewStreamableHTTPHandler(func(r *http.Request) *mcp.Server {
-    return server
+	return server
 }, nil)
 
 // Apply authentication middleware to MCP handler
@@ -185,9 +185,9 @@ authenticatedHandler := authMiddleware(customMiddleware(handler))
 
 ```go
 func jwtVerifier(ctx context.Context, tokenString string) (*auth.TokenInfo, error) {
-    // JWT token verification logic
-    // On success: Return TokenInfo
-    // On failure: Return auth.ErrInvalidToken
+	// JWT token verification logic
+	// On success: Return TokenInfo
+	// On failure: Return auth.ErrInvalidToken
 }
 ```
 
@@ -196,20 +196,20 @@ func jwtVerifier(ctx context.Context, tokenString string) (*auth.TokenInfo, erro
 ```go
 // Get authentication information in MCP tool
 func MyTool(ctx context.Context, req *mcp.CallToolRequest, args MyArgs) (*mcp.CallToolResult, any, error) {
-    // Extract authentication info from request 
-    userInfo := req.Extra.TokenInfo
-    
-    // Check scopes
-    if !slices.Contains(userInfo.Scopes, "read") {
-        return nil, nil, fmt.Errorf("insufficient permissions: read scope required")
-    }
-    
-    // Execute tool logic
-    return &mcp.CallToolResult{
-        Content: []mcp.Content{
-            &mcp.TextContent{Text: "Tool executed successfully"},
-        },
-    }, nil, nil
+	// Extract authentication info from request
+	userInfo := req.Extra.TokenInfo
+
+	// Check scopes
+	if !slices.Contains(userInfo.Scopes, "read") {
+		return nil, nil, fmt.Errorf("insufficient permissions: read scope required")
+	}
+
+	// Execute tool logic
+	return &mcp.CallToolResult{
+		Content: []mcp.Content{
+			&mcp.TextContent{Text: "Tool executed successfully"},
+		},
+	}, nil, nil
 }
 ```