opentel-mcp 0.14.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # Changelog
 
+## 0.15.0
+
+"Make it visible" — no instrumentation changes, no `tools/call` hot-path
+changes. Phase 1 (ADR 022, `docs/adr/022-publish-ui.md`): publishes
+`opentel-mcp-ui`, previously a working but `"private": true`, unpublished
+scaffold with zero mentions in this README. See
+[`opentel-mcp-ui`'s own CHANGELOG](https://www.npmjs.com/package/opentel-mcp-ui)
+for what changed in that package. Phase 2 (ADR 023,
+`docs/adr/023-dev-mode-metrics.md`): dev-mode metrics under
+`setupNodeSdk: true` — see "Added" below.
+
+### Added
+
+- README: a "See it locally" section near the top, pointing at
+  `npx opentel-mcp-ui --demo` — this library had no documented way for a
+  new reader to see its own output before installing anything.
+- `setupNodeSdk: true` now also stands up an owned `MeterProvider` (ADR
+  023): a `PeriodicExportingMetricReader` exporting all 12 `mcp.tool.*`/
+  `mcp.tool.loop.*`/`mcp.tool.schema_drift.*` instruments to stderr every
+  5 seconds, via a new `StderrMetricExporter` (compact
+  `name{attrs} = value` lines, never a stdout-writing JSON dump — same
+  ADR 003 reasoning `StderrSpanExporter` already follows). Gated
+  additionally by `enableMetrics` (default `true`, unchanged option).
+  Closes the gap where the documented 30-second quickstart emitted
+  stderr spans but none of its 12 metrics. `setupNodeSdk: false` (the
+  default, and the production posture) is completely unaffected — every
+  new code path is gated behind the same existing `setupNodeSdk === true`
+  check `StderrSpanExporter` already uses.
+  - If a `MeterProvider` is already registered globally when this runs
+    (your own, or anything else's), this is a complete no-op: nothing is
+    overridden, no exception is thrown, and a single `diag.warn` (once
+    per process, not once per `instrumentMcpServer()` call) names the
+    situation. Detected via `@opentelemetry/api`'s own documented
+    `boolean` return from `setGlobalMeterProvider()` — not by inspecting
+    internals. The abandoned candidate provider built before that check
+    is shut down immediately (fire-and-forget), closing a leak where its
+    own periodic reader would otherwise tick forever, unused, in the
+    background.
+  - `server.shutdown()` (already attached under `setupNodeSdk: true`) now
+    also flushes and shuts down this `MeterProvider`, alongside the
+    existing `TracerProvider` shutdown it already performed.
+  - `StderrMetricExporter` only reprints a metric when its value has
+    actually changed since the last export. Every instrument here is
+    CUMULATIVE, so without this a single early tool call would otherwise
+    reprint two unchanged lines every 5 seconds for the rest of the
+    process's life — confirmed empirically before this fix shipped, not
+    assumed.
+
+### Changed
+
+- **`@opentelemetry/sdk-metrics` is now a runtime (`dependencies`, not
+  `devDependencies`) dependency of `opentel-mcp`, installed for every
+  user — including under `setupNodeSdk: false`, which never executes any
+  code from it.** Needed at import time for the feature above; moving it
+  to `dependencies` means `npm install opentel-mcp` always pulls it in,
+  regardless of whether a given deployment ever sets `setupNodeSdk: true`.
+  Adds no new transitive dependency: its own two dependencies
+  (`@opentelemetry/core`, `@opentelemetry/resources`) were already in
+  this package's tree via `@opentelemetry/sdk-trace-node`/the existing
+  `@opentelemetry/resources` dependency. See ADR 023's "Dependency
+  strategy" section for the full reasoning, including why an optional-peer
+  + dynamic-import approach was considered and rejected.
+
+### Fixed
+
+- The example servers (`examples/hello-server`, `examples/hello-mcpserver`)
+  never showed a metrics line in their own READMEs' "What you'll see": a
+  single piped `tools/call` request exits the process before the 5-second
+  export interval. Both now flush once via `process.on('beforeExit', ...)`
+  right before the process would otherwise exit — confirmed
+  `StdioServerTransport` does not call its own `close()`/`onclose` on
+  stdin EOF, so `beforeExit` is the one hook that still allows the async
+  flush to complete first.
+- Documentation only, no code/behavior changes:
+  - README claimed "Four `mcp.tool.*` metrics" in a way that read as the
+    library's total metric count. Corrected: four is this section's own
+    base call/duration metrics; twelve exist in total across cost/token
+    attribution (2), Agent Thrash Detection (5), and schema drift (1),
+    each already documented in their own sections.
+  - README's test count was stale at every point it was checked this
+    release; now 1017 tests, 1013 passing + 4 intentionally skipped.
+  - README's SigNoz metrics-wiring example described
+    `@opentelemetry/sdk-metrics` as a host-app dependency opentel-mcp
+    "doesn't bundle" — true before this release, no longer true now that
+    it's a real dependency (see "Changed" above).
+
+### CI
+
+- `dependency-audit` (`.github/workflows/ci.yml`) no longer audits this
+  monorepo's own shared, hoisted `node_modules` — `npm audit`, even with
+  `--omit=dev` and run from inside `packages/core/`, scans the entire
+  installed tree regardless of cwd or `--workspace` (confirmed
+  empirically), so it was reporting findings from `examples/*`'s real
+  `@modelcontextprotocol/sdk` dependency (express/hono/ajv transitives)
+  as if they were this library's own. Now packs and installs each of
+  `packages/core`/`packages/ui` into its own clean, throwaway project —
+  the exact tree a real `npm install` produces — and audits that instead.
+
 ## 0.14.0
 
 Adds `errorRecording.redactor`: a host-supplied hook for content

package/README.md

@@ -18,6 +18,26 @@ to your tools' code.
 opentel-mcp is the only Node.js MCP instrumentation library that ties
 tool calls to LLM cost.
 
+## See it locally
+
+```bash
+npx opentel-mcp-ui --demo
+```
+
+Opens a dashboard at `http://127.0.0.1:4319` — no MCP server, no
+Prometheus, no Collector to stand up first. It's seeded with realistic
+fixture data showing exactly what this README is about: tool calls that
+returned `isError: true` inside a successful response, rendered as the
+clean spans a standard OTel setup would show, side by side with what
+opentel-mcp actually caught.
+
+<!-- TODO: screenshot/GIF of the dashboard here -->
+
+Drop `--demo` and point your own instrumented server's `exporterUrl` at
+it to see real traffic instead — see
+[`opentel-mcp-ui`'s README](https://www.npmjs.com/package/opentel-mcp-ui)
+for the two-minute walkthrough.
+
 ## The problem
 
 Your AI agent calls 15 MCP tools across 3 servers this turn. One tool
@@ -38,6 +58,15 @@ npm install opentel-mcp @opentelemetry/api
 
 opentel-mcp is an ES module — add `"type": "module"` to package.json.
 
+If you're starting from a blank project to try the quickstart below
+(rather than adding opentel-mcp to an MCP server you already have), you
+also need the MCP SDK and `zod` — the quickstart's own server and tool
+definitions, not opentel-mcp's dependencies:
+
+```bash
+npm install @modelcontextprotocol/sdk zod
+```
+
 ## 30-second quickstart
 
 ```js
@@ -50,7 +79,7 @@ const server = new McpServer({ name: 'my-server', version: '1.0.0' });
 
 // Wraps every tool registered below. Must run BEFORE server.tool() —
 // see "Ordering constraint" below for why.
-instrumentMcpServer(server, {
+const instrumented = instrumentMcpServer(server, {
   serviceName: 'my-mcp-server', // shows up on your traces
   setupNodeSdk: true, // dev mode: prints traces to your terminal
 });
@@ -62,6 +91,17 @@ server.tool('echo', { text: z.string() }, async ({ text }) => ({
 
 const transport = new StdioServerTransport();
 await server.connect(transport);
+
+// Only needed to see metrics (below) immediately when piping ONE request
+// in and exiting right after, like the "See it working" example does —
+// a real, long-running server sees the same lines on their own, every 5
+// seconds, with no extra code.
+let flushed = false;
+process.on('beforeExit', () => {
+  if (flushed) return;
+  flushed = true;
+  instrumented.shutdown();
+});
 ```
 
 That's it. Every tool call now emits a trace. Wire an exporter to see them
@@ -87,6 +127,21 @@ attributes: {
 No dashboard needed — `setupNodeSdk: true`'s dev exporter printed this
 directly. Point it at a real backend later; see "Two modes" below.
 
+**Metrics print too (v0.15.0+)** — within 5 seconds (not the default
+60-second export interval), a compact one-line-per-metric summary follows
+on stderr, reusing the exact `mcp.tool.*` instruments documented in
+"Metrics" below:
+
+```
+[opentel-mcp metrics] mcp.tool.calls{gen_ai.tool.name=echo,mcp.method.name=tools/call} = 1
+[opentel-mcp metrics] mcp.tool.duration{gen_ai.tool.name=echo,mcp.tool.outcome=success} count=1 avg=0.4ms
+```
+
+No extra configuration, no `@opentelemetry/sdk-metrics` setup of your
+own — `setupNodeSdk: true` now does for metrics what it's always done for
+traces. See "Dev-mode metrics" below for exactly what this does and
+doesn't change.
+
 ---
 
 The rest of this README goes deeper: both server APIs, every attribute
@@ -240,7 +295,17 @@ Runnable end-to-end coverage lives in `test/instrument.v2.test.js` and
 
 An MCP tool can fail two ways: it can throw, or it can return
 `isError: true` on an otherwise-successful response (the case from "The
-problem" above). opentel-mcp treats both the same way — span marked
+problem" above) — exactly like the quickstart's `echo` tool, but with
+`isError: true` added and no `throw` involved:
+
+```js
+server.tool('fetch_weather', { city: z.string() }, async ({ city }) => ({
+  isError: true,
+  content: [{ type: 'text', text: `couldn't reach the weather service for ${city}` }],
+}));
+```
+
+opentel-mcp treats both failure shapes the same way — span marked
 `ERROR`, nothing thrown, the result returned to the caller unchanged:
 
 ```
@@ -273,11 +338,17 @@ success/failure through span status, not an attribute. Source of truth:
 
 ### Metrics
 
-Four `mcp.tool.*` metrics via `@opentelemetry/api`'s Metrics API — same
-API-only pattern as tracing (see "Two modes" below): nothing is recorded
-until a `MeterProvider` is registered. Set `enableMetrics: false` to opt
-out even when one is; tracing is unaffected either way. Source of truth:
-`src/metrics.js`.
+The four base `mcp.tool.*` call/duration metrics below, via
+`@opentelemetry/api`'s Metrics API — same API-only pattern as tracing
+(see "Two modes" below): nothing is recorded until a `MeterProvider` is
+registered — **except under `setupNodeSdk: true`, which registers one for
+you (v0.15.0+); see "Dev-mode metrics" below.** Set `enableMetrics: false`
+to opt out even when one is (dev-mode included); tracing is unaffected
+either way. Source of truth: `src/metrics.js`. Twelve metrics exist
+across the library in total — this section's four, plus two cost/token
+metrics ("Cost & Token Attribution" below), five Agent Thrash Detection
+metrics ("Agent Thrash Detection" below), and one schema-drift metric
+("Tool schema drift detection" below).
 
 | Metric | Type | Unit | Attributes | Emitted when |
 |---|---|---|---|---|
@@ -332,12 +403,61 @@ instrumentMcpServer(server, {});
 
 `http://localhost:4318` is SigNoz's default local OTLP/HTTP (OpenTelemetry
 Protocol — the wire format traces/metrics travel over) endpoint; point it
-at your own collector in production. `@opentelemetry/sdk-metrics` and
-`@opentelemetry/exporter-metrics-otlp-http` are host-app dependencies —
-opentel-mcp doesn't bundle them (see `package.json`'s `peerDependencies`).
-`@opentelemetry/sdk-trace-node` and `@opentelemetry/exporter-trace-otlp-http`
-are already runtime dependencies of opentel-mcp itself (its `setupNodeSdk:
-true` dev path uses them), so no extra install is needed for those two.
+at your own collector in production. `@opentelemetry/exporter-metrics-otlp-http`
+is a host-app dependency — opentel-mcp doesn't bundle it. `@opentelemetry/sdk-metrics`,
+`@opentelemetry/sdk-trace-node`, and `@opentelemetry/exporter-trace-otlp-http`
+are already runtime dependencies of opentel-mcp itself (`@opentelemetry/sdk-metrics`
+as of v0.15.0, for the dev-mode metrics path below; the other two for
+`setupNodeSdk: true`'s dev tracing path, same as before), so no extra
+install is needed for those three — only the OTLP metrics exporter above
+needs installing yourself.
+
+#### Dev-mode metrics (v0.15.0+)
+
+`setupNodeSdk: true` now also stands up an owned `MeterProvider` — the
+same dev-friendly, zero-config posture tracing has always had under this
+flag, extended to metrics (ADR 023, `docs/adr/023-dev-mode-metrics.md`).
+This is a dev-mode-only exception to the API-only framing above, the same
+way `StderrSpanExporter` (ADR 003) is a dev-mode-only exception for
+tracing — `setupNodeSdk: false` (the default, and the production posture)
+is completely unaffected; metrics stay exactly as API-only as they are
+today.
+
+What it does, under `setupNodeSdk: true` and `enableMetrics` (default
+`true`, same flag that already opts out of metrics generally):
+
+- Builds a `MeterProvider` with a `PeriodicExportingMetricReader` exporting
+  to stderr every 5 seconds (not the SDK's own 60-second default — a
+  quickstart user making a few tool calls should see output in a few
+  seconds, not up to a minute later), via a small custom exporter
+  (`src/exporters/stderr-metrics.js`) — same "stderr, never stdout"
+  reasoning as `StderrSpanExporter` (ADR 003): a `StdioServerTransport`
+  server's JSON-RPC stream lives on stdout, so diagnostic output of any
+  kind must go to stderr instead.
+- Prints one line per instrument × attribute-set, not a JSON dump:
+  counters as `name{attrs} = <value>`, histograms as
+  `name{attrs} count=<n> avg=<sum/count><unit>` — see the quickstart's
+  "See it working" section above for a real example.
+- Shares the exact same `Resource` (service.name, and the pricing-staleness
+  attribute when applicable) the dev `TracerProvider` already builds, so
+  the two signals can never carry different `service.name` values in dev
+  mode.
+- **If a `MeterProvider` is already registered globally** — your own, or
+  anything else's — this is a complete no-op: nothing is overridden, no
+  exception is thrown, and a single `diag.warn` (once per process) says
+  so. `setupMeter()` immediately afterward continues to use whatever was
+  already registered, exactly as it does today.
+- Extends `server.shutdown()` (already attached under `setupNodeSdk: true`)
+  to also flush and shut down the `MeterProvider` it registered, alongside
+  the existing `TracerProvider` shutdown — call it during your process's
+  shutdown sequence, same as before, to avoid losing buffered metric data.
+
+`@opentelemetry/sdk-metrics` is a real (non-dev) dependency of opentel-mcp
+as of this feature — not an optional peer, not a dynamic import with a
+fallback path. See ADR 023's "Dependency strategy" section for the full
+reasoning: its own transitive dependencies were already in this package's
+tree via `@opentelemetry/resources`/`@opentelemetry/sdk-trace-node`, so
+this adds no new package beyond itself.
 
 #### Using the Prometheus exporter instead of OTLP — `service.name` needs an extra option
 
@@ -2621,7 +2741,7 @@ pragmatic choice rather than a spec-pure one.
   revision 2026-07-28, v0.10.0+; see "MCP v2 support" above for what's
   covered and `docs/known-gaps.md` entries 6 and 8 for what isn't yet)
 - @opentelemetry/api ^1.9.0
-- 948 tests, 944 passing + 4 intentionally skipped (`npm test`) — see `test/`
+- 1017 tests, 1013 passing + 4 intentionally skipped (`npm test`) — see `test/`
 - `npm run typecheck` (`tsc --noEmit`) type-checks the public `.d.ts`
   surface (`src/index.d.ts` and friends) — see CONTRIBUTING.md
 
@@ -2701,6 +2821,17 @@ pragmatic choice rather than a spec-pure one.
   narrower thing still open, tracked in `docs/known-gaps.md` entry 6:
   `thrashSessionState`'s session-awareness memory isn't shared across v2's
   per-request calls yet, only the fallback id itself.
+- v0.15.0: "Make it visible" ✓ — a recent audit found that this library's
+  real depth (12 metrics, two-SDK support, a working local dashboard) was
+  mostly invisible to a first-time user. Two fixes, no instrumentation
+  changes: publishing `opentel-mcp-ui` (ADR 022,
+  `docs/adr/022-publish-ui.md`) — previously a working but unpublished,
+  `"private": true` scaffold, now `npx opentel-mcp-ui --demo`-able from a
+  clean machine — and dev-mode metrics under `setupNodeSdk: true` (ADR
+  023, `docs/adr/023-dev-mode-metrics.md`, see "Dev-mode metrics" above),
+  closing the gap where the documented 30-second quickstart emitted
+  stderr spans but none of the 12 `mcp.tool.*`/`mcp.tool.loop.*`/
+  `mcp.tool.schema_drift.*` metrics it leads with.
 - Future: failure clustering + regression detection; recovery hints;
   root-cause chaining across parent spans; alignment with the OTel GenAI
   SIG's MCP semantic conventions when published

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -69,13 +69,13 @@
   "dependencies": {
     "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
     "@opentelemetry/resources": "^2.9.0",
+    "@opentelemetry/sdk-metrics": "^2.9.0",
     "@opentelemetry/sdk-trace-node": "^2.9.0"
   },
   "devDependencies": {
     "@modelcontextprotocol/server": "^2.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/context-async-hooks": "^2.9.0",
-    "@opentelemetry/sdk-metrics": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",
     "@vitest/coverage-v8": "^2.1.9",
     "js-yaml": "^4.3.1",

package/src/exporters/stderr-metrics.js

@@ -0,0 +1,142 @@
+/**
+ * @module exporters/stderr-metrics
+ * A PushMetricExporter that prints metrics to stderr, in a compact,
+ * one-line-per-instrument format — not @opentelemetry/sdk-metrics' own
+ * ConsoleMetricExporter, which writes via console.dir (stdout) and dumps
+ * each instrument's full internal {descriptor, dataPointType, dataPoints}
+ * shape as unflattened JSON (ADR 023).
+ *
+ * Sibling to ./stderr.js (StderrSpanExporter, ADR 003) — same
+ * stdio-transport-safety reasoning: stdout is reserved for a
+ * StdioServerTransport server's JSON-RPC stream, so diagnostic output of
+ * any OTel signal must go to stderr instead.
+ *
+ * Reads only the attributes the existing 12 instruments — mcp.tool.*
+ * (src/metrics.js), mcp.tool.loop.* (src/thrash/emitter.js), and
+ * mcp.tool.schema_drift.* (src/schema-drift/emitter.js) — already attach.
+ * Adds no new attribute or metric-label surface of its own, so
+ * METRIC_SAFE_ATTRIBUTES governance is unaffected.
+ */
+
+// DataPointType.HISTOGRAM === 0, .SUM === 3 (@opentelemetry/sdk-metrics) —
+// inlined rather than importing the enum, same "avoid a dependency for a
+// couple of integer constants" call stderr.js already makes for
+// ExportResultCode (see that module's own comment).
+const DATA_POINT_TYPE_HISTOGRAM = 0;
+
+/**
+ * Flattens an attribute bag into a stable, sorted-by-key `{k=v,k=v}`
+ * suffix — deterministic across runs (never insertion-order-dependent),
+ * so a human diffing two terminal sessions sees only real differences.
+ *
+ * @param {Record<string, unknown>} attributes
+ * @returns {string}
+ */
+function formatAttributes(attributes) {
+  const keys = Object.keys(attributes).sort();
+  if (keys.length === 0) return '';
+  return `{${keys.map((key) => `${key}=${attributes[key]}`).join(',')}}`;
+}
+
+/**
+ * One entry per data point: a stable identity `key` (which time series
+ * this is — the instrument name plus its exact attribute set) separate
+ * from `line` (the human-readable text) and `signature` (just the
+ * value-bearing part, cheap to compare across export intervals without
+ * re-parsing `line`). Counters/gauges/up-down-counters print their
+ * current value (`= <n>`); histograms print a count + average
+ * (`count=<n> avg=<sum/count><unit>`) rather than a full bucket dump — a
+ * terminal reader wants "how many, roughly how long," not a distribution.
+ *
+ * @param {import('@opentelemetry/sdk-metrics').MetricData} metric
+ * @returns {Array<{ key: string, line: string, signature: string }>}
+ */
+function formatMetric(metric) {
+  const { name, unit } = metric.descriptor;
+  const entries = [];
+
+  for (const dataPoint of metric.dataPoints) {
+    const attrs = formatAttributes(dataPoint.attributes);
+    const key = `${name}${attrs}`;
+
+    if (metric.dataPointType === DATA_POINT_TYPE_HISTOGRAM) {
+      const { count, sum } = dataPoint.value;
+      const avg = count > 0 && typeof sum === 'number' ? (sum / count).toFixed(1) : '0';
+      entries.push({
+        key,
+        line: `[opentel-mcp metrics] ${key} count=${count} avg=${avg}${unit}`,
+        signature: `${count}:${sum}`,
+      });
+    } else {
+      entries.push({
+        key,
+        line: `[opentel-mcp metrics] ${key} = ${dataPoint.value}`,
+        signature: String(dataPoint.value),
+      });
+    }
+  }
+
+  return entries;
+}
+
+export class StderrMetricExporter {
+  constructor() {
+    // Every mcp.tool.* instrument uses CUMULATIVE aggregation temporality
+    // (the SDK's own default — never overridden here): once a tool is
+    // called even once, that (instrument, attribute-set) pair gets a
+    // permanent data point that every FUTURE export() call re-receives,
+    // unchanged, for the rest of the process's life, regardless of
+    // whether any new activity happened in the interval between. Without
+    // this map, a single call early in a long dev session reprints two
+    // identical lines every 5 seconds forever — confirmed empirically,
+    // not assumed. Keyed by formatMetric()'s own `key` (instrument name +
+    // exact attribute set); values are the last-printed `signature`, so a
+    // repeat export() with no real change is detected and skipped without
+    // re-deriving or re-parsing the full line.
+    this._lastSignatures = new Map();
+  }
+
+  /**
+   * @param {import('@opentelemetry/sdk-metrics').ResourceMetrics} metrics
+   * @param {(result: { code: number }) => void} resultCallback
+   */
+  export(metrics, resultCallback) {
+    try {
+      for (const scopeMetrics of metrics.scopeMetrics) {
+        for (const metric of scopeMetrics.metrics) {
+          // Never emit a line for a metric with zero data points yet (no
+          // calls recorded ever) — a dev terminal showing twelve "= 0"
+          // lines every 5 seconds before any tool has even been called
+          // is noise, not signal. formatMetric() already produces zero
+          // entries for such a metric, so this loop is naturally a no-op
+          // for it without any extra check here.
+          for (const { key, line, signature } of formatMetric(metric)) {
+            if (this._lastSignatures.get(key) === signature) continue;
+            console.error(line);
+            // Set only after a successful print, not before — if
+            // console.error somehow throws, this export() call fails
+            // (caught below, reported via resultCallback({ code: 1 })),
+            // and an SDK-level retry should see this as still unprinted
+            // rather than silently marked done.
+            this._lastSignatures.set(key, signature);
+          }
+        }
+      }
+      // 0 === ExportResultCode.SUCCESS (@opentelemetry/core) — see
+      // stderr.js's identical comment for why this is inlined.
+      resultCallback({ code: 0 });
+    } catch {
+      // Never-throw: a malformed metric data point must degrade to a
+      // failed export, never crash the host process the metric came from.
+      resultCallback({ code: 1 });
+    }
+  }
+
+  forceFlush() {
+    return Promise.resolve();
+  }
+
+  shutdown() {
+    return Promise.resolve();
+  }
+}

package/src/index.d.ts

@@ -44,6 +44,12 @@ export interface InstrumentOptions {
    * for opting out of metrics even when a `MeterProvider` **is**
    * registered, not a substitute for that default.
    *
+   * Also gates `setupNodeSdk`'s dev-mode `MeterProvider` (ADR 023,
+   * `docs/adr/023-dev-mode-metrics.md`, v0.15.0+) — `{ setupNodeSdk: true,
+   * enableMetrics: false }` gets dev-mode traces with no dev-mode metrics
+   * at all, the same combination this flag already produces against a
+   * host-registered `MeterProvider`.
+   *
    * @default true
    */
   enableMetrics?: boolean;
@@ -53,11 +59,28 @@ export interface InstrumentOptions {
    * `NodeTracerProvider` (always exporting to stderr; additionally to
    * `exporterUrl` via OTLP/HTTP if set).
    *
+   * **Also stands up a dev-mode `MeterProvider` (ADR 023,
+   * `docs/adr/023-dev-mode-metrics.md`, v0.15.0+)**, gated additionally by
+   * `enableMetrics` (above, default `true`): a `PeriodicExportingMetricReader`
+   * exporting all 12 `mcp.tool.*`/`mcp.tool.loop.*`/`mcp.tool.schema_drift.*`
+   * instruments to stderr every 5 seconds, in a compact
+   * `name{attrs} = value` format — never `@opentelemetry/sdk-metrics`'
+   * own `ConsoleMetricExporter`, which writes to stdout and would corrupt
+   * a `StdioServerTransport` server's JSON-RPC stream (the same ADR 003
+   * reasoning the dev tracer's stderr-only exporter already follows). If
+   * a `MeterProvider` is already registered globally when this runs, this
+   * is a complete no-op — nothing is overridden, no exception is thrown,
+   * and a single `diag.warn` (once per process) names the situation;
+   * metrics continue to flow through whatever was already registered,
+   * exactly as they would with this flag `false`.
+   *
    * 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.
+   * OpenTelemetry setup. Metrics behavior is completely unaffected by this
+   * flag being `false` — API-only, exactly as documented in the README's
+   * "Metrics" section, with no dev-mode exception.
    *
    * @default false
    */
@@ -326,9 +349,14 @@ export type DuckTypedMcpServer = {
  *   `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. The returned object also gets a
+ *   avoid losing buffered spans. As of v0.15.0 (ADR 023), when dev-mode
+ *   metrics were also set up (`enableMetrics` not `false`, and no
+ *   `MeterProvider` was already registered globally — see `setupNodeSdk`'s
+ *   own doc above), the same `shutdown()` call also flushes and shuts down
+ *   that `MeterProvider`, so one call covers both signals. `shutdown` is
+ *   typed as optional because it is only attached at runtime when
+ *   `setupNodeSdk` is `true`; check for its presence before calling. The
+ *   returned object also gets a
  *   `getThrashSummary()` method (v0.6.0) returning a point-in-time,
  *   in-process {@link ThrashSummary} — no OTel involved, nothing sent
  *   anywhere; see the README's "Agent Thrash Detection" section. Unlike

package/src/instrument.js

@@ -4,13 +4,15 @@
 
 import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
-import { trace, diag, SpanStatusCode, SpanKind } from '@opentelemetry/api';
+import { trace, metrics, diag, SpanStatusCode, SpanKind } from '@opentelemetry/api';
 import { getV1Sdk, getV2Sdk } from './sdk/detect.js';
 import { NodeTracerProvider, SimpleSpanProcessor, BatchSpanProcessor } from '@opentelemetry/sdk-trace-node';
+import { MeterProvider, PeriodicExportingMetricReader } from '@opentelemetry/sdk-metrics';
 import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
 import { resourceFromAttributes } from '@opentelemetry/resources';
 import { resolveOptions } from './config.js';
 import { StderrSpanExporter } from './exporters/stderr.js';
+import { StderrMetricExporter } from './exporters/stderr-metrics.js';
 import { setupMeter } from './metrics.js';
 import { computeFingerprint, MAX_ERROR_CLASS_LENGTH } from './fingerprint/compose.js';
 import { toSpanAttributes, ATTRIBUTE_KEYS } from './fingerprint/attributes.js';
@@ -697,9 +699,31 @@ function assertInstrumentFirst(server, resolved) {
   }
 }
 
+// ADR 023 (v0.15.0): dev-mode metrics' export interval under
+// setupNodeSdk: true — 5s, not @opentelemetry/sdk-metrics'
+// PeriodicExportingMetricReader's own 60s default. A quickstart user
+// making a few tool calls and watching their terminal should see output
+// within a few seconds, not up to a minute later. Not currently exposed
+// as a configurable option — same "no configurable knobs" posture
+// StderrSpanExporter already takes.
+const DEV_METRICS_EXPORT_INTERVAL_MS = 5000;
+
+// Guards the "a MeterProvider is already registered, dev metrics skipped"
+// diagnostic below (ADR 023) so it fires once per process, same
+// once-per-process pattern config.js's warnedServiceNameIgnored/
+// warnedPricingStale already establish.
+let warnedMeterProviderAlreadyRegistered = false;
+
+// Test-only, same purpose as config.js's __resetServiceNameWarnedForTests/
+// __resetPricingStaleWarnedForTests. Not part of the public API.
+export function __resetMeterProviderWarnedForTests() {
+  warnedMeterProviderAlreadyRegistered = false;
+}
+
 /**
  * Resolves the Tracer to use for this server, optionally standing up an
- * owned NodeTracerProvider first.
+ * owned NodeTracerProvider (and, per ADR 023, an owned dev-mode
+ * MeterProvider) first.
  *
  * @param {import('@modelcontextprotocol/sdk/server/index.js').Server} server
  * @param {Required<import('./config.js').InstrumentOptions>} resolved
@@ -724,13 +748,73 @@ function setupTracer(server, resolved) {
         ? { [ATTR_MCP_PRICING_DEFAULT_TABLE_LAST_VERIFIED]: DEFAULT_PRICING_LAST_VERIFIED }
         : {};
 
-    const provider = new NodeTracerProvider({
-      resource: resourceFromAttributes({ 'service.name': resolved.serviceName, ...pricingResourceAttributes }),
-      spanProcessors,
-    });
+    // ADR 023: shared between the dev TracerProvider below and the dev
+    // MeterProvider further down, so service.name (and the pricing
+    // resource attribute) can never drift between the two signals in dev
+    // mode — one Resource construction, not two independently-built ones.
+    const resource = resourceFromAttributes({ 'service.name': resolved.serviceName, ...pricingResourceAttributes });
+
+    const provider = new NodeTracerProvider({ resource, spanProcessors });
     provider.register();
 
-    server.shutdown = () => provider.shutdown();
+    // ADR 023 (v0.15.0): dev-mode metrics. Only attempted when metrics
+    // aren't separately opted out via enableMetrics: false — a host who's
+    // already said "no metrics from this library" via that flag gets
+    // exactly that, with no new interaction between the two options to
+    // reason about.
+    let meterProvider = null;
+    if (resolved.enableMetrics) {
+      const candidateMeterProvider = new MeterProvider({
+        resource,
+        readers: [
+          new PeriodicExportingMetricReader({
+            exporter: new StderrMetricExporter(),
+            exportIntervalMillis: DEV_METRICS_EXPORT_INTERVAL_MS,
+          }),
+        ],
+      });
+
+      // metrics.setGlobalMeterProvider() returns false (documented,
+      // public .d.ts return type — not an internal detail) when a
+      // MeterProvider is already globally registered. In that case the
+      // ALREADY-registered provider — whoever's it is — keeps being what
+      // setupMeter() resolves to immediately below; candidateMeterProvider
+      // is never used for anything and must be shut down immediately
+      // rather than merely left unreferenced: @opentelemetry/sdk-metrics'
+      // MeterProvider constructor already called
+      // PeriodicExportingMetricReader's onInitialized() (confirmed by
+      // reading its source) — i.e. its setInterval is already running
+      // from the moment `new MeterProvider(...)` above returned, BEFORE
+      // this registration attempt — so an un-shut-down loser here would
+      // tick forever, every DEV_METRICS_EXPORT_INTERVAL_MS, exporting an
+      // empty ResourceMetrics (nothing ever creates an instrument on an
+      // abandoned provider) to a StderrMetricExporter nobody reads.
+      // Fire-and-forget, never awaited: shutdown must not block this
+      // synchronous setup path, and a rejection here must never throw
+      // past it (never-throw) — this is purely cleanup of a provider
+      // nothing else will ever reference again.
+      const registered = metrics.setGlobalMeterProvider(candidateMeterProvider);
+      if (registered) {
+        meterProvider = candidateMeterProvider;
+      } else {
+        candidateMeterProvider.shutdown().catch(() => {});
+        if (!warnedMeterProviderAlreadyRegistered) {
+          warnedMeterProviderAlreadyRegistered = true;
+          diag.warn(
+            'opentel-mcp: setupNodeSdk is true, but a MeterProvider is already registered globally — ' +
+              'dev-mode stderr metrics (ADR 023) were not set up, and the existing MeterProvider was left ' +
+              'untouched. This mcp.tool.* metrics will still be recorded through it as normal; only the ' +
+              "convenience stderr printout is skipped. Remove whatever registered a MeterProvider before " +
+              'instrumentMcpServer() ran if you intended to use the dev-mode printout instead.',
+          );
+        }
+      }
+    }
+
+    server.shutdown = async () => {
+      await provider.shutdown();
+      if (meterProvider) await meterProvider.shutdown();
+    };
   }
 
   // Always the final step: when setupNodeSdk is false, this picks up