@tigerdata/mcp-boilerplate 0.4.3 → 0.6.0

package/README.md

@@ -5,16 +5,39 @@ This provides some common code for creating a [Model Context Protocol](https://m
 ## Setup
 
 1. Clone the repository:
+
    ```bash
    git clone <repository-url>
    cd mcp-boilerplate-node
    ```
 
 2. Install dependencies:
+
    ```bash
    npm install
    ```
 
+## Eslint Plugin
+
+This project includes a custom ESLint plugin to guard against the problematic use of optional parameters for tool inputs. Doing so leads to tools that are incompatible with certain models, such as GPT-5.
+
+Add to your `eslint.config.mjs`:
+
+```js
+import boilerplatePlugin from '@tigerdata/mcp-boilerplate/eslintPlugin';
+export default [
+  // ... your existing config
+  {
+    plugins: {
+      'mcp-boilerplate': boilerplatePlugin,
+    },
+    rules: {
+      'mcp-boilerplate/no-optional-tool-params': 'error',
+    },
+  },
+];
+```
+
 ## Development
 
 ### Build

package/dist/eslintPlugin.d.ts

@@ -0,0 +1,13 @@
+/**
+ * TypeScript ESLint plugin for custom rules specific to this project
+ */
+import type { Rule } from 'eslint';
+export declare const rules: {
+    'no-optional-input-schema': Rule.RuleModule;
+};
+declare const _default: {
+    rules: {
+        'no-optional-input-schema': Rule.RuleModule;
+    };
+};
+export default _default;

package/dist/eslintPlugin.js

@@ -0,0 +1,154 @@
+/**
+ * TypeScript ESLint plugin for custom rules specific to this project
+ */
+/**
+ * Rule: no-optional-in-input-schema
+ *
+ * Detects when `.optional()`, `.default()`, or `.nullish()` are called on zod schemas
+ * that are used in the `inputSchema` property of ApiFactory config objects.
+ *
+ * Some LLMs (like GPT-5) require all tool input parameters to be marked as required
+ * in the schema, otherwise the tools become completely unusable. Using .optional(),
+ * .default(), or .nullish() makes parameters optional in the JSON schema, breaking
+ * compatibility with these LLMs.
+ */
+const noOptionalInputSchema = {
+    meta: {
+        type: 'problem',
+        docs: {
+            description: 'Disallow .optional(), .default(), and .nullish() on zod schemas in ApiFactory inputSchema',
+            category: 'Best Practices',
+            recommended: true,
+        },
+        messages: {
+            noOptional: 'Avoid using .optional(), .default(), or .nullish() on zod schemas in inputSchema. Some LLMs (like GPT-5) require all tool parameters to be marked as required, and tools become unusable otherwise. Use .nullable() instead if you need to accept null values, or handle empty/missing values in your function implementation.',
+        },
+        schema: [], // no options
+    },
+    create(context) {
+        // Track variables that are used as the Input type parameter in ApiFactory<Context, Input, Output>
+        const apiFactoryInputSchemas = new Set();
+        const problematicCalls = [];
+        return {
+            // Detect ApiFactory type annotations and extract the Input type parameter
+            VariableDeclarator(node) {
+                const varNode = node;
+                // Check if this variable has a TypeScript type annotation
+                if (varNode.id?.typeAnnotation?.typeAnnotation) {
+                    const typeAnn = varNode.id.typeAnnotation.typeAnnotation;
+                    // Look for ApiFactory type reference
+                    if (typeAnn.type === 'TSTypeReference' &&
+                        typeAnn.typeName?.name === 'ApiFactory') {
+                        // Get the type parameters
+                        const typeParams = typeAnn.typeArguments?.params;
+                        if (typeParams && typeParams.length >= 2) {
+                            const inputTypeParam = typeParams[1];
+                            // Check if it's a typeof reference (e.g., typeof inputSchema2)
+                            if (inputTypeParam.type === 'TSTypeQuery' &&
+                                inputTypeParam.exprName?.type === 'Identifier') {
+                                apiFactoryInputSchemas.add(inputTypeParam.exprName.name);
+                            }
+                        }
+                    }
+                }
+            },
+            // Collect all .optional(), .default(), and .nullish() calls on zod schemas
+            CallExpression(node) {
+                const callNode = node;
+                // Check if this is a .optional(), .default(), or .nullish() call
+                if (callNode.callee.type === 'MemberExpression') {
+                    const memberNode = callNode.callee;
+                    if (memberNode.property.type === 'Identifier' &&
+                        ['optional', 'default', 'nullish'].includes(memberNode.property.name)) {
+                        // Check if it's being called on a zod schema
+                        const isZodSchema = isLikelyZodSchema(memberNode.object);
+                        if (isZodSchema) {
+                            problematicCalls.push(callNode);
+                        }
+                    }
+                }
+            },
+            // After processing the entire file, check all problematic calls
+            'Program:exit'() {
+                for (const node of problematicCalls) {
+                    if (isInsideApiFactoryInputSchema(node, context, apiFactoryInputSchemas)) {
+                        const memberNode = node.callee;
+                        context.report({
+                            node: memberNode.property,
+                            messageId: 'noOptional',
+                        });
+                    }
+                }
+            },
+        };
+    },
+};
+/**
+ * Check if a node is inside a schema that's used as an ApiFactory Input type parameter
+ */
+function isInsideApiFactoryInputSchema(node, context, apiFactoryInputSchemas) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode?.();
+    const ancestors = sourceCode?.getAncestors?.(node) ?? [];
+    // Check ancestors for variables that are ApiFactory input schemas
+    for (const ancestor of ancestors) {
+        // Check if ancestor is a VariableDeclarator whose name is in apiFactoryInputSchemas
+        if (ancestor.type === 'VariableDeclarator') {
+            const varNode = ancestor;
+            if (varNode.id?.type === 'Identifier' &&
+                apiFactoryInputSchemas.has(varNode.id.name)) {
+                return true;
+            }
+        }
+    }
+    // Fallback: walk up parent chain if node.parent is available
+    let current = node.parent;
+    while (current) {
+        // Variable that's an ApiFactory input schema
+        if (current.type === 'VariableDeclarator') {
+            const varNode = current;
+            if (varNode.id?.type === 'Identifier' &&
+                apiFactoryInputSchemas.has(varNode.id.name)) {
+                return true;
+            }
+        }
+        current = current.parent;
+    }
+    return false;
+}
+/**
+ * Heuristic to determine if a node is likely a zod schema
+ */
+function isLikelyZodSchema(node) {
+    if (!node || node.type === 'PrivateIdentifier')
+        return false;
+    // Direct z identifier (the base of all zod schemas)
+    if (node.type === 'Identifier') {
+        return node.name === 'z';
+    }
+    // Direct z.* calls (e.g., z.string)
+    if (node.type === 'MemberExpression') {
+        if (node.object.type === 'Identifier' && node.object.name === 'z') {
+            return true;
+        }
+        // Member expressions that might be chained zod methods (e.g., z.string)
+        return isLikelyZodSchema(node.object);
+    }
+    // Chained method calls on zod schemas (e.g., z.string().describe())
+    if (node.type === 'CallExpression') {
+        if (node.callee.type === 'MemberExpression') {
+            // Recursively check the object of the member expression
+            return isLikelyZodSchema(node.callee.object);
+        }
+        // Also check if the callee itself is 'z'
+        if (node.callee.type === 'Identifier') {
+            return node.callee.name === 'z';
+        }
+    }
+    return false;
+}
+export const rules = {
+    'no-optional-input-schema': noOptionalInputSchema,
+};
+export default {
+    rules,
+};

