Model Context Protocol (MCP) Client and Server

Client supports Stdio and Streamable HTTP. Server supports Stdio and Streamable HTTP.

Install

npm i mcp-nequeo

Usage

Client HTTP Microsoft Docs Search

import { McpTool } from 'mcp-nequeo/src/McpTypes.js';
import { McpClient } from 'mcp-nequeo/src/McpClient.js';
import { McpServerBase } from 'mcp-nequeo/src/McpServerBase.js';
import { McpHost } from 'mcp-nequeo/src/McpHost.js';

const mcpClient = new McpClient("Microsoft Docs Search", "1.2.3");
await mcpClient.openConnectionHttp("https://learn.microsoft.com/api/mcp");

const tools: McpTool[] = mcpClient.getTools();
const microsoft_docs_search = await mcpClient.callTool("microsoft_docs_search", { query: "what is HttpClient" });
await mcpClient.closeConnection();

console.log("Tools:", tools);
console.log("Microsoft Docs Search Result:", microsoft_docs_search);

Client HTTP Microsoft Docs Search

import { McpClient } from '../McpClient.js';
import {
    McpTool,
    McpPrompt,
    McpResource
} from '../McpTypes.js'

/**
 * Microsoft learn.
 * // https://github.com/microsoftdocs/mcp
 */
export class MicrosoftLearn extends McpClient {

    /**
     * Microsoft learn.
     */
    constructor() {
        super("MicrosoftDocsSearch", "1.8.9");
    }

    /**
     * open microsoft learn connection..
     * @returns {boolean} true if opened; else false.
     */
    async openMicrosoftLearn(): Promise<void> {

        try {
            // open a new connection.
            await this.openConnectionHttp("https://learn.microsoft.com/api/mcp");

            // change the required parameter
            let tools: McpTool[] = this.getTools();
            for (var i = 0; i < tools.length; i++) {
                if (!tools[i].parameters.required) {
                    // change
                    tools[i].parameters.required = ['query', 'question'];
                }
            }

        } catch (e) {
            // some error on close.
            if (this.logEvent) this.logEvent("error", "microsoftlearn", "open Microsoft Learn", e);
        }
    }
}

Client MathJs

import { McpClient } from '../McpClient.js';

/**
 * MathJs Math Expression Evaluator.
 */
export class MathJsMath extends McpClient {

    /**
     * MathJs Math Expression Evaluator.
     */
    constructor() {
        super("MathJsMathExpressionEvaluator", "1.0.1");
    }

    /**
     * call the math expression evaluator tool.
     * @param {string} expression     the math expression.
     * @returns {Promise<any>} the evaluated expression.
     */
    async callMathExpressionEvaluatorTool(expression: string): Promise<any> {
        let res: any = await this.callTool("MathExpressionEvaluator", {
            expression: expression
        });

        // return the result.
        return res;
    }

    /**
     * call the math expression evaluator prompt.
     * @param {string} expression     the math expression.
     * @returns {Promise<any>} the evaluated expression.
     */
    async callMathExpressionEvaluatorPrompt(expression: string): Promise<any> {
        let res: any = await this.callPrompt("MathExpressionEvaluator", {
            expression: expression
        });

        // return the result.
        return res;
    }

    ......
    ......
}

Server MathJs

import * as math from 'mathjs';
import { z } from 'zod';
import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";

import {
    McpServerBase,
} from '../McpServerBase.js';
import {
    McpPromptHelper
} from '../McpTypes.js';

/**
 * MathJs Math Expression Evaluator.
 */
export class MathJsMath extends McpServerBase {

    /**
     * MathJs Math Expression Evaluator.
     */
    constructor() {
        super("MathJsMathExpression", "1.0.1", "MathJs math expression evaluator",
            { resources: {}, tools: {}, prompts: {} });
    }

    /**
     * register tool math expression evaluator.
     * @returns {boolean} true if register; else false.
     */
    registerTool_MathExpressionEvaluator(): boolean {

        let localThis = this;
        return this.registerTool(
            "MathExpressionEvaluator",
            {
                description: "Use MathJS to execute the mathematical expressions",
                inputSchema: {
                    expression: z.string().describe("the MathJs mathematical expression")
                }
            },
            async ({ expression }) => ({
                content: [{
                    type: "text",
                    text: localThis.mathExpressionEvaluator(expression)
                }]
            }),
            {
                properties: {
                    expression: {
                        type: 'string',
                        description: 'the MathJs mathematical expression'
                    }
                },
                required: ['expression'],
            }
        );
    }

