@tigerdata/mcp-boilerplate 1.0.2 → 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/dist/skills/types.js

@@ -34,7 +34,7 @@ export const zSkillCfg = z.discriminatedUnion('type', [
     zGitHubSkillCfg,
     zGitHubCollectionSkillCfg,
 ]);
-export const zSkillCfgMap = z.record(zSkillCfg);
+export const zSkillCfgMap = z.record(z.string(), zSkillCfg);
 export const zSkillMatter = z.object({
     name: z.string().trim().min(1),
     description: z.string(),
@@ -42,7 +42,7 @@ export const zSkillMatter = z.object({
 export const zLocalSkill = zSkillMatter.extend(zLocalSkillCfg.shape);
 export const zGitHubSkill = zSkillMatter.extend(zGitHubSkillCfg.shape);
 export const zSkill = z.discriminatedUnion('type', [zLocalSkill, zGitHubSkill]);
-export const zSkillMap = z.record(zSkill);
+export const zSkillMap = z.record(z.string(), zSkill);
 export const zViewSkillInputSchema = {
     skill_name: z
         .string()

package/dist/types.d.ts

@@ -1,7 +1,8 @@
 import type { CompleteResourceTemplateCallback, ListResourcesCallback, ReadResourceCallback, ReadResourceTemplateCallback, ResourceMetadata } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { GetPromptResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import type { Router } from 'express';
-import type { ZodRawShape, ZodTypeAny, z } from 'zod';
+import type { ZodRawShape, z } from 'zod';
+type ObjectOutput<T extends ZodRawShape> = z.infer<z.ZodObject<T>>;
 export type BaseToolConfig = {
     title?: string;
     description?: string;
@@ -40,8 +41,8 @@ export type ToolConfig<InputArgs extends ZodRawShape, OutputArgs extends ZodRawS
 };
 export interface ApiDefinition<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape, SimplifiedOutputArgs = OutputArgs> extends BaseApiDefinition {
     config: ToolConfig<InputArgs, OutputArgs>;
-    fn(args: z.objectOutputType<InputArgs, ZodTypeAny>): Promise<z.objectOutputType<OutputArgs, ZodTypeAny>>;
-    pickResult?(result: z.objectOutputType<OutputArgs, ZodTypeAny>): SimplifiedOutputArgs;
+    fn(args: ObjectOutput<InputArgs>): Promise<ObjectOutput<OutputArgs>>;
+    pickResult?(result: ObjectOutput<OutputArgs>): SimplifiedOutputArgs;
 }
 export type ApiFactory<Context extends Record<string, unknown>, Input extends ZodRawShape, Output extends ZodRawShape, RestOutput = Output> = (ctx: Context, featureFlags: McpFeatureFlags) => ApiDefinition<Input, Output, RestOutput> | Promise<ApiDefinition<Input, Output, RestOutput>>;
 export type RouterFactoryResult = [Router, () => void | Promise<void>];
@@ -52,7 +53,7 @@ export type PromptConfig<InputArgs extends ZodRawShape> = {
 };
 export interface PromptDefinition<InputArgs extends ZodRawShape> extends BasePromptDefinition {
     config: PromptConfig<InputArgs>;
-    fn(args: z.objectOutputType<InputArgs, ZodTypeAny>): Promise<GetPromptResult>;
+    fn(args: ObjectOutput<InputArgs>): Promise<GetPromptResult>;
 }
 export type PromptFactory<Context extends Record<string, unknown>, Input extends ZodRawShape> = (ctx: Context, featureFlags: McpFeatureFlags) => PromptDefinition<Input>;
 export interface TemplatedResourceDefinition {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tigerdata/mcp-boilerplate",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "MCP boilerplate code for Node.js",
   "license": "Apache-2.0",
   "author": "TigerData",
@@ -54,11 +54,14 @@
     "express": "^5.2.1",
     "gray-matter": "^4.0.3",
     "raw-body": "^3.0.2",
-    "yaml": "^2.8.2",
-    "zod": "^3.23.8"
+    "yaml": "^2.8.2"
+  },
+  "peerDependencies": {
+    "zod": "^3.25 || ^4.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.11",
+    "zod": "^3.25.0",
     "@octokit/rest": "^22.0.1",
     "@types/bun": "^1.3.5",
     "@types/express": "^5.0.6",