feat(telemetry): optional OpenTelemetry instrumentation for MCP operations

[getlarge]

Closes #128.

Adds optional OpenTelemetry tracing for MCP operations. Zero cost when no tracer is configured — @opentelemetry/api is an optional peer dep and is only loaded via dynamic import() the first time a span is created.

What's included

• telemetry?: { tracer: TracerLike } on MCPPluginOptions — TracerLike is a structural interface so consumers don't need @opentelemetry/api installed just to import plugin types
• handleRequest wraps each JSON-RPC dispatch in an active span when a tracer is configured, with MCP semconv attributes (mcp.method.name, mcp.session.id, plus mcp.tool.name / mcp.resource.uri / mcp.prompt.name per method)
• withSpan, buildSpanAttributes, MCP_ATTR, TracerLike, HandlerDependencies re-exported from the package root for advanced consumers
• Unit, type-level, and end-to-end integration tests

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: why inlined attribute keys instead of @opentelemetry/semantic-conventions

src/telemetry-constants.ts inlines the six MCP semconv keys as string constants rather than importing from @opentelemetry/semantic-conventions. Reasoning:

• As of @opentelemetry/semantic-conventions@1.40.0, only ATTR_MCP_METHOD_NAME, ATTR_MCP_PROTOCOL_VERSION, ATTR_MCP_RESOURCE_URI, and ATTR_MCP_SESSION_ID are exported. mcp.tool.name and mcp.prompt.name are in the MCP spec but haven't landed in the JS semconv package yet — importing would force a partial-import + hardcoded-strings mix anyway.
• MCP attrs live under semantic-conventions/experimental, an explicitly unstable export path. Coupling to it trades six stable local strings for drift risk on every semconv release.
• The MCP spec itself is the source of truth the semconv package tracks, and the keys are stable there.

There's a // Revisit once all six attrs are exported from a stable semconv path comment in telemetry-constants.ts. Happy to switch to the semconv imports once coverage + path stability catch up, or earlier if you'd prefer to couple to the experimental path now.

Commits

Split into logical chunks for review:

1. chore: add @opentelemetry/api as optional peer dependency
2. feat(telemetry): add telemetry module with dynamic OTel loading
3. feat(telemetry): add TracerLike and telemetry option to MCPPluginOptions
4. feat(telemetry): instrument MCP handlers with OTel spans
5. feat(telemetry): export telemetry utilities from package index
6. test(telemetry): add unit and integration tests

Open questions

• Span kind for the top-level dispatch: INTERNAL (current) or SERVER? Leaning INTERNAL since the Fastify HTTP span is already SERVER.
• SSE broadcast path instrumentation: deferred to a follow-up. Happy to add it here if you'd rather land it together.

Test plan

• npm run typecheck clean
• npm run lint clean
• 13/13 telemetry tests pass (test/telemetry*.ts)
• CI green