MCP Kotlin SDK

适用于 Model Context Protocol 的 Kotlin 多平台 SDK。 它使面向 JVM、Native、JS 和 Wasm 的 Kotlin 应用程序能够使用标准化的协议接口实现 MCP 客户端和服务器。

目录

• 概述
• 安装
  • 构件
  • Gradle 配置 (JVM)
  • 多平台
  • Ktor 依赖项
• 快速入门
  • 创建客户端
  • 创建服务器
• 核心概念
  • MCP 原语
  • 能力
    • 服务器能力
    • 客户端能力
  • 服务器功能
    • 提示
    • 资源
    • 工具
    • 完成
    • 日志记录
    • 分页
  • 客户端功能
    • 根节点
    • 采样
• 传输层
  • STDIO 传输
  • 可流式 HTTP 传输
  • SSE 传输
  • WebSocket 传输
  • ChannelTransport（测试）
• 连接你的服务器
• 示例
• 文档
• 贡献
• 许可证

概述

Model Context Protocol 允许应用程序以标准化的方式为 LLM 提供上下文， 将提供上下文的关注点与实际的 LLM 交互分离。 该 Kotlin SDK 实现了 MCP 规范，使其易于：

• 构建可以连接到任何 MCP 服务器的 MCP 客户端
• 创建公开资源、提示和工具的 MCP 服务器
• 从单个代码库针对 JVM、Native、JS 和 Wasm 进行开发
• 使用标准传输层，如 stdio、SSE、可流式 HTTP 和 WebSocket
• 使用协程友好的 API 处理 MCP 协议消息和生命周期事件

安装

构件

• io.modelcontextprotocol:kotlin-sdk – 总体 SDK（客户端 + 服务器 API）
• io.modelcontextprotocol:kotlin-sdk-client – 仅客户端 API
• io.modelcontextprotocol:kotlin-sdk-server – 仅服务器 API

Gradle 配置 (JVM)

添加 Maven Central 仓库和 SDK 依赖项：

repositories {
    mavenCentral()
}

dependencies {
    // 请参阅上方徽章以获取最新版本
    implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
}

如果您只需要其中一方的 API，请使用 kotlin-sdk-client 或 kotlin-sdk-server：

dependencies {
    implementation("io.modelcontextprotocol:kotlin-sdk-client:$mcpVersion")
    implementation("io.modelcontextprotocol:kotlin-sdk-server:$mcpVersion")
}

多平台

在 Kotlin 多平台项目中，您可以将 SDK 添加到 commonMain：

commonMain {
    dependencies {
        // 既可用作公共依赖，也可用作平台特定依赖
        implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
    }
}

Ktor 依赖项

Kotlin MCP SDK 使用 Ktor，但不会传递性地添加 Ktor 引擎依赖。 您需要自行声明 Ktor 客户端/服务器 依赖项（或复用项目中已有的依赖项），例如：

dependencies {
    // 带有 Ktor 的 MCP 客户端
    implementation("io.ktor:ktor-client-cio:$ktorVersion")
    implementation("io.modelcontextprotocol:kotlin-sdk-client:$mcpVersion")

    // 带有 Ktor 的 MCP 服务器
    implementation("io.ktor:ktor-server-netty:$ktorVersion")
    implementation("io.modelcontextprotocol:kotlin-sdk-server:$mcpVersion")
}

快速入门

让我们创建一个简单的 MCP 客户端和服务器，以演示 Kotlin SDK 的基本用法。

创建客户端

创建一个通过可流式 HTTP 传输连接到服务器并列出可用工具的 MCP 客户端：

import io.ktor.client.HttpClient
import io.ktor.client.plugins.sse.SSE
import io.modelcontextprotocol.kotlin.sdk.client.Client
import io.modelcontextprotocol.kotlin.sdk.client.StreamableHttpClientTransport
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
import kotlinx.coroutines.runBlocking

fun main(args: Array<String>) = runBlocking {
    val url = args.firstOrNull() ?: "http://localhost:3000/mcp"

    val httpClient = HttpClient { install(SSE) }

    val client = Client(
        clientInfo = Implementation(
            name = "example-client",
            version = "1.0.0"
        )
    )

    val transport = StreamableHttpClientTransport(
        client = httpClient,
        url = url
    )

    // 连接到服务器
    client.connect(transport)

    // 列出可用工具
    val tools = client.listTools().tools

    println(tools)
}

创建服务器

