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>
This commit is contained in:
Bo-Yi Wu 2025-10-13 23:47:58 +08:00 • committed by GitHub
commit 920e5a39ba
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 40 additions and 36 deletions

View file

@ -10,7 +10,7 @@ The example implements:
## Usage ## Usage
Start the Server ### Start the Server
```bash ```bash
go run . server 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: 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 go run . -host 0.0.0.0 -port 9000 server
``` ```
## Testing with real-world MCP Clients ## Testing with real-world MCP Clients
Once the server is started, assuming it's the default Once the server is started, assuming it's the default localhost:8080, you can try to add it to a popular MCP client:
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. Once added, Claude Code will be able to discover and use the `cityTime` tool provided by this server.
In Claude Code: 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") ⏺ timezone - cityTime (MCP)(city: "nyc")
⎿ The current time in New York City is 7:30:16 PM EDT on Wedn ⎿ The current time in New York City is 7:30:16 PM EDT on Wedn
esday, July 23, 2025 esday, July 23, 2025
⏺ The current timezone is EDT (Eastern Daylight Time), and it's ⏺ The current timezone is EDT (Eastern Daylight Time), and it's
7:30 PM on Wednesday, July 23, 2025. 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: ⏺ The timezone tool supports three US cities:
- NYC (Eastern Time) - NYC (Eastern Time)
- SF (Pacific Time) - SF (Pacific Time)
- Boston (Eastern Time) - Boston (Eastern Time)
```

View file

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