Update and expand typed tool examples

[rdmcguire]

Given the recent breaking change which some examples haven't been updated along with some current examples largely relying on accessing map keys via untyped string literals (this is very pythonic for a Golang SDK), it would be great to add simple typed tool examples.

This is an example of how I've implemented it, using ToolFor. I'm unsure if this is the intended implementation for a typed tool. Without the ToolFor wrapper, I was responsible for unmarshaling the raw json message which seemed less than ideal. I'm dubious my usage of jsonschema (or lack thereof) is per design intent.

type GitToolArgs struct {
	Repo         string `json:"repo" jsonschema:"Repo URL,pattern=(git|https?).*\\.git"`
	SourceBranch string `json:"sourceBranch" jsonschema:"Source GIT Branch"`
	TargetBranch string `json:"targetBranch" jsonschema:"Target GIT Branch"`
}

func (a *AIWorkerMCP) addGitTool() error {
	a.server.AddTool(mcp.ToolFor[*GitToolArgs, any](&mcp.Tool{
		Annotations: &mcp.ToolAnnotations{
			OpenWorldHint: ptr.To(true),
			ReadOnlyHint:  true,
		},
		Description: "Fetches GIT context",
		Name:        "aiworkermcp-git",
		Title:       "AI Worker GIT MCP",
	}, a.gitToolHandlerFor))

	return nil
}

func (a *AIWorkerMCP) gitToolHandlerFor(ctx context.Context, req *mcp.CallToolRequest, args *GitToolArgs) (
	*mcp.CallToolResult, any, error,
) {
	// some work here
	return &mcp.CallToolResult{
		IsError: false,
		Content: []mcp.Content{
			&mcp.TextContent{
				Text: "some text content here",
			},
		},
	}, nil, nil
}

[jba]

We do intend to add more examples.

You don't need ToolFor in your example. In fact, we just removed it. Use

mcp.AddTool(a.server, &mcp.Tool{...as you have it...}, a.gitToolHandlerFor)

That should work in v0.3.0. Let us know if it doesn't.

[jba]

Also, your tool handler can just return an error. We'll take care of setting IsError.

[rdmcguire]

I'm on v0.3.1, and I don't see how that would work. The type def for ToolHandler lacks support for an args type (unlike ToolHandlerFor)

// A ToolHandler handles a call to tools/call.
// [CallToolParams.Arguments] will contain a map[string]any that has been validated
// against the input schema.
type ToolHandler func(context.Context, *CallToolRequest) (*CallToolResult, error)

// A ToolHandlerFor handles a call to tools/call with typed arguments and results.
type ToolHandlerFor[In, Out any] func(context.Context, *CallToolRequest, In) (*CallToolResult, Out, error)

The comment for ToolHandler is also incorrect, as the recent change removed this in favor of the implementer validating the schema and unmarshaling raw json into the target struct.

This is a pretty heavy walk-back in functionality, and there are also no examples for both validating against the schema or unmarshaling. Apologies if I've misunderstood this, but I don't believe AddTool supports typed args like ToolHandlerFor does and removing it makes this needlessly cumbersome to implement when there was previously a functional and useful implementation.

[jba]

The ToolHandler doc is wrong. I'll address that soon.

Meanwhile, take a look at mcp.AddTool. Not Server.AddTool. Does that help?

[findleyr]

Thanks, we have a critical gap in examples and documentation, but I don't think we regressed in functionality. We're working on fixing our documentation gap ASAP.

[jba]

See #414.

[rdmcguire]

@jba thank you, I overlooked that in your earlier response -- and that does take a mcp.ToolHandlerFor. Assuming the reason for keeping Server.AddTool is backwards compatibility, noting the similar-but-different mcp.AddTool in the doc comment would be great as it's easy to stumble across it.

Thank you!

[jba]

We want to keep Server.AddTool for people who want total control over tool calling. We expect it will be seldom used.