MCP 模板

这是一个提供基础框架的模板仓库，用于构建 macOS 应用程序和命令行工具的模型控制协议（MCP）服务器。

概述

MCP 模板为希望在其项目中实现 MCP 服务器的开发者提供了一个起点。此模板展示了如何以最小的方式使用 mcp-swift-sdk，使其更容易理解 MCP 集成的基础知识。它包括一个可以集成到其他项目的库模板，以及一个简单的命令行示例来演示基本用法。

目的

此仓库旨在成为：

• 展示如何使用 mcp-swift-sdk 的参考实现
• 可以被分叉或克隆作为您自己的 MCP 服务器实现基础的模板
• 通过最少的代码展示核心 MCP 概念的基本示例

特性

当前和计划中的特性包括：

• 基本的 Swift 包结构
• 命令行 "hello world" 示例工具
• 通过 run 命令直接与 MCP 交互的命令行标准 I/O
• App Store 安全的命令行标准 I/O → 独立 Mac 应用通信
• 在包中包含 SSE 服务器 → 基于 SSE 的 MCP 示例命令行应用

安装

Swift 包管理器

在您的 Package.swift 文件中添加以下内容：

dependencies: [
    .package(url: "https://github.com/your-username/mcp-template.git", branch: "main"),
]

然后将依赖项添加到您的目标中：

.target(
    name: "YourTarget",
    dependencies: [
        .product(name: "EasyMCP", package: "mcp-template")
    ]
),

使用

基本示例

import EasyMCP

// 创建 EasyMCP 实例
let mcp = EasyMCP()

// 注册一个工具
try await mcp.register(tool: Tool(
    name: "helloPerson",
    description: "返回友好的问候消息",
    inputSchema: [
        "type": "object",
        "properties": [
            "name": [
                "type": "string",
                "description": "要打招呼的人的名字",
            ]
        ],
        "required": ["name"]
    ]
)) { input in
    // 这是一个异步闭包，因此您可以等待需要长时间运行的任务
    await someOtherAsyncStuffIfYouWant()
    // 返回结果并标记是否出错
    return Result(content: [.text(hello(input["name"]?.stringValue ?? "world"))], isError: false)
}

// 启动 MCP 服务器进行完整的 MCP 交互
try await mcp.start()
try await mcp.waitUntilComplete()

命令行示例

该包包含一个名为 mcpexample 的命令行可执行文件，演示了基本用法：

# 运行基本的 hello 示例
mcpexample hello

# 启动 MCP 服务器以处理 MCP 协议通信
mcpexample run

项目结构

目标

1. EasyMCP (库)

   • MCP 服务器的最小模板实现
   • 展示与 MCP 协议的基本集成
   • 展示如何利用官方 mcp-swift-sdk
   • 包含一个简单的工具示例（helloworld）

2. mcpexample (可执行文件)

   • 使用 EasyMCP 库的简单命令行示例
   • 包含 hello 命令和 run 命令
   • run 命令使用标准 I/O 传输启动完整的 MCP 服务器
   • 使用 ArgumentParser 处理 CLI 参数

3. EasyMCPTests (测试目标)

   • EasyMCP 库功能的模板测试
   • 包含对 hello 函数的基本测试

依赖项

• swift-argument-parser (1.3.0+) - 用于 CLI 参数处理
• mcp-swift-sdk (分支: "feature/wait-for-complete") - 自定义的 MCP 实现分支，增加了等待 MCP 服务器完成的能力

开发

要使用此模板创建您自己的 MCP 服务器：

1. 克隆或分叉此仓库
2. 构建包以验证一切正常工作：

   swift build
   

3. 运行测试：

   swift test
   

4. 修改 EasyMCP 实现以添加自定义功能
5. 扩展命令行示例或创建您自己的 Mac 应用程序

使用 MCP Inspector 诊断和调试自定义 MCP 服务器可能也很有帮助。

$ npx @modelcontextprotocol/inspector

测试您的 MCP 命令行可执行文件

要使用 MCP Inspector 测试和调试您的 MCP 服务器：

1. 在 Xcode 中构建您的命令行可执行文件
2. 转到 Xcode → 产品 → 在 Finder 中显示构建文件夹以找到可执行文件
3. 从该目录复制可执行文件的绝对路径
4. 使用 MCP Inspector 测试您的服务器
5. 在终端中运行：

   npx @modelcontextprotocol/inspector <绝对路径到您的可执行文件> run
   

6. 在浏览器中打开输出中显示的端口：

   🔍 MCP Inspector 正在 http://localhost:5173 上运行 🚀
   

7. 在 MCP Inspector 界面中点击连接按钮
8. 打开活动监视器并搜索您的可执行文件名
9. 验证只有 inspector 和您的工具的一个实例正在运行
10. 在 Xcode → 调试 → 附加到进程 → 在顶部找到您的可执行文件名并附加
11. 在终端中运行 tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
12. 现在您可以通过 inspector 与您的服务器互动，同时在 Xcode 中设置断点！

此设置提供了一个强大的调试环境，您可以在其中：

• 通过 Inspector 的 UI 测试您的 MCP 服务器的功能
• 在代码中设置断点以跟踪执行
• 在操作期间检查变量和状态
• 实时调试资源、提示和工具实现

有关更多调试技巧，请访问 MCP 调试 在 Anthropic 的 modelcontextprotocol.io 站点。

许可证

MIT 许可证。

致谢

• loopwork-ai 提供了 MCP Swift SDK