📌Overview

Purpose: SwiftMCP aims to provide a Swift implementation of the Model Context Protocol (MCP) for seamless JSON-RPC communication across various transport methods.

Overview: SwiftMCP facilitates the creation of JSON-RPC services with support for multiple transport protocols, ensuring compliance with the JSON-RPC 2.0 standard. It enables developers to build robust server applications that handle asynchronous responses and include built-in authorization features.

Key Features:

• Multiple Transport Options: Supports standard I/O for command-line usage and HTTP+SSE for web applications, allowing flexibility in deployment scenarios.

• JSON-RPC 2.0 Compliance: Ensures adherence to JSON-RPC 2.0 standards, promoting interoperability with other services.

• Asynchronous Response Handling: Utilizes Server-Sent Events (SSE) for handling responses asynchronously, enhancing user experience in web applications.

• Built-in Authorization Support: Offers easy integration of authorization mechanisms to secure the server endpoints.

• Cross-Platform Compatibility: Designed to work seamlessly across different platforms, making it versatile for various development environments.

---

SwiftMCP

A Swift implementation of the MCP (Model Context Protocol) for JSON-RPC over various transports.

Features

• Multiple transport options:
  • Standard I/O (stdio) for command-line usage
  • HTTP+SSE (Server-Sent Events) for web applications
• JSON-RPC 2.0 compliant
• Asynchronous response handling via SSE
• Built-in authorization support
• Cross-platform compatibility

Installation

Add SwiftMCP as a dependency in your Package.swift:

dependencies: [
    .package(url: "https://github.com/Cocoanetics/SwiftMCP.git", branch: "main")
]

Usage

Command Line Demo

The included demo application shows how to use SwiftMCP with different transport options:

# Using stdio transport
SwiftMCPDemo stdio

# Using HTTP+SSE transport
SwiftMCPDemo httpsse --port 8080

# Using HTTP+SSE with authorization
SwiftMCPDemo httpsse --port 8080 --token your-secret-token

# Using HTTP+SSE with OpenAPI support
SwiftMCPDemo httpsse --port 8080 --openapi

# Using HTTP+SSE with authorization and OpenAPI support
SwiftMCPDemo httpsse --port 8080 --token your-secret-token --openapi

When using HTTP+SSE transport with the --token option, clients must include an Authorization header with their requests:

Authorization: Bearer your-secret-token

OpenAPI Support

The --openapi option enables OpenAPI endpoints for AI plugin integration. When this option is used, the server will provide an OpenAPI specification at /openapi.json and an AI plugin manifest at /.well-known/ai-plugin.json. This allows for easy integration with AI models and other tools that support OpenAPI.

Custom Server Implementation

To implement your own MCP server:

1. Attach the @MCPServer macro to a reference type like a class or actor.
2. Define your tools using the @MCPTool attribute.
3. Choose and configure a transport.

Example:

@MCPServer
class MyServer {
    @MCPTool
    func add(a: Int, b: Int) -> Int {
        return a + b
    }
}

// Using HTTP+SSE transport with authorization
let server = MyServer()
let transport = HTTPSSETransport(server: server, port: 8080)

// Optional: Add authorization
transport.authorizationHandler = { token in
    guard let token = token, token == "your-secret-token" else {
        return .unauthorized("Invalid token")
    }
    return .authorized
}

try transport.run()

Documentation Extraction

The @MCPServer and @MCPTool macros extract documentation comments to describe the class, parameters, and return values.

Macros Functionality

The macros in this repository provide functionality for defining and exposing tools and servers in the SwiftMCP framework. Key functionalities:

• @MCPServer: Defines a class or actor as an MCP server and extracts documentation comments for class, parameters, and return values.
• @MCPTool: Defines functions within an MCP server that can be called as tools and extracts documentation comments for function, parameters, and return values.

These macros automatically generate the necessary metadata and documentation for the MCP server and its tools, facilitating JSON-RPC communication and integration with AI models.

License

This project is licensed under the BSD 2-clause License - see the LICENSE file for details.