@tigerdata/mcp-boilerplate 1.1.0 → 1.2.0

package/dist/cliEntrypoint.js

@@ -16,7 +16,7 @@ export async function cliEntrypoint(stdioEntrypoint, httpEntrypoint, instrumenta
             case 'http': {
                 let cleanup;
                 if (args.includes('--instrument') ||
-                    process.env.INSTRUMENT === 'true') {
+                    process.env.INSTRUMENT?.toLowerCase().trim() === 'true') {
                     const { instrument } = await import(instrumentation);
                     ({ cleanup } = instrument());
                 }

package/dist/httpServer.d.ts

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import type { Server } from 'node:http';
-import express from 'express';
+import express, { type Router } from 'express';
 import { type AdditionalSetupArgs } from './mcpServer.js';
 import type { BaseApiFactory, BasePromptFactory, ResourceFactory } from './types.js';
-export declare const httpServerFactory: <Context extends Record<string, unknown>>({ name, version, context, apiFactories, promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful, instructions, }: {
+interface HttpServerOptions<Context extends Record<string, unknown>> {
     name: string;
     version?: string;
     context: Context;
@@ -14,10 +14,28 @@ export declare const httpServerFactory: <Context extends Record<string, unknown>
     cleanupFn?: () => void | Promise<void>;
     stateful?: boolean;
     instructions?: string;
-}) => Promise<{
-    app: express.Express;
-    server: Server;
+    /**
+     * When provided, mount routers on this app/router instead of creating a new
+     * one. The caller owns the server lifecycle — `httpServerFactory` will not
+     * call `app.listen()`. The returned `server` will be `null`.
+     */
+    app?: Router;
+    /**
+     * Path to mount the MCP router at. Defaults to `"/mcp"`.
+     */
+    mcpPath?: string;
+    /**
+     * Path to mount the API router at. Defaults to `"/api"`.
+     */
+    apiPath?: string;
+}
+interface HttpServerResult {
+    app: Router;
+    /** `null` when an external `app` was provided (caller owns the server). */
+    server: Server | null;
     apiRouter: express.Router;
     mcpRouter: express.Router;
     registerCleanupFn: (fn: () => Promise<void>) => void;
-}>;
+}
+export declare const httpServerFactory: <Context extends Record<string, unknown>>({ name, version, context, apiFactories, promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful, instructions, app: externalApp, mcpPath, apiPath, }: HttpServerOptions<Context>) => Promise<HttpServerResult>;
+export {};

package/dist/httpServer.js

@@ -7,14 +7,21 @@ import { log } from './logger.js';
 import { mcpServerFactory } from './mcpServer.js';
 import { registerExitHandlers } from './registerExitHandlers.js';
 import { StatusError } from './StatusError.js';
-export const httpServerFactory = async ({ name, version, context, apiFactories = [], promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful = true, instructions, }) => {
+export const httpServerFactory = async ({ name, version, context, apiFactories = [], promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful = true, instructions, app: externalApp, mcpPath = '/mcp', apiPath = '/api', }) => {
     const cleanupFns = cleanupFn
         ? [cleanupFn]
         : [];
     const exitHandler = registerExitHandlers(cleanupFns);
-    log.info('Starting HTTP server...');
-    const app = express();
-    app.enable('trust proxy');
+    let app;
+    let ownApp;
+    if (externalApp) {
+        app = externalApp;
+    }
+    else {
+        ownApp = express();
+        ownApp.enable('trust proxy');
+        app = ownApp;
+    }
     const PORT = process.env.PORT || 3001;
     const inspector = process.env.NODE_ENV !== 'production' ||
         ['1', 'true'].includes(process.env.ENABLE_INSPECTOR ?? '0');
@@ -30,10 +37,10 @@ export const httpServerFactory = async ({ name, version, context, apiFactories =
         instructions,
     }), { name, stateful, inspector });
     cleanupFns.push(mcpCleanup);
-    app.use('/mcp', mcpRouter);
+    app.use(mcpPath, mcpRouter);
     const [apiRouter, apiCleanup] = await apiRouterFactory(context, apiFactories);
     cleanupFns.push(apiCleanup);
-    app.use('/api', apiRouter);
+    app.use(apiPath, apiRouter);
     // Error handler
     app.use((err, _req, res, _next) => {
         if (err instanceof StatusError && err.status < 500) {
@@ -49,19 +56,34 @@ export const httpServerFactory = async ({ name, version, context, apiFactories =
             .status(err instanceof StatusError ? err.status : 500)
             .json({ error: err.message });
     });
-    if (inspector) {
+    if (inspector && 'listen' in app) {
+        const expressApp = app;
         process.env.MCP_USE_ANONYMIZED_TELEMETRY = 'false';
         import('@mcp-use/inspector')
             .then(({ mountInspector }) => {
-            app.use(bodyParser.json());
-            mountInspector(app, {
+            expressApp.use(bodyParser.json());
+            mountInspector(expressApp, {
                 autoConnectUrl: process.env.MCP_PUBLIC_URL ?? `http://localhost:${PORT}/mcp`,
             });
         })
             .catch(log.error);
     }
-    // Start the server
-    const server = app.listen(PORT, async (error) => {
+    // When an external app is provided, the caller owns the server lifecycle.
+    if (externalApp) {
+        return {
+            app,
+            server: null,
+            apiRouter,
+            mcpRouter,
+            registerCleanupFn: (fn) => {
+                cleanupFns.push(fn);
+            },
+        };
+    }
+    // Start the server (ownApp is guaranteed to exist here — we returned early for external apps)
+    if (!ownApp)
+        throw new Error('Expected own Express app');
+    const server = ownApp.listen(PORT, async (error) => {
         if (error) {
             log.error('Error starting HTTP server:', error);
             exitHandler(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tigerdata/mcp-boilerplate",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "MCP boilerplate code for Node.js",
   "license": "Apache-2.0",
   "author": "TigerData",