创建一个 MCP 服务器，该服务器公开一个简单工具，并在嵌入式 Ktor 服务器上运行，使用 Streamable HTTP 传输协议。 有关包含所有必需依赖项的完整工作项目，请参阅 simple-streamable-server 示例。

import io.ktor.server.cio.CIO
import io.ktor.server.engine.embeddedServer
import io.modelcontextprotocol.kotlin.sdk.server.Server
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
import io.modelcontextprotocol.kotlin.sdk.server.mcpStreamableHttp
import io.modelcontextprotocol.kotlin.sdk.types.CallToolResult
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
import io.modelcontextprotocol.kotlin.sdk.types.TextContent
import io.modelcontextprotocol.kotlin.sdk.types.ToolSchema
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

fun main(args: Array<String>) {
    val port = args.firstOrNull()?.toIntOrNull() ?: 3000
    val mcpServer = Server(
        serverInfo = Implementation(
            name = "example-server",
            version = "1.0.0"
        ),
        options = ServerOptions(
            capabilities = ServerCapabilities(
                tools = ServerCapabilities.Tools(listChanged = true),
            ),
        )
    )

    mcpServer.addTool(
        name = "example-tool",
        description = "一个示例工具",
        inputSchema = ToolSchema(
            properties = buildJsonObject {
                put("input", buildJsonObject { put("type", "string") })
            }
        )
    ) { request ->
        CallToolResult(content = listOf(TextContent("你好，世界！")))
    }
    
    embeddedServer(CIO, host = "127.0.0.1", port = port) {
        mcpStreamableHttp {
            mcpServer
        }
    }.start(wait = true)
}

你可以运行该服务器，然后使用客户端连接到它，或者使用 MCP Inspector 进行测试：

npx -y @modelcontextprotocol/inspector

在 Inspector 的 UI 中，连接到 http://localhost:3000/mcp。

核心概念

MCP 原语

MCP 协议定义了用于实现服务器与客户端之间通信的核心原语：

原语	服务器角色	客户端角色	描述
提示	提供带有可选参数的提示模板	请求并使用提示	用于 LLM 交互的交互式模板
资源	公开数据源（文件、API 响应等）	读取并订阅资源	用于增强 LLM 上下文的上下文数据
工具	定义可执行函数	调用工具以执行操作	LLM 可以调用以执行动作的函数
采样	向客户端请求 LLM 补全	执行 LLM 调用并返回结果	由服务器发起的 LLM 请求（反向方向）

功能

功能定义了服务器或客户端支持哪些特性。它们在初始化时声明，并决定可用的操作。

服务器功能

服务器会声明其功能，以告知客户端它们提供的特性：

功能	特性标志	描述
prompts	listChanged	提示模板管理和通知
resources	subscribe listChanged	资源暴露、订阅及更新通知
tools	listChanged	工具发现、执行及列表变更通知
logging	-	服务器日志记录到客户端控制台
completions	-	参数自动补全建议
experimental	自定义属性	非标准实验性功能

客户端功能

客户端会声明其功能，以告知服务器它们支持的特性：

功能	特性标志	描述
sampling	-	客户端可以从 LLM 中采样（执行模型请求）
roots	listChanged	客户端暴露根目录并能通知更改
elicitation	-	客户端可以显示模式/表单对话框以获取结构化输入
experimental	自定义属性	非标准实验性功能

服务器功能

Server API 使你只需几行 Kotlin 代码即可将提示、资源和工具连接起来。每个功能都在一开始就注册好，然后在客户端请求时才被延迟解析，因此你的处理程序可以保持简洁且可挂起。

提示

提示是用户可控的模板，客户端可以通过 prompts/list 发现它们，并在用户选择其中一个时通过 prompts/get 获取（类似于斜杠命令或保存的工作流）。它们最适合重复性的、结构化的起点，而不是临时的模型调用。

val server = Server(
    serverInfo = Implementation(
        name = "example-server",
        version = "1.0.0"
    ),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            prompts = ServerCapabilities.Prompts(listChanged = true),
        ),
    )
)

server.addPrompt(
    name = "code-review",
    description = "请求模型审查一个差异文件",
    arguments = listOf(
        PromptArgument(name = "diff", description = "统一格式的差异文件", required = true),
    ),
) { request ->
    GetPromptResult(
        description = "快速代码审查助手",
        messages = listOf(
            PromptMessage(
                role = Role.User,
                content = TextContent(text = "请审查以下更改：\n${request.arguments?.get("diff")}"),
            ),
        ),
    )
}

