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:
parent
7a89c31c7a
commit
920e5a39ba
2 changed files with 40 additions and 36 deletions
|
|
@ -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)
|
||||||
|
```
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue