mcp : add initial MCP server example (wip)

examples/CMakeLists.txt

@@ -103,6 +103,7 @@ elseif(CMAKE_JS_VERSION)
 else()
     add_subdirectory(cli)
     add_subdirectory(bench)
+    add_subdirectory(mcp)
     add_subdirectory(server)
     add_subdirectory(quantize)
     add_subdirectory(vad-speech-segments)

examples/mcp/CMakeLists.txt

@@ -0,0 +1,15 @@
+set(TARGET whisper-mcp-server)
+add_executable(${TARGET} mcp-server.cpp stdio-transport.cpp mcp-handler.cpp)
+target_include_directories(${TARGET} PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})
+
+set(DEMO_TARGET mcp-demo)
+add_executable(${DEMO_TARGET} mcp-demo.cpp stdio-client.cpp)
+
+include(DefaultTargetOptions)
+
+target_link_libraries(${TARGET} PRIVATE common json_cpp whisper ${CMAKE_THREAD_LIBS_INIT})
+
+# mcp_client only needs json_cpp and threading not whisper.
+target_link_libraries(${DEMO_TARGET} PRIVATE json_cpp ${CMAKE_THREAD_LIBS_INIT})
+
+install(TARGETS ${TARGET} ${DEMO_TARGET} RUNTIME)

examples/mcp/README.md

@@ -0,0 +1,59 @@
+# whisper.cpp/examples/mcp
+This directory contains an example of using the Model Context Protocol (MCP) with `whisper.cpp`. The transport
+used in this example is the simple input/output (stdin/stdout) transport. When using the input/output transport,
+the client is responsible for starting the server as a child process and the communication is done by reading
+and writing data to stardard in/out.
+
+## Usage
+The stdio client demo can be run using the following command:
+```
+./build/bin/mcp-demo
+```
+This will initalize the server using the [initialization] lifecycle phase.
+Following that the client will send a request for the list of tools ([tools/list]) that the server supports.
+It will then send a request to transcribe an audio file.
+
+
+### Claude.ai Desktop integration
+The Whisper.cpp MCP server can be integrated with the Claude.ai Desktop application.
+
+This requires adding a MCP server configuration to the Claude.ai Desktop:
+```console
+$ cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "whisper": {
+      "command": "/Users/danbev/work/ai/whisper.cpp/build/bin/whisper-mcp-server",
+      "args": [
+        "--model",
+        "/Users/danbev/work/ai/whisper.cpp/models/ggml-base.en.bin"
+      ]
+    }
+  }
+}
+```
+Update the above paths to match your local system. And then restart the Claude.ai Desktop application.
+
+After that, clicking on "Connect apps" should show the following:
+
+![Claude.ai MCP integration screen](images/integration.png)
+
+And clicking on `[...]` should show the tools available:
+
+![Claude.ai MCP tools screen](images/tools.png)
+
+We should then be able to transribe an audio file by using a prompt like this:
+```console
+Can you transcribe the audio file at /Users/danbev/work/ai/whisper.cpp/samples/jfk.wav?
+```
+And this will then prompt for accepting to run the transcription tool:
+
+![Claude.ai MCP accept screen](images/transcribe-accept.png)
+
+And this should result in a successful transcription:
+
+![Claude.ai MCP transcription result](images/transcribe-screenshot.png)
+
+
+[initialization]: https://modelcontextprotocol.io/specification/2025-03-26/basic/lifecycle#initialization
+[tools/list]: https://modelcontextprotocol.io/specification/2025-03-26/server/tools#listing-tools

examples/mcp/mcp-demo.cpp

@@ -0,0 +1,84 @@
+#include "stdio-client.hpp"
+
+#include <string>
+#include <iostream>
+
+void pretty_print_json(const json & j) {
+    std::cout << j.dump(2) << std::endl;
+}
+
+int main(int argc, char ** argv) {
+    std::string server_command = "build/bin/whisper-mcp-server";
+
+    if (argc > 1) {
+        server_command = argv[1];
+    }
+
+    printf("Starting MCP Demo\n");
+    printf("Server command: %s\n", server_command.c_str());
+
+    try {
+        mcp::StdioClient client;
+
+        // Start the server
+        printf("Starting server...\n");
+        if (!client.start_server(server_command)) {
+            fprintf(stderr, "Failed to start server\n");
+            return 1;
+        }
+
+        if (!client.wait_for_server_ready(2000)) {
+            fprintf(stderr, "Server failed to start within timeout\n");
+            return 1;
+        }
+
+        client.read_server_logs();
+
+        // Initialize
+        printf("Initializing...\n");
+        json init_response = client.initialize("mcp-demo-client", "1.0.0");
+        printf("Initialize response:\n");
+        pretty_print_json(init_response);
+
+        if (init_response.contains("error")) {
+            fprintf(stderr, "Initialization failed!\n");
+            return 1;
+        }
+
+        // Send initialized notification
+        printf("Sending initialized notification...\n");
+        client.send_initialized();
+        client.read_server_logs();
+
+        // List tools
+        printf("Listing tools...\n");
+        json tools_response = client.list_tools();
+        printf("Tools list response:\n");
+        pretty_print_json(tools_response);
+
+        // Call transcribe tool
+        printf("Calling transcribe tool...\n");
+        json transcribe_args = {
+            {"file", "samples/jfk.wav"}
+        };
+
+        json transcribe_response = client.call_tool("transcribe", transcribe_args);
+        printf("Transcribe response:\n");
+        pretty_print_json(transcribe_response);
+
+        // Call model info tool
+        printf("Calling model info tool...\n");
+        json model_info_response = client.call_tool("model_info", json::object());
+        printf("Model info response:\n");
+        pretty_print_json(model_info_response);
+
+        // Final logs
+        printf("Final server logs:\n");
+        client.read_server_logs();
+    } catch (const std::exception & e) {
+        fprintf(stderr, "Exception: %s\n", e.what());
+        return 1;
+    }
+
+    return 0;
+}