npm package: @quicore/express-mcp
Description: A lightweight package for integrating the Model Context Protocol (MCP) with an Express.js server.
Author: quicore
Latest version: 0.4.0


### `@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

```bash
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`**

```javascript
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`**

```javascript
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)**

```javascript
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.

```javascript
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()`.