SwiftMCP

Swift 实现的 MCP（模型上下文协议），用于通过多种传输方式实现 JSON-RPC。

特性

• 多种传输选项
  • 标准 I/O（标准输入输出）用于命令行使用
  • HTTP+SSE（服务器发送事件）用于 Web 应用程序
• 符合 JSON-RPC 2.0 并支持 OpenAPI 生成
• 内置授权和可选的 OAuth 验证
• 透明的 OAuth 代理模式，适用于 MCP 和 OpenAPI
• 跨平台兼容性

服务器特性

• 工具 – 使用 @MCPTool 暴露函数
• 资源 – 使用 @MCPResource 发布数据
• 提示 – 使用 @MCPPrompt 构建提示
• 实用工具
  • 通过 RequestContext.current 发送进度通知
  • 通过 Session.current 流式传输结构化日志
  • 参数的完成建议（默认值为 Bool 和 CaseIterable）

客户端特性

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

安装

在你的 Package.swift 中添加 SwiftMCP 作为依赖：

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

使用

命令行演示

包含的演示应用程序展示了如何使用 SwiftMCP 和不同的传输选项：

# 使用 stdio 传输
SwiftMCPDemo stdio

# 使用 HTTP+SSE 传输
SwiftMCPDemo httpsse --port 8080

# 使用带有授权的 HTTP+SSE 传输
SwiftMCPDemo httpsse --port 8080 --token your-secret-token

# 使用带有 OpenAPI 支持的 HTTP+SSE 传输
SwiftMCPDemo httpsse --port 8080 --openapi

# 使用带有授权和 OpenAPI 支持的 HTTP+SSE 传输
SwiftMCPDemo httpsse --port  8080 --token your-secret-token --openapi

# 使用带有 OAuth 的 HTTP+SSE 传输
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

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

Authorization: Bearer your-secret-token

OpenAPI 支持

--openapi 选项启用 AI 插件集成的 OpenAPI 端点。当使用此选项时，服务器将在 /openapi.json 提供 OpenAPI 规范，并在 /.well-known/ai-plugin.json 提供 AI 插件清单。这允许轻松地与支持 OpenAPI 的 AI 模型和其他工具进行集成。

OAuth 支持

当 HTTPSSETransport 配置了 OAuthConfiguration，传输会通过配置的 OAuth 提供商验证传入的承载令牌。验证可以使用内省端点或检查 JWT 声明与提供商的 JWKS，当没有内省端点可用时。传输还提供元数据在 /.well-known/oauth-authorization-server 和 /.well-known/oauth-protected-resource 以供客户端发现。

进度、日志、根目录和采样

SwiftMCP 可以在工具运行时发送进度更新，流式传输结构化日志消息到连接的客户端，处理客户端宣布的动态文件系统根目录，并请求小的数据样本进行预览。查看演示服务器中的这些功能的简单实现。《ServerCapabilities》和《Sampling》文章详细描述了这些 API。

自定义服务器实现

要实现自己的 MCP 服务器：

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

示例：

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

// 使用带有授权的 HTTP+SSE 传输
let server = MyServer()
let transport = HTTPSSETransport(server: server, port: 8080)

// 可选：添加授权
transport.authorizationHandler = { token in
    guard let token = token, token == "your-secret-token" else {
        return .unauthorized("无效的令牌")
    }
    return .authorized
}

// 或配置 OAuth 验证
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 宏从文档注释中提取信息来描述类、参数和返回值。

宏的功能

本仓库中的宏提供了定义和暴露工具及服务器的功能。以下是主要功能：

• @MCPServer：此宏用于定义一个类或 actor 作为 MCP 服务器。它从文档注释中提取服务器描述（或可选的 description: 覆盖）。其用法示例如 Demos/SwiftMCPDemo/Calculator.swift 文件中的 Calculator actor，该 actor 使用 @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 {
    /// 根据用户 ID 获取用户资料
    @MCPResource("users://{user_id}/profile")
    func getUserProfile(user_id: Int) -> String {
        return "用户 \(user_id) 的资料"
    }
    
    /// 分页搜索用户
    @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 模板：定义带有大括号 {param} 占位符的模式
• 路径参数：从 URI 路径中提取值（例如，/users/{id}）
• 查询参数：从查询字符串中提取值（例如，?page={page}）
• 可选参数：支持可选参数的默认值
• MIME 类型：可选指定内容类型，使用 mimeType 参数
• 类型安全：参数自动转换为正确的 Swift 类型

服务器自动提供：

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

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

许可证

该项目根据 BSD 2-clause 许可证发布 - 详情见 LICENSE 文件。