@tigerdata/mcp-boilerplate 0.1.0

package/LICENSE

@@ -0,0 +1,177 @@
+
+                             Apache License
+                       Version 2.0, January 2004
+                    http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+  "License" shall mean the terms and conditions for use, reproduction,
+  and distribution as defined by Sections 1 through 9 of this document.
+
+  "Licensor" shall mean the copyright owner or entity authorized by
+  the copyright owner that is granting the License.
+
+  "Legal Entity" shall mean the union of the acting entity and all
+  other entities that control, are controlled by, or are under common
+  control with that entity. For the purposes of this definition,
+  "control" means (i) the power, direct or indirect, to cause the
+  direction or management of such entity, whether by contract or
+  otherwise, or (ii) ownership of fifty percent (50%) or more of the
+  outstanding shares, or (iii) beneficial ownership of such entity.
+
+  "You" (or "Your") shall mean an individual or Legal Entity
+  exercising permissions granted by this License.
+
+  "Source" form shall mean the preferred form for making modifications,
+  including but not limited to software source code, documentation
+  source, and configuration files.
+
+  "Object" form shall mean any form resulting from mechanical
+  transformation or translation of a Source form, including but
+  not limited to compiled object code, generated documentation,
+  and conversions to other media types.
+
+  "Work" shall mean the work of authorship, whether in Source or
+  Object form, made available under the License, as indicated by a
+  copyright notice that is included in or attached to the work
+  (an example is provided in the Appendix below).
+
+  "Derivative Works" shall mean any work, whether in Source or Object
+  form, that is based on (or derived from) the Work and for which the
+  editorial revisions, annotations, elaborations, or other modifications
+  represent, as a whole, an original work of authorship. For the purposes
+  of this License, Derivative Works shall not include works that remain
+  separable from, or merely link (or bind by name) to the interfaces of,
+  the Work and Derivative Works thereof.
+
+  "Contribution" shall mean any work of authorship, including
+  the original version of the Work and any modifications or additions
+  to that Work or Derivative Works thereof, that is intentionally
+  submitted to Licensor for inclusion in the Work by the copyright owner
+  or by an individual or Legal Entity authorized to submit on behalf of
+  the copyright owner. For the purposes of this definition, "submitted"
+  means any form of electronic, verbal, or written communication sent
+  to the Licensor or its representatives, including but not limited to
+  communication on electronic mailing lists, source code control systems,
+  and issue tracking systems that are managed by, or on behalf of, the
+  Licensor for the purpose of discussing and improving the Work, but
+  excluding communication that is conspicuously marked or otherwise
+  designated in writing by the copyright owner as "Not a Contribution."
+
+  "Contributor" shall mean Licensor and any individual or Legal Entity
+  on behalf of whom a Contribution has been received by Licensor and
+  subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+  this License, each Contributor hereby grants to You a perpetual,
+  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+  copyright license to reproduce, prepare Derivative Works of,
+  publicly display, publicly perform, sublicense, and distribute the
+  Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+  this License, each Contributor hereby grants to You a perpetual,
+  worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+  (except as stated in this section) patent license to make, have made,
+  use, offer to sell, sell, import, and otherwise transfer the Work,
+  where such license applies only to those patent claims licensable
+  by such Contributor that are necessarily infringed by their
+  Contribution(s) alone or by combination of their Contribution(s)
+  with the Work to which such Contribution(s) was submitted. If You
+  institute patent litigation against any entity (including a
+  cross-claim or counterclaim in a lawsuit) alleging that the Work
+  or a Contribution incorporated within the Work constitutes direct
+  or contributory patent infringement, then any patent licenses
+  granted to You under this License for that Work shall terminate
+  as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+  Work or Derivative Works thereof in any medium, with or without
+  modifications, and in Source or Object form, provided that You
+  meet the following conditions:
+
+  (a) You must give any other recipients of the Work or
+      Derivative Works a copy of this License; and
+
+  (b) You must cause any modified files to carry prominent notices
+      stating that You changed the files; and
+
+  (c) You must retain, in the Source form of any Derivative Works
+      that You distribute, all copyright, patent, trademark, and
+      attribution notices from the Source form of the Work,
+      excluding those notices that do not pertain to any part of
+      the Derivative Works; and
+
+  (d) If the Work includes a "NOTICE" text file as part of its
+      distribution, then any Derivative Works that You distribute must
+      include a readable copy of the attribution notices contained
+      within such NOTICE file, excluding those notices that do not
+      pertain to any part of the Derivative Works, in at least one
+      of the following places: within a NOTICE text file distributed
+      as part of the Derivative Works; within the Source form or
+      documentation, if provided along with the Derivative Works; or,
+      within a display generated by the Derivative Works, if and
+      wherever such third-party notices normally appear. The contents
+      of the NOTICE file are for informational purposes only and
+      do not modify the License. You may add Your own attribution
+      notices within Derivative Works that You distribute, alongside
+      or as an addendum to the NOTICE text from the Work, provided
+      that such additional attribution notices cannot be construed
+      as modifying the License.
+
+  You may add Your own copyright statement to Your modifications and
+  may provide additional or different license terms and conditions
+  for use, reproduction, or distribution of Your modifications, or
+  for any such Derivative Works as a whole, provided Your use,
+  reproduction, and distribution of the Work otherwise complies with
+  the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+  any Contribution intentionally submitted for inclusion in the Work
+  by You to the Licensor shall be under the terms and conditions of
+  this License, without any additional terms or conditions.
+  Notwithstanding the above, nothing herein shall supersede or modify
+  the terms of any separate license agreement you may have executed
+  with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+  names, trademarks, service marks, or product names of the Licensor,
+  except as required for reasonable and customary use in describing the
+  origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+  agreed to in writing, Licensor provides the Work (and each
+  Contributor provides its Contributions) on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+  implied, including, without limitation, any warranties or conditions
+  of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+  PARTICULAR PURPOSE. You are solely responsible for determining the
+  appropriateness of using or redistributing the Work and assume any
+  risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+  whether in tort (including negligence), contract, or otherwise,
+  unless required by applicable law (such as deliberate and grossly
+  negligent acts) or agreed to in writing, shall any Contributor be
+  liable to You for damages, including any direct, indirect, special,
+  incidental, or consequential damages of any character arising as a
+  result of this License or out of the use or inability to use the
+  Work (including but not limited to damages for loss of goodwill,
+  work stoppage, computer failure or malfunction, or any and all
+  other commercial damages or losses), even if such Contributor
+  has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+  the Work or Derivative Works thereof, You may choose to offer,
+  and charge a fee for, acceptance of support, warranty, indemnity,
+  or other liability obligations and/or rights consistent with this
+  License. However, in accepting such obligations, You may act only
+  on Your own behalf and on Your sole responsibility, not on behalf
+  of any other Contributor, and only if You agree to indemnify,
+  defend, and hold each Contributor harmless for any liability
+  incurred by, or claims asserted against, such Contributor by reason
+  of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/README.md

