MCP Template

MCP 模板

一个模板仓库，为 macOS 应用和命令行工具构建 Model Control Protocol（MCP）服务提供精简基础。

概述

MCP Template 为希望在项目中实现 MCP 服务的开发者提供了一个起点。此模板以精简的方式演示如何使用 mcp-swift-sdk，帮助开发者更轻松地了解 MCP 集成的基础知识。它既包含可集成到其他项目中的库模板，也包含一个用于演示基本用法的简单命令行示例。

用途

此仓库旨在作为：

• 展示如何使用 mcp-swift-sdk 的参考实现
• 可分叉或克隆的模板，为你自己的 MCP 服务实现提供基础
• 通过少量代码展示 MCP 核心概念的精简示例

功能

当前及计划中的功能包括：

• 基本的 Swift 包结构
• 命令行“hello world”示例工具
• 命令行 stdio，可通过 run 命令直接与 MCP 交互
• 符合 App Store 安全要求的命令行 stdio → 独立 Mac 应用通信
• 在 Package 中提供 SSE 服务 → 基于 SSE 的 MCP 命令行应用示例

安装

Swift Package Manager

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

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

然后将依赖项添加到你的 target：

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

用法

基本示例

import EasyMCP

// Create an instance of EasyMCP
let mcp = EasyMCP()

// Register a tool
try await mcp.register(tool: Tool(
    name: "helloPerson",
    description: "Returns a friendly greeting message",
    inputSchema: [
        "type": "object",
        "properties": [
            "name": [
                "type": "string",
                "description": "Name of the person to say hello to",
            ]
        ],
        "required": ["name"]
    ]
)) { input in
    // It's an async closure, so you can await whatever you need to for long running tasks
    await someOtherAsyncStuffIfYouWant()
    // Return your result and flag if it is/not an error
    return Result(content: [.text(hello(input["name"]?.stringValue ?? "world"))], isError: false)
}

// Start the MCP server for full MCP interaction
try await mcp.start()
try await mcp.waitUntilComplete()

命令行示例

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

# Run the basic hello example
mcpexample hello

# Start the MCP server to handle MCP protocol communications
mcpexample run

项目结构

Targets

1. EasyMCP（库）

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

2. mcpexample（可执行文件）

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

3. EasyMCPTests（测试 Target）

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

依赖项

• swift-argument-parser（1.3.0+）- 用于处理 CLI 参数
• mcp-swift-sdk（branch: "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 <absolute_path_to_your_executable> run
   

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

   🔍 MCP Inspector is up and running at 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 的界面测试 MCP 服务的功能
• 在代码中设置断点以跟踪执行过程
• 在运行期间检查变量和状态
• 实时调试资源、提示词和工具实现

如需更多调试技巧，请访问 Anthropic 的 modelcontextprotocol.io 网站上的 MCP 调试。

许可证

采用 MIT 许可证。

致谢

• loopwork-ai 提供的 MCP Swift SDK