Implement initial version of the MCP server APIs

.gitignore

@@ -42,3 +42,6 @@ target
 # Ballerina
 velocity.log*
 *Ballerina.lock
+
+# AI Tools
+CLAUDE.md

ballerina/CompilerPlugin.toml

@@ -0,0 +1,9 @@
+[plugin]
+id = "mcp-compiler-plugin"
+class = "io.ballerina.stdlib.mcp.plugin.McpCompilerPlugin"
+
+[[dependency]]
+path = "../compiler-plugin/build/libs/mcp-compiler-plugin-0.4.3-SNAPSHOT.jar"
+
+[[dependency]]
+path = "../compiler-plugin/build/libs/ballerina-to-openapi-2.3.0.jar"

ballerina/Dependencies.toml

@@ -5,7 +5,7 @@
 
 [ballerina]
 dependencies-toml-version = "2"
-distribution-version = "2201.12.7"
+distribution-version = "2201.12.0"
 
 [[package]]
 org = "ballerina"
@@ -108,9 +108,6 @@ dependencies = [
 	{org = "ballerina", name = "jballerina.java"},
 	{org = "ballerina", name = "lang.value"}
 ]
-modules = [
-	{org = "ballerina", packageName = "io", moduleName = "io"}
-]
 
 [[package]]
 org = "ballerina"
@@ -219,19 +216,15 @@ dependencies = [
 	{org = "ballerina", name = "lang.value"},
 	{org = "ballerina", name = "observe"}
 ]
