feat(mcp-bridge): OTLP/HTTP+JSON span emission (epic #87 item 13)

[hyperpolymath]

Summary

Closes the second Tier A item of epic #87. Every `tools/call` now emits an OTLP/JSON span to the user's collector (Tempo, Jaeger, Honeycomb, Grafana Agent, OTel Collector). Pairs naturally with the `observe-mcp` / `grafana-mcp` / `prometheus-mcp` cartridges — one telemetry destination, one pane.

Why hand-rolled (no `@opentelemetry/api`)

The bridge has zero runtime deps by policy (package.json + CLAUDE.md). Adding ~30 transitive packages for what is structurally a few JSON-RPC wrappers isn't proportionate. OTLP/HTTP+JSON is a stable wire spec; any conformant collector accepts these payloads. ~200 LOC vs ~30 npm packages.

Off by default

Enabled only when `OTEL_EXPORTER_OTLP_ENDPOINT` is set. `startSpan()` returns `null` when disabled; `endSpan(null)` is a guarded no-op. Zero runtime cost when unused.

Env vars (declared in `glama.json`)

Var	Default	Purpose
`OTEL_EXPORTER_OTLP_ENDPOINT`	unset → off	OTLP/HTTP collector URL (e.g. `http://localhost:4318\`)
`OTEL_SERVICE_NAME`	`boj-server`	Resource attribute on every span
`OTEL_SERVICE_VERSION`	`0.4.7`	Resource attribute
`OTEL_BATCH_MS`	`5000`	Span-batch flush interval
`OTEL_EXPORTER_OTLP_HEADERS`	unset	CSV `key=value,…` for auth/tenant headers (e.g. Honeycomb)

Instrumentation

• `tools/call` → span `mcp.tools.call` with attributes:
  • `mcp.tool.name` (string)
  • `mcp.tool.arg_count` (int)
• Status codes (OTLP `status.code`):
  • `1` (OK) on successful dispatch
  • `2` (ERROR) on tool failure, with sanitized error message
  • `2` (ERROR) on hardening-gate rejection, with `mcp.rejection.code` attribute so dashboards can split by reason

Future PRs can wrap `resources/read` and `prompts/get` once #89 lands.

Batching + shutdown safety

• 5s default flush interval (overridable)
• Hooks on `beforeExit`, `SIGTERM`, `SIGINT` force a final flush
• Bounded re-buffer on transport failure (cap 10k spans to avoid runaway)
• `setInterval` is `unref()`'d so it doesn't keep the process alive after stdin closes

Tests

• Disabled-mode: `isEnabled() === false`; `startSpan` returns `null`; `endSpan(null)` is safe; `flush()` is no-op
• Enabled-mode: `traceId` matches `/^[0-9a-f]{32}$/`; `spanId` matches `/^[0-9a-f]{16}$/`; `startNs` is digit string
• 13/13 tests pass (11 existing + 2 new)
• End-to-end smoke: `tools/call boj_health` succeeds with no `OTEL_*` env set; no behavior change observable from the MCP client

What this enables

• Per-tool latency histograms in Grafana via OTLP → Tempo
• Cardinality-controlled tool-call counts in Prometheus (via collector translation)
• Trace-driven debugging when a multi-cartridge composition (e.g. `audit-repo` prompt from feat(mcp-bridge): implement resources + prompts surface (epic #87 item 1) #89) goes wrong — every step is a span on the same trace

Sequencing

Independent of #88 (publish workflow) and #89 (resources/prompts). Can land in any order.

🤖 Generated with Claude Code

[github-actions]

🔍 Hypatia Security Scan

Findings: 29 issues detected

Severity	Count
🔴 Critical	18
🟠 High	4
🟡 Medium	7

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Issue in quality.yml",
    "type": "missing_workflow",
    "file": "quality.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in security-policy.yml",
    "type": "missing_workflow",
    "file": "security-policy.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Python file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/.github/scripts/validate-eclexiaiser.py",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence

[github-actions]

🔍 Hypatia Security Scan

Findings: 29 issues detected

Severity	Count
🔴 Critical	18
🟠 High	4
🟡 Medium	7

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Issue in quality.yml",
    "type": "missing_workflow",
    "file": "quality.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in security-policy.yml",
    "type": "missing_workflow",
    "file": "security-policy.yml",
    "action": "create",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Action hyperpolymath/standards/.github/workflows/governance-reusable.yml@main needs attention",
    "type": "unpinned_action",
    "file": "governance.yml",
    "action": "pin_sha",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Python file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/.github/scripts/validate-eclexiaiser.py",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence