@purinton/mcp-server

A Node.js server for the Model Context Protocol (MCP) with dynamic tool loading, HTTP API, and authentication. Easily extendable with custom tools for AI and automation workflows. Supports both CommonJS and ESM.

---

Table of Contents

• Features
• Installation
• Usage
  • ESM Example
  • CommonJS Example
  • Custom Tool Example (ESM)
  • Custom Tool Example (CommonJS)
• API
• TypeScript
• License

Features

• Model Context Protocol (MCP) server implementation for Node.js
• Dynamic tool loading from a directory (tools/)
  • Loads .mjs files in ESM mode, .cjs files in CommonJS mode
• HTTP API with authentication (Bearer token or custom async callback)
• Express-based, easy to extend
• Utility helpers for tool responses and BigInt-safe serialization
• TypeScript type definitions included
• Supports both CommonJS and ESM usage

Installation

1npm install @purinton/mcp-server

Usage

ESM Example

1// Example for ESM (module JS) usage
2import { mcpServer } from '@purinton/mcp-server';
3
4(async () => {
5  const { app, httpInstance } = await mcpServer({
6    // port: 1234, // You can change the port as needed
7    // authToken: 'your-secret-token', // You can still use this for static token auth
8    // toolsDir: './tools', // Path to your tools directory
9    // name: 'Example MCP Server', // Set your server name
10    // version: '1.0.0', // Set your server version
11    // // Example: custom async auth callback
12    // authCallback: async (token) => {
13    //  // Replace with your own logic, e.g. check token in DB or against a list
14    //  return token === 'your-secret-token';
15    // },
16    // context: { example: 'context' } // Optional context to pass to tools _extra (db, redis, etc.)
17  });
18  console.log('MCP Server started!');
19})();

CommonJS Example

1// Example for CommonJS usage
2const { mcpServer } = require('@purinton/mcp-server');
3
4(async () => {
5  const { app, httpInstance } = await mcpServer({
6    // port: 1234, // You can change the port as needed
7    // authToken: 'your-secret-token', // You can still use this for static token auth
8    // toolsDir: './tools', // Path to your tools directory
9    // name: 'Example MCP Server', // Set your server name
10    // version: '1.0.0', // Set your server version
11    // // Example: custom async auth callback
12    // authCallback: async (token) => {
13    //  // Replace with your own logic, e.g. check token in DB or against a list
14    //  return token === 'your-secret-token';
15    // },
16    // context: { example: 'context' } // Optional context to pass to tools _extra (db, redis, etc.)
17  });
18  console.log('MCP Server started!');
19})();

Note:

• In ESM mode, tools must be .mjs files and use the ESM export signature.
• In CommonJS mode, tools must be .cjs files and use the CommonJS export signature.

Custom Tool Example (ESM)

To add your own tool for ESM, create a file in the tools/ directory (e.g., tools/echo.mjs):

1import { z, buildResponse } from '@purinton/mcp-server';
2
3export default async function ({ mcpServer, toolName, log }) {
4  mcpServer.tool(
5    toolName,
6    "Echo Tool",
7    { echoText: z.string() },
8    async (_args, _extra) => {
9      log.debug(`${toolName} Request`, { _args });
10      const response = {
11        message: "echo-reply",
12        data: {
13          text: _args.echoText
14        }
15      };
16      log.debug(`${toolName} Response`, { response });
17      return buildResponse(response);
18    }
19  );
20}

Custom Tool Example (CommonJS)

To add your own tool for CommonJS, create a file in the tools/ directory (e.g., tools/echo.cjs):

1const { z, buildResponse } = require('@purinton/mcp-server');
2
3module.exports = async function ({ mcpServer, toolName, log }) {
4  mcpServer.tool(
5    toolName,
6    "Echo Tool",
7    { echoText: z.string() },
8    async (_args, _extra) => {
9      log.debug(`${toolName} Request`, { _args });
10      const response = {
11        message: "echo-reply",
12        data: {
13          text: _args.echoText
14        }
15      };
16      log.debug(`${toolName} Response`, { response });
17      return buildResponse(response);
18    }
19  );
20};

API

`async mcpServer(options): Promise<{ app, httpInstance, mcpServer, transport }>```

Starts the MCP + HTTP server. Options:

• log (optional): Logger instance (default: @purinton/log)
• toolsDir (optional): Path to tools directory (default: ./tools relative to the entry file)
• port (optional): Port for HTTP server (default: 1234 or process.env.MCP_PORT)
• authToken (optional): Bearer token for authentication (default: process.env.MCP_TOKEN)
• authCallback (optional): Custom async callback for authentication. Receives (token) and returns true/false or a Promise.
• name (optional): Name for the MCP server
• version (optional): Version for the MCP server
• context (optional): Context object to attach to the MCP server and pass to tools (e.g. database, redis, etc.)

Returns an object with:

• app: Express application instance
• httpInstance: HTTP server instance
• mcpServer: MCP server instance
• transport: HTTP transport instance

convertBigIntToString(value)

Recursively converts all BigInt values in an object to strings.

buildResponse(data)

Wraps a plain JS object into the standard tool response payload.

z

Re-exports zod for schema validation.

TypeScript

Type definitions are included:

1export interface McpServerOptions {
2  log?: any;
3  toolsDir?: string;
4  port?: number | string;
5  authToken?: string;
6  authCallback?: (token?: string) => boolean | Promise<boolean>;
7  name?: string;
8  version?: string;
9  context?: any;
10}
11
12export interface McpServerResult {
13  app: import('express').Application;
14  httpInstance: import('http').Server;
15  mcpServer: any;
16  transport: any;
17}
18
19export function mcpServer(options?: McpServerOptions): Promise<McpServerResult>;
20export function convertBigIntToString(value: any): any;
21export function buildResponse(data: any): { content: { type: 'text'; text: string }[] };
22export { z };

Support

For help, questions, or to chat with the author and community, visit:

Purinton Dev on Discord

License

MIT © 2025 Russell Purinton

Links

• GitHub
• npm
• Discord