AI导哈

JSON-RPC协议实现

SwiftMCP是一个基于Swift的JSON-RPC 2.0协议实现，支持多种传输方式（标准I/O、HTTP+SSE），内置授权和OAuth验证，适用于跨平台开发和服务集成。

  • by Rivonsen
  • Swift
  • 本地部署
  • 更新于
在 GitHub 查看 Rivonsen/SwiftMCP

使用说明

SwiftMCP

用于JSON-RPC的MCP（模型上下文协议）在各种传输上的Swift实现。

特性

  • 多种运输选择
    • 命令行使用的标准I/O（stdio）
    • HTTP+SSE（服务器发送事件）用于web应用程序
  • JSON-RPC 2.0兼容OpenAPI生成
  • 内置授权和可选的OAuth验证
  • MCP和OpenAPI的透明OAuth代理模式
  • 跨平台兼容性

服务器功能

  • 工具 –通过以下方式公开函数 @MCPTool
  • 资源 –发布数据 @MCPResource
  • 提示 –使用构建提示 @MCPPrompt
  • 公用事业
    • 进度通知通过 RequestContext.current
    • 结构化日志流式传输 Session.current
    • 参数完成建议（默认值 Bool 和 CaseIterable)

客户端功能

  • 根 –客户端宣布的动态文件系统根
  • 采样 –请求客户端文件的小预览

安装

将SwiftMCP添加为您的依赖项 Package.swift:

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

用法

命令行演示

附带的演示应用程序显示了如何使用具有不同传输选项的SwiftMCP：

# 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

# Using HTTP+SSE with OAuth
SwiftMCPDemo httpsse --port 8080 \
    --oauth-issuer https://example.com \
    --oauth-token-endpoint https://example.com/oauth/token \
    --oauth-introspection-endpoint https://example.com/oauth/introspect \
    --oauth-jwks-endpoint https://example.com/.well-known/jwks.json \
    --oauth-audience your-api-identifier

当使用HTTP+SSE传输时 --token 选项中，客户端必须在其请求中包含Authorization标头：

Authorization: Bearer your-secret-token

OpenAPI支持

这 --openapi 选项启用OpenAPI端点以进行AI插件集成。使用此选项时，服务器将在以下位置提供OpenAPI规范 /openapi.json AI插件清单位于 /.well-known/ai-plugin.json这使得与支持OpenAPI的AI模型和其他工具的集成变得容易。

OAuth支持

当 HTTPSSETransport 配置了 OAuthConfiguration，运输 通过配置的OAuth提供程序验证传入的承载令牌。 验证可以使用自省端点或通过检查JWT声明 当自省不可用时，提供程序的JWKS。交通也 在以下位置提供元数据 /.well-known/oauth-authorization-server 和 /.well-known/oauth-protected-resource 供客户发现。

进度、测井、根系和取样

SwiftMCP可以在工具运行时发送进度更新，流结构 将消息记录到连接的客户端，处理宣布的动态文件系统根 通过客户端请求小数据样本进行预览。请参阅演示服务器 这些特征的简单实现。这 doc:ServerCapabilities 和 doc:Sampling 文章详细描述了API。

自定义服务器实现

要实现自己的MCP服务器：

  1. 附上 @MCPServer 宏指向类或actor等引用类型
  2. 使用定义您的工具 @MCPTool 属性
  3. 选择并配置传输

例子：

@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
}

// Or configure OAuth validation
transport.oauthConfiguration = OAuthConfiguration(
    issuer: URL(string: "https://example.com")!,
    authorizationEndpoint: URL(string: "https://example.com/authorize")!,
    tokenEndpoint: URL(string: "https://example.com/oauth/token")!,
    introspectionEndpoint: URL(string: "https://example.com/oauth/introspect")!,
    jwksEndpoint: URL(string: "https://example.com/.well-known/jwks.json")!,
    audience: "your-api-identifier",
    clientID: "client",
    clientSecret: "secret"
)

try transport.run()

文档提取

这 @MCPServer 和 @MCPTool 宏提取文档注释来描述类、参数和返回值。

宏功能

此存储库中的宏提供了在SwiftMCP框架中定义和公开工具和服务器的功能。以下是宏的主要功能：

  • @MCPServer：此宏用于将类或参与者定义为MCP服务器。它提取文档注释来描述类、参数和返回值。它的使用示例可以在 Demos/SwiftMCPDemo/Calculator.swift 文件，其中 Calculator 演员被注释为 @MCPServer(name: "SwiftMCP Demo").
  • @MCPTool：此宏用于定义MCP服务器中可称为工具的函数。它还提取文档注释来描述函数、参数和返回值。其使用示例可以在 Demos/SwiftMCPDemo/Calculator.swift 文件，其中包含各种功能，例如 add, subtract, testArray, multiply, divide, greet, ping，以及 noop 注释如下 @MCPTool.
  • @MCPResource：此宏用于通过URI模板公开只读数据。资源允许客户端使用带有路径和查询参数的结构化URI访问数据。宏会自动生成必要的基础设施，以便将URI与模板进行匹配并提取参数。

使用@MCPResource

这 @MCPResource 宏允许您将函数公开为可以通过URI模式访问的资源：

@MCPServer(name: "ResourceServer")
actor ResourceServer {
    /// Get user profile by ID
    @MCPResource("users://{user_id}/profile")
    func getUserProfile(user_id: Int) -> String {
        return "Profile for user \(user_id)"
    }
    
    /// Search users with pagination
    @MCPResource("users://search?q={query}&page={page}", mimeType: "application/json")
    func searchUsers(query: String, page: Int = 1) -> String {
        return """
        {"query": "\(query)", "page": \(page), "results": [...]}
        """
    }
}

主要特点：

  • URI跟URI模板：用花括号中的占位符定义模式 {param}
  • 路径参数：从URI路径中提取值（例如。， /users/{id})
  • 查询参数：从查询字符串中提取值（例如。， ?page={page})
  • 可选参数：支持可选参数的默认值
  • MIME类型：可选择使用指定内容类型 mimeType 参数
  • 类型安全：参数会自动转换为正确的Swift类型

服务器自动提供：

  • 通过以下方式发现资源 mcpResourceTemplates
  • URI匹配和参数提取
  • 类型转换和验证
  • 对缺失或无效参数的错误处理

这些宏有助于自动为MCP服务器及其工具生成必要的元数据和文档，使其更容易公开用于JSON-RPC通信和与AI模型的集成。

许可证

此项目根据BSD 2条款许可证进行许可-有关详细信息，请参阅License文件。

相关 MCP