Runs as an MCP server over stdio, implementing audio processing, subtitle‑to‑LRC and WAV→MP3 conversion, shell command execution, image understanding via Vision API, plus resource/prompt declarations.
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:
| Tool | Description |
|---|---|
transcode_wav_to_mp3 | Convert WAV audio files to MP3 using ffmpeg (deprecated, will be removed in next major version) |
subtitle_to_lrc | Convert subtitle files (SRT/VTT) to LRC format (deprecated, will be removed in next major version) |
execute_command | Execute arbitrary shell commands |
understand_image | Analyze images using a vision model (requires VISION_API_KEY env var) |
| Resource | Description |
|---|---|
audio://server/info | Static server information |
audio://files/{path}/summary | Template-based audio file summary |
| Prompt | Description |
|---|---|
summarize_audio | Create a prompt for summarizing an audio file |
# 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
./gradlew :essential-mcp:linkReleaseExecutableLinuxX64
./gradlew :essential-mcp:linkReleaseExecutableLinuxArm64
./gradlew :essential-mcp:linkReleaseExecutableMingwX64
./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
}
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,
server: ,
): String {
}
Supported context types per declaration:
GNU Affero General Public License v3 (AGPLv3)
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
| Platform | Target | Output |
|---|
| JVM | jvm | JAR / Fat JAR |
| Linux x64 | linuxX64 | Native executable |
| Linux ARM64 | linuxArm64 | Native executable |
| Windows | mingwX64 | Native executable |
| Declaration | Injectable types |
|---|
@McpTool | CallToolRequest, ClientConnection, Server |
@McpResource | ReadResourceRequest, ClientConnection, Server |
@McpPrompt | GetPromptRequest, ClientConnection, Server |
| Annotation | Target | Purpose |
|---|
@McpTool | Function | Define an MCP tool |
@ToolParam | Parameter | Describe a tool parameter |
@McpResource | Function | Define an MCP resource |
@McpPrompt | Function | Define an MCP prompt |
@PromptParam | Parameter | Describe a prompt parameter |
PATH for WAV-to-MP3 transcodingPATH (or configured via SUBTITLE_TO_LRC env var) for subtitle conversionVISION_API_KEY env var (OpenAI-compatible). Optional: VISION_API_URL (default: https://api.openai.com/v1), VISION_MODEL (default: gpt-4o)execute_command defaults to bash; override with SHELL_PATH env var (e.g. SHELL_PATH=C:\Program Files\Git\bin\bash.exe on Windows)| Library | Version | Purpose |
|---|
| Kotlin | 2.3.21 | Multiplatform support |
| Kotlin Coroutines | 1.10.2 | Async I/O for process handling |
| Kotlinx Serialization | 1.9.0 | JSON handling for MCP protocol |
| Kotlinx IO | 0.9.0 | IO abstraction |
| MCP SDK | 0.12.0 | Model Context Protocol implementation |
| KSP | 2.3.7 | Annotation processing |
| KotlinPoet | 2.2.0 | Code generation |
| Ktor | 3.4.1 | HTTP client for vision API |
Surfaced from shared tags and platforms — no rankings paid for.