kotlin-mcp-server-generator

Kotlin MCP 伺服器專案產生器

產生一個完整、可上線的 Kotlin 版 Model Context Protocol (MCP) 伺服器專案。

專案需求

您將建立一個 Kotlin MCP 伺服器，包含：

1. 專案結構：基於 Gradle 的 Kotlin 專案佈局
2. 依賴項：官方 MCP SDK、Ktor 與 kotlinx 函式庫
3. 伺服器設定：已設定的 MCP 伺服器與傳輸方式
4. 工具：至少 2-3 個實用的工具，具備型別化的輸入/輸出
5. 錯誤處理：適當的例外處理與驗證
6. 文件：包含設定與使用說明的 README
7. 測試：使用協程的基本測試結構

範本結構

myserver/
├── build.gradle.kts
├── settings.gradle.kts
├── gradle.properties
├── src/
│   ├── main/
│   │   └── kotlin/
│   │       └── com/example/myserver/
│   │           ├── Main.kt
│   │           ├── Server.kt
│   │           ├── config/
│   │           │   └── Config.kt
│   │           └── tools/
│   │               ├── Tool1.kt
│   │               └── Tool2.kt
│   └── test/
│       └── kotlin/
│           └── com/example/myserver/
│               └── ServerTest.kt
└── README.md

build.gradle.kts 範本

plugins {
    kotlin("jvm") version "2.1.0"
    kotlin("plugin.serialization") version "2.1.0"
    application
}

group = "com.example"
version = "1.0.0"

repositories {
    mavenCentral()
}

dependencies {
    implementation("io.modelcontextprotocol:kotlin-sdk:0.7.2")
    
    // Ktor 用於傳輸
    implementation("io.ktor:ktor-server-netty:3.0.0")
    implementation("io.ktor:ktor-client-cio:3.0.0")
    
    // 序列化
    implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
    
    // 協程
    implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
    
    // 日誌
    implementation("io.github.oshai:kotlin-logging-jvm:7.0.0")
    implementation("ch.qos.logback:logback-classic:1.5.12")
    
    // 測試
    testImplementation(kotlin("test"))
    testImplementation("org.jetbrains.kotlinx:kotlinx-coroutines-test:1.9.0")
}

application {
    mainClass.set("com.example.myserver.MainKt")
}

tasks.test {
    useJUnitPlatform()
}

kotlin {
    jvmToolchain(17)
}

settings.gradle.kts 範本

rootProject.name = "{{PROJECT_NAME}}"

Main.kt 範本

package com.example.myserver

import io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransport
import kotlinx.coroutines.runBlocking
import io.github.oshai.kotlinlogging.KotlinLogging

private val logger = KotlinLogging.logger {}

fun main() = runBlocking {
    logger.info { "正在啟動 MCP 伺服器..." }
    
    val config = loadConfig()
    val server = createServer(config)
    
    // 使用 stdio 傳輸
    val transport = StdioServerTransport()
    
    logger.info { "伺服器 '${config.name}' v${config.version} 已就緒" }
    server.connect(transport)
}

Server.kt 範本

package com.example.myserver

import io.modelcontextprotocol.kotlin.sdk.server.Server
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
import io.modelcontextprotocol.kotlin.sdk.Implementation
import io.modelcontextprotocol.kotlin.sdk.ServerCapabilities
import com.example.myserver.tools.registerTools

fun createServer(config: Config): Server {
    val server = Server(
        serverInfo = Implementation(
            name = config.name,
            version = config.version
        ),
        options = ServerOptions(
            capabilities = ServerCapabilities(
                tools = ServerCapabilities.Tools(),
                resources = ServerCapabilities.Resources(
                    subscribe = true,
                    listChanged = true
                ),
                prompts = ServerCapabilities.Prompts(listChanged = true)
            )
        )
    ) {
        config.description
    }
    
    // 註冊所有工具
    server.registerTools()
    
    return server
}

Config.kt 範本

package com.example.myserver.config

import kotlinx.serialization.Serializable

@Serializable
data class Config(
    val name: String = "{{PROJECT_NAME}}",
    val version: String = "1.0.0",
    val description: String = "{{PROJECT_DESCRIPTION}}"
)

fun loadConfig(): Config {
    return Config(
        name = System.getenv("SERVER_NAME") ?: "{{PROJECT_NAME}}",
        version = System.getenv("VERSION") ?: "1.0.0",
        description = System.getenv("DESCRIPTION") ?: "{{PROJECT_DESCRIPTION}}"
    )
}

Tool1.kt 範本

package com.example.myserver.tools

import io.modelcontextprotocol.kotlin.sdk.server.Server
import io.modelcontextprotocol.kotlin.sdk.CallToolRequest
import io.modelcontextprotocol.kotlin.sdk.CallToolResult
import io.modelcontextprotocol.kotlin.sdk.TextContent
import kotlinx.serialization.json.buildJsonObject
import kotlinx.serialization.json.put
import kotlinx.serialization.json.putJsonObject
import kotlinx.serialization.json.putJsonArray