    /**
     * register prompt math expression evaluator.
     * @returns {boolean} true if register; else false.
     */
    registerPrompt_MathExpressionEvaluator(): boolean {

        return this.registerPrompt(
            "MathExpressionEvaluator",
            {
                description: "Use MathJS to execute the mathematical expressions",
                argsSchema: {
                    expression: z.string().describe("the MathJs mathematical expression")
                }
            },
            async ({ expression }) => ({
                messages: [{
                    role: "user",
                    content: {
                        type: "text",
                        text: `evaluate the math expression: ${expression}`
                    }
                }]
            })
        );
    }

    .......
    .......

    /**
     * register all tools, prompts, resources.
     * @returns {boolean}    true if registered; else false.
     */
    register(): boolean {
        let registeredAll: boolean = true;

        // ternary conditional statement.
        // register tools.
        registeredAll = this.registerTool_MathExpressionEvaluator() && registeredAll ? true : false;
        registeredAll = this.registerPrompt_MathExpressionEvaluator() && registeredAll ? true : false;
        registeredAll = this.registerPrompt_MathExpressionResult() && registeredAll ? true : false;
        registeredAll = this.registerResource_MathJsDocsUrl() && registeredAll ? true : false;
        registeredAll = this.registerResource_MathJsDocsUrl_Version() && registeredAll ? true : false;

        // if all registered.
        return registeredAll;
    }
}

/**
 * start the MathJs math server.
 * @param {boolean} useStreamableHttp   use streamable HTTP to receiving messages.
 * @param {boolean} stateless  set the http transport stateless value; true if stateless; else has state.
 * @returns {MathJsMath}    MathJsMath server; else null.
 */
export async function mainMathJsMathServer(useStreamableHttp: boolean = false, stateless: boolean = true): Promise<MathJsMath | undefined> {

    // start server.
    let mathjsmath_server: MathJsMath = new MathJsMath();
    
    // set state
    mathjsmath_server.setHttpTransportStateless(stateless);

    // if registered
    if (mathjsmath_server.register()) {
        // start server.
        if (useStreamableHttp) {
            await mathjsmath_server.startServerHttp();
        }
        else {
            await mathjsmath_server.startServerStdio();
        }

        // return the server.
        return mathjsmath_server;
    }
    else {
        return null;
    }
}

Client HTTP MathJs

import { MathJsMath } from './clients/MathJsMath.js';

// connect to the server from the client.
const mathjsmathClient = new MathJsMath();
var open = await mathjsmathClient.openConnectionHttp(
    "https://example.com/mcp",
    {
        headers: {
            'Authorization': 'Bearer <secret>'
        }
    });
	
var resultTool = await mathjsmathClient.callMathExpressionEvaluatorTool("sin(pi/2)");
var resultTool1 = await mathjsmathClient.callMathExpressionEvaluatorTool("cos(pi)");
var resultPrompt = await mathjsmathClient.callMathExpressionEvaluatorPrompt("6^4");
var resultPrompt1 = await mathjsmathClient.callMathExpressionResultPrompt("6565");
var resultResource = await mathjsmathClient.callMathJsDocsUrlResource();
var resultResource1 = await mathjsmathClient.callMathJsDocsUrlVersionResource("98765");
await mathjsmathClient.closeConnection();

// display result.
console.log(resultTool.content[0].text);
console.log(resultTool1.content[0].text);
console.log(resultPrompt.messages);
console.log(resultPrompt1.messages);
console.log(resultResource);
console.log(resultResource1);

// results
1
-1
[
  {
    role: 'user',
    content: { type: 'text', text: 'evaluate the math expression: 6^4' }
  }
]
[
  {
    role: 'user',
    content: { type: 'text', text: 'describe the result: 6565, using latex' }
  }
]
{
  contents: [
    {
      uri: 'mathjs://{version}',
      mimeType: 'text/plain',
      text: 'https://mathjs.org/docs/index.html'
    }
  ]
}
{
  contents: [
    {
      uri: 'mathjs://doc/98765/num',
      mimeType: 'text/plain',
      text: 'The document version 98765'
    }
  ]
}

Server HTTP MathJs

import { Request, Response } from 'express';
import {
    StreamableHTTPServerTransport
} from "@modelcontextprotocol/sdk/server/streamableHttp.js";

import { McpHttpTransportModel } from './McpTypes.js';
import { MathJsMath, mainMathJsMathServer } from './servers/MathJsMath.js';

