opentel-mcp 0.1.0 → 0.2.0

package/README.md

@@ -5,9 +5,23 @@
 > long they take, and which ones fail — via standard OTel traces.
 
 [![CI](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/opentel-mcp.svg)](https://www.npmjs.com/package/opentel-mcp)
 [![license](https://img.shields.io/npm/l/opentel-mcp.svg)](https://github.com/Thirumalaiboobathi/opentel-mcp/blob/main/LICENSE)
 
-**Status: pre-release. Not yet published to npm.**
+## Status
+
+`0.x` — the [MCP semantic conventions](https://github.com/open-telemetry/semantic-conventions-genai)
+this library implements are Development-stage and may change. Breaking
+attribute changes will land in minor versions until `1.0`.
+
+## Install
+
+```bash
+npm install opentel-mcp @opentelemetry/api
+```
+
+`opentel-mcp` is an ES module. Your project needs `"type": "module"` in
+its package.json, or you must use `.mjs` file extensions.
 
 ## Why
 
@@ -31,7 +45,7 @@ const server = new Server({ name: 'my-server', version: '1.0.0' }, {
 });
 
 instrumentMcpServer(server, {
-  serviceName: 'my-mcp-server',
+  serviceName: 'my-mcp-server', // required because setupNodeSdk is true below
   setupNodeSdk: true,  // dev-friendly stderr output; omit in prod
                         // if you already have OTel configured
 });
@@ -49,7 +63,7 @@ import { instrumentMcpServer } from 'opentel-mcp';
 const server = new McpServer({ name: 'my-server', version: '1.0.0' });
 
 instrumentMcpServer(server, {
-  serviceName: 'my-mcp-server',
+  serviceName: 'my-mcp-server', // required because setupNodeSdk is true below
   setupNodeSdk: true,
 });
 
@@ -101,12 +115,16 @@ expresses success/failure through span status, not a status attribute.
 **One-line (dev):** `setupNodeSdk: true` sets up a NodeTracerProvider
 that prints spans to stderr (safe alongside stdio-transport MCP servers —
 see ADR 003), optionally + an OTLP exporter if `exporterUrl` is provided.
-No separate OTel SDK setup needed — `serviceName` is still required.
+No separate OTel SDK setup needed — `serviceName` is required in this
+mode, since it names the resource of the provider opentel-mcp creates.
 
 **Bring-your-own-SDK (prod):** Omit `setupNodeSdk` (default false).
 opentel-mcp uses whatever tracer provider you've already registered
 via `trace.setGlobalTracerProvider()`. This means it plugs into any
-existing OTel setup without conflict.
+existing OTel setup without conflict. In this mode the host's
+TracerProvider owns the resource, so `serviceName` is not needed and has
+no effect — set `service.name` on the host's Resource instead. Passing
+`serviceName` anyway is harmless but logs a one-time `diag.warn`.
 
 ## Ordering constraint
 

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "opentel-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.js"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    }
   },
   "files": [
     "src",
@@ -15,13 +19,11 @@
   "engines": {
     "node": ">=20"
   },
-  "workspaces": [
-    "examples/hello-server",
-    "examples/hello-mcpserver"
-  ],
   "scripts": {
     "test": "vitest run",
-    "test:watch": "vitest"
+    "test:watch": "vitest",
+    "prepack": "node scripts/strip-workspaces.js",
+    "postpack": "node scripts/restore-workspaces.js"
   },
   "keywords": [
     "mcp",
@@ -48,13 +50,14 @@
     "@opentelemetry/api": "^1.9.0"
   },
   "dependencies": {
-    "@opentelemetry/sdk-trace-node": "^2.9.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
-    "@opentelemetry/resources": "^2.9.0"
+    "@opentelemetry/resources": "^2.9.0",
+    "@opentelemetry/sdk-trace-node": "^2.9.0"
   },
   "devDependencies": {
-    "vitest": "^2.1.8",
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-base": "^2.9.0"
+    "@opentelemetry/sdk-trace-base": "^2.9.0",
+    "typescript": "^7.0.2",
+    "vitest": "^2.1.8"
   }
 }

package/src/config.js

@@ -3,9 +3,15 @@
  * Options parsing and defaults for instrumentMcpServer().
  */
 
+import { diag } from '@opentelemetry/api';
+
 /**
  * @typedef {object} InstrumentOptions
- * @property {string} serviceName - Required. Identifies this server in emitted telemetry.
+ * @property {string} [serviceName] - Names the resource of the NodeTracerProvider this library creates.
+ *   Required (and must be a non-empty string) when `setupNodeSdk` is true. Has no effect when `setupNodeSdk`
+ *   is false or omitted — in that mode, resource attributes (including `service.name`) come from whatever
+ *   TracerProvider the host application has already registered; passing `serviceName` anyway is harmless but
+ *   logs a one-time `diag.warn`.
  * @property {string} [exporterUrl] - OTLP/HTTP traces endpoint (e.g. 'http://localhost:4318/v1/traces').
  *   Only takes effect when `setupNodeSdk` is true.
  * @property {boolean} [enabled=true] - Set to false to disable instrumentation entirely; instrumentMcpServer()
@@ -18,6 +24,17 @@
  *   instrumentMcpServer() from ever overriding a host application's own OpenTelemetry setup.
  */
 
+// Guards the "serviceName has no effect" diagnostic below so it fires once
+// per process rather than once per instrumented server.
+let warnedServiceNameIgnored = false;
+
+// Test-only: lets test/instrument.test.js get a clean slate for the
+// once-per-process warning above regardless of what earlier tests in the
+// same file already triggered. Not part of the public API.
+export function __resetServiceNameWarnedForTests() {
+  warnedServiceNameIgnored = false;
+}
+
 /**
  * Validates and applies defaults to raw instrumentMcpServer() options.
  *
@@ -26,15 +43,29 @@
  */
 export function resolveOptions(options) {
   const opts = options ?? {};
+  const setupNodeSdk = opts.setupNodeSdk ?? false;
+  const hasServiceName = typeof opts.serviceName === 'string' && opts.serviceName.trim() !== '';
+
+  if (setupNodeSdk && !hasServiceName) {
+    throw new Error(
+      'opentel-mcp: options.serviceName is required when setupNodeSdk is true ' +
+        '(it names the resource of the tracer provider this library creates). ' +
+        "It is not needed otherwise — the host application's registered provider owns the resource.",
+    );
+  }
 
-  if (typeof opts.serviceName !== 'string' || opts.serviceName.trim() === '') {
-    throw new Error('opentel-mcp: options.serviceName is required and must be a non-empty string.');
+  if (!setupNodeSdk && hasServiceName && !warnedServiceNameIgnored) {
+    warnedServiceNameIgnored = true;
+    diag.warn(
+      'opentel-mcp: serviceName was provided but setupNodeSdk is false, so it has no effect. ' +
+        'Resource attributes (including service.name) come from the TracerProvider the host application registered.',
+    );
   }
 
   return {
     serviceName: opts.serviceName,
     exporterUrl: opts.exporterUrl,
     enabled: opts.enabled ?? true,
-    setupNodeSdk: opts.setupNodeSdk ?? false,
+    setupNodeSdk,
   };
 }

package/src/index.d.ts

@@ -0,0 +1,97 @@
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Options for {@link instrumentMcpServer}.
+ */
+export interface InstrumentOptions {
+  /**
+   * Names the resource of the `NodeTracerProvider` this library creates.
+   *
+   * Required (and must be a non-empty string) when `setupNodeSdk` is `true` —
+   * omitting it in that mode throws at runtime. Has no effect when
+   * `setupNodeSdk` is `false` or omitted; in that mode, resource attributes
+   * (including `service.name`) come from whatever `TracerProvider` the host
+   * application has already registered, and passing `serviceName` anyway is
+   * harmless but logs a one-time `diag.warn`.
+   */
+  serviceName?: string;
+
+  /**
+   * OTLP/HTTP traces endpoint (e.g. `'http://localhost:4318/v1/traces'`).
+   *
+   * Only takes effect when `setupNodeSdk` is `true`.
+   */
+  exporterUrl?: string;
+
+  /**
+   * Set to `false` to disable instrumentation entirely; {@link instrumentMcpServer}
+   * becomes a no-op.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+
+  /**
+   * When `true`, {@link instrumentMcpServer} creates and registers its own
+   * `NodeTracerProvider` (always exporting to stderr; additionally to
+   * `exporterUrl` via OTLP/HTTP if set).
+   *
+   * When `false` (the default), spans are emitted via whatever OpenTelemetry
+   * `TracerProvider` the host application has already registered globally —
+   * or dropped silently if none has been registered. This default keeps
+   * {@link instrumentMcpServer} from ever overriding a host application's own
+   * OpenTelemetry setup.
+   *
+   * @default false
+   */
+  setupNodeSdk?: boolean;
+}
+
+/**
+ * A high-level McpServer-like object, matched structurally the same way
+ * {@link instrumentMcpServer} itself matches it at runtime (see ADR 001):
+ * an object exposing a `.server` that looks like a low-level `Server` (has
+ * `setRequestHandler`), plus a `.tool` or `.registerTool` method.
+ *
+ * This structural fallback exists because the imported `McpServer` class
+ * has private fields, which makes TypeScript treat assignability to it as
+ * effectively nominal — an `McpServer` instance created by a *different*
+ * resolved copy of `@modelcontextprotocol/sdk` (e.g. a hoisting mismatch in
+ * a monorepo) would otherwise fail the type check even though it works
+ * fine at runtime, since the runtime never uses `instanceof McpServer` in
+ * the first place. This type mirrors the duck-typing the runtime already
+ * performs instead of relying on class identity.
+ */
+export type DuckTypedMcpServer = {
+  server: { setRequestHandler: (...args: any[]) => any };
+  tool?: (...args: any[]) => any;
+  registerTool?: (...args: any[]) => any;
+};
+
+/**
+ * Instruments an MCP server so every tool call emits an OpenTelemetry span.
+ *
+ * Accepts either a low-level `Server` (from
+ * `@modelcontextprotocol/sdk/server/index.js`) or a high-level `McpServer`
+ * (from `@modelcontextprotocol/sdk/server/mcp.js`). Must be called before any
+ * `tools/call` handler is registered — i.e. before any
+ * `server.setRequestHandler(CallToolRequestSchema, ...)` (low-level) or
+ * `.tool()`/`.registerTool()` (McpServer) calls. Idempotent: calling this
+ * more than once — on the same object, or on the outer `McpServer` and its
+ * inner `Server` interchangeably — is a no-op after the first call.
+ *
+ * @param server - The server instance to instrument.
+ * @param options - Instrumentation options.
+ * @returns The same object that was passed in, for chaining. When
+ *   `options.setupNodeSdk` is `true`, the returned object also gets a
+ *   `shutdown()` method that flushes and shuts down the `NodeTracerProvider`
+ *   created for it — call it during your process's own shutdown sequence to
+ *   avoid losing buffered spans. `shutdown` is typed as optional because it
+ *   is only attached at runtime when `setupNodeSdk` is `true`; check for its
+ *   presence before calling.
+ */
+export function instrumentMcpServer<T extends Server | McpServer | DuckTypedMcpServer>(
+  server: T,
+  options?: InstrumentOptions,
+): T & { shutdown?: () => Promise<void> };