fun Server.registerTool1() {
    addTool(
        name = "tool1",
        description = "描述 tool1 的功能",
        inputSchema = buildJsonObject {
            put("type", "object")
            putJsonObject("properties") {
                putJsonObject("param1") {
                    put("type", "string")
                    put("description", "第一個參數")
                }
                putJsonObject("param2") {
                    put("type", "integer")
                    put("description", "可選的第二個參數")
                }
            }
            putJsonArray("required") {
                add("param1")
            }
        }
    ) { request: CallToolRequest ->
        // 提取並驗證參數
        val param1 = request.params.arguments["param1"] as? String
            ?: throw IllegalArgumentException("param1 為必填")
        val param2 = (request.params.arguments["param2"] as? Number)?.toInt() ?: 0
        
        // 執行工具邏輯
        val result = performTool1Logic(param1, param2)
        
        CallToolResult(
            content = listOf(
                TextContent(text = result)
            )
        )
    }
}

private fun performTool1Logic(param1: String, param2: Int): String {
    // 在此實作工具邏輯
    return "已處理：$param1，數值 $param2"
}

tools/ToolRegistry.kt 範本

package com.example.myserver.tools

import io.modelcontextprotocol.kotlin.sdk.server.Server

fun Server.registerTools() {
    registerTool1()
    registerTool2()
    // 在此註冊其他工具
}

ServerTest.kt 範本

package com.example.myserver

import kotlinx.coroutines.test.runTest
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.test.assertFalse

class ServerTest {
    
    @Test
    fun `test server creation`() = runTest {
        val config = Config(
            name = "test-server",
            version = "1.0.0",
            description = "測試伺服器"
        )
        
        val server = createServer(config)
        
        assertEquals("test-server", server.serverInfo.name)
        assertEquals("1.0.0", server.serverInfo.version)
    }
    
    @Test
    fun `test tool1 execution`() = runTest {
        val config = Config()
        val server = createServer(config)
        
        // 測試工具執行
        // 注意：您需要實作適當的測試工具來呼叫伺服器中的工具
    }
}

README.md 範本

# {{PROJECT_NAME}}

使用 Kotlin 建置的 Model Context Protocol (MCP) 伺服器。

## 說明

{{PROJECT_DESCRIPTION}}

## 需求

- Java 17 或更高版本
- Kotlin 2.1.0

## 安裝

建置專案：

\`\`\`bash
./gradlew build
\`\`\`

## 使用方式

使用 stdio 傳輸執行伺服器：

\`\`\`bash
./gradlew run
\`\`\`

或建置並執行 jar：

\`\`\`bash
./gradlew installDist
./build/install/{{PROJECT_NAME}}/bin/{{PROJECT_NAME}}
\`\`\`

## 設定

透過環境變數設定：

- `SERVER_NAME`：伺服器名稱（預設："{{PROJECT_NAME}}"）
- `VERSION`：伺服器版本（預設："1.0.0"）
- `DESCRIPTION`：伺服器說明

## 可用工具

### tool1
{{TOOL1_DESCRIPTION}}

**輸入：**
- `param1`（字串，必填）：第一個參數
- `param2`（整數，可選）：第二個參數

**輸出：**
- 操作的文字結果

## 開發

執行測試：

\`\`\`bash
./gradlew test
\`\`\`

建置：

\`\`\`bash
./gradlew build
\`\`\`

使用自動重新載入執行（開發模式）：

\`\`\`bash
./gradlew run --continuous
\`\`\`

## 多平台

此專案使用 Kotlin Multiplatform，可針對 JVM、Wasm 和 iOS。
請參閱 `build.gradle.kts` 了解平台設定。

## 授權

MIT

產生說明

產生 Kotlin MCP 伺服器時：

1. Gradle 設定：建立包含所有依賴項的 build.gradle.kts
2. 套件結構：遵循 Kotlin 套件慣例
3. 型別安全：使用 data class 和 kotlinx.serialization
4. 協程：所有操作應為暫停函式
5. 錯誤處理：使用 Kotlin 例外與驗證
6. JSON Schema：使用 buildJsonObject 建立工具 schema
7. 測試：包含協程測試工具
8. 日誌：使用 kotlin-logging 進行結構化日誌
9. 設定：使用 data class 和環境變數
10. 文件：公開 API 加上 KDoc 註解

最佳實務

• 所有非同步操作使用暫停函式
• 善用 Kotlin 的空值安全與型別系統
• 使用 data class 處理結構化資料
• 使用 kotlinx.serialization 處理 JSON
• 使用 sealed class 作為結果型別
• 使用 Result/Either 模式實作適當的錯誤處理
• 使用 kotlinx-coroutines-test 撰寫測試
• 使用依賴注入提升可測試性
• 遵循 Kotlin 編碼慣例
• 使用有意義的名稱與 KDoc 註解

傳輸選項

Stdio 傳輸

val transport = StdioServerTransport()
server.connect(transport)

SSE 傳輸（Ktor）

embeddedServer(Netty, port = 8080) {
    mcp {
        Server(/*...*/) { "說明" }
    }
}.start(wait = true)

多平台設定

對於多平台專案，在 build.gradle.kts 中加入：

kotlin {
    jvm()
    js(IR) { nodejs() }
    wasmJs()
    
    sourceSets {
        commonMain.dependencies {
            implementation("io.modelcontextprotocol:kotlin-sdk:0.7.2")
        }
    }
}