追云似梦
追云似梦

客户端开发者指南

在本教程中，你将学习如何构建一个连接到 MCP 服务器的 LLM 驱动的聊天机器人客户端。建议先完成服务器快速入门教程，了解构建第一个服务器的基础知识。

Kotlin

你可以在这里找到本教程的完整代码。

系统要求

在开始之前，请确保你的系统满足以下要求：

  • Java 17 或更高版本
  • Anthropic API 密钥（Claude）

设置你的环境

首先，如果你还没有安装 java 和 gradle，让我们先安装它们。 你可以从官方 Oracle JDK 网站下载 java。 验证你的 java 安装：

java --version

现在，让我们创建并设置你的项目：

# 为我们的项目创建一个新目录
mkdir kotlin-mcp-client
cd kotlin-mcp-client

# 初始化一个新的 kotlin 项目
gradle init

运行 gradle init 后，你将看到创建项目的选项。 选择 Application 作为项目类型，Kotlin 作为编程语言，以及 Java 17 作为 Java 版本。

或者，你可以使用 IntelliJ IDEA 项目向导创建一个 Kotlin 应用程序。

创建项目后，添加以下依赖项：

val mcpVersion = "0.3.0"
val slf4jVersion = "2.0.9"
val anthropicVersion = "0.8.0"

dependencies {
    implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
    implementation("org.slf4j:slf4j-nop:$slf4jVersion")
    implementation("com.anthropic:anthropic-java:$anthropicVersion")
}

同时，在你的构建脚本中添加以下插件：

plugins {
    id("com.github.johnrengelman.shadow") version "8.1.1"
}

设置你的 API 密钥

你需要从 Anthropic Console 获取一个 Anthropic API 密钥。

设置你的 API 密钥：

export ANTHROPIC_API_KEY='your-anthropic-api-key-here'
Warning

请确保妥善保管你的 ANTHROPIC_API_KEY！

创建客户端

基本客户端结构

首先，让我们创建基本的客户端类：

class MCPClient : AutoCloseable {
    private val anthropic = AnthropicOkHttpClient.fromEnv()
    private val mcp: Client = Client(clientInfo = Implementation(name = "mcp-client-cli", version = "1.0.0"))
    private lateinit var tools: List<ToolUnion>

    // 方法将在这里添加

    override fun close() {
        runBlocking {
            mcp.close()
            anthropic.close()
        }
    }

服务器连接管理

接下来，我们将实现连接到 MCP 服务器的方法：

suspend fun connectToServer(serverScriptPath: String) {
    try {
        val command = buildList {
            when (serverScriptPath.substringAfterLast(".")) {
                "js" -> add("node")
                "py" -> add(if (System.getProperty("os.name").lowercase().contains("win")) "python" else "python3")
                "jar" -> addAll(listOf("java", "-jar"))
                else -> throw IllegalArgumentException("Server script must be a .js, .py or .jar file")
            }
            add(serverScriptPath)
        }

        val process = ProcessBuilder(command).start()
        val transport = StdioClientTransport(
            input = process.inputStream.asSource().buffered(),
            output = process.outputStream.asSink().buffered()
        )

        mcp.connect(transport)

        val toolsResult = mcp.listTools()
        tools = toolsResult?.tools?.map { tool ->
            ToolUnion.ofTool(
                Tool.builder()
                    .name(tool.name)
                    .description(tool.description ?: "")
                    .inputSchema(
                        Tool.InputSchema.builder()
                            .type(JsonValue.from(tool.inputSchema.type))
                            .properties(tool.inputSchema.properties.toJsonValue())
                            .putAdditionalProperty("required", JsonValue.from(tool.inputSchema.required))
                            .build()
                    )
                    .build()
            )
        } ?: emptyList()
        println("Connected to server with tools: ${tools.joinToString(", ") { it.tool().get().name() }}")
    } catch (e: Exception) {
        println("Failed to connect to MCP server: $e")
        throw e
    }
}

同时创建一个辅助函数，用于将 JsonObject 转换为 Anthropic 的 JsonValue：

private fun JsonObject.toJsonValue(): JsonValue {
    val mapper = ObjectMapper()
    val node = mapper.readTree(this.toString())
    return JsonValue.fromJsonNode(node)
}

查询处理逻辑

现在让我们添加处理查询和工具调用的核心功能：

private val messageParamsBuilder: MessageCreateParams.Builder = MessageCreateParams.builder()
    .model(Model.CLAUDE_3_5_SONNET_20241022)
    .maxTokens(1024)

suspend fun processQuery(query: String): String {
    val messages = mutableListOf(
        MessageParam.builder()
            .role(MessageParam.Role.USER)
            .content(query)
            .build()
    )

    val response = anthropic.messages().create(
        messageParamsBuilder
            .messages(messages)
            .tools(tools)
            .build()
    )

    val finalText = mutableListOf<String>()
    response.content().forEach { content ->
        when {
            content.isText() -> finalText.add(content.text().getOrNull()?.text() ?: "")

            content.isToolUse() -> {
                val toolName = content.toolUse().get().name()
                val toolArgs =
                    content.toolUse().get()._input().convert(object : TypeReference<Map<String, JsonValue>>() {})

                val result = mcp.callTool(
                    name = toolName,
                    arguments = toolArgs ?: emptyMap()
                )
                finalText.add("[Calling tool $toolName with args $toolArgs]")

                messages.add(
                    MessageParam.builder()
                        .role(MessageParam.Role.USER)
                        .content(
                            """
                                "type": "tool_result",
                                "tool_name": $toolName,
                                "result": ${result?.content?.joinToString("\n") { (it as TextContent).text ?: "" }}
                            """.trimIndent()
                        )
                        .build()
                )

                val aiResponse = anthropic.messages().create(
                    messageParamsBuilder
                        .messages(messages)
                        .build()
                )

                finalText.add(aiResponse.content().first().text().getOrNull()?.text() ?: "")
            }
        }
    }

    return finalText.joinToString("\n", prefix = "", postfix = "")
}

交互式聊天

我们将添加聊天循环：

suspend fun chatLoop() {
    println("\nMCP Client Started!")
    println("Type your queries or 'quit' to exit.")

    while (true) {
        print("\nQuery: ")
        val message = readLine() ?: break
        if (message.lowercase() == "quit") break
        val response = processQuery(message)
        println("\n$response")
    }
}

主入口点

最后，我们将添加主执行函数：

fun main(args: Array<String>) = runBlocking {
    if (args.isEmpty()) throw IllegalArgumentException("Usage: java -jar <your_path>/build/libs/kotlin-mcp-client-0.1.0-all.jar <path_to_server_script>")
    val serverPath = args.first()
    val client = MCPClient()
    client.use {
        client.connectToServer(serverPath)
        client.chatLoop()
    }
}

运行客户端

要使用任何 MCP 服务器运行你的客户端：

./gradlew build

# 运行客户端
java -jar build/libs/<your-jar-name>.jar path/to/server.jar # jvm 服务器
java -jar build/libs/<your-jar-name>.jar path/to/server.py # python 服务器
java -jar build/libs/<your-jar-name>.jar path/to/build/index.js # node 服务器
Note

如果你正在继续服务器快速入门中的天气教程，你的命令可能看起来像这样：java -jar build/libs/kotlin-mcp-client-0.1.0-all.jar .../samples/weather-stdio-server/build/libs/weather-stdio-server-0.1.0-all.jar

客户端将：