将任何需要模板化的内容都使用提示词来处理：例如错误分类问题、入职检查清单或保存的搜索。仅当您的提示词目录可以在运行时发生变化，并且服务器会在发生变更时发出 notifications/prompts/list_changed 通知时，才设置 listChanged = true。

资源

资源是由应用程序驱动的上下文，客户端可以通过 resources/list 或 resources/templates/list 发现它们，然后使用 resources/read 获取。为每个资源注册一个稳定的 URI，并在被请求时返回 ReadResourceResult——内容可以是文本或二进制数据块。

val server = Server(
    serverInfo = Implementation(
        name = "example-server",
        version = "1.0.0"
    ),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            resources = ServerCapabilities.Resources(subscribe = true, listChanged = true),
        ),
    )
)

server.addResource(
    uri = "note://release/latest",
    name = "发布说明",
    description = "最近一次部署摘要",
    mimeType = "text/markdown",
) { request ->
    ReadResourceResult(
        contents = listOf(
            TextResourceContents(
                text = "版本42已成功部署到生产环境。",
                uri = request.uri,
                mimeType = "text/markdown",
            ),
        ),
    )
}

资源可以是静态文本、生成的 JSON 数据或二进制数据——任何客户端可以呈现给用户或注入到模型上下文中去的内容。如果您会针对特定 URI 的变化发出 notifications/resources/updated 通知，则设置 subscribe = true；如果资源目录本身会发生变化，则设置 listChanged = true，以便在目录变更时发送 notifications/resources/list_changed 通知。

工具

工具是客户端向模型暴露的由模型控制的功能。客户端通过 tools/list 发现这些工具，使用 tools/call 调用它们，而您的处理器会接收 JSON 格式的参数，可以输出流式日志或进度信息，并返回 CallToolResult。对于敏感操作，请务必保留人工干预环节。

val server = Server(
    serverInfo = Implementation(
        name = "example-server",
        version = "1.0.0"
    ),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            tools = ServerCapabilities.Tools(listChanged = true),
        ),
    )
)

server.addTool(
    name = "echo",
    description = "将用户发送的内容原样返回给他们",
) { request ->
    val text = request.arguments?.get("text")?.jsonPrimitive?.content ?: "(空)"
    CallToolResult(content = listOf(TextContent(text = "回声：$text")))
}

根据需要注册任意数量的工具——长时间运行的任务可以通过请求上下文报告进度，而工具也可以在需要客户端的 LLM 时触发采样（见下文）。仅当您的工具目录可以在运行时发生变化，并且服务器会在发生变更时发出 notifications/tools/list_changed 通知时，才设置 listChanged = true。

补全功能

补全功能为提示词或资源模板提供参数建议。声明 completions 功能，并处理 completion/complete 请求，以返回最多 100 个排序后的值（如果分页显示，则应包含 total 和 hasMore）。

val server = Server(
    serverInfo = Implementation(
        name = "example-server",
        version = "1.0.0"
    ),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            completions = ServerCapabilities.Completions,
        ),
    )
)

val session = server.createSession(
    StdioServerTransport(
        inputStream = System.`in`.asSource().buffered(),
        outputStream = System.out.asSink().buffered()
    )
)

session.setRequestHandler<CompleteRequest>(Method.Defined.CompletionComplete) { request, _ ->
    val options = listOf("kotlin", "compose", "coroutine")
    val matches = options.filter { it.startsWith(request.argument.value.lowercase()) }

    CompleteResult(
        completion = CompleteResult.Completion(
            values = matches.take(3),
            total = matches.size,
            hasMore = matches.size > 3,
        ),
    )
}

使用 context.arguments 来优化依赖字段的建议（例如，根据所选语言筛选框架列表）。

日志记录

日志记录允许服务器使用 RFC 5424 级别（从 debug 到 emergency）向客户端流式传输结构化日志通知。声明 logging 功能；客户端可以通过 logging/setLevel 提升最低日志级别，而服务器则会发出带有严重性、可选的日志记录器名称和 JSON 数据的 notifications/message 通知。

val server = Server(
    serverInfo = Implementation("example-server", "1.0.0"),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            logging = ServerCapabilities.Logging,
        ),
    )
)

val session = server.createSession(
    StdioServerTransport(
        inputStream = System.`in`.asSource().buffered(),
        outputStream = System.out.asSink().buffered()
    )
)

session.sendLoggingMessage(
    LoggingMessageNotification(
        LoggingMessageNotificationParams(
            level = LoggingLevel.Info,
            logger = "startup",
            data = buildJsonObject { put("message", "Server started") },
        ),
    ),
)

