opentel-mcp 0.14.0 → 0.16.0

package/CHANGELOG.md

@@ -1,5 +1,192 @@
 # Changelog
 
+## 0.16.0
+
+Finishes what 0.15 started. Telemetry now survives the way MCP clients
+actually stop servers (`flushOnExit`), and two new signals land: errors
+your agent can't act on, and opt-in resources/prompts coverage. Plus a fix
+for SDK v2 servers that declare `capabilities.tools`.
+`setupNodeSdk: false` (production) behavior is unchanged apart from the
+new span attributes on `isError: true` results and the v2 fix; resources/
+prompts coverage is off unless you opt in. No new metric label keys.
+
+### Added
+
+- **`flushOnExit` (ADR 024, `docs/adr/024-flush-on-exit.md`).** Under
+  `setupNodeSdk: true`, buffered spans and dev-mode metrics are now
+  flushed automatically when the process stops: on `beforeExit` (stdin
+  closed, loop drained), `SIGTERM` and `SIGINT`. MCP clients built on the
+  SDK's stdio transport stop servers with exactly that sequence (stdin
+  close → SIGTERM → SIGKILL, 2 s apart); the old `process.on('beforeExit')`
+  snippet only covered the first step. On by default with
+  `setupNodeSdk: true`; `flushOnExit: false` opts out;
+  `flushOnExit: { timeoutMs }` lowers the 1000 ms cap.
+  - One listener set per process, however many servers are instrumented,
+    and it's removed again once every server has shut down.
+  - After flushing, a signal is re-raised when no other listener for it
+    exists, so the process still dies by that signal. If your code has its
+    own listener, yours decides. `beforeExit` never changes the exit code.
+  - **No effect at all with `setupNodeSdk: false`** (production
+    behavior unchanged): passing it there logs a one-time `diag.warn`.
+  - Not covered: `process.exit()` (call `await server.shutdown()` first)
+    and `SIGKILL`.
+
+- **Unactionable tool errors (ADR 025, `docs/adr/025-unactionable-errors.md`).**
+  Every `isError: true` span now carries `mcp.failure.unactionable`
+  (boolean) and `mcp.failure.content_length_bucket` (`empty` | `tiny` |
+  `short` | `medium` | `long`). Unactionable means no content, or under
+  10 characters of trimmed text with no image/audio/resource item: an
+  error that gives the agent nothing to act on. Computed only from text
+  lengths and non-text item counts, never from the text; a canary-string
+  test checks every exported span and metric. Span-only (no metric label,
+  `METRIC_SAFE_ATTRIBUTES` unchanged); fingerprints and categories
+  unchanged. Configure with `unactionableErrors: { enabled, minTextLength }`
+  or `OTEL_MCP_UNACTIONABLE_ERRORS_ENABLED` /
+  `OTEL_MCP_UNACTIONABLE_ERRORS_MIN_TEXT_LENGTH`.
+
+- **Resources and prompts coverage, opt-in (ADR 026,
+  `docs/adr/026-resources-prompts-coverage.md`).**
+  `coverage: { resources: true, prompts: true }` also traces
+  `resources/read`, `resources/list`, `resources/templates/list`,
+  `prompts/get` and `prompts/list`, on SDK v1 and v2, low-level `Server`
+  and `McpServer`. Both are off by default; nothing changes unless you opt in.
+  - Spans are named by method (`prompts/get <name>` for prompts/get) and
+    carry `mcp.method.name` (+ `gen_ai.prompt.name` on prompts/get, capped
+    at 128 characters). `gen_ai.tool.name` is absent.
+  - Never captured: resource URIs, prompt arguments, result content, or
+    the exception message of a failing request (SDK resource errors embed
+    the URI). Failures get status `ERROR`, `error.type` and the usual
+    fingerprint/category/channel.
+  - New histogram `mcp.server.operation.duration`, labeled by
+    `mcp.method.name` + `error.type` only. No new label keys;
+    `mcp.method.name` stays a fixed set of constants (now 7 values).
+  - A handler already registered when `instrumentMcpServer()` runs is
+    skipped with one `diag.warn`, never a throw. That includes SDK v2
+    `McpServer` declaring `capabilities.resources/prompts` in its
+    constructor.
+
+### Changed
+
+- `server.shutdown()` (under `setupNodeSdk: true`) is now idempotent:
+  every call returns the same promise, so an explicit `shutdown()` and
+  `flushOnExit` never shut the providers down twice.
+- The README quickstart and both examples no longer need the
+  `process.on('beforeExit', ...)` block; it's been removed.
+
+### Fixed
+
+- **SDK v2: a `McpServer` constructed with `capabilities: { tools: {} }`
+  can now be instrumented.** v2's `McpServer` installs its own
+  `tools/list`/`tools/call` dispatchers in its constructor when that
+  capability is declared, so `instrumentMcpServer()` threw
+  `INSTRUMENT_FIRST_ERROR` on every such server, whatever the call order.
+  It now recognizes McpServer's own constructor-installed handlers (v2
+  McpServer, installer ran, no tool registered yet, not yet connected),
+  takes them down with the public `removeRequestHandler()`, and lets
+  McpServer re-install them through the instrumented `setRequestHandler`,
+  so they're wrapped like any lazily-installed handler. Genuine misorders
+  still throw: a tool registered before instrumenting (v1 or v2, with or
+  without declared capabilities) or a low-level `Server` handler
+  registered first. Present since v2 support shipped (SDK 2.0.0).
+
+## 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
@@ -65,12 +94,22 @@ await server.connect(transport);
 ```
 
 That's it. Every tool call now emits a trace. Wire an exporter to see them
-(next section).
+(next section). When the server stops — your MCP client closing stdin, or
+sending SIGTERM/SIGINT — anything still buffered is flushed first,
+automatically (see "Flushing on exit" below).
 
 ## See it working
 
-Run the snippet above and this prints to your terminal — a real, captured
-run (full dump: `examples/hello-mcpserver/README.md`):
+Save the snippet as `server.js`. On its own it just waits: an MCP server
+reads requests from stdin and does nothing until a client sends one. To
+try it without a client, pipe in a single tool call:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"echo","arguments":{"text":"hi"}}}' | node server.js
+```
+
+The JSON-RPC response goes to stdout, and this prints to stderr — a real,
+captured run (full dump: `examples/hello-mcpserver/README.md`):
 
 ```
 name: 'tools/call echo'
@@ -87,6 +126,23 @@ 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+)** — a compact one-line-per-metric summary
+on stderr, reusing the exact `mcp.tool.*` instruments documented in
+"Metrics" below. A long-running server prints it every 5 seconds (not the
+default 60-second export interval). The one-shot piped run above prints it
+once as it exits, because the server flushes when stdin closes (v0.16.0,
+see "Flushing on exit"):
+
+```
+[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 +296,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:
 
 ```
@@ -250,6 +316,60 @@ error.type = tool_error
 
 Verified in `test/instrument.test.js`'s "tool-level failure" tests.
 
+#### Errors your agent can't act on (v0.16.0)
+
+An `isError: true` result with no content, or just `"Error"`, tells the
+model nothing about what went wrong or what to do next — a common cause
+of retries and thrash. Every `isError: true` span also carries:
+
+| Attribute | Values |
+| --- | --- |
+| `mcp.failure.unactionable` | `true` when there's no content, or fewer than 10 characters of text (whitespace-trimmed) and no image/audio/resource item |
+| `mcp.failure.content_length_bucket` | `empty` (0) · `tiny` (1–9) · `short` (< 80) · `medium` (< 500) · `long` |
+
+Both are computed **only from lengths and item counts — never from the
+text itself** (proved by a canary-string test in
+`test/unactionable.test.js`), on spans only, never as metric labels. They
+don't change fingerprints or categories. Configure with
+`unactionableErrors: { enabled, minTextLength }` (defaults `true`, `10`).
+Design: [ADR 025](../../docs/adr/025-unactionable-errors.md).
+
+### Resources and prompts (opt-in, v0.16.0)
+
+Tools are traced by default. `resources/*` and `prompts/*` requests can be
+traced too, if you turn them on:
+
+```js
+instrumentMcpServer(server, {
+  coverage: { resources: true, prompts: true }, // either or both
+});
+```
+
+| Method | Span name | Attributes |
+| --- | --- | --- |
+| `resources/read`, `resources/list`, `resources/templates/list` | the method, e.g. `resources/read` | `mcp.method.name` |
+| `prompts/get` | `prompts/get <prompt name>` | `mcp.method.name`, `gen_ai.prompt.name` |
+| `prompts/list` | `prompts/list` | `mcp.method.name` |
+
+- **Never captured:** resource URIs, prompt arguments, result content. A
+  failing request gets status `ERROR`, `error.type`, and the usual
+  fingerprint/category/channel (`mcp.failure.*`), but **not** the exception
+  message, because SDK resource errors embed the URI in it.
+- `gen_ai.tool.name` is absent (not empty) on these spans, so they never
+  show up in per-tool views or tool metrics.
+- Durations go to a separate histogram, `mcp.server.operation.duration`,
+  labeled only by `mcp.method.name` (one of the five methods above) and
+  `error.type`. No thrash detection or cost tracking applies.
+- **Ordering:** instrument before registering resources/prompts, same as
+  tools. If a handler for one of these methods already exists, that method
+  is skipped with a single `diag.warn`. It never throws, so turning this on
+  can't break an existing server. On an SDK v2 `McpServer`, declaring
+  `capabilities: { resources: {}, prompts: {} }` in the constructor
+  registers those handlers immediately (and so skips them); leave them out,
+  since registering a resource or prompt declares the capability for you.
+
+Design: [ADR 026](../../docs/adr/026-resources-prompts-coverage.md).
+
 ### Span attributes
 
 Every span follows the OpenTelemetry MCP semantic conventions (see
@@ -273,11 +393,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 +458,83 @@ 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. As of v0.16.0 this runs
+  automatically when the process stops — see "Flushing on exit" below.
+
+### Flushing on exit (`flushOnExit`, v0.16.0)
+
+Under `setupNodeSdk: true`, buffered spans and dev-mode metrics are
+flushed automatically when the process stops. It's on by default; pass
+`flushOnExit: false` to turn it off. MCP clients built on the SDK's stdio
+transport stop a server by closing stdin, then sending SIGTERM 2 seconds
+later, then SIGKILL; this covers the first two:
+
+| Event | What happens |
+| --- | --- |
+| stdin closes and nothing else keeps the process alive | flushed on `beforeExit`; the process exits with its own exit code |
+| `SIGTERM` / `SIGINT` | flushed, then the same signal is re-raised so the process still dies by it, unless your code has its own listener for that signal, in which case yours decides |
+| `process.exit()` | **not covered**: call `await server.shutdown()` before exiting |
+| `SIGKILL` | can't be intercepted |
+
+The flush waits at most 1000 ms (`flushOnExit: { timeoutMs }` can only
+lower that), so a stuck exporter can't keep a stopping server alive.
+`server.shutdown()` is safe to call yourself as well: it runs once, however
+many times it's called. With `setupNodeSdk: false` this option does
+nothing — your application owns its providers and its shutdown. Design:
+[ADR 024](../../docs/adr/024-flush-on-exit.md).
+
+`@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
 
@@ -2121,6 +2318,7 @@ so they're spelled out instead of forced into one bucket.
 | `mcp.tool.pricing_status` | span attr, metric label | **blend — library-computed, depends on tool + host** | which of three enum values depends on a tool-controlled model name resolving (or not) in a library-default-or-host-overridden pricing table |
 | `mcp.failure.fingerprint` / `.signature` / `.category` / `.origin` / `.channel` | span attr (2 also metric labels) | library-computed | hashes/enums — the governed core this project has kept clean since v0.4.0 |
 | `mcp.failure.error_class` | span attr | **blend — tool-controlled, capped only** | `err.name`, length-capped at 128 characters but, unlike everything hashed into the fingerprint, *not* pattern-scrubbed — a documented, deliberate tradeoff (`docs/known-gaps.md` entry 10) |
+| `mcp.failure.unactionable` / `.content_length_bucket` | span attr | library-computed | a boolean and a 5-value enum derived from the trimmed text LENGTH and non-text item COUNT of an `isError: true` result — no text is read for anything but its length (ADR 025, v0.16.0) |
 | `mcp.failure.validation_paths` | span attr | mostly library-computed (gated) | one legacy Zod-issue-rendering path can still carry a tool-controlled dynamic object key, now redacted to a `<KEY>` placeholder rather than closed structurally (`docs/known-gaps.md` entry 10, item 3) |
 | `exception.type` (event) | event attr | tool-controlled | length-capped only under `'normalized'` mode; uncapped under `'full'` (the native SDK call) |
 | `exception.message` / `.stacktrace` (event), status message | event attr + status | **blend — layered** | raw tool content under `'full'`; this library's `normalizeMessage()`/`parseAndNormalizeStack()` transform of that same content under `'normalized'`; optionally a host-supplied `errorRecording.redactor`'s output feeding *that*, first (v0.14.0) — the most layered-provenance attribute in the system |
@@ -2621,7 +2819,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 +2899,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.16.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -69,13 +69,14 @@
   "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",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "@modelcontextprotocol/server": "2.3.1",
     "@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/attributes.js

@@ -76,6 +76,29 @@ export const MCP_METHOD_NAME_TOOLS_CALL = 'tools/call';
 /** Well-known mcp.method.name value for a tools/list request (ADR 010, schema drift detection). */
 export const MCP_METHOD_NAME_TOOLS_LIST = 'tools/list';
 
+// ADR 026 (v0.16.0, opt-in `coverage`): the five resource/prompt methods.
+// mcp.method.name only ever takes these fixed string constants, never a
+// value read from a request, so its value space stays bounded (7 total).
+
+/** Well-known mcp.method.name value for a resources/read request (ADR 026). */
+export const MCP_METHOD_NAME_RESOURCES_READ = 'resources/read';
+/** Well-known mcp.method.name value for a resources/list request (ADR 026). */
+export const MCP_METHOD_NAME_RESOURCES_LIST = 'resources/list';
+/** Well-known mcp.method.name value for a resources/templates/list request (ADR 026). */
+export const MCP_METHOD_NAME_RESOURCES_TEMPLATES_LIST = 'resources/templates/list';
+/** Well-known mcp.method.name value for a prompts/get request (ADR 026). */
+export const MCP_METHOD_NAME_PROMPTS_GET = 'prompts/get';
+/** Well-known mcp.method.name value for a prompts/list request (ADR 026). */
+export const MCP_METHOD_NAME_PROMPTS_LIST = 'prompts/list';
+
+/**
+ * gen_ai.prompt.name — the prompt a prompts/get span requested (ADR 026).
+ * Span attribute only, never a metric label. Capped at
+ * MAX_PROMPT_NAME_LENGTH, since the value comes from the request.
+ */
+export const ATTR_GEN_AI_PROMPT_NAME = 'gen_ai.prompt.name';
+export const MAX_PROMPT_NAME_LENGTH = 128;
+
 // --- Custom (non-spec) attributes ---
 
 /**