kotlin-mcp-server-generator

Kotlin MCP Server Project Generator

Generate a complete Model Context Protocol (MCP) server project in Kotlin.

Project Requirements

You will create a Kotlin MCP server with:

1. Project Structure: Gradle-based Kotlin project layout
2. Dependencies: Official MCP SDK, Ktor, and kotlinx libraries
3. Server Setup: Configured MCP server with transports
4. Tools: At least 2-3 useful tools with typed inputs/outputs
5. Error Handling: Proper exception handling and validation
6. Documentation: README with setup and usage instructions
7. 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.md

build.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 server, only needed for the SSE transport
    implementation("io.ktor:ktor-server-netty: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(),
            )
        )
    ) {
        config.description
    }
    
    // Register all tools
    server.registerTools()
    
    return server
}

Config.kt Template

package com.example.myserver

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

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, sent to LLM clients as server instructions; set it only from a trusted source and keep it short

## 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
\`\`\`

## License

MIT

Generation Instructions

When generating a Kotlin MCP server:

1. Gradle Setup: Create proper build.gradle.kts with all dependencies
2. Package Structure: Follow Kotlin package conventions
3. Type Safety: Use data classes and kotlinx.serialization
4. Coroutines: All operations should be suspending functions
5. Error Handling: Use Kotlin exceptions and validation
6. JSON Schemas: Use buildJsonObject for tool schemas
7. Testing: Include coroutine test utilities
8. Logging: Use kotlin-logging for structured logging
9. Configuration: Use data classes and environment variables
10. Documentation: KDoc comments for public APIs
11. Project names: Validate the project name before substitution. It must start with a lowercase letter and contain only lowercase letters, digits and hyphens, up to sixty four characters. Escape backslashes, double quotes and dollar signs in the project description and tool descriptions before placing them in Kotlin or Gradle string literals, or reject values that contain them.
12. Gradle wrapper: Generate the Gradle wrapper with a pinned Gradle version and a distribution checksum, commit the wrapper files, and validate the wrapper in CI before running it.
13. Dependency verification: Enable Gradle dependency locking for all configurations and generate Gradle dependency verification metadata with strong checksums. Commit both alongside the build script.
14. Dependency versions: The versions shown are examples and may be outdated, and the logback version shown has known vulnerabilities. Before generating, look up the latest patched stable releases of logback, Ktor, the MCP SDK and the other libraries, use them, and confirm the templates still compile against them.
15. Stdio logging: With the stdio transport, configure logback so console logs go to standard error or a file, because standard output carries the protocol stream.
16. Server lifetime: Keep the process running until the session closes, so the stdio server stays available after it connects.
17. Server instructions: The server description is sent to LLM clients as server instructions. Take it from a trusted, reviewed source and enforce a length limit on it.
18. Tool files: Create Tool2.kt following the same pattern as Tool1.kt, list the tool registry file alongside the tool files, include every import the tool code needs, and verify the tool registration and argument access code against the pinned SDK version.

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
• Treat all tool arguments as untrusted: enforce length limits on strings and allowed ranges on numbers, and validate arguments before passing them to files, shells, network calls or queries
• Return input validation failures as tool results marked as errors, with generic messages, so the model can see the problem and react to it

Transport Options

Stdio Transport

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

SSE Transport (Ktor)

Stdio is the default transport. Before using this SSE example, bind the server to the loopback interface only, validate the Origin and Host headers, and require authentication. Any access beyond the local machine also needs TLS or a reverse proxy.

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

Multiplatform Configuration

Optional. For multiplatform projects only, and only with the targets the user explicitly requests, add to build.gradle.kts:

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