日志中应避免包含敏感数据，客户端应在自己的用户界面中展示这些日志。

分页

列表操作会返回分页结果，并附带一个不透明的 nextCursor。客户端需要将该游标传递回去以获取下一页内容。支持的列表调用包括：resources/list、resources/templates/list、prompts/list 和 tools/list。请将游标视为不透明对象——不要解析或在不同会话之间持久化它们。

val server = Server(
    serverInfo = Implementation("example-server", "1.0.0"),
    options = ServerOptions(
        capabilities = ServerCapabilities(
            resources = ServerCapabilities.Resources(),
        ),
    )
)

val session = server.createSession(
    StdioServerTransport(
        inputStream = System.`in`.asSource().buffered(),
        outputStream = System.out.asSink().buffered()
    )
)

val resources = listOf(
    Resource(uri = "note://1", name = "Note 1", description = "First"),
    Resource(uri = "note://2", name = "Note 2", description = "Second"),
    Resource(uri = "note://3", name = "Note 3", description = "Third"),
)
val pageSize = 2

session.setRequestHandler<ListResourcesRequest>(Method.Defined.ResourcesList) { request, _ ->
    val start = request.params?.cursor?.toIntOrNull() ?: 0
    val page = resources.drop(start).take(pageSize)
    val next = if (start + page.size < resources.size) (start + page.size).toString() else null

    ListResourcesResult(
        resources = page,
        nextCursor = next,
    )
}

仅当还有更多项目时才包含 nextCursor；如果游标为空，则表示分页结束。

客户端功能

客户端在初始化时会公布其能力（如根目录、采样、诱导等）。此后，它们可以在响应来自服务器的请求的同时，继续发起诸如 listTools 或 callTool 之类的调用。

根目录

根目录允许客户端声明服务器被允许操作的范围。声明 roots 能力，响应 roots/list 请求，并在设置 listChanged = true 时发出 notifications/roots/list_changed 通知。URI 必须 是 file:// 路径。

val client = Client(
    clientInfo = Implementation("demo-client", "1.0.0"),
    options = ClientOptions(
        capabilities = ClientCapabilities(roots = ClientCapabilities.Roots(listChanged = true)),
    ),
)

client.addRoot(
    uri = "file:///Users/demo/projects",
    name = "Projects",
)
client.sendRootsListChanged()

每当文件系统视图发生变化时，调用 addRoot/removeRoot，并使用 sendRootsListChanged() 通知服务器。确保根目录列表由用户控制，并撤销不再授权的条目。

择样

择样功能使服务器能够请求客户端调用其首选的大型语言模型。声明 sampling 能力（如果支持工具启用的择样，则还需声明 sampling.tools），并处理 sampling/createMessage 请求。审批流程中应始终有人工参与。

val client = Client(
    clientInfo = Implementation("demo-client", "1.0.0"),
    options = ClientOptions(
        capabilities = ClientCapabilities(
            sampling = buildJsonObject { putJsonObject("tools") { } }, // 如果不支持工具使用，则省略 tools
        ),
    ),
)

client.setRequestHandler<CreateMessageRequest>(Method.Defined.SamplingCreateMessage) { request, _ ->
    val content = request.messages.lastOrNull()?.content
    val prompt = if (content is TextContent) content.text else "your topic"
    CreateMessageResult(
        model = "gpt-4o-mini",
        role = Role.Assistant,
        content = TextContent(text = "Here is a short note about $prompt"),
    )
}

在处理器中，您可以选择任何模型或提供商，要求审批，或拒绝请求。如果不支持工具使用，请在能力声明中省略 sampling.tools。

传输协议

所有传输协议共享相同的 API 接口，因此您无需修改业务逻辑即可更改部署方式。请选择最适合服务器运行环境的传输协议。

STDIO 传输协议

StdioClientTransport 和 StdioServerTransport 通过标准输入/输出隧道传输 MCP 消息，非常适合需要启动辅助进程的编辑器插件或 CLI 工具。无需任何网络配置。

可流式 HTTP 传输协议

StreamableHttpClientTransport 以及 Ktor 的 mcpStreamableHttp() 和 mcpStatelessStreamableHttp() 辅助函数，可通过单个 HTTP 端点暴露 MCP，支持可选的仅 JSON 或 SSE 流式响应。这是远程部署的推荐选择，并能很好地与代理或服务网格集成。

