@quicore/express-mcp

@quicore/express-mcp is a streamlined package designed to effortlessly integrate the Model Context Protocol (MCP) with an Express.js server. By building on top of @quicore/expressjs and @modelcontextprotocol/sdk, it abstracts away the complex setup of the MCP transport and server, allowing you to concentrate on your application's business logic and tool definitions.

Features

• Seamless Express Integration: Connects the MCP server directly into an Express.js application with minimal configuration.
• Simplified Setup: Automatically handles the creation and management of the StreamableHTTPServerTransport and McpServer.
• Built-in Health Check: Includes a default health check endpoint at the root (/) to ensure your server is live and responsive.
• Efficient Tool Management: Provides a fluent API with addTool and addTools methods for easy registration of new tools.
• Tool Scaffolding: The included MCPTools class simplifies tool creation by letting you define metadata, input schemas (using Zod), and handlers in a structured way.
• Flexible Session Handling: Supports optional session IDs for creating and managing different transport connections.

Installation

npm install @quicore/express-mcp

Usage

1. Setting Up the Server

First, create an instance of ExpressMCP and configure it with your desired settings for both the MCP server and the underlying web server.

index.js

import { ExpressMCP } from "@quicore/express-mcp";

// Correct configuration for QuicoreExpressServer
const webConfig = {
  webserver: {
    http: { port: 3000 },
    express: {
      cookie: true,
      helmet: true,
      urlencodedExtended: true,
    },
  },
};

const mcpConfig = {
  // Required name for your MCP server
  name: "My Awesome MCP Server",
  // Optional version string
  version: "1.0.0",
};

// Create and initialize the ExpressMCP instance
const mcpApp = new ExpressMCP(mcpConfig, webConfig);

// Start the server
mcpApp.start().then(() => {
  console.log(`Server is running at http://localhost:${webConfig.webserver.http.port}`);
}).catch(err => {
  console.error("Failed to start server:", err);
  process.exit(1);
});

2. Defining and Registering Tools

Use the MCPTools class to create your application's tools. It uses Zod to define and validate input schemas, ensuring robust and predictable tool execution.

lib/myTool.js

import { MCPTools } from "@quicore/express-mcp";

export class GetCurrentWeatherTool extends MCPTools {
  constructor() {
    super("getCurrentWeather", "Get the current weather for a location.");

    this.setDescription("Retrieves the current weather conditions for a specified city.");

    // Define input parameters using Zod types as strings
    this.setParameter("location", "string", true); // required string
    this.setParameter("unit", "string", false);    // optional string

    // Set the handler function that contains your tool's logic
    this.setHandler(async (input) => {
      console.log(`Getting weather for ${input.location} with unit ${input.unit || 'celsius'}`);
      
      // Your tool logic here (e.g., calling an external API)
      const weatherData = {
        location: input.location,
        temperature: 25,
        unit: input.unit || 'celsius',
        conditions: "Sunny"
      };

      return weatherData;
    });
  }
}

Now, register this tool with your ExpressMCP instance:

index.js (continued)

import { ExpressMCP } from "@quicore/express-mcp";
import { GetCurrentWeatherTool } from "./lib/myTool.js";

// ... (existing setup code)

const mcpApp = new ExpressMCP(mcpConfig, webConfig);

// Create an instance of the tool
const weatherTool = new GetCurrentWeatherTool();

// Add the tool to the MCP server
mcpApp.addTool(weatherTool);

// You can also add multiple tools at once
// mcpApp.addTools([weatherTool, anotherTool]);

// Start the server
mcpApp.start().then(() => {
    console.log(`Server is running at http://localhost:${webConfig.webserver.http.port}`);
}).catch(err => {
    console.error("Failed to start server:", err);
    process.exit(1);
});

3. Accessing Quicore Express Config

The ExpressMCP class exposes the underlying QuicoreExpressServer instance, giving you full control to customize the server with additional routes or middleware.

import { ExpressMCP } from "@quicore/express-mcp";

const mcpApp = new ExpressMCP({ name: "My Server" }, {
  webserver: {
    http: { port: 3000 }
  }
});

// Access the underlying Express application instance
const expressApp = mcpApp.server.app;

// Use the Express app to add more routes
expressApp.get('/custom-route', (req, res) => {
  res.send('This is a custom route added directly via Express.');
});

mcpApp.start();

API Reference

new ExpressMCP(mcpConfig, webConfig)

• mcpConfig (Object): Configuration for the MCP server.
  • name (string, required): The unique name of the MCP server.
  • version (string, optional, default: "1.0.0"): The server's version.
• webConfig (Object): The configuration for QuicoreExpressServer. See the official npm documentation for @quicore/expressjs for all available options.

ExpressMCP Methods

• initialize(): Initializes the Express server with common middleware and routes. This is called automatically by start().
• start(): Starts the Express server and begins listening for requests.
• stop(): Stops the server and cleans up the MCP transport connection.
• addTool(tool: MCPTools): Registers a single MCPTools instance with the server.
• addTools(tools: MCPTools | MCPTools[]): Registers one or more MCPTools instances.

new MCPTools(id, title)

• id (string): A unique identifier for the tool.
• title (string): A human-readable title for the tool.

MCPTools Methods

• setDescription(description): Sets a descriptive string for the tool.
• setParameter(paramId, typeString, required = true): Defines an input parameter. typeString must be one of the supported Zod types ('string', 'number', 'boolean', etc.).
• setHandler(handlerFunction): Sets the asynchronous function that will be invoked when the tool is executed.
• register(server): Registers the tool with an McpServer instance. This method is called internally when using ExpressMCP.addTool().