feat(mcp-server): log the initialize handshake

[gilgardosh]

Why

The connector went blind between Aug 18 and Aug 26 — every tool returned its summary line and no
rows. #4295 fixes the cause (rows lived only in structuredContent, a field a client may ignore).

This PR addresses the second problem that incident exposed: the server had no idea the client
had changed.

Establishing that it was the client took a rollback test — checking out e31e8066, the commit
that demonstrably worked on Aug 18 including a successful tag write, and running it today reproduces
the failure exactly. Same commit, same server, opposite outcome. Confirming it then meant reading
Claude Desktop's own log directory:

Date	Log file	Event vocabulary	Outcome
Aug 10	main.log	Making remote MCP tool call: accounter_get_charges → Remote tool call succeeded	rows arrived
Aug 26	claude.ai-web.log	[MCP] tool_approval_gate {"toolName":"Accounter:accounter_search_charges",…}	rows missing

None of that should have required someone's ~/Library/Logs. initialize (handler.ts) never read
request.params and never logged, so there was no record of the client's name, its version, the
protocol revision it asked for, or the capabilities it declared. The connector already logs every
tool call and every auth failure — the handshake was the one hop with no trace.

What

Every initialize emits one structured line tagged event: "mcp_initialize", joining tool_call
as the second selectable event:

Field	Why
clientName, clientVersion	the fields that date a client-side behaviour change
requestedProtocolVersion / servedProtocolVersion	what was asked vs what we answered
protocolVersionMismatch	the one field worth alerting on
clientCapabilities	names only, sorted — values are unbounded and caller-supplied
userId, correlationId	matches tool_call, so a session joins across both events

Three decisions worth reviewing

Logged from dispatchMcpRequest, not from the case 'initialize' that builds the response.
handleRpcRequest is the pure, env-free half and takes only the request — it has neither the caller
nor the correlation id to log. Delegating to it afterwards keeps the response built in exactly one
place, so the two cannot drift. The sync handleMcpBody path has no production call sites and stays
silent, which conveniently leaves its existing test of the pure response shape untouched (there's a
test asserting that silence).

describeInitializeParams is total. params is unknown off the wire and validated only as a
non-null object or array, so every field is narrowed there and anything unexpected degrades to
null/[]. A malformed handshake must still produce a line — a client sending something the server
cannot parse is precisely the event worth seeing, and an exception would lose it. Covered with
params as null, a string, an array, a number, and a clientInfo that is variously a string, an
array, null, or has non-string fields.

Caller-derived fields are spread beneath the canonical ones, matching the tool_call line.
Without it, clientInfo would be an authenticated way to attribute a call to a different userId —
there's a test for that specifically. Client strings are clipped before reaching the log.

Deliberately excluded

• A labeledTotals counter keyed by client version. /metrics is unauthenticated while calling
  a tool requires a token — already flagged in the runbook as worth closing — and client identity is
  a fingerprint of the deployment. It belongs in the log rather than on a public endpoint. Worth
  revisiting once /metrics is gated.
• Protocol-version negotiation. The server keeps answering 2025-06-18 unconditionally; this
  only records what was asked. Changing what the server advertises is a live behavioural change to a
  connector that has just broken once, and should be decided against a logged mismatch rather than a
  guess — which is what protocolVersionMismatch now provides.

Verification

• 785 tests pass (53 files), 14 of them new; typecheck, eslint and prettier clean
• The initialize response is unchanged — asserted directly; this adds a log line, not a new
  response
• Docs: README gains a "Handshake logging" section; runbook gains §3.1 with the field reference and
  jq recipes (the cross-reference from README was renumbered to match)

Note the first real run will answer something this investigation could not: which protocol revision
Claude Desktop 1.37937.1 actually negotiates.

🤖 Generated with Claude Code

[github-actions]

🚀 Snapshot Release (alpha)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package	Version	Info
@accounter/client	0.1.0-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎
@accounter/green-invoice-graphql	0.8.7-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎
@accounter/hashavshevet-mesh	0.2.13-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎
@accounter/israeli-vat-scraper	0.1.13-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎
@accounter/modern-poalim-scraper	0.11.0-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎
@accounter/payper-mesh	0.2.13-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎
@accounter/scraper-app	0.0.3-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎
@accounter/server	0.2.0-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎
@accounter/shaam-uniform-format-generator	0.2.7-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎
@accounter/shaam6111-generator	0.1.9-alpha-20260827074134-8e15b7dbde9c5f6555c22f5a0b64e97df041cd7a	npm ↗︎ unpkg ↗︎

[Copilot]

🟢 Approval recommended

The change is low-risk (additive logging + tests + docs) and does not alter protocol responses or tool execution behavior.

Pull request overview

Adds structured logging for the MCP initialize handshake so the server can attribute behavior changes to specific clients (name/version/capabilities/protocol) without relying on client-side logs—complementing existing per-tool-call logging.

Changes:

• Emit a single structured event: "mcp_initialize" log line per initialize call (including client info, protocol versions, capabilities, userId, correlationId).
• Add parsing/clipping helper (describeInitializeParams) plus unit tests and handshake logging tests.
• Document the new log event in the package README + operations runbook, and publish via a changeset.

File summaries

File	Description
packages/mcp-server/src/mcp/handler.ts	Introduces mcp_initialize event logging on initialize and adds total parsing + clipping helpers for client-supplied fields.
packages/mcp-server/src/mcp/tests/handler.test.ts	Adds unit tests for parameter parsing and verifies exactly-one handshake log line + invariants.
packages/mcp-server/README.md	Documents handshake logging semantics and how it relates to tool-call usage logging.
packages/mcp-server/docs/operations-runbook.md	Adds a dedicated section for handshake log fields and jq recipes for analysis/alerting.
.changeset/mcp-log-initialize-handshake.md	Bumps @accounter/mcp-server with a patch changeset describing the new logging behavior.

Review details

Suppressed comments (1)

packages/mcp-server/src/mcp/tests/handler.test.ts:556

• dispatchMcpRequest is exercised here with a primitive string params, but the real HTTP path rejects primitive params in asJsonRpcRequest. Using an array keeps the “unparseable handshake still logs” intent while matching a shape that can actually arrive over JSON-RPC.

    await initialize('not-an-object');

• Files reviewed: 5/5 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.