opentel-mcp 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,185 @@
 # Changelog
 
+## 0.17.0
+
+Staleness detection: a read tool that returns data older than its own
+freshness window now shows up, even though the call succeeded. Suggested by
+the r/mcp community. Opt-in per tool; tools that don't report freshness
+are untouched. No new metric label keys.
+
+### Added
+
+- **Staleness detection (ADR 027, `docs/adr/027-staleness-detection.md`).**
+  A tool reports freshness in its result's `_meta` under
+  `FRESHNESS_META_KEY` (`'io.github.thirumalaiboobathi.opentel-mcp/freshness'`,
+  a reverse-DNS key per the MCP spec): `{ asOf, maxAgeMs }` or
+  `{ asOf, freshUntil }` (both allowed; the earlier deadline wins).
+  `asOf`/`freshUntil` are epoch milliseconds or ISO 8601 strings with a
+  timezone. Every successful `tools/call` carrying it gets:
+  - span attributes `mcp.tool.freshness.verdict` (`fresh` | `stale` |
+    `unknown`), `.data_age_ms`, `.max_age_ms`, `.limit_source`
+    (`max_age_ms` | `fresh_until` | `config`) and, for `unknown`,
+    `.unknown_reason` (`invalid_as_of` | `future_as_of` | `missing_window`
+    | `invalid_window`);
+  - `+1` on the new `mcp.tool.stale_responses` counter (label:
+    `gen_ai.tool.name` only) when stale.
+  - **Stale is not an error:** span status stays `OK`, no `error.type`,
+    never a silent failure, ToolOutcome stays `SUCCESS`.
+  - Responses without the key get no verdict and no attributes.
+    `isError: true` responses are skipped.
+  - Malformed input (epoch seconds, timezone-less ISO strings, negative
+    windows, `freshUntil` before `asOf`, `asOf` more than 5 s in the
+    future, throwing getters…) never throws: it yields `unknown` with a
+    reason and at most one `diag.warn` per tool.
+  - Only `asOf`, `maxAgeMs` and `freshUntil` under that one key are read;
+    content and other `_meta` fields are never read for this, and raw
+    values never reach spans, metrics or logs (canary-tested).
+- **`staleness` option.** `staleness.tools[toolName].maxAgeMs` overrides a
+  tool's own window (config can't supply `asOf`); `staleness.enabled:
+  false` turns the feature off. On by default, which is a no-op for tools
+  that don't report freshness.
+- **Types:** `FRESHNESS_META_KEY`, `FreshnessMeta` (autocomplete for the
+  `_meta` value), `FreshnessTimestamp`, `FreshnessVerdict`, and
+  `InstrumentOptions.staleness`.
+
+### Security
+
+- **Credentials are scrubbed from recorded exceptions, in every mode.**
+  Bearer and Basic tokens, AWS access key ids, `sk-`/`sk-proj-`/`sk-ant-`,
+  Stripe, `ghp_`/`github_pat_`, Slack `xox…` and Google `AIza…` keys, JWTs,
+  passwords in URLs (`https://user:<password>@host`), and the values of keys like
+  `token=`, `api_key=`, `access_token=`, `password=`, `client_secret` are
+  replaced with `<SECRET>`. Ordinary words and ids (`token expired`, UUIDs,
+  commit hashes) are left alone.
+- **Behavior change: the default `errorRecording.mode: 'full'` is no
+  longer raw and uncapped.** It still records the error's type, message and
+  stack, keeping ids, paths, URLs and line numbers, but with credentials
+  scrubbed as above, the message capped at 4096 characters and the stack at
+  16384 (a ` …[truncated by opentel-mcp]` marker shows where).
+  `exception.type` is capped at 128 characters, as in `'normalized'` mode.
+  Ordinary errors are recorded exactly as before. There is no switch back
+  to unscrubbed output. To record *less*, use `'normalized'`, `'none'`, or
+  a `redactor`.
+- **Fingerprints change only for errors that contain a credential.** The
+  same patterns now run first in `'normalized'` mode and in fingerprinting,
+  so two errors that differ only by a leaked token now share one
+  fingerprint (before, each token value made its own). Expect a one-time
+  regrouping of those errors only.
+- A thrown value whose properties throw when read (e.g. a throwing
+  `message` getter) now still marks the span `ERROR`; before, the span was
+  left with no status.
+- New test: one canary test runs every feature at once (fingerprinting,
+  cost and budget, thrash, schema drift, unactionable errors,
+  resources/prompts coverage, staleness) on SDK v1 and v2, `Server` and
+  `McpServer`, and checks that no tool argument, result content, `_meta`
+  value, resource URI, prompt argument or request `_meta` reaches any span,
+  metric or diag log. Nothing leaked; no code change was needed.
+- New `SECURITY.md` at the repository root: private vulnerability reporting
+  and what the library does and doesn't record.
+
+### Changed
+
+- The cost extractor and staleness detection now read `result._meta`
+  through one shared accessor (`src/result-meta.js`). Extraction behavior is
+  unchanged.
+- Dev-mode metrics (`setupNodeSdk: true`) print 13 instruments, up from 12.
+- README examples and `examples/hello-mcpserver` use `registerTool()`
+  instead of the deprecated `server.tool()`.
+- README's configuration table now lists `unactionableErrors`, `coverage`
+  and `staleness`; the misplaced `unactionableErrors` doc comment in
+  `index.d.ts` is back on its own option.
+- Test: the flush-on-exit "capped at 1000 ms" check now allows up to 5 s
+  (half the uncapped 10 s), so a loaded CI runner can't fail it.
+
+## 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

