feat(mcp-server): metrics and tracing telemetry (prompt 19)

[gilgardosh]

Summary

Implements Prompt 19 — Metrics and tracing integration from
docs/mcp/implementation-blueprint.md,
adding the operational telemetry required for production readiness (spec §11.2/§11.3). Stacked on
top of the prompt 18 branch (claude/mcp-prompt-18-rate-limiting).

What's included

Metrics registry — src/observability/metrics.ts

• requestsTotal — request counter keyed by "<tool>|<outcome>" (outcome is success or a
  taxonomy-derived error class).
• latencyMs — cumulative latency histogram (fixed ms buckets + +Inf, with count/sum).
• authFailuresTotal — auth-failure counter keyed by reason (missing_token, invalid_token).
• upstreamErrorsTotal — upstream failure counter keyed by category.
• rateLimitedTotal — total rate-limited requests.
• outcomeForCode() maps every error taxonomy code to its outcome label.
• Process-wide memoized singleton via getMetrics(). Labels carry no PII — only tool names,
  outcome classes, and error categories.

Tracing spans — src/observability/tracing.ts

• Dependency-free withSpan(name, correlationId, fn) emitting structured span start/span end
  debug logs with the correlation id and duration.
• Wired around token verification (auth:verify), tool execution (tool:<name>), and each upstream
  GraphQL call (upstream:graphql).

Wiring

• The tool executor records outcome + latency (and rate-limited/upstream sub-counters) via an
  optional injected Metrics.
• The transport handler records auth-failure counters by reason.
• GET /metrics exposes a snapshot.
• Correlation id already propagates upstream via the X-Correlation-Id header; the upstream span
  makes each call traceable.

Testing

• src/observability/__tests__/metrics.test.ts — counters, histogram bucketing, snapshot, reset,
  singleton, and full outcomeForCode mapping.
• src/observability/__tests__/tracing.test.ts — withSpan result passthrough, start/end logging,
  and error re-throw with a failed span.
• src/tools/__tests__/metrics.execute.test.ts — executor records success / validation_error /
  rate_limited outcomes and is a no-op without a registry.

yarn workspace @accounter/mcp-server typecheck, lint, and test (224 passing) all green.

🤖 Generated with Claude Code

---

Generated by Claude Code

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[Copilot]

Pull request overview

Adds production-oriented telemetry to the @accounter/mcp-server package by introducing an in-memory metrics registry and lightweight tracing spans, then wiring both into request authentication, tool execution, and upstream GraphQL calls, with a /metrics endpoint and accompanying tests/docs.

Changes:

• Introduces Metrics (counters + latency histogram) and exposes a process-wide snapshot at GET /metrics.
• Adds dependency-free withSpan() tracing and wraps auth verification, tool execution, and upstream GraphQL queries.
• Wires metric recording into the tool executor and auth handler; adds vitest coverage for metrics/tracing behavior.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/mcp-server/src/upstream/graphql-client.ts	Wraps upstream GraphQL query retries in a tracing span keyed by correlation id.
packages/mcp-server/src/tools/execute.ts	Records per-tool outcomes/latency to an optional metrics registry and wraps tool handlers in spans.
packages/mcp-server/src/tools/tests/metrics.execute.test.ts	Adds executor-level tests ensuring metrics are recorded (and no-op when absent).
packages/mcp-server/src/server.ts	Exposes GET /metrics returning the in-memory metrics snapshot.
packages/mcp-server/src/observability/tracing.ts	Adds lightweight span helper emitting structured start/end debug logs.
packages/mcp-server/src/observability/metrics.ts	Adds in-memory metrics registry, snapshot/reset, and outcome mapping.
packages/mcp-server/src/observability/tests/tracing.test.ts	Tests span logging, passthrough behavior, and error rethrow semantics.
packages/mcp-server/src/observability/tests/metrics.test.ts	Tests counters, histogram bucketing, snapshot/reset, and singleton behavior.
packages/mcp-server/src/mcp/handler.ts	Records auth-failure metrics and spans token verification; injects metrics into tool execution.
packages/mcp-server/README.md	Documents the new metrics snapshot endpoint and tracing behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.