@tigerdata/mcp-boilerplate 1.3.5 → 1.5.0

package/README.md

@@ -10,10 +10,53 @@ npm install @tigerdata/mcp-boilerplate
 
 See [tiger-skills-mcp-server](https://github.com/tigerdata/tiger-skills-mcp-server) for an example MCP server using this boilerplate.
 
+### DNS Rebinding Protection
+
+MCP servers reachable over HTTP can be targeted by [DNS rebinding attacks](https://en.wikipedia.org/wiki/DNS_rebinding), where a malicious website bypasses the browser same-origin policy by pointing a domain at a localhost (or otherwise private) address to reach a local server. The MCP SDK guards against this by validating the `Host` header against an allow-list.
+
+This check is **most useful for localhost / development servers** without HTTPS or authentication. Hosted servers served on public hostnames generally don't need it (and would reject legitimate traffic unless every allowed hostname is listed), so `httpServerFactory` leaves it **disabled by default** — it is opt-in via the `dnsRebindingProtection` option (scoped to the MCP and API mount paths):
+
+```ts
+import { httpServerFactory } from '@tigerdata/mcp-boilerplate';
+
+await httpServerFactory({
+  name: 'my-server',
+  context,
+  // Omitted (default): disabled, UNLESS MCP_ALLOWED_HOSTS is set — in which
+  //   case protection is enabled using that env var's allow-list.
+  // true: enabled. Uses the MCP_ALLOWED_HOSTS allow-list when set, otherwise
+  //   localhost-only (localhost, 127.0.0.1, [::1]).
+  // string[]: enabled with this exact allow-list (MCP_ALLOWED_HOSTS ignored).
+  //   Hostnames only, without ports; use [::1] for IPv6.
+  // false: disabled. Always wins, even if MCP_ALLOWED_HOSTS is set.
+  dnsRebindingProtection: true,
+});
+```
+
+The `MCP_ALLOWED_HOSTS` environment variable can both enable and configure protection without touching code: set it to a comma-separated list of hostnames (e.g. `localhost,127.0.0.1,[::1]`) and protection turns on using that list. It is consulted whenever `dnsRebindingProtection` is omitted or `true`, but is ignored when an explicit `string[]` is passed (that list wins) or when `false` is passed (protection stays off).
+
+### Binding to a specific network interface
+
+Separately from Host header validation, you can restrict which network interface the server's socket accepts connections on via the `host` option (forwarded to `app.listen()`). Binding to loopback is an OS-level defense that makes the port unreachable from other machines entirely — useful for localhost/development servers:
+
+```ts
+await httpServerFactory({
+  name: 'my-server',
+  context,
+  host: '127.0.0.1', // only accept connections on loopback
+});
+```
+
+Defaults to the `HOST` environment variable, or all available interfaces when unset. This is independent of `dnsRebindingProtection` and is ignored when an external `app` is provided (the caller owns the server lifecycle).
+
 ### Skills
 
 Add skills support to your MCP server by leveraging the skills submodule in `@tigerdata/mcp-boilerplate/skills`. See the [Skills README](./src/skills/README.md) for details.
 
+### Logging
+
+The exported `log` helper writes to the console (via `stderr`, to avoid interfering with the stdio MCP transport) and emits OpenTelemetry log records. The `CONSOLE_LOG_LEVEL` environment variable sets the minimum severity written to the console: `debug` (the default, writes everything), `info`, `warn`, `error`, or `none` to disable console output entirely. OpenTelemetry log records are always emitted regardless of this setting.
+
 ## 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.

package/dist/eslintPlugin.js

@@ -17,7 +17,6 @@ const noOptionalInputSchema = {
         type: 'problem',
         docs: {
             description: 'Disallow .optional(), .default(), and .nullish() on zod schemas in ApiFactory inputSchema',
-            category: 'Best Practices',
             recommended: true,
         },
         messages: {
@@ -91,7 +90,7 @@ const noOptionalInputSchema = {
  * 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 sourceCode = context.sourceCode;
     const ancestors = sourceCode?.getAncestors?.(node) ?? [];
     // Check ancestors for variables that are ApiFactory input schemas
     for (const ancestor of ancestors) {

package/dist/httpServer.d.ts

@@ -28,6 +28,44 @@ interface HttpServerOptions<Context extends Record<string, unknown>> {
      * Path to mount the API router at. Defaults to `"/api"`.
      */
     apiPath?: string;
+    /**
+     * DNS rebinding protection via Host header validation. DNS rebinding
+     * attacks can bypass the browser same-origin policy by pointing a domain at
+     * a localhost address, letting a malicious website reach a local server.
+     * Validating the Host header against an allow-list prevents this. This is
+     * especially important for servers without authorization or HTTPS.
+     *
+     * Protection is **disabled by default** (opt-in). This library is primarily
+     * used by hosted MCP servers served on arbitrary public hostnames, where a
+     * Host allow-list would reject legitimate traffic and the DNS rebinding
+     * threat (a victim's browser reaching an unauthenticated `localhost`
+     * server) does not apply. Localhost/development servers should opt in.
+     *
+     * The `MCP_ALLOWED_HOSTS` environment variable (a comma-separated list of
+     * hostnames) is consulted when this option is omitted or `true`, and is
+     * ignored when an explicit `string[]` or `false` is passed:
+     *
+     * - omitted (default): disabled, unless `MCP_ALLOWED_HOSTS` is set — in
+     *   which case protection is enabled using that allow-list.
+     * - `true`: enabled. Uses the `MCP_ALLOWED_HOSTS` allow-list when set,
+     *   otherwise defaults to localhost (`localhost`, `127.0.0.1`, `[::1]`).
+     * - `string[]`: enabled, validating against exactly these hostnames
+     *   (`MCP_ALLOWED_HOSTS` is ignored). Hostnames only, without ports; for
+     *   IPv6, use bracket notation (e.g. `"[::1]"`).
+     * - `false`: disabled. Always wins, even if `MCP_ALLOWED_HOSTS` is set.
+     */
+    dnsRebindingProtection?: boolean | readonly string[];
+    /**
+     * Network interface (hostname or IP address) to bind the HTTP server to.
+     * Forwarded to `app.listen()`. For example, `"127.0.0.1"` restricts the
+     * server to loopback so it is unreachable from other machines — a strong,
+     * OS-level defense for localhost/development servers.
+     *
+     * Defaults to the `HOST` environment variable, or undefined (bind all
+     * available interfaces) when unset. Ignored when an external `app` is
+     * provided, since the caller owns the server lifecycle.
+     */
+    host?: string;
 }
 interface HttpServerResult {
     app: Router;
@@ -37,5 +75,5 @@ interface HttpServerResult {
     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 declare const httpServerFactory: <Context extends Record<string, unknown>>({ name, version, context, apiFactories, promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful, instructions, app: externalApp, mcpPath, apiPath, dnsRebindingProtection, host, }: HttpServerOptions<Context>) => Promise<HttpServerResult>;
 export {};

package/dist/httpServer.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { hostHeaderValidation } from '@modelcontextprotocol/sdk/server/middleware/hostHeaderValidation.js';
 import bodyParser from 'body-parser';
 import express from 'express';
 import { apiRouterFactory } from './http/api.js';
@@ -7,7 +8,37 @@ 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, app: externalApp, mcpPath = '/mcp', apiPath = '/api', }) => {
+const LOCALHOST_HOSTNAMES = ['localhost', '127.0.0.1', '[::1]'];
+const hostnamesFromEnv = () => {
+    const fromEnv = process.env.MCP_ALLOWED_HOSTS?.split(',')
+        .map((hostname) => hostname.trim())
+        .filter(Boolean);
+    return fromEnv?.length ? fromEnv : null;
+};
+/**
+ * Resolves the Host header allow-list for DNS rebinding protection.
+ * Returns `null` when protection is disabled. Protection is disabled by
+ * default (opt-in); it is enabled by passing `true`, passing an explicit
+ * allow-list, or setting the `MCP_ALLOWED_HOSTS` environment variable.
+ */
+const resolveAllowedHostnames = (dnsRebindingProtection) => {
+    // Explicit custom allow-list.
+    if (Array.isArray(dnsRebindingProtection)) {
+        return [...dnsRebindingProtection];
+    }
+    // Explicit opt-out wins over the env var.
+    if (dnsRebindingProtection === false) {
+        return null;
+    }
+    // Explicitly enabled: use the env-configured allow-list when present,
+    // otherwise fall back to localhost-only.
+    if (dnsRebindingProtection === true) {
+        return hostnamesFromEnv() ?? [...LOCALHOST_HOSTNAMES];
+    }
+    // Disabled by default (omitted), unless the env var opts in.
+    return hostnamesFromEnv();
+};
+export const httpServerFactory = async ({ name, version, context, apiFactories = [], promptFactories, resourceFactories, additionalSetup, cleanupFn, stateful = true, instructions, app: externalApp, mcpPath = '/mcp', apiPath = '/api', dnsRebindingProtection, host = process.env.HOST, }) => {
     const cleanupFns = cleanupFn
         ? [cleanupFn]
         : [];
@@ -22,7 +53,20 @@ export const httpServerFactory = async ({ name, version, context, apiFactories =
         ownApp.enable('trust proxy');
         app = ownApp;
     }
-    const PORT = process.env.PORT || 3001;
+    const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : 3001;
+    if (!Number.isInteger(PORT) || PORT < 0 || PORT > 65535) {
+        throw new Error(`Invalid PORT environment variable: ${process.env.PORT}`);
+    }
+    // DNS rebinding protection: validate the Host header against an allow-list.
+    // Scoped to the MCP and API mount paths so callers providing an external
+    // app keep full control over their other routes.
+    const allowedHostnames = resolveAllowedHostnames(dnsRebindingProtection);
+    const hostValidation = allowedHostnames
+        ? hostHeaderValidation(allowedHostnames)
+        : null;
+    if (allowedHostnames) {
+        log.info('DNS rebinding protection enabled', { allowedHostnames });
+    }
     const inspector = process.env.NODE_ENV !== 'production' ||
         ['1', 'true'].includes(process.env.ENABLE_INSPECTOR ?? '0');
     const [mcpRouter, mcpCleanup] = mcpRouterFactory(context, (context, featureFlags) => mcpServerFactory({
@@ -37,9 +81,15 @@ export const httpServerFactory = async ({ name, version, context, apiFactories =
         instructions,
     }), { name, stateful, inspector });
     cleanupFns.push(mcpCleanup);
+    if (hostValidation) {
+        app.use(mcpPath, hostValidation);
+    }
     app.use(mcpPath, mcpRouter);
     const [apiRouter, apiCleanup] = await apiRouterFactory(context, apiFactories);
     cleanupFns.push(apiCleanup);
+    if (hostValidation) {
+        app.use(apiPath, hostValidation);
+    }
     app.use(apiPath, apiRouter);
     // Error handler
     app.use((err, _req, res, _next) => {
@@ -83,21 +133,26 @@ export const httpServerFactory = async ({ name, version, context, apiFactories =
     // 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) => {
+    const onListen = async (error) => {
         if (error) {
             log.error('Error starting HTTP server:', error);
             exitHandler(1);
         }
         else {
-            log.info(`HTTP Server listening on port ${PORT}`);
+            log.info(`HTTP Server listening on ${host ? `${host}:${PORT}` : `port ${PORT}`}`);
             if (inspector) {
                 log.info(`🌐 MCP inspector running at http://localhost:${PORT}/inspector`);
             }
         }
-    });
-    cleanupFns.push(async () => {
-        await server.close();
-    });
+    };
+    // `app.listen` overloads differ by whether a host is provided; calling with
+    // an explicit `undefined` host binds all interfaces (Node's default).
+    const server = host
+        ? ownApp.listen(PORT, host, onListen)
+        : ownApp.listen(PORT, onListen);
+    cleanupFns.push(() => new Promise((resolve, reject) => {
+        server.close((error) => (error ? reject(error) : resolve()));
+    }));
     return {
         app,
         server,

package/dist/httpServer.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/httpServer.spec.js

@@ -0,0 +1,135 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import express from 'express';
+import { httpServerFactory } from './httpServer.js';
+const startServer = async (dnsRebindingProtection) => {
+    const app = express();
+    await httpServerFactory({
+        name: 'test-server',
+        context: {},
+        app,
+        dnsRebindingProtection,
+    });
+    const server = app.listen(0);
+    await new Promise((resolve) => server.once('listening', resolve));
+    const address = server.address();
+    if (!address || typeof address === 'string') {
+        throw new Error('Expected a TCP server address');
+    }
+    return {
+        port: address.port,
+        cleanup: async () => {
+            await new Promise((resolve, reject) => {
+                server.close((err) => (err ? reject(err) : resolve()));
+            });
+        },
+    };
+};
+const postMcp = (port, host) => {
+    const headers = {
+        'content-type': 'application/json',
+        accept: 'application/json, text/event-stream',
+    };
+    if (host !== undefined) {
+        headers.host = host;
+    }
+    // Use 127.0.0.1 so the request reaches the server, while overriding the
+    // Host header to exercise validation.
+    return fetch(`http://127.0.0.1:${port}/mcp`, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            jsonrpc: '2.0',
+            id: 1,
+            method: 'initialize',
+            params: {
+                protocolVersion: '2025-06-18',
+                capabilities: {},
+                clientInfo: { name: 'test', version: '1.0.0' },
+            },
+        }),
+    });
+};
+describe('httpServerFactory DNS rebinding protection', () => {
+    const started = [];
+    afterEach(async () => {
+        while (started.length > 0) {
+            const s = started.pop();
+            await s?.cleanup();
+        }
+    });
+    const track = (s) => {
+        started.push(s);
+        return s;
+    };
+    it('rejects disallowed Host headers when protection is enabled', async () => {
+        const { port } = track(await startServer(true));
+        const res = await postMcp(port, 'evil.example.com');
+        expect(res.status).toBe(403);
+        const body = (await res.json());
+        expect(body.error?.message).toContain('Invalid Host');
+    });
+    it('is disabled by default when the option is omitted', async () => {
+        const { port } = track(await startServer(undefined));
+        const res = await postMcp(port, 'evil.example.com');
+        expect(res.status).not.toBe(403);
+    });
+    it('allows localhost Host headers when protection is enabled', async () => {
+        const { port } = track(await startServer(true));
+        const res = await postMcp(port, `127.0.0.1:${port}`);
+        // Not a 403 — the request passes Host validation and reaches the MCP
+        // handler (which then negotiates the session normally).
+        expect(res.status).not.toBe(403);
+    });
+    it('allows any Host header when protection is disabled', async () => {
+        const { port } = track(await startServer(false));
+        const res = await postMcp(port, 'evil.example.com');
+        expect(res.status).not.toBe(403);
+    });
+    it('validates against a custom allow-list', async () => {
+        const { port } = track(await startServer(['mcp.internal']));
+        const allowed = await postMcp(port, 'mcp.internal');
+        expect(allowed.status).not.toBe(403);
+        const denied = await postMcp(port, 'localhost');
+        expect(denied.status).toBe(403);
+    });
+});
+describe('httpServerFactory interface binding', () => {
+    it('binds to the requested host', async () => {
+        const prevPort = process.env.PORT;
+        process.env.PORT = '0';
+        try {
+            const { server } = await httpServerFactory({
+                name: 'test-server',
+                context: {},
+                host: '127.0.0.1',
+            });
+            if (!server) {
+                throw new Error('Expected own server');
+            }
+            try {
+                if (!server.listening) {
+                    await new Promise((resolve, reject) => {
+                        server.once('listening', resolve);
+                        server.once('error', reject);
+                    });
+                }
+                const address = server.address();
+                if (!address || typeof address === 'string') {
+                    throw new Error('Expected a TCP server address');
+                }
+                expect(address.address).toBe('127.0.0.1');
+            }
+            finally {
+                await new Promise((resolve, reject) => server.close((err) => (err ? reject(err) : resolve())));
+            }
+        }
+        finally {
+            if (prevPort === undefined) {
+                delete process.env.PORT;
+            }
+            else {
+                process.env.PORT = prevPort;
+            }
+        }
+    });
+});

package/dist/logger.js

@@ -1,12 +1,30 @@
 import { logs, SeverityNumber, } from '@opentelemetry/api-logs';
 const name = process.env.OTEL_SERVICE_NAME || 'mcp-app';
 const logger = logs.getLogger(name);
+const consoleLogLevelSeverity = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    none: 4,
+};
+const configuredConsoleLogLevel = (process.env.CONSOLE_LOG_LEVEL || 'debug').toLowerCase();
+if (!(configuredConsoleLogLevel in consoleLogLevelSeverity)) {
+    throw new Error(`Invalid CONSOLE_LOG_LEVEL '${process.env.CONSOLE_LOG_LEVEL}'. ` +
+        `Expected one of: ${Object.keys(consoleLogLevelSeverity).join(', ')}.`);
+}
+const minConsoleLogSeverity = consoleLogLevelSeverity[configuredConsoleLogLevel];
+const writeToConsole = (level, ...args) => {
+    if (consoleLogLevelSeverity[level] >= minConsoleLogSeverity) {
+        console.error(...args);
+    }
+};
 // Helper functions to replace console.log
 // We use console.error for all levels so that messages are written to stderr
 // and not stdout, which would interfere with the stdio MCP transport.
 export const log = {
     debug: (...args) => {
-        console.error(...args);
+        writeToConsole('debug', ...args);
         const [body, attributes] = args;
         logger.emit({
             severityText: 'DEBUG',
@@ -20,7 +38,7 @@ export const log = {
         });
     },
     info: (...args) => {
-        console.error(...args);
+        writeToConsole('info', ...args);
         const [body, attributes] = args;
         logger.emit({
             severityText: 'INFO',
@@ -34,7 +52,7 @@ export const log = {
         });
     },
     warn: (...args) => {
-        console.error(...args);
+        writeToConsole('warn', ...args);
         const [body, attributes] = args;
         logger.emit({
             severityText: 'WARN',
@@ -48,7 +66,7 @@ export const log = {
         });
     },
     error: (...args) => {
-        console.error(...args);
+        writeToConsole('error', ...args);
         const [body, error, attributes] = args;
         logger.emit({
             severityText: 'ERROR',

package/dist/skills/types.d.ts

@@ -36,6 +36,7 @@ export declare const zGitHubSkillCfg: z.ZodObject<{
     type: z.ZodLiteral<"github">;
     repo: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type GitHubSkillCfg = z.infer<typeof zGitHubSkillCfg>;
 export declare const zGitHubCollectionSkillCfg: z.ZodObject<{
@@ -45,6 +46,7 @@ export declare const zGitHubCollectionSkillCfg: z.ZodObject<{
     type: z.ZodLiteral<"github_collection">;
     repo: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type GitHubCollectionSkillCfg = z.infer<typeof zGitHubCollectionSkillCfg>;
 export declare const zSkillCfg: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -60,6 +62,7 @@ export declare const zSkillCfg: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"github">;
     repo: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     enabled_skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -67,6 +70,7 @@ export declare const zSkillCfg: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"github_collection">;
     repo: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "type">;
 export type SkillCfg = z.infer<typeof zSkillCfg>;
 export declare const zSkillCfgMap: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -82,6 +86,7 @@ export declare const zSkillCfgMap: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUn
     type: z.ZodLiteral<"github">;
     repo: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     enabled_skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
     disabled_skills: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -89,6 +94,7 @@ export declare const zSkillCfgMap: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUn
     type: z.ZodLiteral<"github_collection">;
     repo: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "type">>;
 export type SkillCfgMap = z.infer<typeof zSkillCfgMap>;
 export declare const zSkillMatter: z.ZodObject<{
@@ -109,6 +115,7 @@ export declare const zGitHubSkill: z.ZodObject<{
     type: z.ZodLiteral<"github">;
     repo: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type GitHubSkill = z.infer<typeof zGitHubSkill>;
 export declare const zSkill: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -122,6 +129,7 @@ export declare const zSkill: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"github">;
     repo: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "type">;
 export type Skill = z.infer<typeof zSkill>;
 export declare const zSkillMap: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -135,6 +143,7 @@ export declare const zSkillMap: z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion
     type: z.ZodLiteral<"github">;
     repo: z.ZodString;
     path: z.ZodOptional<z.ZodString>;
+    ref: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "type">>;
 export type SkillMap = z.infer<typeof zSkillMap>;
 export interface SkillsFlags {

package/dist/skills/types.js

@@ -22,11 +22,13 @@ export const zGitHubSkillCfg = z.object({
     type: z.literal('github'),
     repo: z.string(),
     path: z.string().optional(),
+    ref: z.string().optional(),
 });
 export const zGitHubCollectionSkillCfg = zCollectionFlagsCfg.extend({
     type: z.literal('github_collection'),
     repo: z.string(),
     path: z.string().optional(),
+    ref: z.string().optional(),
 });
 export const zSkillCfg = z.discriminatedUnion('type', [
     zLocalSkillCfg,

package/dist/skills/utils.js

@@ -107,7 +107,7 @@ const doLoadSkills = async (octokit) => {
             log.error(`Failed to load skill at path: ${skillPath}`, err);
         }
     };
-    const loadGitHubPath = async (owner, repo, path, flags) => {
+    const loadGitHubPath = async (owner, repo, path, ref, flags) => {
         if (shouldIgnorePath(path, flags))
             return;
         const skillPath = `${path}/SKILL.md`;
@@ -120,6 +120,7 @@ const doLoadSkills = async (octokit) => {
                 owner,
                 repo,
                 path: skillPath,
+                ...(ref ? { ref } : {}),
             });
             if (Array.isArray(skillFileResponse.data) ||
                 skillFileResponse.data.type !== 'file') {
@@ -127,6 +128,7 @@ const doLoadSkills = async (octokit) => {
                     owner,
                     repo,
                     path: skillPath,
+                    ref,
                 });
                 return;
             }
@@ -140,13 +142,14 @@ const doLoadSkills = async (octokit) => {
                 type: 'github',
                 repo: `${owner}/${repo}`,
                 path,
+                ...(ref ? { ref } : {}),
                 name,
                 description,
             });
             skillContentCache.set(`${name}/SKILL.md`, content);
         }
         catch (err) {
-            log.error(`Failed to load skill at GitHub path: ${owner}/${repo}/${skillPath}\n${err.message}`);
+            log.error(`Failed to load skill at GitHub path: ${owner}/${repo}/${skillPath}${ref ? `@${ref}` : ''}\n${err.message}`);
         }
     };
     const promises = [];
@@ -181,7 +184,7 @@ const doLoadSkills = async (octokit) => {
                         log.error(`Invalid GitHub repo format in skill config: ${cfg.repo}`, null, { name, repo: cfg.repo });
                         break;
                     }
-                    promises.push(loadGitHubPath(owner, repo, cfg.path || '.'));
+                    promises.push(loadGitHubPath(owner, repo, cfg.path || '.', cfg.ref));
                     break;
                 }
                 case 'github_collection': {
@@ -201,9 +204,10 @@ const doLoadSkills = async (octokit) => {
                         owner,
                         repo,
                         path: rootPath,
+                        ...(cfg.ref ? { ref: cfg.ref } : {}),
                     });
                     if (!Array.isArray(dirResponse.data)) {
-                        log.error(`Expected github_collection repo path to be a directory`, null, { name, owner, repo, path: cfg.path || '.' });
+                        log.error(`Expected github_collection repo path to be a directory`, null, { name, owner, repo, path: cfg.path || '.', ref: cfg.ref });
                         break;
                     }
                     const flags = parseCollectionFlags(cfg);
@@ -217,7 +221,7 @@ const doLoadSkills = async (octokit) => {
                             });
                             continue;
                         }
-                        promises.push(loadGitHubPath(owner, repo, entry.path, flags));
+                        promises.push(loadGitHubPath(owner, repo, entry.path, cfg.ref, flags));
                     }
                     break;
                 }
@@ -385,6 +389,7 @@ const getSkillContent = async ({ skill, path: targetPath, octokit, }) => {
                 owner,
                 repo,
                 path,
+                ...(skill.ref ? { ref: skill.ref } : {}),
             });
             if (Array.isArray(response.data)) {
                 // Directory listing

package/dist/testSetup.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/testSetup.js

@@ -0,0 +1,14 @@
+// Test preload (configured via bunfig.toml) that silences console output so
+// successful `bun test` / `bun check` runs stay quiet. Our logger and some
+// dependencies write directly to the console, which would otherwise flood the
+// output with logs. Set VERBOSE_TESTS=1 to keep the original console behavior
+// when debugging.
+if (!process.env.VERBOSE_TESTS) {
+    const noop = () => { };
+    console.log = noop;
+    console.info = noop;
+    console.debug = noop;
+    console.warn = noop;
+    console.error = noop;
+}
+export {};

package/dist/tracing.d.ts

@@ -1,4 +1,6 @@
 import { type Span, type Tracer } from '@opentelemetry/api';
-import type { GenerateTextResult, ModelMessage, ToolSet } from 'ai';
+import type { generateText, ModelMessage } from 'ai';
+type AnyGenerateTextResult = Awaited<ReturnType<typeof generateText>>;
 export declare const withSpan: <T>(tracer: Tracer, name: string, fn: (span: Span) => Promise<T>) => Promise<T>;
-export declare const addAiResultToSpan: (span: Span, aiResult: GenerateTextResult<ToolSet, unknown>, inputMessages: ModelMessage[]) => void;
+export declare const addAiResultToSpan: (span: Span, aiResult: AnyGenerateTextResult, inputMessages: ModelMessage[]) => void;
+export {};

package/dist/tracing.js

@@ -20,7 +20,12 @@ export const withSpan = async (tracer, name, fn) => {
     });
 };
 const getToolContent = (content) => {
-    const { type, value } = content.output;
+    const { output } = content;
+    // The `execution-denied` output variant carries no `value` field.
+    if (!('value' in output)) {
+        return output;
+    }
+    const { type, value } = output;
     if (type === 'json' && value) {
         if (typeof value === 'object' && 'structuredContent' in value) {
             return value.structuredContent;
@@ -33,7 +38,7 @@ const getToolContent = (content) => {
     else if (value) {
         return value;
     }
-    return content.output;
+    return output;
 };
 const annotateModelMessage = (m, i) => {
     const msg = {
@@ -43,9 +48,13 @@ const annotateModelMessage = (m, i) => {
     };
     if (m.role === 'tool' && Array.isArray(m.content)) {
         const [c] = m.content;
-        msg.id = c.toolCallId;
-        msg.name = c.toolName;
-        msg.content = getToolContent(c);
+        // A tool message's content may also include tool-approval responses,
+        // which have no tool result to annotate.
+        if (c?.type === 'tool-result') {
+            msg.id = c.toolCallId;
+            msg.name = c.toolName;
+            msg.content = getToolContent(c);
+        }
     }
     return msg;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tigerdata/mcp-boilerplate",
-  "version": "1.3.5",
+  "version": "1.5.0",
   "description": "MCP boilerplate code for Node.js",
   "license": "Apache-2.0",
   "author": "TigerData",
@@ -38,24 +38,26 @@
     "prepublishOnly": "tsc",
     "watch": "tsc --watch",
     "lint": "./bun x @biomejs/biome check",
-    "test": "./bun test ./src"
+    "test": "./bun test ./src",
+    "check": "tsc --noEmit && ./bun --silent lint --write && ./bun --silent run test --only-failures",
+    "release": "bump-release"
   },
   "dependencies": {
-    "@mcp-use/inspector": "^0.24.5",
-    "@modelcontextprotocol/sdk": "^1.27.1",
-    "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
-    "@opentelemetry/exporter-trace-otlp-grpc": "^0.213.0",
-    "@opentelemetry/instrumentation-http": "^0.213.0",
-    "@opentelemetry/sdk-metrics": "^2.6.0",
-    "@opentelemetry/sdk-node": "^0.213.0",
-    "@opentelemetry/sdk-trace-node": "^2.6.0",
-    "@opentelemetry/semantic-conventions": "^1.40.0",
-    "@toon-format/toon": "^2.1.0",
+    "@mcp-use/inspector": "^10.0.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.77.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.219.0",
+    "@opentelemetry/instrumentation-http": "^0.219.0",
+    "@opentelemetry/sdk-metrics": "^2.8.0",
+    "@opentelemetry/sdk-node": "^0.219.0",
+    "@opentelemetry/sdk-trace-node": "^2.8.0",
+    "@opentelemetry/semantic-conventions": "^1.41.1",
+    "@toon-format/toon": "^2.3.0",
     "express": "^5.2.1",
     "gray-matter": "^4.0.3",
     "raw-body": "^3.0.2",
-    "yaml": "^2.8.2"
+    "yaml": "^2.9.0"
   },
   "peerDependencies": {
     "migrate": "^2.1.0",
@@ -71,18 +73,19 @@
     }
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.8",
-    "migrate": "^2.1.0",
-    "pg": "^8.16.3",
-    "zod": "^4.3.6",
+    "@biomejs/biome": "^2.5.1",
     "@octokit/rest": "^22.0.1",
-    "@types/bun": "^1.3.10",
+    "@tigerdata/bump-release": "^0.1.2",
+    "@types/bun": "^1.3.14",
     "@types/express": "^5.0.6",
-    "@types/node": "^22.19.15",
-    "@typescript-eslint/typescript-estree": "^8.57.1",
-    "ai": "^5.0.155",
-    "eslint": "^9.39.4",
-    "typescript": "^5.9.3"
+    "@types/node": "^24.13.2",
+    "@typescript-eslint/typescript-estree": "^8.62.0",
+    "ai": "^7.0.2",
+    "eslint": "^10.5.0",
+    "migrate": "^2.1.0",
+    "pg": "^8.22.0",
+    "typescript": "^6.0.3",
+    "zod": "^4.3.6"
   },
   "publishConfig": {
     "access": "public"