Skip to content

CodeWitness 1.0.25

Choose a tag to compare

@github-actions github-actions released this 09 Nov 14:28
· 1 commit to main since this release

CodeWitness 1.0.25 gives the MCP server a voice: codewitness mcp now prints one line on standard error as it
starts listening — version, protocol revision and the tools it is about to advertise. A stdio MCP server is silent
by protocol and the harness that spawns it logs nothing when a connection succeeds, so "the server came up" and
"the server never came up" were indistinguishable from the outside. The diagnostics stream is now injected rather
than named, so the test asserts the channel an operator actually reads.

What changed

  • The MCP server announces itself once, on standard error, as it starts listening. The line is
    [codewitness] MCP server ready: 1.0.25, protocol 2025-06-18, 7 tools: version, inspect, test, verify, report, issues, reproduce — the version, the protocol revision the server implements, and the tool list the client is
    about to see. It is written before the first request is read, so it appears in the client's console at the
    moment the process is up rather than at the moment something is first asked of it.

  • The diagnostics stream is a constructor argument, not System.err by name. McpServer gained a
    four-argument constructor taking the stream its banner and its failure notes are written to; the three-argument
    constructor delegates to it with System.err, so existing call sites and tests compile unchanged. The three
    notes that used to reach for System.err — stdin failed, cannot write protocol response, and the stack
    trace of an unexpected tool fault — now go through the same stream. That is what lets the new test read the
    channel the operator reads instead of capturing a global.

  • The tool list in the banner is the list the server advertises. McpTools.toolNames() became
    package-private, so the banner and the unknown-tool error message read one string rather than two copies.

  • Why the server has to be the one to speak. The asymmetry that raised this issue is a difference of
    transport, not of diligence. A harness plugin runs inside the harness process, so its startup console.log
    lands on the harness's own stdout — that is how dsh-file-upload announces the MarkItDown CLI. An MCP server
    is a child process: its stdout is the JSON-RPC channel, where one non-JSON byte ends the session, so it can
    never print there. The harness does not cover the gap either — @deepseek-ai/dsh-mcp-client makes four
    ctx.logger calls and every one sits on an error path, and cordis's logger only fills an in-memory buffer that
    nothing prints. The channel that does reach the operator is stderr, which the MCP SDK's stdio transport
    inherits from the harness by default (stdio: ['pipe', 'pipe', stderr ?? 'inherit']), and which CodeWitness
    already uses for progress and errors.

What this does not fix

  • The banner is not a health check. It is written when the process starts serving, which is before the
    client's initialize and long before any tool runs. A server that starts and then fails on its first tool call
    still announced itself, and one that cannot start at all still says nothing — the second is the honest signal,
    and it is the case the line was added to make visible.

  • It is only as visible as the stderr the client gives it. The MCP standard library inherits the child's
    stderr, so the line reaches the terminal a harness was started from; a client that captures stderr and never
    forwards it will not show the line, and nothing on this side can force that.

  • Only CodeWitness speaks now. The other MCP servers this machine's harness launches — laya, depmcp,
    goosebuckle, rea — are silent for exactly the same reason and are untouched here. Each needs the same one-line
    announcement in its own entry point; that is a change per server, not a change to this one.

  • The tool names in the banner are still hand-maintained. toolNames() is a written-out string, not derived
    from list(). The new test asserts the count and the phrase, so a tool added without touching the string fails
    the suite rather than the banner — but the string is still edited by hand.

Verified for this release

  • Full reactor suite: 1,785 tests, 0 failures, 0 errors, 0 skipped — one more than 1.0.24's 1,784, the new
    McpServerTest.announcesItselfOnStartup.
  • The guard was proved to fire. Routing the banner to the protocol stream instead of the diagnostics stream —
    one line, reverted afterwards — failed all seven McpServerTest cases: the six existing ones with non-JSON output on the MCP stream: [codewitness] MCP server ready: …, and the new one on its first assertion. Restored,
    the class is green again.
  • A real process, not only the unit test: printf initialize | ./codewitness mcp writes exactly one line to
    stderr and exactly one JSON-RPC response to stdout. Standard output staying protocol-only is the invariant the
    whole design rests on, and it is the half a unit test can miss.
  • Self-check against the built jar (./codewitness verify . --requirements selfcheck/requirements.yaml --config selfcheck/codewitness.yaml --no-mutation --max-duration 30m): all seven ground rules VERIFIED,
    1,785 tests executed and passed, 0 findings — five suppressed with their reasons — coverage 71.3% line
    (25,780/36,148) and 59.6% branch, 30 resolved dependencies with 0 advisories from OSV, and exit 0 in
    1 m 49 s. Run CW-2026-11-09-CHKRJ. selfcheck/README.md quotes this run.
  • ./codewitness version prints codewitness 1.0.25.

Process note

The defect was in the transport, and no test could have failed on it: the tool answered every request correctly,
and what was missing was the absence of a request. It surfaced by comparing two servers in one harness and asking
why one spoke — the harness's plugin announced, the harness's MCP server did not. The generalisable lesson is that
a silent success and a missing process look identical unless something says otherwise, and the something has
to be the process itself.

The first fix that suggests itself — patch the harness's MCP client to log every successful connection — is the
wrong one, for three reasons worth writing down: it lives in root-owned installed code, it announces for servers
that never asked to be announced, and it only helps clients that are that harness. A server that says "I am
ready" is portable; a harness that says "your server is ready" is not.

Compatibility

  • No CLI command, flag, exit code contract, report key, SARIF profile, codewitness.yaml key or adapter-SPI
    change. The interface contract frozen at 1.0 is untouched.
  • One new line on standard error at startup. A conforming MCP client reads standard output only, so nothing is
    affected; the MCP specification forbids treating stderr as protocol, and a client that parses it would have to
    tolerate a line it did not ask for.
  • McpServer's three-argument constructor is preserved as an overload, so source compatibility holds for any
    caller outside the class.