-modules = [
-	{org = "ballerina", packageName = "log", moduleName = "log"}
-]
 
 [[package]]
 org = "ballerina"
 name = "mcp"
 version = "0.4.3"
 dependencies = [
 	{org = "ballerina", name = "http"},
-	{org = "ballerina", name = "io"},
 	{org = "ballerina", name = "jballerina.java"},
-	{org = "ballerina", name = "log"}
+	{org = "ballerina", name = "uuid"}
 ]
 modules = [
 	{org = "ballerina", packageName = "mcp", moduleName = "mcp"}
@@ -314,4 +307,7 @@ dependencies = [
 	{org = "ballerina", name = "lang.int"},
 	{org = "ballerina", name = "time"}
 ]
+modules = [
+	{org = "ballerina", packageName = "uuid", moduleName = "uuid"}
+]
 

ballerina/build.gradle

@@ -27,7 +27,9 @@ def packageName = "mcp"
 def packageOrg = "ballerina"
 def tomlVersion = stripBallerinaExtensionVersion("${project.version}")
 def ballerinaTomlFilePlaceHolder = new File("${project.rootDir}/build-config/resources/Ballerina.toml")
+def compilerPluginTomlFilePlaceHolder = new File("${project.rootDir}/build-config/resources/CompilerPlugin.toml")
 def ballerinaTomlFile = new File("$project.projectDir/Ballerina.toml")
+def compilerPluginTomlFile = new File("$project.projectDir/CompilerPlugin.toml")
 
 def stripBallerinaExtensionVersion(String extVersion) {
     if (extVersion.matches(project.ext.timestampedVersionRegex)) {
@@ -55,6 +57,11 @@ task updateTomlFiles {
         def newConfig = ballerinaTomlFilePlaceHolder.text.replace("@project.version@", project.version)
         newConfig = newConfig.replace("@toml.version@", tomlVersion)
         ballerinaTomlFile.text = newConfig
+
+        def ballerinaToOpenApiVersion = project.ballerinaToOpenApiVersion
+        def newCompilerPluginToml = compilerPluginTomlFilePlaceHolder.text.replace("@project.version@", project.version)
+        newCompilerPluginToml = newCompilerPluginToml.replace("@ballerinaToOpenApiVersion.version@", ballerinaToOpenApiVersion)
+        compilerPluginTomlFile.text = newCompilerPluginToml
     }
 }
 
@@ -94,7 +101,9 @@ updateTomlFiles.dependsOn copyStdlibs
 
 build.dependsOn "generatePomFileForMavenPublication"
 build.dependsOn ":${packageName}-native:build"
+build.dependsOn ":${packageName}-compiler-plugin:build"
 test.dependsOn ":${packageName}-native:build"
+test.dependsOn ":${packageName}-compiler-plugin:build"
 
 publishToMavenLocal.dependsOn build
 publish.dependsOn build

ballerina/client.bal

@@ -23,7 +23,7 @@ public type ClientConfiguration record {|
     ClientCapabilityConfiguration capabilityConfig?;
 |};
 
-# Configuration options for initializing an MCP client.
+# Configuration for MCP client capabilities.
 public type ClientCapabilityConfiguration record {|
     # Capabilities to be advertised by this client.
     ClientCapabilities capabilities?;
@@ -33,112 +33,84 @@ public type ClientCapabilityConfiguration record {|
 
 # Represents an MCP client built on top of the Streamable HTTP transport.
 public distinct isolated client class Client {
-    # MCP server URL.
-    private final string serverUrl;
-    # Client implementation details (e.g., name and version).
-    private final Implementation clientInfo;
-    # Capabilities supported by the client.
-    private final ClientCapabilities clientCapabilities;
-
     # Transport for communication with the MCP server.
-    private StreamableHttpClientTransport? transport = ();
+    private StreamableHttpClientTransport transport;
     # Server capabilities.
     private ServerCapabilities? serverCapabilities = ();
     # Server implementation information.
     private Implementation? serverInfo = ();
     # Request ID generator for tracking requests.
     private int requestId = 0;
 
-    # Initializes a new MCP client with the provided server URL and client details.
+    # Initializes a new MCP client and establishes connection to the server.
+    # Performs protocol handshake and capability exchange. Client is ready for use after construction.
     #
-    # + serverUrl - MCP server URL.
-    # + clientInfo - Client details, such as name and version.
-    # + config - Optional configuration containing client capabilities.
-    public isolated function init(string serverUrl, *ClientConfiguration config) {
-        self.serverUrl = serverUrl;
-        self.clientInfo = config.info.cloneReadOnly();
-        self.clientCapabilities = (config.capabilityConfig?.capabilities).cloneReadOnly() ?: {};
-    }
-
-    # Establishes a connection to the MCP server and performs protocol initialization.
-    #
-    # + return - A ClientError if initialization fails, or nil on success.
-    isolated remote function initialize() returns ClientError? {
-        lock {
-            // Create and initialize transport.
-            StreamableHttpClientTransport newTransport = check new StreamableHttpClientTransport(self.serverUrl);
-            self.transport = newTransport;
-
-            string? sessionId = newTransport.getSessionId();
+    # + serverUrl - MCP server URL
+    # + config - Client configuration including info and capabilities
+    # + return - ClientError if initialization fails, nil on success
+    public isolated function init(string serverUrl, *ClientConfiguration config) returns ClientError? {
+        // Create and initialize transport.
+        StreamableHttpClientTransport newTransport = check new (serverUrl);
+        self.transport = newTransport;
+
+        string? sessionId = newTransport.getSessionId();
+
+        // If a session ID exists, assume reconnection and skip initialization.
+        if sessionId is string {
+            return;
+        }
 
-            // If a session ID exists, assume reconnection and skip initialization.
-            if sessionId is string {
-                return;
+        // Prepare and send the initialization request.
+        InitializeRequest initRequest = {
+            params: {
+                protocolVersion: LATEST_PROTOCOL_VERSION,
+                capabilities: config.capabilityConfig?.capabilities ?: {},
+                clientInfo: config.info
             }
+        };
 
-            // Prepare and send the initialization request.
-            InitializeRequest initRequest = {
-                method: "initialize",
-                params: {
-                    protocolVersion: LATEST_PROTOCOL_VERSION,
-                    capabilities: self.clientCapabilities,
-                    clientInfo: self.clientInfo
-                }
-            };
+        ServerResult response = check self.sendRequestMessage(initRequest);
 
-            ServerResult response = check self.sendRequestMessage(initRequest);
-
-            if response is InitializeResult {
-                final readonly & string protocolVersion = response.protocolVersion;
-                // Validate protocol compatibility.
-                if (!SUPPORTED_PROTOCOL_VERSIONS.some(v => v == protocolVersion)) {
-                    return error ProtocolVersionError(
-                        string `Server protocol version '${
-                            protocolVersion}' is not supported. Supported versions: ${
-                            SUPPORTED_PROTOCOL_VERSIONS.toString()}.`
-                    );
-                }
-
-                // Store server capabilities and info.
-                self.serverCapabilities = response.capabilities;
-                self.serverInfo = response.serverInfo;
-
-                // Send notification to complete initialization.
-                InitializedNotification initNotification = {
-                    method: "notifications/initialized"
-                };
-                check self.sendNotificationMessage(initNotification);
-            } else {
-                return error ClientInitializationError(
-                    string `Initialization failed: unexpected response type '${
-                        (typeof response).toString()}' received from server.`
-                );
-            }
+        if !(response is InitializeResult) {
+            return error ClientInitializationError(
+                string `Initialization failed: unexpected response type '${
+                    (typeof response).toString()}' received from server.`
+            );
+        }
+
+        final string protocolVersion = response.protocolVersion;
+        // Validate protocol compatibility.
+        if (!SUPPORTED_PROTOCOL_VERSIONS.some(v => v == protocolVersion)) {
+            return error ProtocolVersionError(
+                string `Server protocol version '${
+                    protocolVersion}' is not supported. Supported versions: ${
+                    SUPPORTED_PROTOCOL_VERSIONS.toString()}.`
+            );
         }
+
+        // Store server capabilities and info.
+        self.serverCapabilities = response.capabilities.cloneReadOnly();
+        self.serverInfo = response.serverInfo.cloneReadOnly();
+
+        // Send notification to complete initialization.
+        InitializedNotification initNotification = {};
+        check self.sendNotificationMessage(initNotification);
     }
 
     # Opens a server-sent events (SSE) stream for asynchronous server-to-client communication.
     #
     # + return - Stream of JsonRpcMessages or a ClientError.
     isolated remote function subscribeToServerMessages() returns stream<JsonRpcMessage, StreamError?>|ClientError {
         lock {
-            StreamableHttpClientTransport? currentTransport = self.transport;
-            if currentTransport is () {
-                return error UninitializedTransportError(
-                    "Subscription failed: client transport is not initialized."
-                );
-            }
-            return currentTransport.establishEventStream();
+            return self.transport.establishEventStream();
         }
     }
 
     # Retrieves the list of available tools from the server.
     #
     # + return - List of available tools or a ClientError.
     isolated remote function listTools() returns ListToolsResult|ClientError {
-        ListToolsRequest listToolsRequest = {
-            method: "tools/list"
-        };
+        ListToolsRequest listToolsRequest = {};
 
         ServerResult result = check self.sendRequestMessage(listToolsRequest);
         if result is ListToolsResult {
@@ -156,7 +128,6 @@ public distinct isolated client class Client {
     # + return - Result of the tool execution or a ClientError.
     isolated remote function callTool(CallToolParams params) returns CallToolResult|ClientError {
         CallToolRequest toolCallRequest = {
-            method: "tools/call",
             params: params
         };
 
@@ -175,20 +146,10 @@ public distinct isolated client class Client {
     # + return - A ClientError if closure fails, or nil on success.
     isolated remote function close() returns ClientError? {
         lock {
-            StreamableHttpClientTransport? currentTransport = self.transport;
-            if currentTransport is () {
-                return error UninitializedTransportError(
-                    "Closure failed: client transport is not initialized."
-                );
-            }
-
             do {
-                check currentTransport.terminateSession();
-                lock {
-                    self.transport = ();
-                    self.serverCapabilities = ();
-                    self.serverInfo = ();
-                }
+                check self.transport.terminateSession();
+                self.serverCapabilities = ();
+                self.serverInfo = ();
                 return;
             } on fail error e {
                 return error ClientError(string `Failed to disconnect from server: ${e.message()}`, e);
@@ -202,26 +163,17 @@ public distinct isolated client class Client {
     # + return - ServerResult, a stream of results, or a ClientError.
     private isolated function sendRequestMessage(Request request) returns ServerResult|ClientError {
         lock {
-            StreamableHttpClientTransport? currentTransport = self.transport;
-            if currentTransport is () {
-                return error UninitializedTransportError(
-                    "Cannot send request: client transport is not initialized."
-                );
-            }
+            self.requestId += 1;
 
-            lock {
-                self.requestId += 1;
-
-                JsonRpcRequest jsonRpcRequest = {
-                    ...request.cloneReadOnly(),
-                    jsonrpc: JSONRPC_VERSION,
-                    id: self.requestId
-                };
+            JsonRpcRequest jsonRpcRequest = {
+                ...request.cloneReadOnly(),
+                jsonrpc: JSONRPC_VERSION,
+                id: self.requestId
+            };
 
-                JsonRpcMessage|stream<JsonRpcMessage, StreamError?>|StreamableHttpTransportError? response =
-                    currentTransport.sendMessage(jsonRpcRequest);
-                return processServerResponse(response).cloneReadOnly();
-            }
+            JsonRpcMessage|stream<JsonRpcMessage, StreamError?>|StreamableHttpTransportError? response =
+                self.transport.sendMessage(jsonRpcRequest);
+            return processServerResponse(response).cloneReadOnly();
         }
     }
 
@@ -231,19 +183,12 @@ public distinct isolated client class Client {
     # + return - A ClientError if sending fails, or nil on success.
     private isolated function sendNotificationMessage(Notification notification) returns ClientError? {
         lock {
-            StreamableHttpClientTransport? currentTransport = self.transport;
-            if currentTransport is () {
-                return error UninitializedTransportError(
-                "Cannot send notification: client transport is not initialized."
-                );
-            }
-
             JsonRpcNotification jsonRpcNotification = {
                 ...notification.cloneReadOnly(),
                 jsonrpc: JSONRPC_VERSION
             };
 
-            _ = check currentTransport.sendMessage(jsonRpcNotification);
+            _ = check self.transport.sendMessage(jsonRpcNotification);
         }
     }
 }