MCP tool results use ATX Markdown headings (##/###) — render as oversized fonts in Markdown-rendering clients

[mdsharpe]

Summary

The MCP tools return result text using ATX Markdown headings (##, ###).
In MCP clients that render tool output as rich Markdown (e.g. the Claude Code
VSCode extension), every heading is shown at H1/H2/H3 font size. Because some
tools emit one heading per result, a normal query fills the transcript with
large-font lines and is persistently distracting.

This is purely about the MCP output rendering — the CLI/TTY output is fine.

Where it comes from

dist/mcp/tools.js formats results with ##/###. Examples as seen by the client:

codegraph_status:

## CodeGraph Status
**Files indexed:** 1953
...
### Nodes by Kind:
...

codegraph_search — one ### heading per hit, so 10 results = 10 oversized headings:

## Search Results (10 found)

### WidgetSeeder (method)
src/.../WidgetSeeder.cs:31

### WidgetSeeder (class)
src/.../WidgetSeeder.cs:18
...

The per-result ### headings are the worst offender, since the noise scales
with result count.

Why the client can't fix it

There's no client-side control for this in at least the Claude Code VSCode
extension — tool-result text is rendered as Markdown uniformly, with no
plain-text or heading-size option. So the only effective lever is the server's
output format.

Concrete ask (cheapest first)

1. Drop ATX headings in favor of bold labels — **Search Results (10 found)**
   and **WidgetSeeder** (method) instead of ##/###. Bold renders
   at normal size, so structure is preserved without font-scaling, and it needs
   no flag or config. This alone would resolve it for everyone.

2. Or, if the heading style is wanted by default, an opt-in plain/compact mode
   via an env knob — e.g. CODEGRAPH_PLAIN=1, consistent with the existing
   CODEGRAPH_* knobs (CODEGRAPH_ASCII, CODEGRAPH_UNICODE, …) — that emits
   the same content without ATX headings.

Either is fine; (1) is the lowest-risk and benefits all Markdown-rendering
clients without configuration.

Environment

• codegraph 0.9.9 (npm, linux-x64 engine bundle)
• Transport: MCP stdio (codegraph serve --mcp)
• Client: Claude Code VSCode extension

[maxmilian]

Confirmed locally on main: the ATX headings come from src/mcp/tools.ts — e.g. ## Search Results and the per-hit ### <name> (<kind>) (around L3325/L3331), ## CodeGraph Status (L2886) — plus a number of ###/#### headers elsewhere in that file and in src/context/formatter.ts. Happy to pick this up.

Before I open a PR, which direction do you prefer?

1. Change the default — swap the ATX headings for bold labels (**Search Results (10 found)**, **WidgetSeeder** (method)) across the board. Zero-config win for every Markdown-rendering client, but it changes the default output agents currently parse and touches the heading assertions in ~7 test files.

2. Opt-in env knob — add CODEGRAPH_PLAIN=1 (consistent with the existing CODEGRAPH_ASCII/CODEGRAPH_UNICODE in src/ui/glyphs.ts) that emits the same content without ATX headings, leaving the default untouched.

Both are straightforward — I'll go whichever way you prefer.

[mdsharpe]

Personally I would be happy with the opt-in CODEGRAPH_PLAIN=1 if that works for you.