opentel-mcp 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## 0.10.0
+
+**⚠️ Behavior change, unrelated to the feature below — read this first.**
+`instrumentMcpServer()` now throws for a server object it cannot
+confidently wrap, instead of silently instrumenting nothing.
+`detectServerKind()` (`src/instrument.js`) previously accepted any
+`McpServer`-shaped object whose `.server` merely *had* a
+`setRequestHandler` method — it now additionally requires `.server
+instanceof <Server>` for a real, recognized SDK class. An object that
+satisfies the outer shape but fails that check now throws a new,
+specific error (`UNWRAPPABLE_MCPSERVER_ERROR` — names what was detected
+and the plausible causes: a duplicate/mismatched SDK install, an SDK not
+resolvable from this package's own location, or an unsupported SDK) at
+`instrumentMcpServer()` call time, rather than succeeding and producing
+zero telemetry. This closes a confirmed gap (`docs/known-gaps.md` entry
+7, now marked fixed): an `@modelcontextprotocol/server` (MCP v2) object
+passed to a pre-0.10.0 `instrumentMcpServer()` satisfied the old, looser
+check and appeared to instrument successfully — `getThrashSummary`/
+`getObservationState` attached, no error — while producing zero spans,
+zero metrics, and zero fingerprinting for every tool call. No escape
+hatch was added; see ADR 015 (`docs/adr/015-mcp-v2-support.md`) for the
+full argument against one. **If you're seeing this new error on upgrade**
+and you believe your object genuinely is a real `Server`/`McpServer`
+instance, check for a duplicate/mismatched install of whichever SDK it
+came from (`npm dedupe`, or check for multiple installed copies) — a real
+v1 or v2 `Server`/`McpServer` from a single, consistently-resolved SDK
+install is unaffected by this change.
+
+### Added — `@modelcontextprotocol/server` (MCP v2, protocol revision 2026-07-28) support
+
+Both the original `@modelcontextprotocol/sdk` ("v1") and the new
+`@modelcontextprotocol/server` ("v2") now work with `instrumentMcpServer()`
+— two separate, OPTIONAL peer dependencies (install whichever one(s) you
+actually use; `package.json`'s `peerDependenciesMeta` marks both
+`optional: true`, verified against real, clean external installs with
+only one, the other, or neither installed — not just `package.json`
+syntax). Same `Server`/`McpServer` API shapes as v1; detection and
+wrapping happen automatically, resolved once per `instrumentMcpServer()`
+call by which SDK the object actually came from. Full design and
+Phase-by-phase implementation notes: ADR 015
+(`docs/adr/015-mcp-v2-support.md`).
+
+What works the same as v1: spans, standard attributes (including
+`jsonrpc.request.id`, now read from v2's `ctx.mcpReq.id`), deep failure
+fingerprinting, and `mcp.failure.channel`/`mcp.failure.validation_paths`
+classification (`channel.js`/`validation-paths.js` both gained a
+v2-specific code path — the "MCP error N:" wrapper v1 disguises errors
+with doesn't exist in v2, and v2's rendered validation-issue text uses a
+third, distinct format from either of v1's two).
+
+**v2's own `createMcpHandler`/`serveStdio` construct a fresh `Server`/
+`McpServer` per request by default (a factory function you provide), not
+once at process start.** `instrumentMcpServer()` needs to run *inside*
+that factory, on every invocation — see the README's new "MCP v2 support"
+section for a worked example. `instanceKey` (v0.9.0) is the existing
+mechanism for sharing tracker state across those repeated calls; nothing
+new was added for this, since ADR 012's original design already covers
+this exact deployment shape, v2 just makes it the default instead of an
+edge case.
+
+**Two gaps not closed this release, both tracked in `docs/known-gaps.md`
+with a "Status update (v0.10.0)" note:** Agent Thrash Detection's fallback
+session id still doesn't survive v2's per-request factory pattern even
+with `instanceKey` set (entry 6 — real session ids work fine either way),
+and `isSingleConnectionTransport()`'s transport-detection heuristic still
+misclassifies the transport `createMcpHandler` builds internally (entry
+8, live as of this release, not merely forward-looking). Both were
+explicitly scoped out of this round, not overlooked; workaround for
+either: `thrashDetection: { enabled: false }`.
+
 ## 0.9.0
 
 **⚠️ Fixed, with a fingerprint behavior change — read this before the

package/README.md

@@ -129,6 +129,111 @@ await server.connect(transport);
 Runnable versions of both live in `examples/hello-server/` and
 `examples/hello-mcpserver/`.
 
+## MCP v2 (`@modelcontextprotocol/server`) support (v0.10.0+)
+
+Both the original SDK and the new one work with `instrumentMcpServer()` —
+they're two separate, OPTIONAL peer dependencies (install whichever one(s)
+you actually use):
+
+- `@modelcontextprotocol/sdk` ("v1" throughout this README) — protocol
+  revisions through 2025-11-25. The `Server`/`McpServer` APIs above.
+- `@modelcontextprotocol/server` ("v2") — protocol revision 2026-07-28,
+  whose headline change is removing the `initialize` handshake and the
+  `Mcp-Session-Id` Streamable HTTP header in favor of a stateless,
+  self-contained-request model. Same `Server`/`McpServer` shapes, same
+  `instrumentMcpServer()` call — detection and wrapping happen
+  automatically, resolved once per `instrumentMcpServer()` call by which
+  SDK the object you passed in actually came from (ADR 015,
+  `docs/adr/015-mcp-v2-support.md`).
+
+```js
+import { McpServer } from '@modelcontextprotocol/server';
+import { instrumentMcpServer } from 'opentel-mcp';
+import { z } from 'zod';
+
+const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+instrumentMcpServer(server, { serviceName: 'my-mcp-server' });
+
+server.registerTool('echo', { inputSchema: z.object({ text: z.string() }) }, async ({ text }) => ({
+  content: [{ type: 'text', text }],
+}));
+```
+
+**The important difference isn't the API — it's the deployment shape.**
+v2's own `createMcpHandler`/`serveStdio` entry points construct a fresh
+`Server`/`McpServer` instance **per request** (via a factory function you
+provide), not once at process start — including for `createMcpHandler`'s
+default stateless HTTP posture, not just an edge case. That means
+`instrumentMcpServer()` has to run **inside the factory**, on every
+invocation, not once at module load the way the v1 examples above do:
+
+```js
+import { createMcpHandler } from '@modelcontextprotocol/server';
+import { McpServer } from '@modelcontextprotocol/server';
+import { instrumentMcpServer } from 'opentel-mcp';
+
+const handler = createMcpHandler((ctx) => {
+  const server = new McpServer({ name: 'my-server', version: '1.0.0' });
+
+  // Runs on every request this factory serves. instanceKey is what makes
+  // that not mean "trackers reset every time" — see below.
+  instrumentMcpServer(server, { serviceName: 'my-mcp-server', instanceKey: 'my-mcp-server' });
+
+  server.registerTool('echo', { inputSchema: z.object({ text: z.string() }) }, async ({ text }) => ({
+    content: [{ type: 'text', text }],
+  }));
+
+  return server;
+});
+```
+
+**`instanceKey` (see the dedicated section below) is the mechanism for
+this** — it's not a new, v2-specific option; it's the same one ADR 012
+built for a v1 "stateless Streamable HTTP" deployment shape that turned
+out to be exactly what v2 makes the *default*, SDK-recommended pattern
+instead of something a host happened to build. Without it, the same four
+in-memory trackers ("In-memory tracker state is scoped to one
+instrumentMcpServer() call" below) reset to empty on every request under
+this pattern, same as they always have for any fresh-instance-per-request
+deployment — v2 doesn't change that mechanism, it just makes hitting it
+the default instead of an edge case.
+
+**What works today:** spans, standard attributes (`mcp.method.name`,
+`gen_ai.tool.name`, `jsonrpc.request.id` — read from v2's `ctx.mcpReq.id`),
+deep failure fingerprinting, `mcp.failure.channel`/`mcp.failure.validation_paths`
+classification, and — as of this release — Agent Thrash Detection's
+fallback-session path and transport auto-detection all work the same as
+v1 (ADR 015 Phases 1–3, plus a follow-up round documented in ADR 015's
+Update section):
+
+- `isSingleConnectionTransport()` requires positive confirmation
+  (`transport.constructor.name === 'StdioServerTransport'`) for v2
+  specifically, instead of inferring single-connection from an absent
+  `sessionId` property — closing a confirmed false positive against the
+  transport `createMcpHandler` builds internally
+  (`PerRequestHTTPServerTransport`), which also has no `sessionId`, for
+  the opposite reason stdio doesn't. v1 is completely unaffected by this
+  change. See `docs/known-gaps.md` entry 8 for the full history.
+- The generated fallback session id is now shared across repeated
+  `instrumentMcpServer()` calls when `instanceKey` is set (the same
+  registry the four ADR-012 trackers already use), fixing the gap
+  "instanceKey alone does not fix thrash detection" below originally
+  described for v1's stateless deployment shape, for the v2 factory
+  pattern specifically. See `docs/known-gaps.md` entry 6.
+
+**One narrower thing still open**, tracked in `docs/known-gaps.md` entry
+6's own update: `thrashSessionState` (the internal flag tracking "has
+this server ever proven itself session-aware") is not registry-backed the
+way the fallback id now is, so that specific memory still resets on every
+v2 per-request call. This only matters for a deployment that mixes
+real-session-id calls with occasional no-session-id ones under a shared
+`instanceKey` — thrash detection using a **real** session id on every
+call (`ctx.sessionId`) is unaffected either way.
+
+Runnable end-to-end coverage lives in `test/instrument.v2.test.js` and
+`test/integration/thrash-v2-transport-detection.test.js`, not a dedicated
+`examples/` directory yet.
+
 ## What gets emitted
 
 ### Tool-level failures, specifically
@@ -484,7 +589,13 @@ convenience default, not a maintained price list.
   one instrumentMcpServer() call" below for what that means under a
   fresh-`Server`-per-request deployment. Session-scoped limits are also
   skipped gracefully (not enforced against a fallback key) for transports
-  with no session id, like stdio.
+  with no session id, like stdio. **`perSessionUsd` is unsupported under
+  stateless MCP (no real session id available at all) — unchanged from
+  ADR 012's conclusion, and there is no fix pending.** Unlike thrash
+  detection, this budget tracker has no fingerprint-equivalent attribute
+  on the span today, so "Fleet-wide fingerprint frequency" below has
+  nothing to substitute with for this scope specifically. `perToolUsd` is
+  unaffected — it never depended on session id.
 
 ## Agent Thrash Detection (v0.6.0+)
 
@@ -735,6 +846,22 @@ in order:
    `assumeSingleSession` left at its default `false` — detection is
    **skipped silently** for that call rather than guessing.
 
+**For `@modelcontextprotocol/server` (v2) users:** this structural check —
+"no `sessionId` property on the transport" — is v1-specific. v2's
+transport `createMcpHandler` builds internally
+(`PerRequestHTTPServerTransport`) *also* declares no `sessionId`
+property, but for the opposite reason stdio doesn't: the 2026-07-28
+protocol revision has no session concept at the transport level at all,
+not because each instance is genuinely 1:1 with one client — so for v2
+specifically, this function requires POSITIVE confirmation
+(`transport.constructor.name === 'StdioServerTransport'`) instead of
+inferring single-connection from the absent property. `PerRequestHTTPServerTransport`
+correctly falls through to "undetermined" rather than being misclassified.
+v1's own check is completely unaffected by this. See `docs/known-gaps.md`
+entry 8 for the full history (including the period where this was a
+confirmed, live false positive) and ADR 015's Update section for the
+design argument.
+
 **The risk of getting this wrong:** if you set `assumeSingleSession: true`
 on a transport that's actually serving multiple concurrent clients (a
 typical HTTP/SSE deployment behind a load balancer, for instance), their
@@ -798,6 +925,14 @@ Streamable HTTP), consecutive-failure tracking never accumulates past a
 single call, and `mcp.tool.loop.detected` never fires — silently. Confirmed
 gap, ADR 012.
 
+**For deployments with no real session id at all** (see "instanceKey"
+above, specifically the "MCP spec 2026-07-28" subsection, for exactly
+when this applies) — **thrash detection is unsupported, unchanged from
+ADR 012's conclusion.** There is a partial, downstream substitute: "Fleet-
+wide fingerprint frequency" below. Read its caveat before treating it as a
+fix for this gap — it detects how often a bug occurs across every caller,
+not whether one agent is looping.
+
 **A malformed `tools/call` request produces zero telemetry — no span, no
 fingerprint, nothing.** If a request fails `CallToolRequestSchema`
 validation itself (e.g. a missing or wrongly-typed `name`/`arguments`
@@ -1457,9 +1592,16 @@ different, also-common shape: **"stateless" Streamable HTTP, where a fresh
 Under that topology, every one of these four trackers is discarded and
 rebuilt from empty before it ever sees a second data point, unless
 `instanceKey` is set — and, for Agent Thrash Detection specifically, a
-real session id is also available on every call. Without both, nothing
-accumulates, nothing crosses a threshold, and nothing warns that this is
-happening — the affected feature is silently inert.
+real session id is also available on every call. MCP spec 2025-11-25 and
+earlier transports give you this automatically; **`@modelcontextprotocol/server`
+(v2, protocol revision 2026-07-28) still has a real, optional `sessionId`
+field on every call — it isn't removed — but its default,
+`createMcpHandler`-driven stateless deployment shape usually doesn't
+populate it, the same "no session id" shape stdio has always had for v1**
+— see "MCP spec 2026-07-28..." below for exactly what this does and
+doesn't mean. Without both a shared tracker and a real session id on every
+call, nothing accumulates, nothing crosses a threshold, and nothing warns
+that this is happening — the affected feature is silently inert.
 
 **Confirmed, not a hypothetical, and now has a partial fix.** Reproduced
 directly in `test/integration/thrash-stateless-http-lifecycle.test.js`:
@@ -1473,13 +1615,18 @@ trackers, and the `instanceKey` design: ADR 012
 (`docs/adr/012-tracker-lifecycle-and-shared-state.md`). Tracked in
 `docs/known-gaps.md`.
 
-**If you instrument a fresh `Server`/`McpServer` per request: set
-`instanceKey`.** Read the section immediately below in full before relying
-on it — it has one required companion for thrash detection specifically
-(a real session id, not the generated fallback), and it does not help at
-all across multiple processes or containers (Lambda, Cloud Run, or any
-horizontally-scaled deployment). Both are easy to miss and produce the
-exact same silent-inertness symptom as this section describes.
+**If you instrument a fresh `Server`/`McpServer` per request — including
+every `@modelcontextprotocol/server` (v2) deployment via `createMcpHandler`/
+`serveStdio`, whose factory pattern makes this the default, not an edge
+case — set `instanceKey`.** Read the section immediately below in full
+before relying on it — it has one required companion for thrash detection
+specifically (a real session id, not the generated fallback — under v2's
+default stateless posture this companion usually isn't met, not because
+it's structurally impossible but because nothing provides one; see "MCP
+spec 2026-07-28..." below), and it does not help at all across multiple
+processes or containers (Lambda, Cloud Run, or any horizontally-scaled
+deployment). All three are easy to miss and produce the exact same
+silent-inertness symptom as this section describes.
 
 ## instanceKey: sharing tracker state across instrumentMcpServer() calls (v0.9.0+)
 
@@ -1542,19 +1689,25 @@ past 1, and nothing warns you.
 2. a real `extra.sessionId` on every call, so the lookup key inside that
    shared tracker is stable across calls too.
 
-Real Streamable HTTP transports give you (2) automatically — the SDK
-threads a real client session id through `extra.sessionId` on every
-request regardless of whether the `Server` object handling it was just
-constructed, so the common "stateless Streamable HTTP" case works with
-`instanceKey` alone, no extra effort. **You will NOT get (2) for free —
-and thrash detection will stay silently inert despite `instanceKey` being
-set — if:** you're using a custom `Transport` implementation that never
+Real Streamable HTTP transports built against **MCP spec 2025-11-25 or
+earlier** give you (2) automatically — the SDK threads a real client
+session id through `extra.sessionId` on every request regardless of
+whether the `Server` object handling it was just constructed, so the
+common "stateless Streamable HTTP" case works with `instanceKey` alone,
+no extra effort, **for every spec version through 2025-11-25**. That
+version qualifier is load-bearing, not throat-clearing — see the
+subsection immediately below. **You will NOT get (2) for free — and
+thrash detection will stay silently inert despite `instanceKey` being set
+— if:** you're using a custom `Transport` implementation that never
 exposes a `sessionId`, you've set `assumeSingleSession: true` (which
-exists specifically to opt into the generated fallback), or anything else
-lands on the fallback path described in "Session id resolution" above. If
-you're in any of those cases, you need your own mechanism for threading a
-stable, real session identity into each call — `instanceKey` cannot
-manufacture one for you, and there is no configuration of it that will.
+exists specifically to opt into the generated fallback), anything else
+lands on the fallback path described in "Session id resolution" above,
+**or your transport is built against MCP spec 2026-07-28 or later — see
+below, this is a different problem `instanceKey` cannot solve at all,
+not a configuration gap.** If you're in one of the first three cases, you
+need your own mechanism for threading a stable, real session identity
+into each call — `instanceKey` cannot manufacture one for you, and there
+is no configuration of it that will.
 
 This composition requirement is specific to Agent Thrash Detection's
 per-session lookup key. Schema drift detection and the `ToolOutcome`
@@ -1563,6 +1716,70 @@ sufficient for both. Budget tracking's `perToolUsd` scope is also
 session-independent; its `perSessionUsd` scope inherits the identical
 requirement, for the identical reason.
 
+### MCP spec 2026-07-28 / `@modelcontextprotocol/server` (v2) — session identity and `instanceKey`
+
+**Correcting an earlier version of this section:** MCP spec 2026-07-28
+does NOT remove session identity from this library's reach entirely —
+`@modelcontextprotocol/server` (v2)'s `ctx.sessionId` is still a real,
+optional field this library reads (ADR 015 Finding 3).
+
+[MCP spec 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28/changelog)
+removes protocol-level sessions and the `Mcp-Session-Id` header from the
+Streamable HTTP transport's WIRE format — not deprecated, removed — along
+with the `initialize`/`notifications/initialized` handshake that used to
+mint one. That's a real, confirmed spec fact. But it's a statement about
+the wire protocol, not about the SDK's object model: v2's `ctx.sessionId`
+(the direct equivalent of v1's `extra.sessionId`) is still there in the
+type, and this library reads it the same way for both SDKs. The practical
+effect is that `createMcpHandler`'s default, stateless deployment shape
+usually just doesn't populate it — the same "no session id" shape stdio
+has always had for v1, not a new, structurally-impossible-to-meet
+requirement. A v2 deployment that does provide a real session id (a
+custom transport, or a future v2 transport with its own session concept)
+gets ordinary, working thrash detection, no different from v1.
+
+**For the common case where v2 genuinely provides no real session id**
+(the `createMcpHandler` stateless default): as of this release, two
+fixes together make thrash detection work correctly here, the same way
+it does for v1's equivalent stdio case.
+
+1. `isSingleConnectionTransport()` no longer auto-detects
+   `PerRequestHTTPServerTransport` (the transport `createMcpHandler`
+   builds internally) as single-connection at all — see "Known
+   limitations" above and `docs/known-gaps.md` entry 8. So the fallback
+   path below is no longer reached automatically for a typical v2 HTTP
+   deployment; it requires an explicit, informed `assumeSingleSession: true`
+   opt-in (or a genuinely single-connection v2 `serveStdio` deployment,
+   which is positively confirmed the same way stdio always has been).
+2. **For whichever deployments do legitimately reach the fallback path**
+   (that explicit opt-in, or v2 stdio): the generated fallback session id
+   is now shared across repeated `instrumentMcpServer()` calls when
+   `instanceKey` is set — the same registry the four ADR-012 trackers
+   already use, one more namespaced entry, no new bound/eviction policy.
+   Previously this id was regenerated fresh on every call regardless of
+   `instanceKey` (per "instanceKey alone does not fix thrash detection"
+   above), so v2's factory pattern (a fresh instance, and a fresh
+   `instrumentMcpServer()` call, per request) meant nothing ever
+   accumulated even for an intentional, correctly-configured
+   single-connection deployment. Fixed: `test/integration/thrash-v2-transport-detection.test.js`
+   drives 5 separate `instrumentMcpServer()` calls sharing one
+   `instanceKey`, each a fresh v2 `Server` with no real session id, and
+   confirms `mcp.tool.loop.detected` now fires by the 5th.
+
+**One narrower thing still open**, tracked in `docs/known-gaps.md` entry
+6's own update: `thrashSessionState` — the flag tracking "has this server
+ever proven itself session-aware" (used by `resolveThrashSessionId()`'s
+rule 2, which skips a later no-session call rather than merging it, once
+a server has shown it hands out real ids) — is still a plain per-call
+object, not registry-backed. This only matters for a deployment mixing
+real-session-id calls with occasional no-session-id ones under a shared
+`instanceKey`; rule 1 (a real session id always wins) is unaffected
+either way.
+
+**This package's actual v2 support status:** `@modelcontextprotocol/server`
+is a supported, optional peer dependency as of v0.10.0 (ADR 015) — see
+the "MCP v2 support" section above.
+
 ### Registry bounds, and what eviction means
 
 The internal registry `instanceKey` looks trackers up in is bounded, not
@@ -1610,6 +1827,79 @@ via the `OTEL_MCP_INSTANCE_KEY` environment variable (lower precedence
 than the option itself). An empty or whitespace-only value from either
 source is treated the same as omitting it entirely.
 
+## Fleet-wide fingerprint frequency (a Tempo recipe, not a library feature)
+
+Under stateless MCP — no real session id at all, the exact gap the
+`instanceKey` section above documents in full — Agent Thrash Detection's
+in-process tracker has nothing to key episodes on, and stays silently
+inert. That doesn't mean there's nothing to query downstream:
+`mcp.failure.fingerprint` (see "Failure Fingerprinting" above) is already
+a plain span attribute on every failed `tools/call` span whenever
+fingerprinting is enabled, unconditional on session id or any in-process
+accumulation. A trace backend that can aggregate by an arbitrary span
+attribute can group by it directly, today, with zero new opentel-mcp
+emission. Full investigation: ADR 012's third update
+(`docs/adr/012-tracker-lifecycle-and-shared-state.md`).
+
+**⚠️ Read this before treating the query below as "thrash detection for
+stateless deployments" — it is not that.** Agent Thrash Detection's whole
+premise is *one agent* retrying *one broken call*. Grouping by
+`mcp.failure.fingerprint` alone has no dimension to separate callers by —
+it counts occurrences of a bug, full stop. **One agent hitting the same
+bug 3 times in a row, and three unrelated users each hitting it once, are
+indistinguishable by this query — both produce a count of 3 for the same
+fingerprint.** That's a real, useful signal (fleet-wide bug-frequency
+monitoring) but it is a different question from "is this agent stuck in a
+loop," and presenting it as the latter would be dishonest. There is
+currently no supported way to add a caller-identity dimension to this
+query — see ADR 012's third update for why that would require the library
+to read an application-chosen tool argument (the MCP spec's own answer
+for session continuity under 2026-07-28 is a server-minted handle passed
+back as an ordinary tool argument) and put it on the span, which is a new
+kind of attribute this library doesn't emit today and a separate design
+decision, not a small addition.
+
+### Why Tempo, and not the other two backends ADR 013 investigated
+
+ADR 013 investigated attribute/event queryability across SigNoz, Tempo,
+and Jaeger, but for a different need (rendering panels over single spans
+or traces). This recipe needs a capability that investigation didn't
+cover: aggregating — counting, grouping — across many separate traces by
+an attribute value, not just filtering by one.
+
+- **Tempo** — TraceQL metrics queries support `by(<attribute>)` grouping
+  over arbitrary span attributes at query time, including high-cardinality
+  ones like `mcp.failure.fingerprint`. The query below is real, pasteable
+  TraceQL, not pseudo-syntax.
+- **SigNoz** — can express the equivalent, but only as a ClickHouse SQL
+  panel inside a Dashboard, per ADR 013's finding that raw ClickHouse
+  querying is Dashboard-only, not reachable from the ad-hoc query API a
+  live "what's failing right now" view would use.
+- **Jaeger** — cannot. Its documented `api_v3.QueryService` (`FindTraces`)
+  has no aggregation or grouping parameter of any kind — confirmed
+  against the proto directly, per ADR 013.
+
+### A working Tempo query
+
+```traceql
+{ span.mcp.failure.fingerprint != "" && status = error }
+  | count_over_time() by (span.mcp.failure.fingerprint)
+```
+
+Run this as a TraceQL metrics query (Grafana Explore, Tempo data source)
+over your evaluation window. To alert on it, wrap it in a Grafana alert
+rule with a threshold condition — e.g. fire when any series' value is
+`>= 3` over a 5-minute window. Tune the threshold and window to your own
+traffic; `3` matches this library's own default thrash
+`thrashDetection.threshold` purely for familiarity, not because it's
+derived for fleet-wide monitoring.
+
+**Narrow this to one tool or one deployment by adding more attributes to
+the filter** — e.g. `&& span.gen_ai.tool.name = "lookup_customer"` — the
+same way you'd narrow any other TraceQL query. This doesn't change the
+identity-dimension caveat above: narrowing by tool name still can't tell
+one looping agent apart from several unrelated callers of that same tool.
+
 ## Two modes
 
 ### Quick dev setup
