opentel-mcp 0.1.0 → 0.1.1

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,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -15,13 +15,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",

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,
   };
 }