SKILL.md
Kotlin MCP Server Project Generator
Generate a complete, production-ready Model Context Protocol (MCP) server project in Kotlin.
Project Requirements
You will create a Kotlin MCP server with:
- Project Structure: Gradle-based Kotlin project layout
- Dependencies: Official MCP SDK, Ktor, and kotlinx libraries
- Server Setup: Configured MCP server with transports
- Tools: At least 2-3 useful tools with typed inputs/outputs
- Error Handling: Proper exception handling and validation
- Documentation: README with setup and usage instructions
- Testing: Basic test structure with coroutines
Template Structure
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.mdbuild.gradle.kts Template
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 for transports
implementation("io.ktor:ktor-server-netty:3.0.0")
implementation("io.ktor:ktor-client-cio:3.0.0")
// Serialization
implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.7.3")
// Coroutines
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-core:1.9.0")
// Logging
implementation("io.github.oshai:kotlin-logging-jvm:7.0.0")
implementation("ch.qos.logback:logback-classic:1.5.12")
// Testing
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 Template
rootProject.name = "{{PROJECT_NAME}}"Main.kt Template
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 { "Starting MCP server..." }
val config = loadConfig()
val server = createServer(config)
// Use stdio transport
val transport = StdioServerTransport()
logger.info { "Server '${config.name}' v${config.version} ready" }
server.connect(transport)
}Server.kt Template
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
}
// Register all tools
server.registerTools()
return server
}Config.kt Template
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 Template
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 = "Description of what tool1 does",
inputSchema = buildJsonObject {
put("type", "object")
putJsonObject("properties") {
putJsonObject("param1") {
put("type", "string")
put("description", "First parameter")
}
putJsonObject("param2") {
put("type", "integer")
put("description", "Optional second parameter")
}
}
putJsonArray("required") {
add("param1")
}
}
) { request: CallToolRequest ->
// Extract and validate parameters
val param1 = request.params.arguments["param1"] as? String
?: throw IllegalArgumentException("param1 is required")
val param2 = (request.params.arguments["param2"] as? Number)?.toInt() ?: 0
// Perform tool logic
val result = performTool1Logic(param1, param2)
CallToolResult(
content = listOf(
TextContent(text = result)
)
)
}
}
private fun performTool1Logic(param1: String, param2: Int): String {
// Implement tool logic here
return "Processed: $param1 with value $param2"
}tools/ToolRegistry.kt Template
package com.example.myserver.tools
import io.modelcontextprotocol.kotlin.sdk.server.Server
fun Server.registerTools() {
registerTool1()
registerTool2()
// Register additional tools here
}ServerTest.kt Template
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 = "Test server"
)
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)
// Test tool execution
// Note: You'll need to implement proper testing utilities
// for calling tools in the server
}
}README.md Template
# {{PROJECT_NAME}}
A Model Context Protocol (MCP) server built with Kotlin.
## Description
{{PROJECT_DESCRIPTION}}
## Requirements
- Java 17 or higher
- Kotlin 2.1.0
## Installation
Build the project:
\`\`\`bash
./gradlew build
\`\`\`
## Usage
Run the server with stdio transport:
\`\`\`bash
./gradlew run
\`\`\`
Or build and run the jar:
\`\`\`bash
./gradlew installDist
./build/install/{{PROJECT_NAME}}/bin/{{PROJECT_NAME}}
\`\`\`
## Configuration
Configure via environment variables:
- `SERVER_NAME`: Server name (default: "{{PROJECT_NAME}}")
- `VERSION`: Server version (default: "1.0.0")
- `DESCRIPTION`: Server description
## Available Tools
### tool1
{{TOOL1_DESCRIPTION}}
**Input:**
- `param1` (string, required): First parameter
- `param2` (integer, optional): Second parameter
**Output:**
- Text result of the operation
## Development
Run tests:
\`\`\`bash
./gradlew test
\`\`\`
Build:
\`\`\`bash
./gradlew build
\`\`\`
Run with auto-reload (development):
\`\`\`bash
./gradlew run --continuous
\`\`\`
## Multiplatform
This project uses Kotlin Multiplatform and can target JVM, Wasm, and iOS.
See `build.gradle.kts` for platform configuration.
## License
MITGeneration Instructions
When generating a Kotlin MCP server:
- Gradle Setup: Create proper
build.gradle.ktswith all dependencies
- Package Structure: Follow Kotlin package conventions
- Type Safety: Use data classes and kotlinx.serialization
- Coroutines: All operations should be suspending functions
- Error Handling: Use Kotlin exceptions and validation
- JSON Schemas: Use
buildJsonObjectfor tool schemas
- Testing: Include coroutine test utilities
- Logging: Use kotlin-logging for structured logging
- Configuration: Use data classes and environment variables
- Documentation: KDoc comments for public APIs
Best Practices
- Use suspending functions for all async operations
- Leverage Kotlin's null safety and type system
- Use data classes for structured data
- Apply kotlinx.serialization for JSON handling
- Use sealed classes for result types
- Implement proper error handling with Result/Either patterns
- Write tests using kotlinx-coroutines-test
- Use dependency injection for testability
- Follow Kotlin coding conventions
- Use meaningful names and KDoc comments
Transport Options
Stdio Transport
val transport = StdioServerTransport()
server.connect(transport)SSE Transport (Ktor)
embeddedServer(Netty, port = 8080) {
mcp {
Server(/*...*/) { "Description" }
}
}.start(wait = true)Multiplatform Configuration
For multiplatform projects, add to build.gradle.kts:
kotlin {
jvm()
js(IR) { nodejs() }
wasmJs()
sourceSets {
commonMain.dependencies {
implementation("io.modelcontextprotocol:kotlin-sdk:0.7.2")
}
}
}