package/dist/http/api.js

@@ -8,7 +8,7 @@ export const apiRouterFactory = (context, apiFactories) => {
     const router = Router();
     router.use(bodyParser.json());
     for (const factory of apiFactories) {
-        const tool = factory(context);
+        const tool = factory(context, {});
         if (!tool.method || !tool.route)
             continue;
         router[tool.method](tool.route, async (req, res) => {
@@ -23,9 +23,7 @@ export const apiRouterFactory = (context, apiFactories) => {
                 parsedInput = Input.parse(input);
             }
             catch (error) {
-                res
-                    .status(400)
-                    .json({
+                res.status(400).json({
                     error: 'zod validation failure',
                     issues: error.issues,
                 });

package/dist/http/mcp.d.ts

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

package/dist/http/mcp.js

@@ -11,8 +11,29 @@ const tracer = trace.getTracer(name ? `${name}.router.mcp` : 'router.mcp');
 export const mcpRouterFactory = (context, createServer, { name, stateful = true, } = {}) => {
     const router = Router();
     const transports = new Map();
+    const sessionFeatureFlags = new Map();
+    const toSet = (flag) => flag
+        ? Array.isArray(flag)
+            ? new Set(flag)
+            : typeof flag === 'string'
+                ? new Set(flag.split(',').map((s) => s.trim()))
+                : null
+        : null;
+    const parseFeatureFlags = (req) => ({
+        prompts: req.query.prompts !== 'false' && req.query.prompts !== '0',
+        enabledPrompts: toSet(req.query.enabled_prompts),
+        disabledPrompts: toSet(req.query.disabled_prompts),
+        resources: req.query.resources !== 'false' && req.query.resources !== '0',
+        enabledResources: toSet(req.query.enabled_resources),
+        disabledResources: toSet(req.query.disabled_resources),
+        tools: req.query.tools !== 'false' && req.query.tools !== '0',
+        enabledTools: toSet(req.query.enabled_tools),
+        disabledTools: toSet(req.query.disabled_tools),
+        query: req.query,
+    });
     const handleStatelessRequest = async (req, res) => {
-        const { server } = createServer(context);
+        const featureFlags = parseFeatureFlags(req);
+        const { server } = createServer(context, featureFlags);
         const transport = new StreamableHTTPServerTransport({
             sessionIdGenerator: undefined,
         });
@@ -60,20 +81,23 @@ export const mcpRouterFactory = (context, createServer, { name, stateful = true,
                 });
                 return;
             }
+            const featureFlags = parseFeatureFlags(req);
             transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: () => randomUUID(),
                 onsessioninitialized: (sessionId) => {
                     log.info(`Session initialized with ID: ${sessionId}`);
                     transports.set(sessionId, transport);
+                    sessionFeatureFlags.set(sessionId, featureFlags);
                 },
                 onsessionclosed: (sessionId) => {
                     if (sessionId && transports.has(sessionId)) {
                         log.info(`Transport closed for session ${sessionId}, removing from transports map`);
                         transports.delete(sessionId);
+                        sessionFeatureFlags.delete(sessionId);
                     }
                 },
             });
-            const { server } = createServer(context);
+            const { server } = createServer(context, featureFlags);
             await server.connect(transport);
         }
         await transport.handleRequest(req, res, body);

package/dist/httpServer.d.ts

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
 import express from 'express';
-import { ApiFactory, PromptFactory } from './types.js';
+import { ApiFactory, PromptFactory, ResourceFactory } from './types.js';
 import { AdditionalSetupArgs } from './mcpServer.js';
 import { Server } from 'node:http';
-export declare const httpServerFactory: <Context extends Record<string, unknown>>({ name, version, context, apiFactories, promptFactories, additionalSetup, cleanupFn, stateful, }: {
+export declare const httpServerFactory: <Context extends Record<string, unknown>>({ name, version, context, apiFactories, promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful, }: {
     name: string;
     version?: string;
     context: Context;
     apiFactories?: readonly ApiFactory<Context, any, any>[];
     promptFactories?: readonly PromptFactory<Context, any>[];
+    resourceFactories?: readonly ResourceFactory<Context>[];
     additionalSetup?: (args: AdditionalSetupArgs<Context>) => void;
     cleanupFn?: () => void | Promise<void>;
     stateful?: boolean;

package/dist/httpServer.js

@@ -6,7 +6,7 @@ import { registerExitHandlers } from './registerExitHandlers.js';
 import { mcpServerFactory } from './mcpServer.js';
 import { log } from './logger.js';
 import { StatusError } from './StatusError.js';
-export const httpServerFactory = ({ name, version, context, apiFactories = [], promptFactories = [], additionalSetup, cleanupFn, stateful = true, }) => {
+export const httpServerFactory = ({ name, version, context, apiFactories = [], promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful = true, }) => {
     const cleanupFns = cleanupFn
         ? [cleanupFn]
         : [];
@@ -14,13 +14,15 @@ export const httpServerFactory = ({ name, version, context, apiFactories = [], p
     log.info('Starting HTTP server...');
     const app = express();
     app.enable('trust proxy');
-    const [mcpRouter, mcpCleanup] = mcpRouterFactory(context, () => mcpServerFactory({
+    const [mcpRouter, mcpCleanup] = mcpRouterFactory(context, (context, featureFlags) => mcpServerFactory({
         name,
         version,
         context,
         apiFactories,
         promptFactories,
+        resourceFactories,
         additionalSetup,
+        featureFlags,
     }), { name, stateful });
     cleanupFns.push(mcpCleanup);
     app.use('/mcp', mcpRouter);

package/dist/index.d.ts

@@ -2,8 +2,8 @@ export { cliEntrypoint } from './cliEntrypoint.js';
 export { httpServerFactory } from './httpServer.js';
 export { log } from './logger.js';
 export { stdioServerFactory } from './stdio.js';
-export { type ApiFactory } from './types.js';
+export type { ApiFactory, McpFeatureFlags, PromptFactory, ResourceFactory, ParsedQs, } from './types.js';
 export { StatusError } from './StatusError.js';
-export { type AdditionalSetupArgs } from './mcpServer.js';
+export type { AdditionalSetupArgs } from './mcpServer.js';
 export { withSpan, addAiResultToSpan } from './tracing.js';
 export { registerExitHandlers } from './registerExitHandlers.js';

package/dist/mcpServer.d.ts

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

package/dist/mcpServer.js

@@ -1,116 +1,227 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { SpanStatusCode, trace, context as otelContext, propagation, SpanKind, } from '@opentelemetry/api';
 import { log } from './logger.js';
 const name = process.env.OTEL_SERVICE_NAME;
 const tracer = trace.getTracer(name ? `${name}.mcpServer` : 'mcpServer');
-const enabledTools = process.env.MCP_ENABLED_TOOLS
-    ? new Set(process.env.MCP_ENABLED_TOOLS.split(',').map((s) => s.trim()))
-    : null;
-const disabledTools = process.env.MCP_DISABLED_TOOLS
-    ? new Set(process.env.MCP_DISABLED_TOOLS.split(',').map((s) => s.trim()))
-    : null;
-export const mcpServerFactory = ({ name, version = '1.0.0', context, apiFactories, promptFactories = [], additionalSetup, }) => {
+const toSet = (str) => str ? new Set(str.split(',').map((s) => s.trim())) : null;
+const enabledTools = toSet(process.env.MCP_ENABLED_TOOLS);
+const disabledTools = toSet(process.env.MCP_DISABLED_TOOLS);
+const enabledPrompts = toSet(process.env.MCP_ENABLED_PROMPTS);
+const disabledPrompts = toSet(process.env.MCP_DISABLED_PROMPTS);
+const enabledResources = toSet(process.env.MCP_ENABLED_RESOURCES);
+const disabledResources = toSet(process.env.MCP_DISABLED_RESOURCES);
+const shouldSkip = (item, enabledSets, disabledSets) => {
+    if (item.disabled)
+        return true;
+    for (const enabledSet of enabledSets) {
+        if (enabledSet && !enabledSet.has(item.name)) {
+            return true;
+        }
+    }
+    for (const disabledSet of disabledSets) {
+        if (disabledSet && disabledSet.has(item.name)) {
+            return true;
+        }
+    }
+    return false;
+};
+export const mcpServerFactory = ({ name, version = '1.0.0', context, apiFactories = [], promptFactories = [], resourceFactories = [], additionalSetup, additionalCapabilities = {}, featureFlags = {}, }) => {
+    const enablePrompts = featureFlags.prompts !== false;
+    const enableResources = featureFlags.resources !== false;
+    const enableTools = featureFlags.tools !== false;
     const server = new McpServer({
         name,
         version,
     }, {
         capabilities: {
-            tools: {},
-            ...(promptFactories.length ? { prompts: {} } : null),
+            ...(enableTools && apiFactories.length ? { tools: {} } : null),
+            ...(enablePrompts && promptFactories.length ? { prompts: {} } : null),
+            ...(enableResources && resourceFactories.length
+                ? { resources: {} }
+                : null),
+            ...additionalCapabilities,
         },
     });
-    for (const factory of apiFactories) {
-        const tool = factory(context);
-        if (tool.disabled)
-            continue;
-        if (enabledTools && !enabledTools.has(tool.name)) {
-            continue;
-        }
-        if (disabledTools && disabledTools.has(tool.name)) {
-            continue;
-        }
-        server.registerTool(tool.name, {
-            ...tool.config,
-            annotations: {
-                ...tool.config.annotations,
-                // Some clients (e.g. claude code) do not yet support the title field
-                // at the top level and instead expect it in annotations. We also
-                // don't allow setting different titles in two places as that doesn't
-                // make sense.
-                title: tool.config.title,
-            },
-        }, async (args, extra) => {
-            let traceContext = otelContext.active();
-            if (extra?._meta?.traceparent) {
-                // Some MCP clients (e.g. pydantic) pass the parent trace context
-                traceContext = propagation.extract(traceContext, {
-                    traceparent: extra._meta.traceparent,
-                    tracestate: extra._meta.tracestate,
+    if (enableTools) {
+        for (const factory of apiFactories) {
+            const tool = factory(context, featureFlags);
+            if (shouldSkip(tool, [enabledTools, featureFlags.enabledTools], [disabledTools, featureFlags.disabledTools])) {
+                continue;
+            }
+            server.registerTool(tool.name, {
+                ...tool.config,
+                annotations: {
+                    ...tool.config.annotations,
+                    // Some clients (e.g. claude code) do not yet support the title field
+                    // at the top level and instead expect it in annotations. We also
+                    // don't allow setting different titles in two places as that doesn't
+                    // make sense.
+                    title: tool.config.title,
+                },
+            }, async (args, extra) => {
+                let traceContext = otelContext.active();
+                if (extra?._meta?.traceparent) {
+                    // Some MCP clients (e.g. pydantic) pass the parent trace context
+                    traceContext = propagation.extract(traceContext, {
+                        traceparent: extra._meta.traceparent,
+                        tracestate: extra._meta.tracestate,
+                    });
+                }
+                return tracer.startActiveSpan(`mcp.tool.${tool.name}`, { kind: SpanKind.SERVER }, traceContext, async (span) => {
+                    span.setAttribute('mcp.tool.args', JSON.stringify(args));
+                    try {
+                        const result = await tool.fn(args);
+                        const text = JSON.stringify(result);
+                        span.setAttribute('mcp.tool.responseBytes', text.length);
+                        span.setStatus({ code: SpanStatusCode.OK });
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text,
+                                },
+                            ],
+                            structuredContent: result,
+                        };
+                    }
+                    catch (error) {
+                        log.error('Error invoking tool:', error);
+                        span.recordException(error);
+                        span.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: error.message,
+                        });
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Error: ${error.message || 'Unknown error'}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    finally {
+                        span.end();
+                    }
                 });
+            });
+        }
+    }
+    if (enablePrompts) {
+        for (const factory of promptFactories) {
+            const prompt = factory(context, featureFlags);
+            if (shouldSkip(prompt, [enabledPrompts, featureFlags.enabledPrompts], [disabledPrompts, featureFlags.disabledPrompts])) {
+                continue;
             }
-            return tracer.startActiveSpan(`mcp.tool.${tool.name}`, { kind: SpanKind.SERVER }, traceContext, async (span) => {
-                span.setAttribute('mcp.tool.args', JSON.stringify(args));
+            server.registerPrompt(prompt.name, prompt.config, async (args) => tracer.startActiveSpan(`mcp.prompt.${prompt.name}`, async (span) => {
+                span.setAttribute('mcp.prompt.args', JSON.stringify(args));
                 try {
-                    const result = await tool.fn(args);
-                    const text = JSON.stringify(result);
-                    span.setAttribute('mcp.tool.responseBytes', text.length);
+                    const result = await prompt.fn(args);
                     span.setStatus({ code: SpanStatusCode.OK });
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text,
-                            },
-                        ],
-                        structuredContent: result,
-                    };
+                    return result;
                 }
                 catch (error) {
-                    log.error('Error invoking tool:', error);
+                    log.error('Error invoking prompt:', error);
                     span.recordException(error);
                     span.setStatus({
                         code: SpanStatusCode.ERROR,
                         message: error.message,
                     });
-                    return {
-                        content: [
-                            {
-                                type: 'text',
-                                text: `Error: ${error.message || 'Unknown error'}`,
-                            },
-                        ],
-                        isError: true,
-                    };
+                    throw error;
                 }
                 finally {
                     span.end();
                 }
-            });
-        });
+            }));
+        }
     }
-    for (const factory of promptFactories) {
-        const prompt = factory(context);
-        server.registerPrompt(prompt.name, prompt.config, async (args) => tracer.startActiveSpan(`mcp.prompt.${prompt.name}`, async (span) => {
-            span.setAttribute('mcp.prompt.args', JSON.stringify(args));
-            try {
-                const result = await prompt.fn(args);
-                span.setStatus({ code: SpanStatusCode.OK });
-                return result;
-            }
-            catch (error) {
-                log.error('Error invoking prompt:', error);
-                span.recordException(error);
-                span.setStatus({
-                    code: SpanStatusCode.ERROR,
-                    message: error.message,
-                });
-                throw error;
+    if (enableResources) {
+        for (const factory of resourceFactories) {
+            const resource = factory(context, featureFlags);
+            if (shouldSkip(resource, [enabledResources, featureFlags.enabledResources], [disabledResources, featureFlags.disabledResources])) {
+                continue;
             }
-            finally {
-                span.end();
+            switch (resource.type) {
+                case 'static': {
+                    server.registerResource(resource.name, resource.uri, resource.config, async (uri, extra) => tracer.startActiveSpan(`mcp.resource.static.${resource.name}`, async (span) => {
+                        span.setAttribute('mcp.resource.uri', uri.toString());
+                        span.setAttribute('mcp.resource.extra', JSON.stringify(extra));
+                        try {
+                            const result = await resource.read(uri, extra);
+                            span.setStatus({ code: SpanStatusCode.OK });
+                            return result;
+                        }
+                        catch (error) {
+                            log.error('Error invoking resource:', error);
+                            span.recordException(error);
+                            span.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: error.message,
+                            });
+                            throw error;
+                        }
+                        finally {
+                            span.end();
+                        }
+                    }));
+                    break;
+                }
+                case 'templated': {
+                    server.registerResource(resource.name, new ResourceTemplate(resource.uriTemplate, {
+                        list: resource.list &&
+                            ((extra) => tracer.startActiveSpan(`mcp.resource.templated.${resource.name}.list`, async (span) => {
+                                try {
+                                    const result = await resource.list(extra);
+                                    span.setAttribute('mcp.resource.list.uris', result.resources.map((r) => r.uri).join(', '));
+                                    span.setStatus({ code: SpanStatusCode.OK });
+                                    return result;
+                                }
+                                catch (error) {
+                                    log.error('Error invoking resource list:', error);
+                                    span.recordException(error);
+                                    span.setStatus({
+                                        code: SpanStatusCode.ERROR,
+                                        message: error.message,
+                                    });
+                                    throw error;
+                                }
+                                finally {
+                                    span.end();
+                                }
+                            })),
+                        complete: resource.complete,
+                    }), resource.config, async (uri, variables, extra) => tracer.startActiveSpan(`mcp.resource.templated.${resource.name}`, async (span) => {
+                        span.setAttribute('mcp.resource.uri', uri.toString());
+                        span.setAttribute('mcp.resource.variables', JSON.stringify(variables));
+                        span.setAttribute('mcp.resource.extra', JSON.stringify(extra));
+                        try {
+                            const result = await resource.read(uri, variables, extra);
+                            span.setStatus({ code: SpanStatusCode.OK });
+                            return result;
+                        }
+                        catch (error) {
+                            log.error('Error invoking resource:', error);
+                            span.recordException(error);
+                            span.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: error.message,
+                            });
+                            throw error;
+                        }
+                        finally {
+                            span.end();
+                        }
+                    }));
+                    break;
+                }
+                default: {
+                    // @ts-expect-error exhaustive check
+                    throw new Error(`Unknown resource type: ${resource.type}`);
+                }
             }
-        }));
+        }
     }
-    additionalSetup?.({ context, server });
+    additionalSetup?.({ context, server, featureFlags });
     return { server };
 };

package/dist/stdio.d.ts

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

package/dist/stdio.js

@@ -2,7 +2,7 @@
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { mcpServerFactory } from './mcpServer.js';
 import { registerExitHandlers } from './registerExitHandlers.js';
-export const stdioServerFactory = async ({ name, version, context, apiFactories, promptFactories = [], additionalSetup, cleanupFn, }) => {
+export const stdioServerFactory = async ({ name, version, context, apiFactories, promptFactories, resourceFactories, additionalSetup, cleanupFn, }) => {
     try {
         console.error('Starting default (STDIO) server...');
         const transport = new StdioServerTransport();
@@ -12,6 +12,7 @@ export const stdioServerFactory = async ({ name, version, context, apiFactories,
             context,
             apiFactories,
             promptFactories,
+            resourceFactories,
             additionalSetup,
         });
         await server.connect(transport);

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import { z } from 'zod';
 import type { ZodRawShape, ZodTypeAny } from 'zod';
 import type { ToolAnnotations, GetPromptResult } from '@modelcontextprotocol/sdk/types.js';
 import { Router } from 'express';
+import { CompleteResourceTemplateCallback, ListResourcesCallback, ReadResourceCallback, ReadResourceTemplateCallback, ResourceMetadata } from '@modelcontextprotocol/sdk/server/mcp.js';
 export type ToolConfig<InputArgs extends ZodRawShape, OutputArgs extends ZodRawShape> = {
     title?: string;
     description?: string;
@@ -18,7 +19,7 @@ export interface ApiDefinition<InputArgs extends ZodRawShape, OutputArgs extends
     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) => ApiDefinition<Input, Output, RestOutput>;
+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>];
 export type PromptConfig<InputArgs extends ZodRawShape> = {
     title?: string;
@@ -28,6 +29,44 @@ export type PromptConfig<InputArgs extends ZodRawShape> = {
 export interface PromptDefinition<InputArgs extends ZodRawShape> {
     name: string;
     config: PromptConfig<InputArgs>;
+    disabled?: boolean;
     fn: (args: z.objectOutputType<InputArgs, ZodTypeAny>) => Promise<GetPromptResult>;
 }
-export type PromptFactory<Context extends Record<string, unknown>, Input extends ZodRawShape> = (ctx: Context) => PromptDefinition<Input>;
+export type PromptFactory<Context extends Record<string, unknown>, Input extends ZodRawShape> = (ctx: Context, featureFlags: McpFeatureFlags) => PromptDefinition<Input>;
+export interface TemplatedResourceDefinition {
+    type: 'templated';
+    name: string;
+    uriTemplate: string;
+    list?: ListResourcesCallback;
+    complete?: {
+        [variable: string]: CompleteResourceTemplateCallback;
+    };
+    config: ResourceMetadata;
+    disabled?: boolean;
+    read: ReadResourceTemplateCallback;
+}
+export interface StaticResourceDefinition {
+    type: 'static';
+    name: string;
+    uri: string;
+    config: ResourceMetadata;
+    disabled?: boolean;
+    read: ReadResourceCallback;
+}
+export type ResourceDefinition = TemplatedResourceDefinition | StaticResourceDefinition;
+export type ResourceFactory<Context extends Record<string, unknown>> = (ctx: Context, featureFlags: McpFeatureFlags) => ResourceDefinition;
+export interface ParsedQs {
+    [key: string]: undefined | string | ParsedQs | (string | ParsedQs)[];
+}
+export interface McpFeatureFlags {
+    prompts?: boolean;
+    enabledPrompts?: Set<string> | null;
+    disabledPrompts?: Set<string> | null;
+    resources?: boolean;
+    enabledResources?: Set<string> | null;
+    disabledResources?: Set<string> | null;
+    tools?: boolean;
+    enabledTools?: Set<string> | null;
+    disabledTools?: Set<string> | null;
+    query?: ParsedQs;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tigerdata/mcp-boilerplate",
-  "version": "0.4.3",
+  "version": "0.6.0",
   "description": "MCP boilerplate code for Node.js",
   "license": "Apache-2.0",
   "author": "TigerData",
@@ -17,6 +17,10 @@
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     },
+    "./eslintPlugin": {
+      "import": "./dist/eslintPlugin.js",
+      "types": "./dist/eslintPlugin.d.ts"
+    },
     "./instrumentation": {
       "import": "./dist/instrumentation.js",
       "types": "./dist/instrumentation.d.ts"
@@ -33,28 +37,28 @@
     "lint:fix": "eslint --fix"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.20.1",
+    "@modelcontextprotocol/sdk": "^1.22.0",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.66.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.207.0",
-    "@opentelemetry/instrumentation-http": "^0.207.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.67.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.208.0",
+    "@opentelemetry/instrumentation-http": "^0.208.0",
     "@opentelemetry/sdk-metrics": "^2.2.0",
-    "@opentelemetry/sdk-node": "^0.207.0",
+    "@opentelemetry/sdk-node": "^0.208.0",
     "@opentelemetry/sdk-trace-node": "^2.2.0",
-    "@opentelemetry/semantic-conventions": "^1.37.0",
+    "@opentelemetry/semantic-conventions": "^1.38.0",
     "express": "^5.1.0",
     "raw-body": "^3.0.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
-    "@eslint/js": "^9.35.0",
-    "@types/express": "^5.0.3",
-    "@types/node": "^22.16.4",
-    "ai": "^5.0.17",
-    "eslint": "^9.35.0",
+    "@eslint/js": "^9.39.1",
+    "@types/express": "^5.0.5",
+    "@types/node": "^22.19.1",
+    "ai": "^5.0.93",
+    "eslint": "^9.39.1",
     "prettier": "^3.6.2",
-    "typescript": "^5.8.3",
-    "typescript-eslint": "^8.43.0"
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.4"
   },
   "publishConfig": {
     "access": "public"