A Kotlin Multiplatform MCP (Model Context Protocol) server that provides audio processing, subtitles, and command execution capabilities.

MCP server running over stdio transport, providing three declaration types:

MyMCPTools/
├── mcp-tool-annotations/            # Multiplatform annotations
│   └── src/commonMain/kotlin/       #   @McpTool, @ToolParam, @McpResource, @McpPrompt, @PromptParam
├── mcp-tool-ksp/                    # KSP processor for code generation
│   └── src/
│       ├── main/kotlin/             #   Processor & validators
│       └── test/kotlin/             #   Processor tests
├── process/                         # Shared process handling (expect/actual)
│   └── src/
│       ├── commonMain/kotlin/       #   Common Process/ProcessBuilder API
│       ├── jvmMain/kotlin/          #   JVM implementation
│       ├── linuxMain/kotlin/        #   Linux native implementation
│       └── mingwMain/kotlin/        #   Windows native implementation
├── essential-mcp/                 # Main MCP server
│   └── src/
│       ├── commonMain/kotlin/       #   Shared code, tool/resource/prompt implementations
│       │   ├── mcptool/             #     Tool implementations
│       │   └── utils/               #     Utilities
│       ├── commonTest/kotlin/       #   Common tests
│       ├── jvmMain/kotlin/          #   JVM entry point
│       ├── linuxMain/kotlin/        #   Linux native entry
│       ├── mingwMain/kotlin/        #   Windows native entry
│       └── nativeMain/kotlin/       #   Shared native entry
└── gradle/                          # Gradle wrapper

# General
./gradlew build              # Build all modules, run tests
./gradlew assemble           # Build without testing
./gradlew spotlessApply      # Format code (Kotlin, Gradle KTS)
./gradlew spotlessCheck      # Check formatting without changes

# JVM
./gradlew :essential-mcp:jvmJar    # Build JVM JAR
./gradlew :essential-mcp:fatJar    # Build fat/uber JAR
./gradlew :essential-mcp:jvmRun    # Run directly

# JVM (standalone)
java -jar essential-mcp/build/libs/essential-mcp-jvm-1.1.1.jar

# Native executables
./gradlew :essential-mcp:linkReleaseExecutableLinuxX64
./gradlew :essential-mcp:linkReleaseExecutableLinuxArm64
./gradlew :essential-mcp:linkReleaseExecutableMingwX64

# Native (after linking)
./essential-mcp/build/bin/linuxX64/executable/essential-mcp-1.1.1

./gradlew test               # Run all tests (common + platform-specific)
./gradlew :essential-mcp:jvmTest  # Run JVM tests only
./gradlew :mcp-tool-ksp:test        # Run KSP processor tests
./gradlew test --tests "*PlatformTest"  # Run specific test class

./gradlew :essential-mcp:kspCommonMainKotlinMetadata  # Run KSP manually

The KSP task is automatically wired to run before compilation tasks. Generated sources are output to build/generated/ksp/metadata/commonMain/kotlin/.

Tools are defined using @McpTool. KSP auto-generates registration code. Functions return String — the generated wrapper converts to CallToolResult:

@McpTool(
    name = "my_tool",
    description = "Does something useful"
)
suspend fun myTool(
    @ToolParam(description = "Input path") input: String,
    @ToolParam(description = "Output path") output: String
): String {
    // Implementation
    return "[OK] $output"
}

Resources are defined using @McpResource:

@McpResource(
    uri = "audio://server/info",
    name = "audio_server_info",
    description = "Information about the MCP audio tools server.",
    mimeType = "text/plain",
)
fun audioServerInfo(): String = "MCP audio tools server"

Prompts are defined using @McpPrompt. Parameters must be annotated with @PromptParam:

@McpPrompt(
    name = "summarize_audio",
    description = "Create a prompt for summarizing an audio file.",
)
fun summarizeAudioPrompt(
    @PromptParam(description = "Path to the audio file.", name = "audio_path")
    audioPath: String,
): String = "Summarize the audio file at: $audioPath"

Unannotated parameters with SDK context types are automatically injected in generated code:

@McpTool(name = "my_tool", description = "Does something useful")
suspend fun myTool(
    @ToolParam(description = "Input path") input: String,
    conn: ClientConnection,       // injected: the client connection
    request: CallToolRequest,     // injected: the original request
    server: Server,               // injected: the MCP server instance
): String {
    // Implementation
}

Supported context types per declaration:

• ffmpeg must be installed and available in PATH for WAV-to-MP3 transcoding
• subtitle_to_lrc binary must be installed in PATH (or configured via SUBTITLE_TO_LRC env var) for subtitle conversion
• Vision API requires VISION_API_KEY env var (OpenAI-compatible). Optional: VISION_API_URL (default: https://api.openai.com/v1), VISION_MODEL (default: gpt-4o)
• Shell path for execute_command defaults to bash; override with SHELL_PATH env var (e.g. SHELL_PATH=C:\Program Files\Git\bin\bash.exe on Windows)

GNU Affero General Public License v3 (AGPLv3)