Windsurf support

[glaciotech]

I'm trying to get the MCP server to work with Windsurf. I'm not sure if this is an issue with how i'm creating the server or something to do with how Windsurf expects MCP servers to respond. So starting out with a question.

I can get Windsurf to detect the MCP server and it sees the tools listed, but at the same time it's showing 0 tools available and if i try and get Cascade to invoke any of the tools it doesn't think it has any. It's possible from looking at the Firecrawl MCP source and doing some inference that Windsurf expects the tools to be listed as resources as well, but if anyone has any guidance or experience here it would be a great help?

Below is the quick code i threw together to test this from Windsurf along with a screenshot of what i'm seeing in Windsurf.

Thanks

final class App: Sendable {
    
    let logger = Logger(label: "com.example.mcp-server")
    let server: Server

    init() async {

        let server = Server(name: "TestMCPServer", version: "1.0", capabilities: .init(logging: Server.Capabilities.Logging(),
            resources: .init(subscribe: true, listChanged: true),
            tools: .init(listChanged: true)
        ))
    
        
        await server.withMethodHandler(ListResources.self) { _ in
            let resources = [
                Resource(name: "Tools", uri: "www.glacio.tech", description: "List of available tools for MCP")
            ]
            return .init(resources: resources)
        }
        
        //// Register a tool list handler
        await server.withMethodHandler(ListTools.self) { _ in
            let tools = [
                Tool(
                    name: "weather",
                    description: "Get current weather for a location",
                    inputSchema: .object([
                        "location": .string("City name or coordinates"),
                        "units": .string("Units of measurement, e.g., metric, imperial")
                    ]),
                ),
                Tool(
                    name: "calculator",
                    description: "Perform calculations",
                    inputSchema: .object([
                        "expression": .string("Mathematical expression to evaluate")
                    ])
                )
            ]
            return .init(tools: tools)
        }
        
        //// Register a tool call handler
        await server.withMethodHandler(CallTool.self) { params in
            switch params.name {
            case "weather":
                let location = params.arguments?["location"]?.stringValue ?? "Unknown"
                let units = params.arguments?["units"]?.stringValue ?? "metric"
                let weatherData = getWeatherData(location: location, units: units) // Your implementation
                return .init(
                    content: [.text("Weather for \(location): \(weatherData.temperature)°, \(weatherData.conditions)")],
                    isError: false
                )
                
            case "calculator":
                if let expression = params.arguments?["expression"]?.stringValue {
                    let result = evaluateExpression(expression) // Your implementation
                    return .init(content: [.text("\(result)")], isError: false)
                } else {
                    return .init(content: [.text("Missing expression parameter")], isError: true)
                }
                
            default:
                return .init(content: [.text("Unknown tool")], isError: true)
            }
        }
        
        self.server = server
    }
    
    func start() async throws {
        
        print("CLI app has exited.")
        
        // Create MCP service and other services
        let transport = StdioTransport(logger: logger)
        let mcpService = MCPService(server: server, transport: transport)

        // Create service group with signal handling
        let serviceGroup = ServiceGroup(
            services: [mcpService],
            configuration: .init(gracefulShutdownSignals: [.sigterm, .sigint]), logger: logger
        )
        
            
        // Run the service group - this blocks until shutdown
        try await serviceGroup.run()
    }
}

try! await App().start()

struct MCPService: Service {
    
    let server: Server
    let transport: StdioTransport
    
    init(server: Server, transport: StdioTransport) {
        self.server = server
        self.transport = transport
    }
    
    func run() async throws {
        // Start the server
        try await server.start(transport: transport)

        // Keep running until external cancellation
        try await Task.sleep(for: .seconds(10000)) 
    }

    func shutdown() async throws {
        // Gracefully shutdown the server
        await server.stop()
    }
}

struct WeatherDataType {
    var temperature: Double
    var conditions: String
}

func getWeatherData(location: String, units: String) -> WeatherDataType {
    return WeatherDataType(temperature: 80, conditions: "Sunny")
}

func evaluateExpression(_ expression: String) -> String {
    "Evaluated \(expression)"
}

[glaciotech]

So i managed to find a little more information on what's happening here. Windsurf is producing this error for the tools

failed to validate tool input schema for tool: weather: invalid JSON schema: jsonschema validation failed with 'https://json-schema.org/draft/2020-12/schema#' - at '': allOf failed - at '/type': anyOf failed - at '/type': value must be one of 'array', 'boolean', 'integer', 'null', 'number', 'object', 'string' - at '/type': got string, want array.

