@tigerdata/mcp-boilerplate 0.9.1 → 0.9.2

package/dist/http/api.d.ts

@@ -1,6 +1,5 @@
 /**
  * REST API alternative to MCP for direct use of the same tools.
  */
-import { type ZodRawShape } from 'zod';
-import type { ApiFactory, RouterFactoryResult } from '../types.js';
-export declare const apiRouterFactory: <Context extends Record<string, unknown>>(context: Context, apiFactories: readonly ApiFactory<Context, ZodRawShape, ZodRawShape>[]) => RouterFactoryResult;
+import type { BaseApiFactory, RouterFactoryResult } from '../types.js';
+export declare const apiRouterFactory: <Context extends Record<string, unknown>>(context: Context, apiFactories: readonly BaseApiFactory<Context>[]) => RouterFactoryResult;

package/dist/http/mcp.d.ts

@@ -2,7 +2,8 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { McpFeatureFlags, RouterFactoryResult } from '../types.js';
 export declare const mcpRouterFactory: <Context extends Record<string, unknown>>(context: Context, createServer: (context: Context, featureFlags: McpFeatureFlags) => {
     server: McpServer;
-}, { name, stateful, }?: {
+}, { name, stateful, inspector, }?: {
     name?: string;
     stateful?: boolean;
+    inspector?: boolean;
 }) => RouterFactoryResult;

package/dist/http/mcp.js

@@ -8,7 +8,7 @@ import getRawBody from 'raw-body';
 import { log } from '../logger.js';
 const name = process.env.OTEL_SERVICE_NAME;
 const tracer = trace.getTracer(name ? `${name}.router.mcp` : 'router.mcp');
