Implementing tools using a dedicated type

[colombod]

The MCP protocol allows for tool collection to change over time (see the specs here).

With the current state of this project users will have to override the behaviour of the ListToolsHandler and also write code to keep the list of tools consistent. This will introduce a lot of overhead when the goal is to allow for some tool to be removed from the capability list. It would be also required to write code to notify clients about the tool availability changes.

The message flow to implement will be up to the tool developer.

Using a more specific type

public abstract class McpTool {
 public  ToolDescriptor Descriptor {get;}
 public Availability Availability {get; }
 protected void SetAvailability(Availability availability){}
 internal Action<Availability> OnAvailabilityChanged {get;}

The McpServer could implement the message flow and listing functionality in a consistent way for all tool implementation.
A developer would need to use this type only when requiring advanced functionalities for tool availability changes, in any other cases the current offer via custom attributes would be fine.

[PederHP]

The 'raw' handler contract does provide a way to do this:

McpServerOptions options = new()
{
    ServerInfo = new() { Name = "MyServer", Version = "1.0.0" },
    Capabilities = new() 
    {
        Tools = new()
        {
            ListToolsHandler = async (request, cancellationToken) =>
            {
                return new ListToolsResult()
                {
                    Tools =
                    [
                        new Tool()
                        {
                            Name = "echo",
                            Description = "Echoes the input back to the client.",
                            InputSchema = new JsonSchema()
                            {
                                Type = "object",
                                Properties = new Dictionary<string, JsonSchemaProperty>()
                                {
                                    ["message"] = new JsonSchemaProperty() { Type = "string", Description = "The input to echo back." }
                                }
                            },
                        }
                    ]
                };
            },

            CallToolHandler = async (request, cancellationToken) =>
            {
                if (request.Params?.Name == "echo")
                {
                    if (request.Params.Arguments?.TryGetValue("message", out var message) is not true)
                    {
                        throw new McpServerException("Missing required argument 'message'");
                    }

                    return new CallToolResponse()
                    {
                        Content = [new Content() { Text = $"Echo: {message}", Type = "text" }]
                    };
                }

                throw new McpServerException($"Unknown tool: '{request.Params?.Name}'");
            },
        }
    },
};

This allows you change the list at any time. I can see how it would be useful to have a facility to use availability without having to implement the raw handlers. But perhaps this could be done with a builder extension that registers a Tool filter instead? This would avoid having parallel abstractions for tool convenience.

Something like:

builder.Services
    .AddMcpServer()
    .WithStdioServerTransport()
    .WithTools()
    .WithToolsFilter(toolsFilter); // toolsFilter implements availability filter

Or it could be located via DI, so that registering an IToolsFilter would add it.

I think if it is possible to avoid the added complexity of a non-protocol, non-AIFunction abstraction of Tool, that is preferable. But your use case of availability is a good way to simplify the concept of "dynamic tool lists" to something that I think can actually work pretty well with the existing extension while still providing a flexible and customizable mechanism.

[stephentoub]

cc: @halter73, something to think about as part of what we want the end-to-end setup/config/DI/etc. story to look like

[colombod]

If the tool filter needs to take into account other complex scenarios (dependency not available , circuit breaker, intermittent availability) the builder patter becomes complex, not easy to test, maintain and compose.

Also not sure I understand how the filter helps with observing the tools availability, there is still the need for an additional component triggering the tool list change notification.

From the specification it seems clear that the mcp is based on some form of observability which I can clearly see with the current setup story , DI, builders and handlers.

Do you have a design in mind?

[PederHP]

If the tool filter needs to take into account other complex scenarios (dependency not available , circuit breaker, intermittent availability) the builder patter becomes complex, not easy to test, maintain and compose.

Also not sure I understand how the filter helps with observing the tools availability, there is still the need for an additional component triggering the tool list change notification.

Ah! That's a good point about change notifications. I'll give it some thought - I still think it would best to find a way that works with the AIFunction abstractions rather than exist in parallel. But I can see how the observability is a tricky point.

Until there is a facility, my suggestion would be to use the raw handlers if you need dynamic tools set and change notifications. The extensions provide a lot of convenience, but it's not that painful to use the raw handlers and implement a mapping. I've done it myself when dogfooding the library.

But thank you for raising an important point about observability. There's a similar concern for prompts, resources, etc. So perhaps the solution is also to find an abstraction that works across primitives.

[twenzel]

@PederHP You mean it might also be possible that a resource or prompt change its "availability" over time (e.g. some dependend service might have changed etc)?

Is there some like the AIFunction-> Tool counterpart for resources and prompts?

[PederHP]

@PederHP You mean it might also be possible that a resource or prompt change its "availability" over time (e.g. some dependend service might have changed etc)?

Is there some like the AIFunction-> Tool counterpart for resources and prompts?

Yes the protocol allows for change notifications for all List-type primitives. An example of this could be what you mentioned, but it could also be if a server acts as an aggregator or proxy (which is increasingly popular in the ecosystem), then when "sub-servers" are dynamically added/removed, the aggregate list can be updated.

Resources have counterparts in Microsoft.Extensions.AI.Abstractions. Prompts can be represented by ChatMessage, I suppose, and Prompt templates (ie Prompts with arguments) as methods that return ChatMessage. Perhaps an attribute could be used to map properties and methods to Prompt primitives.

I think it makes good sense to support raw handlers as an option to ensure every part of the protocol is always available regardless what abstractions are used on top. But then to MEAI abstractions for the extensions and whenever possible avoid introducing library specific non-protocol types. I won't rule out there are cases where it is impossible not to introduce such types, but for the current capabilities I think there's a good chance it's possible.

[twenzel]

I just thinking about implementing a general approach for all list types on top of the raw protocol handlers.

So then it might be required to provide a abstraction for resources, prompts etc (like we did with the tools) first.