/**
* get the route
* @param {Request} request
* @param {Response} response
* @returns {Promise<void>} the response.
*/
export async function route(request: Request, response: Response): Promise<void> {

	// /mcp
	if (request.url.startsWith("/mcp") &&
		request.method.toUpperCase() === "POST") {
			
		// create a new server, stateless = true
		const mathJsMathServer: MathJsMath = await mainMathJsMathServer(true, true);
		
		// if created
		if (mathJsMathServer) {
			// if server open
			if (mathJsMathServer.hasStarted()) {
			
				// handle the request, stateless = true, so use "sessionid"
				let transportModel: McpHttpTransportModel = mathJsMathServer.findHttpTransport("sessionid");
				let transport: StreamableHTTPServerTransport = transportModel.transport;
				
				// onclose lambda.
				response.on('close', async () => {
					// close server.
					await mathJsMathServer.stopServer();
				});

				// send the mcp response.
				await transport.handleRequest(request, response, request.body);
			}
		}
	}
}

MCP Host

import { OpenAI } from "openai";
import {
	FunctionTool,
	ResponseOutputItem,
	ResponseFunctionToolCall
} from "openai/src/resources/responses/responses.js";
import {
	McpTool,
	McpFunctionTool
} from './McpTypes.js';
import {
	McpHost,
	McpServerModel,
	McpClientModel
} from './McpHost.js';

import { MathJsMath } from "./servers/MathJsMath.js";
import { MicrosoftLearn } from "./clients/MicrosoftLearn.js";

/**
* create a new mcp host.
* @returns {McpHost} the host.
*/
async function createMcpHost(): Promise<McpHost> {

	// create a new host.
	let mcpHost: McpHost = new McpHost();

	// load MathJs server
	let mathJsMath: MathJsMath = new MathJsMath();
	mathJsMath.register();
	mcpHost.addServerFunctionTools("mathJsMath", mathJsMath);

	// load Microsoft Learn client
	let microsoftLearn: MicrosoftLearn = new MicrosoftLearn();
	await microsoftLearn.openMicrosoftLearn();
	mcpHost.addClientFunctionTools("microsoftlearn", microsoftLearn);

	// return the mcp host.
	return mcpHost;
}

/**
* get the tools.
* @param {McpHost} mcpHost     the mcp host.
* @returns {FunctionTool[]}    the list of tools
*/
function getTools(mcpHost: McpHost): Array<FunctionTool> {
    	// the tools
    	let tools: Array<FunctionTool> = [];

    	// get the host.
    	let functionTools: McpFunctionTool[] = mcpHost.getFunctionTools();
    	for (var i = 0; i < functionTools.length; i++) {
        	// add to tools
        	let tool: McpTool = functionTools[i];
        	tools.push({
            		type: "function",
            		name: tool.name,
            		description: tool.description,
            		parameters: {
                		type: 'object',
                		properties: tool.parameters.properties,
                		required: tool.parameters.required,
                		additionalProperties: false
            		},
            		strict: true
        	})
    	}

    	// return the tools
    	return tools;
}

/**
 * find the tool to execute the request.
 * @param {ResponseOutputItem} response     the output response.
 * @param {McpHost} mcpHost     the mcp host.
 * @returns {Array<string>} the list of results.
 */
async function findTool(response: ResponseOutputItem, mcpHost: McpHost): Promise<Array<string>> {

    	// results
    	let results: Array<string> = [];

    	try {
        	// get the host.
        	let functionTool: ResponseFunctionToolCall = response as ResponseFunctionToolCall;
        	let tool: McpFunctionTool = null;

        	// try find tool
        	tool = mcpHost.findFunctionTool(functionTool.name);
        	if (tool) {
            		try {
                		let payload: any = undefined;

                		// find the server.
                		let serverModel: McpServerModel = mcpHost.findServer(tool.serverId);
                		if (serverModel) {
                    			// call the tool.
                    			payload = await serverModel.server.callTool(functionTool.name, JSON.parse(functionTool.arguments));

                    			// add the result.
                    			results.push(payload.content[0].text);
                		}

                		// find the client.
                		let clientModel: McpClientModel = mcpHost.findClient(tool.clientId);
                		if (clientModel) {
                    			// call the tool.
                    			payload = await clientModel.client.callTool(functionTool.name, JSON.parse(functionTool.arguments));

                    			// add the result.
                    			results.push(payload.content[0].text);
                		}
            		} catch (ex) {
                		results.push(`error: ${ex}`);
            		}
        	}
    	} catch (ex) {
        	results.push(`error: ${ex}`);
    	}

    	// return the results
    	return results;
}