feat(telemetry): optional OpenTelemetry instrumentation for MCP operations

[getlarge]

Closes #128.

Adds optional OpenTelemetry tracing for MCP server operations. There is no telemetry-path overhead when no tracer is configured; @opentelemetry/api remains an optional peer dependency and is loaded dynamically only when tracing is enabled.

What's included

• telemetry?: { tracer: TracerLike } on MCPPluginOptions. TracerLike is structural, so consumers do not need @opentelemetry/api installed merely to import plugin types.
• MCP requests and notifications are wrapped in active SERVER spans.
• Span names follow {mcp.method.name} {target} for tool and prompt operations, for example tools/call echo.
• Attributes follow the current MCP/GenAI conventions, including:
  • mcp.method.name, mcp.session.id, and mcp.protocol.version
  • gen_ai.tool.name, gen_ai.prompt.name, and gen_ai.operation.name
  • jsonrpc.request.id, rpc.response.status_code, and error.type
  • mcp.resource.uri where applicable
  • network.transport and HTTP network.protocol.* attributes
  • server-side client.address and client.port when available
• W3C trace context and baggage are extracted from MCP params._meta through the configured OpenTelemetry propagator. When a remote MCP parent is present, the ambient HTTP span is linked rather than used as the MCP span parent.
• Streamable HTTP/SSE is recorded as TCP (or QUIC when applicable) plus HTTP protocol attributes; the stdio adapter records network.transport = pipe.
• JSON-RPC and tool errors update span attributes/status according to the MCP conventions. Successful spans remain UNSET rather than being forced to OK.
• Tool arguments and results are not captured because those convention fields are opt-in and may contain sensitive data.
• withSpan, buildSpanAttributes, MCP_ATTR, TracerLike, and HandlerDependencies are exported for advanced consumers.

Usage

import { trace } from '@opentelemetry/api'
import mcpPlugin from '@platformatic/mcp'

await app.register(mcpPlugin, {
  telemetry: { tracer: trace.getTracer('my-mcp-server', '1.0.0') },
})

Design note: local semantic-convention constants

The MCP conventions are still marked Development and now live in the OpenTelemetry GenAI semantic-conventions repository. The current convention uses gen_ai.tool.name and gen_ai.prompt.name; the older mcp.tool.name and mcp.prompt.name names are not used.

@opentelemetry/semantic-conventions does not provide the complete current set through its stable entry point. Its earlier MCP exports were incubating, and version 1.42 deprecated them after MCP/GenAI conventions moved to the separate GenAI repository. The package also recommends copying unstable definitions into instrumentation libraries instead of importing the incubating entry point at runtime.

For those reasons, this PR keeps the small set of required keys in src/telemetry-constants.ts, with a source link to the current GenAI MCP specification. This avoids adding a runtime semantic-conventions dependency while making convention drift explicit and reviewable.

Upstream reconciliation

The branch includes upstream main through v2.4.0 and preserves the newer tool authorization, task, and onToolCallComplete behavior alongside telemetry instrumentation.

Test plan

• npm run typecheck
• npm run lint
• npm run test:types
• npm run build
• 78 focused telemetry, HTTP/stdio transport, protocol negotiation, authorization, in-process tool-call, and completion-hook tests
• GitHub Actions green on Node.js 22 and 24

[mcollina]

lgtm

[mcollina]

Can you fix the conflicts?

[getlarge]

@mcollina done, also updated to reflect progress in https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/mcp.md#recording-mcp-transport