@@ -1662,10 +1952,15 @@ pragmatic choice rather than a spec-pure one.
 - Node.js 20+
 - Windows, macOS, Linux (CI matrix tested)
 - Pure JavaScript, zero native dependencies
-- Supports both low-level `Server` and high-level `McpServer` APIs
-- @modelcontextprotocol/sdk ^1.0.0
+- Supports both low-level `Server` and high-level `McpServer` APIs, from
+  either of two SDKs — see "Both server APIs" and "MCP v2 support" above
+- @modelcontextprotocol/sdk ^1.0.0 (optional peer — v1, protocol revisions
+  through 2025-11-25)
+- @modelcontextprotocol/server ^2.0.0 (optional peer — v2, protocol
+  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
-- 498 tests (`npm test`) — see `test/`
+- 748 tests, 744 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
 
@@ -1720,6 +2015,19 @@ pragmatic choice rather than a spec-pure one.
   a documented, pasteable OpenTelemetry Collector `tailsamplingprocessor`
   config that keeps expensive/budget-exceeded/thrashing traces alongside
   a normal probabilistic sample for everything else.
+- v0.10.0: `@modelcontextprotocol/server` (MCP v2, protocol revision
+  2026-07-28) support ✓ — see "MCP v2 support" above and ADR 015
+  (`docs/adr/015-mcp-v2-support.md`). Spans, standard attributes, failure
+  fingerprinting, `mcp.failure.channel`/`validation_paths` classification,
+  and Agent Thrash Detection (including the transport auto-detection
+  heuristic and the fallback session id under `instanceKey`) all work the
+  same as v1. Also hardened `detectServerKind()` to fail loudly instead of
+  silently instrumenting nothing for an unrecognized/unwrappable server
+  object — a behavior change (an object that previously silently no-op'd
+  now throws), separate from v2 support itself; see the CHANGELOG. 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.
 - 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.9.0",
+  "version": "0.10.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -55,14 +55,24 @@
   "homepage": "https://github.com/Thirumalaiboobathi/opentel-mcp#readme",
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.0.0",
+    "@modelcontextprotocol/server": ">=2.0.0",
     "@opentelemetry/api": "^1.9.0"
   },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "@modelcontextprotocol/server": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@opentelemetry/exporter-trace-otlp-http": "^0.220.0",
     "@opentelemetry/resources": "^2.9.0",
     "@opentelemetry/sdk-trace-node": "^2.9.0"
   },
   "devDependencies": {
+    "@modelcontextprotocol/server": "^2.0.0",
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-metrics": "^2.9.0",
     "@opentelemetry/sdk-trace-base": "^2.9.0",