mcpHTTPClient.m

classdef mcpHTTPClient < handle
% An MCP client (streamable HTTP only)

% Copyright 2025 The MathWorks, Inc.
    properties (SetAccess=private)
        Endpoint
        ServerTools (1,:)
    end

    properties (Access=private)
        counter = 0;
    end

    properties (Hidden)
        % test seam
        Send = @send
    end

    methods
        function obj = mcpHTTPClient(endpoint, varargin)
            obj.Endpoint = endpoint;
            % undocumented test seam
            if nargin > 2 && isequal(varargin{1}, "Send")
                obj.Send = varargin{2};
            end
            obj.ServerTools = obj.retrieveTools;
        end

        function result = callTool(obj, tool, varargin)
            if isstruct(tool)
                toolName = string(tool.name);
                if isfield(tool,"arguments") && ~isstruct(tool.arguments)
                    tool.arguments = mcp.util.verbatimJSON(tool.arguments);
                end
            else
                toolName = string(tool);
                tool = struct(...
                    "name",tool,"arguments",struct(varargin{:}));
            end
            for k=1:numel(obj)
                toolNames = string(cellfun(@(s) s.name,obj(k).ServerTools,'UniformOutput',false));
                if ~any(toolName==toolNames)
                    continue;
                end
                sessionIDField = obj(k).initialize();
                request = obj(k).makeRequest("tools/call", ...
                    tool, sessionIDField);
                response = obj(k).Send(request,obj(k).Endpoint);
                if response.StatusCode == matlab.net.http.StatusCode.Unauthorized
                    throwError("mcp:needsAuthorization");
                elseif response.StatusCode ~= matlab.net.http.StatusCode.OK
                    throwError("mcp:serverError",getServerErrorText(response));
                end
                data = response.Body.Data;
                if ~isstruct(data)
                    data = erase(data,"data: ping"+optionalPattern(char(13))+newline);
                    data = extractBetween(data,"data: ",optionalPattern(char(13))+newline);
                    data = jsondecode(data);
                end
                if isfield(data,"error")
                    error(data.error);
                end
                if isempty([data.result.content])
                    result = "";
                else
                    result = string(join([data.result.content.text],""));
                end
                if isfield(data.result,"isError") && isequal(data.result.isError,true)
                    error(result);
                end
                return
            end
            % if we fall off the end of this for loop, nothing in the input
            % vector knows about that tool.
            throwError("mcp:unknownTool")
        end
    end

    methods (Access=private)
        function sessionIDField = initialize(obj)
            request = obj.makeRequest("initialize",struct(...
                "protocolVersion", "2025-06-18",...
                "capabilities",struct(),...
                "clientInfo",struct(...
                    "name","MATLAB MCP HTTP Client",...
                    "version","0.0.1"...
                )...
            ),[]);

            try
                response = obj.Send(request,obj.Endpoint);
            catch exc
                if isa(exc, "matlab.net.http.HTTPException")
                    if exc.identifier == "MATLAB:webservices:UnknownHost"
                        throwError("mcp:noSuchHost",obj.Endpoint);
                    end
                end
                throw(exc);
            end

            values = [response.Header.Value];
            sessionID = values([response.Header.Name] == "mcp-session-id");
            sessionIDField = matlab.net.http.field.GenericParameterizedField("mcp-session-id",sessionID);

            initDone = obj.makeRequest("notifications/initialized",[],sessionIDField);
            obj.Send(initDone,obj.Endpoint);
        end

        function body = makeBody(obj,method,params)
            payload = struct(...
                "jsonrpc","2.0",...
                "method",method);

            if ~strcmp(method,"notifications/initialized")
                obj.counter = obj.counter + 1;
                payload.id = obj.counter;
            end
            if ~isequal(params,[])
                payload.params = params;
            end
            body = matlab.net.http.MessageBody(payload);
        end

        function request = makeRequest(obj,method,params,sessionIDField)
            contentTypeField = matlab.net.http.field.ContentTypeField('application/json');
            type1 = matlab.net.http.MediaType("application/json");
            type2 = matlab.net.http.MediaType("text/event-stream");
            acceptField = matlab.net.http.field.AcceptField([type1 type2]);
            expectNothing = matlab.net.http.HeaderField('Expect', '');
            header = [acceptField contentTypeField sessionIDField expectNothing];

            body = obj.makeBody(method,params);

            method = matlab.net.http.RequestMethod.POST;
            request = matlab.net.http.RequestMessage(method,header,body);
        end

        function tools = retrieveTools(obj)
            arguments
                obj (1,1) mcpHTTPClient
            end

            sessionIDField = obj.initialize();
            request = obj.makeRequest("tools/list", struct(), sessionIDField);
            response = obj.Send(request,obj.Endpoint);
            if response.StatusCode == matlab.net.http.StatusCode.Unauthorized
                throwError("mcp:needsAuthorization");
            elseif response.StatusCode ~= matlab.net.http.StatusCode.OK
                throwError("mcp:serverError",getServerErrorText(response));
            end
            tools = response.Body.Data;
            if ~isstruct(tools)
                tools = jsondecode("{"+extractBetween(tools,"data: {","}"+optionalPattern(char(13))+newline)+"}");
            end
            if isfield(tools,"result") && isfield(tools.result,"tools")
                tools = tools.result.tools;
            end
            if ~iscell(tools)
                tools = mat2cell(tools,ones(numel(tools),1));
            end
        end

    end
end

function errortxt = getServerErrorText(response)
    errortxt = response.Body.Data;
    if isstruct(errortxt)
        if isfield(errortxt,"error_description")
            errortxt = errortxt.error_description;
        else
            errortxt = jsonencode(errortxt);
        end
    end
    errortxt = string(errortxt);
    if response.Body.ContentType.Subtype == "html"
        errortxt = extractHTMLText(errortxt);
    end
    if strlength(errortxt) < 1
        errortxt = string(response.StatusLine);
    end
end

function throwError(id,varargin)
persistent catalog
if isempty(catalog)
    catalog = dictionary("string", "string");
    catalog("mcp:needsAuthorization") = "Servers that require authorization are not supported.";
    catalog("mcp:unknownTool") = "Unrecognized tool";
    catalog("mcp:serverError") = "Server returned error: ""%s""";
    catalog("mcp:noSuchHost") = "Unknown host ""%s""";
end
throwAsCaller(MException(id,catalog(id),varargin{:}));
end