feat(mcp): add request log writer (PoC for #1351)

[nhangen]

Refs #1351.

Summary

Wraps the CallToolRequestSchema handler with an instrumented() helper that appends one JSONL line per tools/call to a configurable log file:

{"ts":"2026-05-10T18:00:00Z","tool":"impact","durationMs":214,"resultBytes":1834,"error":null}

The same wrapper can host an OTLP span emitter alongside or instead of the JSONL writer — the single seam is src/mcp/server.ts:166.

Changes

• gitnexus/src/mcp/request-log.ts — resolveLogPath(), appendRequestLog(), instrumented(toolName, fn, resultBytesOf?, errorOf?). Async append, mkdir -p on the parent, errors swallowed.
• gitnexus/src/mcp/server.ts — wraps the existing handler. Behaviour unchanged when logging is disabled. errorOf reads the { isError: true, ... } envelope so tool errors land in the log with their message (the handler converts thrown errors into a returned envelope, so the wrapper's catch branch never sees them).
• gitnexus/test/unit/mcp/request-log.test.ts — 14 unit tests.

Configuration

Opt-in default:

GITNEXUS_MCP_REQUEST_LOG	Result
unset / empty	disabled
off / false / 0	disabled
on / true / 1	~/.gitnexus/mcp-requests.log
/abs/path/log	that path

Privacy

Tool inputs (params/rawArgs) are never logged. The error field captures error messages verbatim; tool errors routinely echo input (cypher parse errors include the offending clause, etc.). Treat the log as input-adjacent.

Verify

cd gitnexus
npm install
npx vitest run test/unit/mcp/request-log.test.ts   # 14 pass

End-to-end after npm run build:

GITNEXUS_MCP_REQUEST_LOG=on gitnexus mcp
# drive via any MCP client, then:
cat ~/.gitnexus/mcp-requests.log

Risk

• One JSON.stringify + one fs.appendFile per tool call. Fire-and-forget; the request handler returns without awaiting.
• In-flight writes can be lost on shutdown() — no drain in this PoC. See decision table below.
• Unbounded log size — no rotation in this PoC.
• Rollback: revert the commit. No DB, schema, or index changes; no new runtime deps.

Recommended decisions for v1

#	Decision	Recommendation
2	JSONL only vs JSONL + OTLP	Both. JSONL stays as the local fallback; OTLP exporter behind OTEL_EXPORTER_OTLP_ENDPOINT. Same wrapper hosts both.
3	Log tool input vs size-only	Size-only. error already leaks input under failure; broadening would move privacy backwards.
4	Log rotation	Daily rotation, 30-day retention, opt-out via env. Free with pino transports (see #6).
5	Drain on shutdown()	Yes — await Promise.allSettled(pending) before server.close(). Cheap and bounded.
6	Hand-rolled appendFile vs core/logger.ts (pino)	Refactor to pino. createLogger('mcp-requests', { ... }) gives NDJSON, log-injection hardening, and the existing test seam.

One open question

Opt-in or opt-out default? Opt-in maximises privacy posture; opt-out gives server-side ground truth without setup. Both are one line in resolveLogPath(). Maintainer's call.

Draft until that decision lands and we scope whether #2/#4/#5/#6 ship in this PR or as follow-ups.

---

Local CI:

• npx vitest run test/unit/mcp/request-log.test.ts — 14 pass.
• npx tsc --noEmit — clean on the changed files (baseline has unrelated tree-sitter errors from --ignore-scripts install).
• .husky/pre-commit not run locally; please verify in CI.

[vercel]

@nhangen is attempting to deploy a commit to the NexusCore Team on Vercel.

A member of the Team first needs to authorize it.

[nhangen]

Apologies for the noise here. I misread the assignment on the first pass — @magyargergo asked for OpenTelemetry/Prometheus with quantized, anonymous metrics, and I shipped a JSONL request log instead, with OTel framed as a follow-up. That inverts the ask. Closing this and starting fresh with an OTel meter + Prometheus exporter as the primary path. Will open a new PR shortly.

[magyargergo]

@nhangen this could be interesting 🧐 I'm open for something new if they are well tested in practice and there are working solutions. :)