@@ -0,0 +1,56 @@
+# MCP Boilerplate for Node.js
+
+This provides some common code for creating a [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP) server in Node.js.
+
+## Setup
+
+1. Clone the repository:
+   ```bash
+   git clone <repository-url>
+   cd mcp-boilerplate-node
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+## Development
+
+### Build
+
+To build the TypeScript project:
+
+```bash
+npm run build
+```
+
+This compiles the TypeScript files from `src/` to JavaScript in `dist/`.
+
+### Watch Mode
+
+To run TypeScript compilation in watch mode (rebuilds on file changes):
+
+```bash
+npm run watch
+```
+
+### Linting
+
+This project uses ESLint for code linting with TypeScript support.
+
+To run the linter:
+
+```bash
+npm run lint
+```
+
+To automatically fix linting issues where possible:
+
+```bash
+npm run lint:fix
+```
+
+### Continuous Integration
+
+The project includes GitHub Actions that automatically run linting checks on all pushes and pull requests to ensure code quality standards are maintained.

package/dist/StatusError.js

@@ -0,0 +1,7 @@
+export class StatusError extends Error {
+    status;
+    constructor(message, status = 500) {
+        super(message);
+        this.status = status;
+    }
+}

package/dist/cliEntrypoint.js

@@ -0,0 +1,42 @@
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export async function cliEntrypoint(stdioEntrypoint, httpEntrypoint, instrumentation = join(__dirname, './instrumentation.js')) {
+    // Parse command line arguments first
+    const args = process.argv.slice(2);
+    const scriptName = args[0] || 'stdio';
+    try {
+        // Dynamically import only the requested module to prevent all modules from initializing
+        switch (scriptName) {
+            case 'stdio': {
+                // Import and run the stdio server
+                await import(stdioEntrypoint);
+                break;
+            }
+            case 'http': {
+                let cleanup;
+                if (args.includes('--instrument') ||
+                    process.env.INSTRUMENT === 'true') {
+                    ({ cleanup } = await import(instrumentation));
+                }
+                // Import and run the HTTP server
+                const { registerCleanupFn } = await import(httpEntrypoint);
+                if (cleanup && registerCleanupFn) {
+                    registerCleanupFn(cleanup);
+                }
+                break;
+            }
+            default: {
+                console.error(`Unknown script: ${scriptName}`);
+                console.log('Available scripts:');
+                console.log('- stdio');
+                console.log('- http');
+                process.exit(1);
+            }
+        }
+    }
+    catch (error) {
+        console.error('Error running script:', error);
+        process.exit(1);
+    }
+}

package/dist/http/api.js

@@ -0,0 +1,39 @@
+/**
+ * REST API alternative to MCP for direct use of the same tools.
+ */
+import { Router } from 'express';
+import bodyParser from 'body-parser';
+import { z } from 'zod';
+export const apiRouterFactory = (context, apiFactories) => {
+    const router = Router();
+    router.use(bodyParser.json());
+    for (const factory of apiFactories) {
+        const tool = factory(context);
+        if (!tool.method || !tool.route)
+            continue;
+        router[tool.method](tool.route, async (req, res) => {
+            const Input = z.object(tool.config.inputSchema);
+            const input = {
+                ...req.params,
+                ...req.query,
+                ...req.body,
+            };
+            let parsedInput;
+            try {
+                parsedInput = Input.parse(input);
+            }
+            catch (error) {
+                res
+                    .status(400)
+                    .json({
+                    error: 'zod validation failure',
+                    issues: error.issues,
+                });
+                return;
+            }
+            const result = await tool.fn(parsedInput);
+            res.json(tool.pickResult ? tool.pickResult(result) : result);
+        });
+    }
+    return [router, () => { }];
+};

package/dist/http/mcp.js

@@ -0,0 +1,153 @@
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { Router } from 'express';
+import { randomUUID } from 'node:crypto';
+import getRawBody from 'raw-body';
+import { log } from '../logger.js';
+export const mcpRouterFactory = (context, createServer, stateful = true) => {
+    const router = Router();
+    const transports = new Map();
+    const handleStatelessRequest = async (req, res) => {
+        const { server } = createServer(context);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        res.on('close', () => {
+            transport.close();
+            server.close();
+        });
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    };
+    const handleStatefulRequest = async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        let transport;
+        let body = req.body;
+        if (sessionId) {
+            if (!transports.has(sessionId)) {
+                res.status(404).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32000,
+                        message: 'Not Found: No session found for that ID',
+                    },
+                    id: sessionId,
+                });
+                return;
+            }
+            transport = transports.get(sessionId);
+        }
+        else {
+            if (!body) {
+                body = await getRawBody(req, {
+                    limit: '4mb',
+                    encoding: 'utf-8',
+                });
+                body = JSON.parse(body.toString());
+            }
+            if (!isInitializeRequest(body)) {
+                res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32000,
+                        message: 'Invalid request: Missing session ID',
+                    },
+                    id: null,
+                });
+                return;
+            }
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sessionId) => {
+                    log.info(`Session initialized with ID: ${sessionId}`);
+                    transports.set(sessionId, transport);
+                },
+                onsessionclosed: (sessionId) => {
+                    if (sessionId && transports.has(sessionId)) {
+                        log.info(`Transport closed for session ${sessionId}, removing from transports map`);
+                        transports.delete(sessionId);
+                    }
+                },
+            });
+            const { server } = createServer(context);
+            await server.connect(transport);
+        }
+        await transport.handleRequest(req, res, body);
+    };
+    router.post('/', async (req, res) => {
+        try {
+            await (stateful
+                ? handleStatefulRequest(req, res)
+                : handleStatelessRequest(req, res));
+        }
+        catch (error) {
+            log.error('Error handling MCP request:', error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32603,
+                        message: 'Internal server error',
+                    },
+                    id: null,
+                });
+            }
+        }
+    });
+    // Reusable handler for GET and DELETE requests
+    const handleSessionRequest = async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (!stateful) {
+            res.status(405).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Method not allowed."
+                },
+                id: null
+            });
+            return;
+        }
+        if (!sessionId) {
+            res.status(400).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32000,
+                    message: 'Invalid request: Missing session ID',
+                },
+                id: null,
+            });
+            return;
+        }
+        if (!transports.get(sessionId)) {
+            res.status(404).json({
+                jsonrpc: '2.0',
+                error: {
+                    code: -32000,
+                    message: 'Not Found: No session found for that ID',
+                },
+                id: sessionId,
+            });
+            return;
+        }
+        await transports.get(sessionId).handleRequest(req, res);
+    };
+    // Handle GET requests for server-to-client notifications via SSE
+    router.get('/', handleSessionRequest);
+    // Handle DELETE requests for session termination
+    router.delete('/', handleSessionRequest);
+    const cleanup = async () => {
+        // Close all active transports to properly clean up resources
+        for (const sessionId in transports) {
+            try {
+                log.info(`Closing transport for session ${sessionId}`);
+                await transports.get(sessionId).close();
+                transports.delete(sessionId);
+            }
+            catch (error) {
+                log.error(`Error closing transport for session ${sessionId}:`, error);
+            }
+        }
+    };
+    return [router, cleanup];
+};

package/dist/httpServer.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import express from 'express';
+import { mcpRouterFactory } from './http/mcp.js';
+import { apiRouterFactory } from './http/api.js';
+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, }) => {
+    const cleanupFns = cleanupFn
+        ? [cleanupFn]
+        : [];
+    const exitHandler = registerExitHandlers(cleanupFns);
+    log.info('Starting HTTP server...');
+    const app = express();
+    const [mcpRouter, mcpCleanup] = mcpRouterFactory(context, () => mcpServerFactory({
+        name,
+        version,
+        context,
+        apiFactories,
+        promptFactories,
+        additionalSetup,
+    }), stateful);
+    cleanupFns.push(mcpCleanup);
+    app.use('/mcp', mcpRouter);
+    const [apiRouter, apiCleanup] = apiRouterFactory(context, apiFactories);
+    cleanupFns.push(apiCleanup);
+    app.use('/api', apiRouter);
+    // Error handler
+    app.use(function (err, req, res, _next) {
+        if (err instanceof StatusError && err.status < 500) {
+            log.info('HTTP error response', {
+                message: err.message,
+                status: err.status,
+            });
+        }
+        else {
+            log.error('Unexpected HTTP handler error', err);
+        }
+        res
+            .status(err instanceof StatusError ? err.status : 500)
+            .json({ error: err.message });
+    });
+    // Start the server
+    const PORT = process.env.PORT || 3001;
+    const server = app.listen(PORT, (error) => {
+        if (error) {
+            log.error('Error starting HTTP server:', error);
+            exitHandler(1);
+        }
+        else {
+            log.info(`HTTP Server listening on port ${PORT}`);
+        }
+    });
+    cleanupFns.push(async () => {
+        await server.close();
+    });
+    return {
+        app,
+        server,
+        apiRouter,
+        mcpRouter,
+        registerCleanupFn: (fn) => {
+            cleanupFns.push(fn);
+        },
+    };
+};

package/dist/instrumentation.js

@@ -0,0 +1,58 @@
+import { NodeSDK } from '@opentelemetry/sdk-node';
+import { resourceFromAttributes } from '@opentelemetry/resources';
+import { OTLPTraceExporter as GrpcTraceExporter } from '@opentelemetry/exporter-trace-otlp-grpc';
+import { OTLPTraceExporter as HttpTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
+import { getNodeAutoInstrumentations } from '@opentelemetry/auto-instrumentations-node';
+import { BatchSpanProcessor, } from '@opentelemetry/sdk-trace-base';
+import { BatchLogRecordProcessor, } from '@opentelemetry/sdk-logs';
+import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-http';
+import { log } from './logger.js';
+const spanProcessors = [];
+const logRecordProcessors = [];
+if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
+    spanProcessors.push(new BatchSpanProcessor(new GrpcTraceExporter()));
+}
+if (process.env.JAEGER_TRACES_ENDPOINT) {
+    spanProcessors.push(new BatchSpanProcessor(new GrpcTraceExporter({
+        url: process.env.JAEGER_TRACES_ENDPOINT,
+    })));
+}
+if (process.env.LOGFIRE_TRACES_ENDPOINT) {
+    spanProcessors.push(new BatchSpanProcessor(new HttpTraceExporter({
+        url: process.env.LOGFIRE_TRACES_ENDPOINT,
+        headers: process.env.LOGFIRE_TOKEN
+            ? { Authorization: `Bearer ${process.env.LOGFIRE_TOKEN}` }
+            : {},
+    })));
+}
+if (process.env.LOGFIRE_LOGS_ENDPOINT) {
+    logRecordProcessors.push(new BatchLogRecordProcessor(new OTLPLogExporter({
+        url: process.env.LOGFIRE_LOGS_ENDPOINT,
+        headers: process.env.LOGFIRE_TOKEN
+            ? { Authorization: `Bearer ${process.env.LOGFIRE_TOKEN}` }
+            : {},
+    })));
+}
+export const sdk = new NodeSDK({
+    instrumentations: [getNodeAutoInstrumentations()],
+    spanProcessors,
+    logRecordProcessors,
+    resource: resourceFromAttributes({
+        'deployment.environment.name': process.env.LOGFIRE_ENVIRONMENT || process.env.NODE_ENV || 'development',
+        'service.instance.id': process.env.HOSTNAME,
+    }),
+});
+// Initialize the SDK and register with the OpenTelemetry API
+sdk.start();
+log.info('OpenTelemetry initialized');
+export const cleanup = async () => {
+    try {
+        await Promise.all(spanProcessors.map((sp) => sp.shutdown()));
+        await Promise.all(logRecordProcessors.map((lp) => lp.shutdown()));
+        await sdk.shutdown();
+        log.info('OpenTelemetry terminated');
+    }
+    catch (error) {
+        log.error('Error terminating OpenTelemetry', error);
+    }
+};

package/dist/logger.js

@@ -0,0 +1,67 @@
+import { logs, SeverityNumber } from '@opentelemetry/api-logs';
+const name = process.env.OTEL_SERVICE_NAME || 'mcp-app';
+const logger = logs.getLogger(name);
+// Helper functions to replace console.log
+export const log = {
+    debug: (...args) => {
+        console.debug(...args);
+        const [body, attributes] = args;
+        logger.emit({
+            severityText: 'DEBUG',
+            severityNumber: SeverityNumber.DEBUG,
+            body,
+            attributes: {
+                'log.level': 'debug',
+                'service.name': name,
+                ...attributes,
+            },
+        });
+    },
+    info: (...args) => {
+        console.info(...args);
+        const [body, attributes] = args;
+        logger.emit({
+            severityText: 'INFO',
+            severityNumber: SeverityNumber.INFO,
+            body,
+            attributes: {
+                'log.level': 'info',
+                'service.name': name,
+                ...attributes,
+            },
+        });
+    },
+    warn: (...args) => {
+        console.warn(...args);
+        const [body, attributes] = args;
+        logger.emit({
+            severityText: 'WARN',
+            severityNumber: SeverityNumber.WARN,
+            body,
+            attributes: {
+                'log.level': 'warn',
+                'service.name': name,
+                ...attributes,
+            },
+        });
+    },
+    error: (...args) => {
+        console.error(...args);
+        const [body, error, attributes] = args;
+        logger.emit({
+            severityText: 'ERROR',
+            severityNumber: SeverityNumber.ERROR,
+            body,
+            attributes: {
+                'log.level': 'error',
+                'service.name': name,
+                ...(error && {
+                    'error.name': error.name,
+                    'error.message': error.message,
+                    'error.stack': error.stack,
+                }),
+                ...attributes,
+            },
+        });
+    },
+};

package/dist/mcpServer.js

@@ -0,0 +1,104 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SpanStatusCode, trace } 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 server = new McpServer({
+        name,
+        version,
+    }, {
+        capabilities: {
+            tools: {},
+            ...(promptFactories.length ? { prompts: {} } : null),
+        },
+    });
+    for (const factory of apiFactories) {
+        const tool = factory(context);
+        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) => tracer.startActiveSpan(`mcp.tool.${tool.name}`, 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();
+            }
+        }));
+    }
+    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;
+            }
+            finally {
+                span.end();
+            }
+        }));
+    }
+    additionalSetup?.({ context, server });
+    return { server };
+};

package/dist/registerExitHandlers.js

@@ -0,0 +1,26 @@
+import { log } from './logger.js';
+let handlingExit = false;
+export const registerExitHandlers = (cleanupFns) => {
+    const exitHandler = (code = 0) => {
+        if (handlingExit)
+            return;
+        handlingExit = true;
+        log.info('Shutting down server...');
+        Promise.allSettled(cleanupFns.map((fn) => fn())).finally(() => {
+            log.info('Server shutdown complete');
+            process.exit(code);
+        });
+    };
+    // Handle server shutdown
+    process.on('SIGINT', () => {
+        exitHandler();
+    });
+    process.on('SIGTERM', () => {
+        exitHandler();
+    });
+    process.on('uncaughtException', (err) => {
+        log.error('Uncaught Exception:', err);
+        exitHandler(1);
+    });
+    return exitHandler;
+};

package/dist/stdio.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+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, }) => {
+    try {
+        console.error('Starting default (STDIO) server...');
+        const transport = new StdioServerTransport();
+        const { server } = mcpServerFactory({
+            name,
+            version,
+            context,
+            apiFactories,
+            promptFactories,
+            additionalSetup,
+        });
+        await server.connect(transport);
+        // Cleanup on exit
+        registerExitHandlers([
+            async () => {
+                await server.close();
+            },
+            async () => {
+                await cleanupFn?.();
+            },
+        ]);
+    }
+    catch (error) {
+        console.error('Server error:', error);
+        process.exit(1);
+    }
+};

package/dist/tracing.js

@@ -0,0 +1,59 @@
+import { log } from './logger.js';
+export const withSpan = async (tracer, name, fn) => {
+    return tracer.startActiveSpan(name, async (span) => {
+        try {
+            return await fn(span);
+        }
+        catch (error) {
+            log.error(`Error in span ${name}`, error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    });
+};
+const getToolContent = (content) => {
+    const { type, value } = content.output;
+    if (type === 'json' && value) {
+        if (typeof value === 'object' && 'structuredContent' in value) {
+            return value.structuredContent;
+        }
+        else if (typeof value === 'object' && 'content' in value) {
+            return value.content;
+        }
+        return value;
+    }
+    else if (value) {
+        return value;
+    }
+    return content.output;
+};
+const annotateModelMessage = (m, i) => {
+    const msg = {
+        ...m,
+        'event.name': `gen_ai.${m.role}.message`,
+        'gen_ai.message.index': Math.max(0, i - 1),
+    };
+    if (m.role === 'tool' && Array.isArray(m.content)) {
+        const [c] = m.content;
+        msg.id = c.toolCallId;
+        msg.name = c.toolName;
+        msg.content = getToolContent(c);
+    }
+    return msg;
+};
+export const addAiResultToSpan = (span, aiResult, inputMessages) => {
+    span.setAttribute('final_result', aiResult.text);
+    const messages = [...inputMessages, ...aiResult.response.messages].map(annotateModelMessage);
+    span.setAttribute('all_messages_events', JSON.stringify(messages));
+    // This is required for logfire to parse the events properly
+    span.setAttribute('logfire.json_schema', JSON.stringify({
+        type: 'object',
+        properties: { all_messages_events: { type: 'array' } },
+    }));
+    if (aiResult.totalUsage) {
+        span.setAttribute('gen_ai.usage.input_tokens', aiResult.totalUsage.inputTokens || 0);
+        span.setAttribute('gen_ai.usage.output_tokens', aiResult.totalUsage.outputTokens || 0);
+    }
+};

package/dist/types.js

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

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@tigerdata/mcp-boilerplate",
+  "version": "0.1.0",
+  "description": "MCP boilerplate code for Node.js",
+  "license": "UNLICENSED",
+  "author": "TigerData",
+  "homepage": "https://tigerdata.com",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "lint": "eslint",
+    "lint:fix": "eslint --fix"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.15.1",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/auto-instrumentations-node": "^0.62.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.203.0",
+    "@opentelemetry/instrumentation-http": "^0.203.0",
+    "@opentelemetry/sdk-metrics": "^2.0.1",
+    "@opentelemetry/sdk-node": "^0.203.0",
+    "@opentelemetry/sdk-trace-node": "^2.0.1",
+    "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",
+    "prettier": "^3.6.2",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.43.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}