opentel-mcp 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,166 @@
 # 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
+feature below.** The `auth` failure classifier
+(`src/fingerprint/classify/auth.js`) missed "permission denied" and
+"access denied" — the standard phrasing from Unix, git, AWS IAM, and GCP
+for a permission/authorization failure. It only recognized
+HTTP-status-derived wording (`unauthorized`, `forbidden`,
+`authenticat(e|ion)`) plus 401/403 status codes and a handful of known
+auth-library error names. Messages using the OS/CLI phrasing above fell
+through every classifier and landed in the `internal` catch-all instead.
+Found by running realistic error text through this project's own UI demo
+(`packages/ui/demo/populate.js`) and checking what `DEFAULT_CLASSIFIERS`
+actually returned for it — not assumed. Now also matches "not authorized",
+"permission(s) denied", "access denied", "insufficient permission(s)", and
+Node's own `EACCES`/`EPERM` error codes; still does not match bare
+"authorized" or "permission" alone (see the classifier's own docblock for
+the false-positive cases this deliberately excludes, e.g. "user denied the
+permission request").
+
+**This changes fingerprints for affected messages.** `category` is one of
+the hashed inputs `computeFingerprint()` combines into
+`mcp.failure.fingerprint` (see ADR 006). A permission-denied failure that
+previously classified as `internal` now classifies as `auth` — the fields
+feeding the hash change, so the fingerprint itself changes for anyone whose
+tool emits this wording. This does **not** amend the closed 8-category
+taxonomy ADR 006 established (`validation | timeout | network | auth |
+dependency | serialization | internal | unknown`) — `auth` already existed;
+this is a pattern-coverage fix to when the existing category fires, not a
+new category. If you alert or dashboard on a specific `mcp.failure.fingerprint`
+value for a permission error, expect a new value after upgrading.
+
+### Added — `instanceKey`: sharing tracker state across `instrumentMcpServer()` calls
+
+`instanceKey` (a string option on `instrumentMcpServer()`, or the
+`OTEL_MCP_INSTANCE_KEY` env var — lower precedence than the option) lets
+repeated `instrumentMcpServer()` calls that pass the same key share Agent
+Thrash Detection, budget tracking, schema drift detection, and the
+`ToolOutcome` counter's state, instead of each call constructing all four
+fresh and discarding them. Fixes the gap documented in the README's
+"In-memory tracker state is scoped to one `instrumentMcpServer()` call"
+section and `docs/known-gaps.md` entry 6, under a "stateless" Streamable
+HTTP deployment shape (a fresh `Server`/`McpServer` re-instrumented on
+every incoming request). Full design: ADR 012
+(`docs/adr/012-tracker-lifecycle-and-shared-state.md`).
+
+Backed by an internal, bounded, TTL-evicting registry (1000 distinct keys
+per process, 24h TTL renewed on every use — both ADR 012's proposed
+defaults) — fully internal, no new public type. Omit `instanceKey` (the
+default) for behavior byte-identical to every prior version: trackers are
+constructed fresh on every call, and the registry is never touched.
+
+**⚠️ Composition requirement: `instanceKey` alone does not fix Agent
+Thrash Detection.** `ThrashDetector` looks episodes up by `(sessionId,
+toolName, fingerprint)` — `instanceKey` shares the tracker object, but
+without a real, transport-provided `extra.sessionId` on every call, each
+`instrumentMcpServer()` call still generates its own random per-connection
+fallback session id, fresh, regardless of `instanceKey`. Sharing the
+tracker doesn't help if the lookup key inside it differs every call —
+each request lands as its own one-off episode instead of contributing to
+one shared loop. Real Streamable HTTP transports provide a real session id
+automatically, so the common case works with `instanceKey` alone — but a
+custom `Transport`, `assumeSingleSession: true`, or anything else on the
+generated-fallback path will set `instanceKey`, see nothing happen, and
+have every reason to think the fix is broken. Same silent-inertness shape
+as the original gap, one layer deeper. See the README's new "instanceKey"
+section for the full explanation and what to do about it — this is not a
+footnote there either.
+
+**⚠️ Does not help across process boundaries.** `instanceKey`'s registry
+is one process's in-memory state. On Lambda, Cloud Run, or any
+horizontally-scaled deployment, concurrent/recycled instances each hold
+their own independent registry — passing the identical `instanceKey`
+string everywhere does not change that. Counters remain instance-local and
+best-effort by design; this is a structural limitation, not a
+configuration gap, and this library deliberately does not add an external
+store (Redis/DynamoDB) to close it — see ADR 012's Update section for the
+full reasoning.
+
+**Documentation:** the "Metrics" section now covers wiring the Prometheus
+exporter specifically (`@opentelemetry/exporter-prometheus`), not just the
+OTLP example that was already there. Its pull-based text exposition format
+does not attach resource attributes (including `service.name`) to
+individual metric points by default — only to a separate `target_info`
+series — which is invisible with one service but means every series looks
+identical the moment you're scraping more than one instrumented server
+into the same Prometheus. Documents the fix
+(`withResourceConstantLabels: /^service\.name$/`) with a worked example.
+No code change; this behavior was always there, just undocumented. Found
+building `dashboards/grafana-mcp-health.json`'s verification harness.
+
 ## 0.8.0
 
 Three features. **Tool schema drift detection**: a server that silently