这些辅助函数会自动安装带有 McpJson 的 ContentNegotiation 插件——请勿自行安装，否则会记录警告信息。两者都接受 path 参数（默认为 "/mcp"），以便将端点挂载到任意 URL：

embeddedServer(CIO, port = 3000) {
    mcpStreamableHttp(path = "/api/mcp") {
        MyServer()
    }
}.start(wait = true)

针对基于浏览器的客户端（例如 MCP Inspector）的 CORS 设置： 如果您从基于浏览器的客户端连接，需要安装 Ktor 的 CORS 插件，以允许并暴露 MCP 特定的头部信息：

install(CORS) {
    anyHost() // 在生产环境中限制为特定来源
    allowMethod(HttpMethod.Options)
    allowMethod(HttpMethod.Get)
    allowMethod(HttpMethod.Post)
    allowMethod(HttpMethod.Delete)
    allowNonSimpleContentTypes = true
    allowHeader("Mcp-Session-Id")
    allowHeader("Mcp-Protocol-Version")
    exposeHeader("Mcp-Session-Id")
    exposeHeader("Mcp-Protocol-Version")
}

SSE 传输

服务器发送事件仍可用于与旧版 MCP 客户端的向后兼容。提供了两个 Ktor 辅助函数：

• Application.mcp { } — 自动安装 SSE 和带有 McpJson 的 ContentNegotiation，然后在 / 路径下注册 MCP 端点。请勿自行安装 ContentNegotiation——SDK 已经处理好了。
• Route.mcp { } — 在当前路由路径下注册 MCP 端点；需要先在应用中调用 install(SSE)。使用此方法可以在其他路由旁边或特定路径前缀下托管 MCP：

embeddedServer(CIO, port = 3000) {
    install(SSE)
    routing {
        route("/api/mcp") {
            mcp { MyServer() }
        }
    }
}.start(wait = true)

对于新项目，建议使用可流式 HTTP。

WebSocket 传输

WebSocketClientTransport 结合相应的服务器工具，可以提供全双工、低延迟的连接——这在您预计会有大量通知或长时间会话，并且反向代理已经终止 WebSocket 连接的情况下非常有用。

ChannelTransport（测试）

ChannelTransport 提供了一种简单、无需网络的传输方式，适用于测试和本地开发。它使用 Kotlin 协程通道在客户端和服务器之间建立全双工连接，从而无需设置网络即可轻松测试 MCP 功能。

连接您的服务器

1. 在端口 3000 上启动一个示例 HTTP 服务器：

   ./gradlew :samples:kotlin-mcp-server:run
   

2. 使用 MCP Inspector 或 Claude Desktop/Code 进行连接：

   npx -y @modelcontextprotocol/inspector --connect http://localhost:3000
   # 或
   claude mcp add --transport http kotlin-mcp http://localhost:3000
   

3. 在 Inspector 中，确认提示、工具、资源、补全和日志是否正常显示。在本地反复迭代，直到您准备好将服务器部署到任何您希望的位置。

示例

samples 目录包含可运行的项目，展示了使用各种传输方式实现的 MCP 服务器和客户端。请参阅 samples 概览，其中提供了对比表格和详细说明。

文档

• API 参考文档
• 模型上下文协议文档
• MCP 规范

贡献

在贡献之前，请阅读 贡献指南 和 行为准则。

许可证

本项目对新贡献采用 Apache 2.0 许可证，现有代码则采用 MIT 许可证——详情请参阅 LICENSE 文件。

Kotlin MCP SDK 快速上手指南

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Kotlin: 版本 2.2 或更高。
• JDK: 版本 11 或更高（针对 JVM 目标）。
• 构建工具: Gradle (推荐) 或 Maven。
• 平台支持: 支持 JVM, Native, JS (Wasm) 多平台开发。
• 依赖框架: 本 SDK 基于 Ktor 构建，但不会传递性引入 Ktor 引擎依赖，您需要根据项目需求手动添加对应的 Ktor Client 或 Server 依赖。

安装步骤

1. 配置仓库

在 build.gradle.kts (或 build.gradle) 中添加 Maven Central 仓库：

repositories {
    mavenCentral()
}

提示：国内开发者若访问 Maven Central 较慢，可在 settings.gradle.kts 中配置阿里云镜像：

dependencyResolutionManagement {
    repositories {
        maven { url = uri("https://maven.aliyun.com/repository/public") }
        mavenCentral()
    }
}

2. 添加依赖