-export const mcpRouterFactory = (context, createServer, { name, stateful = true, } = {}) => {
+export const mcpRouterFactory = (context, createServer, { name, stateful = true, inspector = false, } = {}) => {
     const router = Router();
     const transports = new Map();
     const sessionFeatureFlags = new Map();
@@ -198,7 +198,11 @@ export const mcpRouterFactory = (context, createServer, { name, stateful = true,
   <h1>${name}</h1>
   <h2>Model Context Protocol (MCP) Server</h2>
   <p>This endpoint is used for MCP communication. Please use an MCP-compatible client to interact with this server.</p>
-
+  ${inspector
+                ? `
+  <h3>Inspector</h3>
+  <p>You can use the <a href="/inspector">MCP Inspector</a> for testing purposes.</p>`
+                : ''}
   <h3>Claude Code</h3>
   <p>To connect to this MCP server using Claude Code, run the following command in your terminal:</p>
   <pre><code>claude mcp add --transport http ${name || req.get('host')} ${fullUrl}</code></pre>

package/dist/httpServer.d.ts

@@ -1,15 +1,14 @@
 #!/usr/bin/env node
 import type { Server } from 'node:http';
 import express from 'express';
-import type { ZodRawShape } from 'zod';
 import { type AdditionalSetupArgs } from './mcpServer.js';
-import type { ApiFactory, PromptFactory, ResourceFactory } from './types.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, }: {
     name: string;
     version?: string;
     context: Context;
-    apiFactories?: readonly ApiFactory<Context, ZodRawShape, ZodRawShape>[];
-    promptFactories?: readonly PromptFactory<Context, ZodRawShape>[];
+    apiFactories?: readonly BaseApiFactory<Context>[];
+    promptFactories?: readonly BasePromptFactory<Context>[];
     resourceFactories?: readonly ResourceFactory<Context>[];
     additionalSetup?: (args: AdditionalSetupArgs<Context>) => void;
     cleanupFn?: () => void | Promise<void>;

package/dist/httpServer.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import bodyParser from 'body-parser';
 import express from 'express';
 import { apiRouterFactory } from './http/api.js';
 import { mcpRouterFactory } from './http/mcp.js';
@@ -14,6 +15,9 @@ export const httpServerFactory = ({ name, version, context, apiFactories = [], p
     log.info('Starting HTTP server...');
     const app = express();
     app.enable('trust proxy');
+    const PORT = process.env.PORT || 3001;
+    const inspector = process.env.NODE_ENV !== 'production' ||
+        ['1', 'true'].includes(process.env.ENABLE_INSPECTOR ?? '0');
     const [mcpRouter, mcpCleanup] = mcpRouterFactory(context, (context, featureFlags) => mcpServerFactory({
         name,
         version,
@@ -24,7 +28,7 @@ export const httpServerFactory = ({ name, version, context, apiFactories = [], p
         additionalSetup,
         featureFlags,
         instructions,
-    }), { name, stateful });
+    }), { name, stateful, inspector });
     cleanupFns.push(mcpCleanup);
     app.use('/mcp', mcpRouter);
     const [apiRouter, apiCleanup] = apiRouterFactory(context, apiFactories);
@@ -45,15 +49,26 @@ export const httpServerFactory = ({ name, version, context, apiFactories = [], p
             .status(err instanceof StatusError ? err.status : 500)
             .json({ error: err.message });
     });
+    if (inspector) {
+        process.env.MCP_USE_ANONYMIZED_TELEMETRY = 'false';
+        import('@mcp-use/inspector')
+            .then(({ mountInspector }) => {
+            app.use(bodyParser.json());
+            mountInspector(app, { autoConnectUrl: `http://localhost:${PORT}/mcp` });
+        })
+            .catch(log.error);
+    }
     // Start the server
-    const PORT = process.env.PORT || 3001;
-    const server = app.listen(PORT, (error) => {
+    const server = app.listen(PORT, async (error) => {
         if (error) {
             log.error('Error starting HTTP server:', error);
             exitHandler(1);
         }
         else {
             log.info(`HTTP Server listening on port ${PORT}`);
+            if (inspector) {
+                log.info(`🌐 MCP inspector running at http://localhost:${PORT}/inspector`);
+            }
         }
     });
     cleanupFns.push(async () => {

package/dist/mcpServer.d.ts

@@ -1,7 +1,6 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ServerCapabilities } from '@modelcontextprotocol/sdk/types.js';
-import type { ZodRawShape } from 'zod';
-import type { ApiFactory, McpFeatureFlags, PromptFactory, ResourceFactory } from './types.js';
+import type { BaseApiFactory, BasePromptFactory, McpFeatureFlags, ResourceFactory } from './types.js';
 export interface AdditionalSetupArgs<Context extends Record<string, unknown>> {
     context: Context;
     server: McpServer;
@@ -11,8 +10,8 @@ export declare const mcpServerFactory: <Context extends Record<string, unknown>>
     name: string;
     version?: string;
     context: Context;
-    apiFactories?: readonly ApiFactory<Context, ZodRawShape, ZodRawShape>[];
-    promptFactories?: readonly PromptFactory<Context, ZodRawShape>[];
+    apiFactories?: readonly BaseApiFactory<Context>[];
+    promptFactories?: readonly BasePromptFactory<Context>[];
     resourceFactories?: readonly ResourceFactory<Context>[];
     additionalSetup?: (args: AdditionalSetupArgs<Context>) => void;
     additionalCapabilities?: ServerCapabilities;

package/dist/mcpServer.js

@@ -59,7 +59,7 @@ export const mcpServerFactory = ({ name, version = '1.0.0', context, apiFactorie
                     // make sense.
                     title: tool.config.title,
                 },
-            }, async (args, extra) => {
+            }, (async (args, extra) => {
                 let traceContext = otelContext.active();
                 if (extra?._meta?.traceparent) {
                     // Some MCP clients (e.g. pydantic) pass the parent trace context
@@ -106,7 +106,7 @@ export const mcpServerFactory = ({ name, version = '1.0.0', context, apiFactorie
                         span.end();
                     }
                 });
-            });
+            }));
         }
     }
     if (enablePrompts) {

package/dist/stdio.d.ts

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
-import type { ZodRawShape } from 'zod';
 import { type AdditionalSetupArgs } from './mcpServer.js';
-import type { ApiFactory, PromptFactory, ResourceFactory } from './types.js';
+import type { BaseApiFactory, BasePromptFactory, ResourceFactory } from './types.js';
 export declare const stdioServerFactory: <Context extends Record<string, unknown>>({ name, version, context, apiFactories, promptFactories, resourceFactories, additionalSetup, cleanupFn, instructions, }: {
     name: string;
     version?: string;
     context: Context;
-    apiFactories?: readonly ApiFactory<Context, ZodRawShape, ZodRawShape>[];
-    promptFactories?: readonly PromptFactory<Context, ZodRawShape>[];
+    apiFactories?: readonly BaseApiFactory<Context>[];
+    promptFactories?: readonly BasePromptFactory<Context>[];
     resourceFactories?: readonly ResourceFactory<Context>[];
     additionalSetup?: (args: AdditionalSetupArgs<Context>) => void;
     cleanupFn?: () => Promise<void>;

package/dist/types.d.ts

@@ -2,21 +2,46 @@ import type { CompleteResourceTemplateCallback, ListResourcesCallback, ReadResou
 import type { GetPromptResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import type { Router } from 'express';
 import type { ZodRawShape, ZodTypeAny, z } from 'zod';
-export type ToolConfig<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape> = {
+export type BaseToolConfig = {
     title?: string;
     description?: string;
-    inputSchema: InputArgs;
-    outputSchema: OutputArgs;
+    inputSchema: ZodRawShape;
+    outputSchema: ZodRawShape;
     annotations?: ToolAnnotations;
 };
-export interface ApiDefinition<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape, SimplifiedOutputArgs = OutputArgs> {
+export interface BaseApiDefinition {
     name: string;
     method?: 'get' | 'post' | 'put' | 'delete';
     route?: string | string[];
-    config: ToolConfig<InputArgs, OutputArgs>;
+    config: BaseToolConfig;
     disabled?: boolean;
-    fn: (args: z.objectOutputType<InputArgs, ZodTypeAny>) => Promise<z.objectOutputType<OutputArgs, ZodTypeAny>>;
-    pickResult?: (result: z.objectOutputType<OutputArgs, ZodTypeAny>) => SimplifiedOutputArgs;
+    fn(args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    pickResult?(result: Record<string, unknown>): unknown;
+}
+export type BaseApiFactory<Context extends Record<string, unknown>> = (ctx: Context, featureFlags: McpFeatureFlags) => BaseApiDefinition;
+export type BasePromptConfig = {
+    title?: string;
+    description?: string;
+    inputSchema: ZodRawShape;
+};
+export interface BasePromptDefinition {
+    name: string;
+    config: BasePromptConfig;
+    disabled?: boolean;
+    fn(args: Record<string, unknown>): Promise<GetPromptResult>;
+}
+export type BasePromptFactory<Context extends Record<string, unknown>> = (ctx: Context, featureFlags: McpFeatureFlags) => BasePromptDefinition;
+export type ToolConfig<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape> = {
+    title?: string;
+    description?: string;
+    inputSchema: InputArgs;
+    outputSchema: OutputArgs;
+    annotations?: ToolAnnotations;
+};
+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;
 }
 export type ApiFactory<Context extends Record<string, unknown>, Input extends ZodRawShape, Output extends ZodRawShape, RestOutput = Output> = (ctx: Context, featureFlags: McpFeatureFlags) => ApiDefinition<Input, Output, RestOutput>;
 export type RouterFactoryResult = [Router, () => void | Promise<void>];
@@ -25,11 +50,9 @@ export type PromptConfig<InputArgs extends ZodRawShape> = {
     description?: string;
     inputSchema: InputArgs;
 };
-export interface PromptDefinition<InputArgs extends ZodRawShape> {
-    name: string;
+export interface PromptDefinition<InputArgs extends ZodRawShape> extends BasePromptDefinition {
     config: PromptConfig<InputArgs>;
-    disabled?: boolean;
-    fn: (args: z.objectOutputType<InputArgs, ZodTypeAny>) => Promise<GetPromptResult>;
+    fn(args: z.objectOutputType<InputArgs, ZodTypeAny>): 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": "0.9.1",
+  "version": "0.9.2",
   "description": "MCP boilerplate code for Node.js",
   "license": "Apache-2.0",
   "author": "TigerData",
@@ -31,11 +31,12 @@
   ],
   "scripts": {
     "build": "tsc",
-    "prepare": "tsc",
+    "prepublishOnly": "tsc",
     "watch": "tsc --watch",
     "lint": "./bun x @biomejs/biome check"
   },
   "dependencies": {
+    "@mcp-use/inspector": "^0.13.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/auto-instrumentations-node": "^0.67.3",