  1. 连接到指定的服务器
  2. 列出可用的工具
  3. 启动一个交互式聊天会话，你可以：
    • 输入查询
    • 查看工具执行情况
    • 获取来自 Claude 的响应

工作原理

以下是高级工作流程图：

Client<< Tools MCP Server Claude Client Client<< Tools MCP Server Claude Client User Send queryGet available toolsSend query with tool descriptionsDecide tool executionRequest tool executionExecute chosen toolsReturn resultsSend resultsSend tool resultsProvide final responseDisplay response User

当你提交查询时：

  1. 客户端从服务器获取可用工具列表
  2. 你的查询连同工具描述一起发送给 Claude
  3. Claude 决定使用哪些工具（如果需要）
  4. 客户端通过服务器执行任何请求的工具调用
  5. 结果发送回 Claude
  6. Claude 提供自然语言响应
  7. 响应显示给你

最佳实践

  1. 错误处理

    • 利用 Kotlin 的类型系统显式建模错误
    • 在可能出现异常的地方使用 try-catch 块包装外部工具和 API 调用
    • 提供清晰且有意义的错误消息
    • 优雅地处理网络超时和连接问题

  2. 安全性

    • 在 local.properties、环境变量或密钥管理器中安全地存储 API 密钥和机密
    • 验证所有外部响应以避免意外或不安全的数据使用
    • 在使用工具时要谨慎对待权限和信任边界

故障排除

服务器路径问题

  • 仔细检查服务器脚本的路径是否正确
  • 如果相对路径不起作用，请使用绝对路径
  • 对于 Windows 用户，确保在路径中使用正斜杠（/）或转义的反斜杠（\）
  • 确保已安装所需的运行时（java 用于 Java，npm 用于 Node.js，或 uv 用于 Python）
  • 验证服务器文件具有正确的扩展名（Java 用 .jar，Node.js 用 .js，或 Python 用 .py）

正确路径使用示例：

# Relative path
java -jar build/libs/client.jar ./server/build/libs/server.jar

# Absoulute path
java -jar build/libs/client.jar /Users/username/projects/mcp-server/build/libs/server.jar

# Windows path (either format works)
java -jar build/libs/client.jar C:/projects/mcp-server/build/libs/server.jar
java -jar build/libs/client.jar C:\\projects\\mcp-server\\build\\libs\\server.jar

响应时间

  • 第一次响应可能需要长达30秒的时间
  • 这是正常现象，因为此时正在进行：
    • 服务器初始化
    • Claude处理查询
    • 工具执行
  • 后续响应通常会更快
  • 在这个初始等待期间请不要中断进程

常见错误消息

如果你看到：

  • Connection refused：确保服务器正在运行且路径正确
  • Tool execution failed：验证工具所需的环境变量是否已设置
  • ANTHROPIC_API_KEY is not set：检查你的环境变量
文章目录
© 2024, MRLJDX (Version: 20250624.0510)
Powered by