根据您的项目类型选择依赖方式。请将 $mcpVersion 替换为最新版本号（参考 README 顶部的徽章）。

方案 A：完整 SDK (客户端 + 服务端)

dependencies {
    implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
}

方案 B：仅客户端 或 仅服务端

dependencies {
    // 仅客户端
    implementation("io.modelcontextprotocol:kotlin-sdk-client:$mcpVersion")
    
    // 仅服务端
    implementation("io.modelcontextprotocol:kotlin-sdk-server:$mcpVersion")
}

方案 C：Kotlin Multiplatform (KMP)

在 commonMain 源集中添加：

commonMain {
    dependencies {
        implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
    }
}

3. 配置 Ktor 引擎 (必需)

SDK 需要您显式声明 Ktor 引擎依赖。

对于 MCP 客户端:

dependencies {
    implementation("io.ktor:ktor-client-cio:$ktorVersion") // 或其他引擎
    implementation("io.modelcontextprotocol:kotlin-sdk-client:$mcpVersion")
}

对于 MCP 服务端:

dependencies {
    implementation("io.ktor:ktor-server-netty:$ktorVersion") // 或其他引擎
    implementation("io.modelcontextprotocol:kotlin-sdk-server:$mcpVersion")
}

基本使用

以下示例展示如何快速创建一个 MCP 服务端和一个连接到该服务端的客户端。

1. 创建 MCP 服务端

创建一个暴露简单工具（Tool）的服务端，运行在嵌入式 Ktor 服务器上，使用 Streamable HTTP 传输协议。

import io.ktor.server.cio.CIO
import io.ktor.server.engine.embeddedServer
import io.modelcontextprotocol.kotlin.sdk.server.Server
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
import io.modelcontextprotocol.kotlin.sdk.server.mcpStreamableHttp
import io.modelcontextprotocol.kotlin.sdk.types.CallToolResult
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
import io.modelcontextprotocol.kotlin.sdk.types.ServerCapabilities
import io.modelcontextprotocol.kotlin.sdk.types.TextContent
import io.modelcontextprotocol.kotlin.sdk.types.ToolSchema
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put

fun main(args: Array<String>) {
    val port = args.firstOrNull()?.toIntOrNull() ?: 3000
    
    // 初始化服务器
    val mcpServer = Server(
        serverInfo = Implementation(
            name = "example-server",
            version = "1.0.0"
        ),
        options = ServerOptions(
            capabilities = ServerCapabilities(
                tools = ServerCapabilities.Tools(listChanged = true),
            ),
        )
    )

    // 注册一个工具
    mcpServer.addTool(
        name = "example-tool",
        description = "An example tool",
        inputSchema = ToolSchema(
            properties = buildJsonObject {
                put("input", buildJsonObject { put("type", "string") })
            }
        )
    ) { request ->
        // 处理工具调用逻辑
        CallToolResult(content = listOf(TextContent("Hello, world!")))
    }
    
    // 启动嵌入式服务器
    embeddedServer(CIO, host = "127.0.0.1", port = port) {
        mcpStreamableHttp {
            mcpServer
        }
    }.start(wait = true)
}

2. 创建 MCP 客户端

创建一个客户端，通过 Streamable HTTP 连接到上述服务器，并列出可用的工具。

import io.ktor.client.HttpClient
import io.ktor.client.plugins.sse.SSE
import io.modelcontextprotocol.kotlin.sdk.client.Client
import io.modelcontextprotocol.kotlin.sdk.client.StreamableHttpClientTransport
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
import kotlinx.coroutines.runBlocking

fun main(args: Array<String>) = runBlocking {
    val url = args.firstOrNull() ?: "http://localhost:3000/mcp"

    // 配置 HttpClient 并安装 SSE 插件
    val httpClient = HttpClient { install(SSE) }

    // 初始化客户端
    val client = Client(
        clientInfo = Implementation(
            name = "example-client",
            version = "1.0.0"
        )
    )

    // 配置传输层
    val transport = StreamableHttpClientTransport(
        client = httpClient,
        url = url
    )

    // 连接服务器
    client.connect(transport)

    // 获取并打印可用工具列表
    val tools = client.listTools().tools
    println(tools)
}

3. 运行与测试

1. 先运行服务端代码（默认端口 3000）。
2. 再运行客户端代码。
3. 或者，您可以使用官方 MCP Inspector 进行可视化测试：

   npx -y @modelcontextprotocol/inspector
   

   在 Inspector 界面中连接地址：http://localhost:3000/mcp。