package/README.md

@@ -77,40 +77,39 @@ import { z } from 'zod';
 
 const server = new McpServer({ name: 'my-server', version: '1.0.0' });
 
-// Wraps every tool registered below. Must run BEFORE server.tool() —
+// Wraps every tool registered below. Must run BEFORE server.registerTool() —
 // see "Ordering constraint" below for why.
-const instrumented = instrumentMcpServer(server, {
+instrumentMcpServer(server, {
   serviceName: 'my-mcp-server', // shows up on your traces
   setupNodeSdk: true, // dev mode: prints traces to your terminal
 });
 
 // A normal tool, registered exactly as usual.
-server.tool('echo', { text: z.string() }, async ({ text }) => ({
+server.registerTool('echo', { inputSchema: { text: z.string() } }, async ({ text }) => ({
   content: [{ type: 'text', text: `you said: ${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
-(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'
@@ -127,10 +126,12 @@ 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
+**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:
+"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
@@ -299,7 +300,7 @@ 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 }) => ({
+server.registerTool('fetch_weather', { inputSchema: { city: z.string() } }, async ({ city }) => ({
   isError: true,
   content: [{ type: 'text', text: `couldn't reach the weather service for ${city}` }],
 }));
@@ -315,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
@@ -344,11 +399,12 @@ The four base `mcp.tool.*` call/duration metrics below, via
 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).
+either way. Source of truth: `src/metrics.js`. Thirteen `mcp.tool.*`
+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), one schema-drift metric
+("Tool schema drift detection" below), and `mcp.tool.stale_responses`
+("Staleness detection" below).
 
 | Metric | Type | Unit | Attributes | Emitted when |
 |---|---|---|---|---|
@@ -449,8 +505,30 @@ What it does, under `setupNodeSdk: true` and `enableMetrics` (default
   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.
+  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
@@ -502,6 +580,181 @@ See `dashboards/grafana-mcp-health.json` and `dashboards/dev/` in the repo
 for a full worked example (dashboard JSON + a script that exercises this
 exact setup end to end).
 
+## Staleness detection (v0.17.0)
+
+A read tool can return data older than it should be: a quote from four
+minutes ago, yesterday's bars after today's session opened. The call
+succeeds, the span is green, and the agent acts on stale data with full
+confidence. opentel-mcp can flag that, if the tool says how fresh its data
+is. The tool is the source of truth, because only it knows its own data
+cadence. Config is only an override. (Suggested by the r/mcp community.)
+
+**It's opt-in, per tool.** A tool adds one key to its result's `_meta`:
+
+```js
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { instrumentMcpServer, FRESHNESS_META_KEY } from 'opentel-mcp';
+import { z } from 'zod';
+
+const server = new McpServer({ name: 'market-data', version: '1.0.0' });
+
+// Before any registerTool() call.
+instrumentMcpServer(server, {
+  serviceName: 'market-data',
+  setupNodeSdk: true, // dev mode: prints spans to stderr
+});
+
+// Stand-in for your real feed. This quote is 4 minutes old.
+async function fetchQuote(symbol) {
+  return { symbol, price: 101.5, timestamp: Date.now() - 4 * 60_000 };
+}
+
+server.registerTool(
+  'get_quote',
+  { description: 'Latest quote for a symbol', inputSchema: { symbol: z.string() } },
+  async ({ symbol }) => {
+    const quote = await fetchQuote(symbol);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(quote) }],
+      _meta: {
+        [FRESHNESS_META_KEY]: {
+          asOf: quote.timestamp, // when the data is from: epoch ms, or ISO 8601 with a timezone
+          maxAgeMs: 5_000, // a quote is fresh for 5 seconds
+        },
+      },
+    };
+  },
+);
+
+await server.connect(new StdioServerTransport());
+```
+
+Save it as `server.js` and send it one call:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_quote","arguments":{"symbol":"ACME"}}}' | node server.js
+```
+
+The span on stderr (from a real run) is still `OK`, and now says why the
+answer shouldn't be trusted:
+
+```
+name: 'tools/call get_quote'
+attributes: {
+  ...
+  'mcp.tool.freshness.verdict': 'stale',
+  'mcp.tool.freshness.data_age_ms': 240001,
+  'mcp.tool.freshness.max_age_ms': 5000,
+  'mcp.tool.freshness.limit_source': 'max_age_ms'
+},
+status: { code: 1 }   // OK: stale data isn't an error
+[opentel-mcp metrics] mcp.tool.stale_responses{gen_ai.tool.name=get_quote} = 1
+```
+
+### The `_meta` contract
+
+`FRESHNESS_META_KEY` is `'io.github.thirumalaiboobathi.opentel-mcp/freshness'`
+(a reverse-DNS key, as the MCP spec recommends for custom `_meta` keys).
+Its value:
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `asOf` | epoch **milliseconds**, or ISO 8601 string **with** `Z`/`±hh:mm` | When the data is from (the quote's timestamp, the bar's close), not when the tool ran. Required. |
+| `maxAgeMs` | number ≥ 0 | How long the data stays fresh. |
+| `freshUntil` | same as `asOf` | An absolute deadline, for windows that aren't a fixed duration. |
+
+Give `asOf` plus `maxAgeMs`, `freshUntil`, or both. With both, the
+**earlier deadline wins**. For data that's good until the trading session
+closes:
+
+```js
+_meta: {
+  [FRESHNESS_META_KEY]: {
+    asOf: bars.closeTime,              // '2026-10-12T20:00:00Z'
+    freshUntil: nextSessionClose,      // '2026-10-13T20:00:00Z'
+  },
+},
+```
+
+TypeScript users get autocomplete from the exported `FreshnessMeta` type:
+`{ asOf, maxAgeMs } satisfies FreshnessMeta`.
+
+### Overriding a tool's window from config
+
+```js
+instrumentMcpServer(server, {
+  staleness: {
+    tools: {
+      get_quote: { maxAgeMs: 2_000 }, // replaces get_quote's own maxAgeMs/freshUntil
+    },
+  },
+});
+```
+
+The override replaces the tool's window entirely (`limit_source` becomes
+`config`). It can't supply `asOf`: a response without the freshness key
+gets no verdict, whatever the config says. An invalid value (negative,
+non-finite) is ignored with one `diag.warn`. `staleness: { enabled: false }`
+turns the whole feature off.
+
+### What gets emitted
+
+| Attribute | Type | When |
+| --- | --- | --- |
+| `mcp.tool.freshness.verdict` | `fresh` \| `stale` \| `unknown` | The tool sent the freshness key |
+| `mcp.tool.freshness.data_age_ms` | integer ms | `asOf` was readable |
+| `mcp.tool.freshness.max_age_ms` | integer ms | A verdict exists: the effective window (deadline minus `asOf`) |
+| `mcp.tool.freshness.limit_source` | `max_age_ms` \| `fresh_until` \| `config` | A verdict exists |
+| `mcp.tool.freshness.unknown_reason` | `invalid_as_of` \| `future_as_of` \| `missing_window` \| `invalid_window` | Verdict is `unknown` |
+
+Plus one counter, `mcp.tool.stale_responses` (label: `gen_ai.tool.name`),
+`+1` per stale response.
+
+- **Tools that don't report freshness get nothing.** No attribute, no
+  verdict; never `fresh`, never `stale`. Their spans are unchanged.
+- **Stale isn't an error.** Span status stays `OK`, there's no
+  `error.type`, and it's never counted as a silent failure. Alert on the
+  verdict or the counter, not on error rate.
+- **`isError: true` responses are skipped.** They're already failures.
+- **Malformed freshness never breaks a call.** It gets `unknown` with a
+  reason, at most one `diag.warn` per tool, and the result goes back to
+  the client untouched. Common mistakes it catches: epoch **seconds**
+  instead of milliseconds, an ISO string with no timezone, `asOf` more than
+  5 s in the future (up to 5 s is treated as clock skew), and `freshUntil`
+  before `asOf`.
+- **Privacy:** only `asOf`, `maxAgeMs` and `freshUntil` under that one key
+  are read. Result content and other `_meta` fields are never read for
+  this, and raw values are never emitted, only the derived numbers
+  (checked by a canary test in `test/staleness.test.js`).
+- **Data age is span-only**, never a metric label.
+
+### Seeing it in the dashboard
+
+`opentel-mcp-ui` 0.3.0+ shows the data age in its feed, a **Stale data**
+filter, and stale rate as a fifth health-grade signal. Start it, then point
+the server above at it with one more option:
+
+```bash
+npx opentel-mcp-ui    # dashboard at http://127.0.0.1:4319
+```
+
+```js
+instrumentMcpServer(server, {
+  serviceName: 'market-data',
+  setupNodeSdk: true,
+  exporterUrl: 'http://127.0.0.1:4319/v1/traces', // send spans to the dashboard too
+});
+```
+
+Each run of the `echo … | node server.js` command above now shows up in the
+dashboard's feed and under **Stale data**. The tool gets a grade once it has
+10 calls, and the stale-data signal joins it once 10 of those carried a
+`fresh` or `stale` verdict, so send the command ten times. With every call
+stale, `get_quote` grades **F**, "set by stale data 100% (F)".
+
+Design and every edge case: [ADR 027](../../docs/adr/027-staleness-detection.md).
+
 ## Failure Fingerprinting (v0.4.0+)
 
 Groups logically identical failures under one stable identifier, even
@@ -586,7 +839,11 @@ per-call-site wrapping; tracked in the roadmap below.
 **What this controls, and who needs it.** Whenever a `tools/call`/
 `tools/list` handler throws, this library records the thrown error's
 message and stack trace onto the span it creates for that call — by
-default, exactly as the tool wrote them, no redaction. If your tools call
+default, as the tool wrote them, except that recognizable credentials
+(Bearer/Basic tokens, AWS key ids, `sk-`/`ghp_`/`xox…` API keys, JWTs,
+passwords in URLs, `token=`/`api_key=`/`password=` values) are replaced
+with `<SECRET>` and the message and stack are capped at 4096 and 16384
+characters (v0.17.0). If your tools call
 third-party services, wrap unaudited dependencies, or you otherwise don't
 control every string a tool might throw, that's a real channel for
 whatever those errors happen to contain (an email address, an internal
@@ -606,7 +863,7 @@ span:
 
 | Mode | `exception.message` / status message | `exception.stacktrace` | When to use |
 |---|---|---|---|
-| `'full'` (default) | Raw `err.message`, unmodified | Raw `err.stack`, unmodified | Today's behavior, unchanged — matches what every other OTel-instrumented library in the same trace does for the same kind of event |
+| `'full'` (default) | Raw `err.message`, credentials → `<SECRET>`, capped at 4096 chars (v0.17.0) | Raw `err.stack`, same scrubbing, capped at 16384 chars | Everything else kept: ids, paths, URLs, line numbers. Before v0.17.0 both were unmodified |
 | `'normalized'` | `normalizeMessage(err.message)` — the exact scrubbing pipeline (`src/fingerprint/normalize/message.js`) fingerprinting already runs before hashing: UUIDs, emails, URLs, IPs, timestamps, filesystem paths, hex runs, quoted ids | Reconstructed from `parseAndNormalizeStack()` (`src/fingerprint/normalize/stack.js`) — keeps every function name/file/line, strips only the local `cwd` prefix (and collapses `node_modules` package versions) | Tool results come from third-party or unaudited MCP servers and you want the same scrubbing fingerprinting already trusts, applied to the raw exception content too |
 | `'none'` | Not set — `span.setStatus({ code: ERROR })` with no message, the same pattern already used for tool-level `isError: true` failures | Not set | You rely entirely on `mcp.failure.*` (category/fingerprint/signature — already hashed/normalized) and don't want any free-text exception content on the span at all |
 
@@ -2144,11 +2401,13 @@ found')`, or a tool result puts a credential in a field this library
 reads, that content is exactly what reaches your telemetry backend. Three
 channels carry it:
 
-- **`span.recordException(err)` / `span.setStatus({ message })`** on every
+- **The `exception` event / `span.setStatus({ message })`** on every
   thrown `tools/call`/`tools/list` error — `exception.message` and
-  `exception.stacktrace` are set from `err.message`/`err.stack` verbatim
-  by default. `errorRecording.mode` controls this; see "Error recording"
-  above.
+  `exception.stacktrace` are set from `err.message`/`err.stack` by
+  default, with recognizable credentials replaced by `<SECRET>` and
+  lengths capped (v0.17.0), but otherwise unchanged: a customer's name or
+  any other free text in a message still reaches the span.
+  `errorRecording.mode` controls this; see "Error recording" above.
 - **`mcp.tool.model` / `gen_ai.response.model`** — a tool result's own
   declared model field, admitted once it passes a length/character-shape
   check (v0.13.0). The check bounds shape, not content: a well-formed but
@@ -2241,9 +2500,11 @@ 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.tool.freshness.verdict` / `.data_age_ms` / `.max_age_ms` / `.limit_source` / `.unknown_reason` | span attr | library-computed | enums and integer ms derived from the tool's own `_meta[FRESHNESS_META_KEY]` `asOf`/`maxAgeMs`/`freshUntil`; raw values are never emitted, and no other `_meta` field or content is read (ADR 027, v0.17.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 |
+| `exception.type` (event) | event attr | tool-controlled | length-capped at 128 characters under both `'full'` and `'normalized'` (v0.17.0) |
+| `exception.message` / `.stacktrace` (event), status message | event attr + status | **blend — layered** | raw tool content under `'full'`, minus recognizable credentials and length-capped (v0.17.0); 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 |
 | `mcp.tool.schema_drift_detected` / `mcp.tool.thrash_detected` | boolean span attr | library-computed | only ever set to `true`; omitted on a clean call |
 | `mcp.tool.schema_drift.type` | event attr, metric label | library-computed | classifier enum |
 | `mcp.tool.schema_drift.previous_hash` / `.current_hash` | event attr | library-computed | a hash *of* tool-controlled content (the tool's own `inputSchema`), not the schema itself |
@@ -2321,6 +2582,9 @@ truth: `src/config.js`.
 | `thrashDetection` | object | see below | Controls Agent Thrash Detection[^10] — see "Agent Thrash Detection" above. Requires `fingerprinting: true` |
 | `schemaDrift` | object | see below | Controls tool schema drift detection[^11] — see "Tool schema drift detection" above. `enabled: true` by default changes `instrumentMcpServer()`'s throw behavior on upgrade — see that section's "Behavior change on upgrade" |
 | `errorRecording` | object | see below | Controls what raw exception content reaches `recordException()`/`setStatus()`[^12] — see "Error recording" above |
+| `unactionableErrors` | object | `{ enabled: true, minTextLength: 10 }` | `{ enabled?, minTextLength? }`: flags `isError: true` results with no usable text via `mcp.failure.unactionable` / `mcp.failure.content_length_bucket` (span-only). Env: `OTEL_MCP_UNACTIONABLE_ERRORS_ENABLED`, `OTEL_MCP_UNACTIONABLE_ERRORS_MIN_TEXT_LENGTH` — see "Errors your agent can't act on" above |
+| `coverage` | object | `{ resources: false, prompts: false }` | Opt-in tracing of `resources/*` and `prompts/*` — see "Resources and prompts" above |
+| `staleness` | object | `{ enabled: true }` | `{ enabled?, tools?: { [toolName]: { maxAgeMs } } }`: per-tool override of the freshness window a tool reports in `_meta` — see "Staleness detection" above |
 
 [^10]: `{ enabled?, threshold?, windowMs?, maxTrackedKeys?, entryTtlMs?, reEmitAfter?, assumeSingleSession? }`, all fields optional, individually defaulted, and individually overridable via an `OTEL_MCP_THRASH_*` env var — see "Agent Thrash Detection" → "Configuration" above for the full table.
 [^11]: `{ enabled?, maxTrackedTools? }`, all fields optional, individually defaulted, and individually overridable via an `OTEL_MCP_SCHEMA_DRIFT_*` env var — see "Tool schema drift detection" → "Configuration" above for the full table.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentel-mcp",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "One-line OpenTelemetry instrumentation for Model Context Protocol (MCP) servers",
   "type": "module",
   "main": "src/index.js",
@@ -73,7 +73,8 @@
     "@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-trace-base": "^2.9.0",