Based on looking through the ListTool tests it seems the output is more like an example JSON then a JSON schema.

i.e. This is the output being created and sent back on the "tools/list" call.

{
  "name": "weather",
  "description": "Get current weather for a location",
  "inputSchema": {
    "location": "City name or coordinates",
    "units": "Units of measurement, e.g., metric, imperial"
  }
}

but based on the error i think Windsurf is expecting something more like this

{
  "name": "weather",
  "description": "Get current weather for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or coordinates"
      },
      "units": {
        "type": "string",
        "description": "Units of measurement, e.g., metric, imperial"
      }
    },
    "required": ["location", "units"]
  }
}

I'm sure I'm probably missing something here, any input to point me in the right direction would be great. Is there an option I need to specify to get json schema output on the "tools/list" call?

[glaciotech]

Yep. I've confirmed it, this is definitely the issue. I used a library that produces a JSONSchema output and the Tools now work in Windsurf.

[mattt]

Hi @glaciotech. Sorry about the incorrect usage in the README. I just opened #136 with a fix.

[ptliddle]

I created a fork which integrates a library i created as part of some other AI integration work. The library allows you to define a Swift struct along with some property wrappers and have it spit out a JSON Schema. Let me know if there's any interest in this coming over to the main project. The library needs some cleaning up but it does work and is what allowed me to get it working with Windsurf.

For instance instead of for tool description

Tool(
    name: "weather",
    description: "Get current weather for a location",
    inputSchema: .object([
        "location": .string("City name or coordinates"),
        "units": .string("Units of measurement, e.g., metric, imperial")
    ]),
)

you can do

struct WeatherToolSchema: ProducesJSONSchema {
    static let exampleValue: App.WeatherToolSchema = WeatherToolSchema(location: "Paris", units: "Celsius")
    
    @SchemaInfo(description: "City name or coordinates")
    var location: String = ""
    
    @SchemaInfo(description: "Units of measurement, e.g., metric, imperial")
    var units: String = ""
}

let weatherToolSchema = JsonSchemaCreator.createJSONSchema(for: WeatherToolSchema())

Tool(
    name: "weather",
    description: "Get current weather for a location",
    inputSchema: weatherToolSchema
)

[ptliddle]

SwiftyJsonSchema Integration

It's done by adding an extension to Value so it can easily be rebased on top of the latest core code or added directly to a project if anyone needs this capability.

Documentation

[mattt]

Thanks for sharing, @ptliddle.

There are a few different packages out there that use macros to automatically generate schemas. So far, I've been -1 on adopting macros in projects; I generally like their ergonomics, but not enough to justify the cost of adding swift-syntax as a dependency and going through the approval flow. The former objection seems to be addressed by Xcode 26 now using a prebuilt library, so I'm starting to look at options.

Without a strong consensus around any existing community package, I'm inclined to target the Foundation Models framework Generable macro, to see if that can be applied here (#135).

For JSON Schema generally, I didn't find any existing packages that worked how I wanted, so I built loopwork-ai/JSONSchema.

[phimage]

The fix doesn't seem sufficient.

For the args:

"location": .string("City name or coordinates"),
"units": .string("Units of measurement, e.g., metric, imperial")

We need valid json schema values — i.e., a dictionary with keys like type: "string", description: "City name or coordinates", etc.

That's why, for my test, I used a full dictionary to describe the tool to make it work with Claude Desktop

(Although using loopwork-ai/JSONSchema, which you already use for iMCP, is a cleaner approach)

[ptliddle]

Take a look at mcp-swift-sdk-helpers while @mattt works on this. This supersedes my comment above and i think is a cleaner way to do it, rather then having a fork of this repo.

As value takes a Codable object I added an extension allowing you to basically use SwiftyJSONSchema to create a valid schema. As JSONSchema adheres to Codable it's fully compatible with the current code, but produces a proper JSON Schema object. You can see how it's used here Defining Tool Input Schemas and Enums

I also added ParamInitializable which allows you to easily convert the request params from the server into your Swift model (just don't look at the code it's quick and dirty!, needs a better long term solution) You can see how that's used here Implementing the Tool Handler. Basically for this you just initialize your model with the request params i.e. try YourModel(with: params)