Tools for AI apps

Droppy runs a Model Context Protocol (MCP) server that AI apps on the Mac connect to. Once the user allows it, an app such as Claude can search the Droplet Store, switch droplets on and off, and run what a droplet offers. Adopt MCPToolProviding to offer typed tools there, and declare minAPI 1.21.0 in droplet.json:

extension WorldClockDroplet: MCPToolProviding {
    var mcpTools: [DropletMCPTool] {
        [
            DropletMCPTool(
                name: "add_city",
                title: "Add a city",
                summary: "Adds a city to World Clock. Returns the cities it now shows.",
                inputSchemaJSON: #"{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}"#
            ),
        ]
    }

    func performMCPTool(named name: String, argumentsJSON: String) async throws -> String {
        guard name == "add_city" else { throw WorldClockError.unknownTool(name) }
        let arguments = try JSONDecoder().decode(AddCity.self, from: Data(argumentsJSON.utf8))
        try model.add(city: arguments.city)
        return try String(decoding: JSONEncoder().encode(model.cities), as: UTF8.self)
    }
}

The AI app sees each tool as droplet_<your id>_<name>, with your summary as the description it reads and your schema as the arguments it sends. What you return goes back to it as text, or as structured content when it is JSON. An error you throw comes back as a failed call that names your droplet.

Writing good tools

• Name a tool for what it does (add_city, start_recording), lowercase, at most 32 characters.
• Write the summary for a reader who has never seen your droplet: what it does, what it takes, what it returns.
• Treat the arguments as untrusted input. They come from a model, which may have read them in a web page or a file. Check every field and never run anything an argument names.
• Keep a call short. Droppy answers a call that runs longer than 60 seconds with a timeout and cancels your task.
• Keep mcpTools cheap and stable: Droppy reads it when your droplet starts and whenever droplets change. At most 32 tools are listed; one with an invalid name, an empty title or summary, or a schema that is not a JSON object is left out.

Shortcut actions show up too

Every action you register through DropletShortcutsService is offered to AI apps as well, under its title, through Droppy's droplet_run_action tool. It takes no arguments and runs the same handler your shortcut runs. A droplet whose actions are "do what the shortcut does" needs nothing more.

What the user decides

Nothing reaches an AI app until the user turns on MCP in Droppy's Settings, MCP, approves that app, and allows "Browse and manage droplets". Mark a tool isDestructive when it deletes or overwrites something the user cannot get back: Droppy then asks the user before every call, and lists the tool only while "Delete and clear items" is allowed too.

• MCPToolProviding
• DropletMCPTool
• DropletShortcutsService