maui-labs mcp-tools.instructions.md

MCP Tool Development Guide

Adding a New MCP Tool

Step 1: Create the Tool File

Create src/Cli/Microsoft.Maui.Cli/DevFlow/Mcp/Tools/MyNewTool.cs:

using System.ComponentModel;
using ModelContextProtocol;
using ModelContextProtocol.Server;
using ModelContextProtocol.Protocol;
using Microsoft.Maui.Cli.DevFlow.Mcp;

namespace Microsoft.Maui.Cli.DevFlow.Mcp.Tools;

[McpServerToolType]
public sealed class MyNewTool
{
    [McpServerTool(Name = "maui_my_action"),
     Description("Clear, complete description of what this tool does. Mention when an AI agent should use it.")]
    public static async Task<string> MyAction(
        McpAgentSession session,
        [Description("Describe what this parameter controls")] string requiredParam,
        [Description("Describe this optional parameter and its default behavior")] bool optionalFlag = false,
        [Description("Agent HTTP port (optional if only one agent connected)")] int? agentPort = null)
    {
        var agent = await session.GetAgentClientAsync(agentPort);
        // Call agent.* methods to interact with the running app
        var result = await agent.SomeMethodAsync(requiredParam);
        return result ?? "No result";
    }
}

Step 2: Register the Tool

Add to src/Cli/Microsoft.Maui.Cli/DevFlow/Mcp/McpServerHost.cs:

.WithTools<MyNewTool>()

Step 3: Add the Corresponding AgentClient Method (if needed)

If the tool calls a new agent endpoint, add the client method in Microsoft.Maui.DevFlow.Client/AgentClient.cs.

Naming Conventions

• Tool names: maui_ prefix + snake_case action: maui_screenshot, maui_tap, maui_network
• Class names: PascalCase with a Tool or Tools suffix: ScreenshotTool, InteractionTools, NetworkTool
• Use plural *Tools when grouping multiple related actions in one file (e.g., InteractionTools has tap, fill, clear)
• One file can contain multiple related tools (e.g., InteractionTools has tap, fill, clear)

Parameter Rules