JSON output mode broken for MCP servers using structuredContent and isError shapes; recovery logs pollute stdout

[ChrisBot2026]

Summary

mcporter call <server>.<tool> --output json produces output that is not valid JSON in two common cases (resulting in three independent bugs), and an unrelated daemon recovery diagnostic line is logged to stdout, which corrupts the JSON output stream when the daemon needs to recover.

These bugs were surfaced during integration of openclaw's qmd memory backend with mcporter's daemon (keep-alive) mode, but they affect any MCP server using the standard structuredContent / isError shapes.

Encountered with mcporter@0.7.3 on macOS 25.4 / Node 25.5.

All three are 1-line fixes; full reproducers and proposed patches below.

---

Bug 1 — tryParseJson returns null for plain structuredContent objects

File: dist/result-utils.js, function tryParseJson.

When an MCP server returns a tool result like:

{
  "content": [{"type": "text", "text": "..."}],
  "structuredContent": {"results": [...]}
}

mcporter's Result.json() calls tryParseJson(structuredContent). The current implementation returns the value only if it has a .json or .data property; otherwise it falls through to return null. For structuredContent, both branches are typically absent — structuredContent IS the parsed value — so Result.json() returns null.

That null then defeats the case 'json' happy path in printCallOutput (dist/cli/output-utils.js), which falls through to printRaw(raw) → util.inspect(raw). The result is emitted as a JS object literal (with [Object] placeholders for nested arrays), which JSON.parse cannot parse.

Reproducer

Any MCP server returning structuredContent triggers this. Concrete example using QMD (a memory-search MCP):

mcporter call qmd.query --args '{
  "searches":[{"type":"lex","query":"openclaw"}],
  "limit":3,
  "rerank":false
}' --output json --timeout 30000

Pre-patch output (broken):

{
  content: [ [Object] ],
  structuredContent: { results: [ [Object], [Object], [Object] ] }
}

Expected output (valid JSON):

{
  "content": [...],
  "structuredContent": {"results": [...]}
}

(or just the structuredContent body, depending on intent).

Proposed fix (1-line addition)

                 if ('data' in value) {
                     return value.data ?? null;
                 }
+                return value;
             }
             if (typeof value === 'string') {

This returns the plain object as-is when neither .json nor .data is present. It's safe because tryParseJson is only called on values mcporter already considers "JSON-like", and downstream attemptPrintJson will JSON.stringify it.

---

Bug 2 — printCallOutput case 'json' falls back to util.inspect for isError/text-only responses

File: dist/cli/output-utils.js, function printCallOutput, case 'json'.

Even with Bug 1 fixed, when an MCP tool returns an error envelope like:

{
  "content": [{"type": "text", "text": "..."}],
  "isError": true
}

(no structuredContent), wrapped.json() returns null because there's nothing JSON-shaped to extract. The case 'json' then falls through to printRaw(raw) → util.inspect again. So callers parsing --output json choke on error responses.

Reproducer

mcporter call qmd.query --args '{
  "searches":[{"type":"vec","query":"verify-patches.sh"}],
  "limit":1
}' --output json --timeout 30000

(QMD's vec search rejects hyphens in queries with an isError envelope.)

Pre-patch output (broken):

{ content: [ [Object] ], isError: true }

Expected output (valid JSON):

{
  "content": [{"type": "text", "text": "Negation (-term) is not supported in vec/hyde queries. Use lex for exclusions."}],
  "isError": true
}

Proposed fix (1-line addition + comment, using existing attemptPrintJson helper)

         case 'json': {
             const jsonValue = wrapped.json();
             if (jsonValue !== null && attemptPrintJson(jsonValue)) {
                 return;
             }
+            if (raw != null && attemptPrintJson(raw)) {
+                return;
+            }
             printRaw(raw);
             return;
         }

attemptPrintJson is already an existing helper in the same file that does console.log(JSON.stringify(value, null, 2)) and returns true/false on success. This adds a JSON-stringify of the raw envelope as a fallback before the util.inspect path.

---

Bug 3 — logDaemonRetry writes to stdout, polluting --output json

File: dist/daemon/runtime-wrapper.js, function logDaemonRetry.

When the daemon's keep-alive child exits and a call needs to recover the server, mcporter logs:

[mcporter] Restarting '<server>' before retrying <op>: <reason>

via console.log. That goes to stdout — which is the JSON output stream. So the diagnostic line gets prepended to the JSON body, breaking JSON.parse(stdout) for callers (in our case openclaw's qmd-manager does exactly this).

Reproducer

# Start the daemon, kill the qmd-mcp child, then call:
mcporter daemon start
pkill -f 'qmd.*mcp'
mcporter call qmd.query --args '{"searches":[{"type":"lex","query":"x"}],"limit":1}' --output json --timeout 30000

Pre-patch output (broken — stdout is corrupted):

[mcporter] Restarting 'qmd' before retrying callTool: Not connected
{
  "results": [...]
}

Expected: stdout = pure JSON; the diagnostic line on stderr.

Proposed fix (1-character semantic change)

 function logDaemonRetry(server, operation, error) {
     const reason = error instanceof Error ? error.message : String(error);
-    console.log(`[mcporter] Restarting '${server}' before retrying ${operation}: ${reason}`);
+    console.error(`[mcporter] Restarting '${server}' before retrying ${operation}: ${reason}`);
 }

Diagnostics belong on stderr for any tool whose stdout is structured output.

---

Net impact

For an MCP integration that calls mcporter call --output json and parses the stdout as JSON — including any TypeScript SDK consumer — these three bugs make the integration unusable without local patches. We currently maintain all three fixes as 1-line patches in our installed mcporter@0.7.3 to make our QMD memory-backend integration work.

Repro script (combining all three) and side-by-side pre/post patch outputs available on request — happy to attach if useful.

---

Adjacent issues observed (out of scope, but useful context)

These were observed during the same integration work but are separate bugs and not necessarily mcporter's responsibility.

Bug D — mcporter daemon start is not idempotent

Running mcporter daemon start while a daemon is already up appears to spawn additional foreground daemon processes rather than no-op'ing. We observed up to 11 orphan mcporter daemon start --foreground processes accumulating across a test session. Each new daemon spawned its own child MCP servers, multiplying memory cost.

Workaround: mcporter daemon stop && pkill -f 'mcporter daemon' before each start.

Suggestion: have mcporter daemon start check mcporter daemon status first and no-op if already running, and/or have it close any prior socket cleanly.

Bug E — qmd MCP server treats hyphens as negation operators in vec/hyde search

Not mcporter's bug — this is in @tobilu/qmd's MCP server. Filed here only for cross-reference. Filenames like verify-patches.sh and dates like 2026-05-04 get rejected by qmd's vec/hyde parsers with Negation (-term) is not supported in vec/hyde queries. Use lex for exclusions. Affects any MCP wrapper that forwards user queries verbatim. Should be filed against tobilu/qmd — flagging here purely to explain the isError envelopes referenced in Bug 2's reproducer.

[steipete]

Fixed on main via #163 / e2c0641.\n\nWhat changed:\n- Keep-alive daemon retry diagnostics now go to stderr, so mcporter call --output json keeps stdout parseable after daemon recovery.\n- Added regression coverage for MCP isError envelopes staying valid JSON under --output json.\n- Current main already covered the structuredContent/raw JSON fallback cases from this issue; this closes the remaining stdout-pollution path.\n\nVerified before merge with focused Vitest coverage, pnpm check, full pnpm test, pnpm build, and git diff --check.

[steipete]

Fixed on main and shipped in mcporter 0.10.2.

Verified against the current source/tests:

• Plain structuredContent objects now round-trip through Result.json(): src/result-utils.ts plus tests/result-utils.test.ts.
• mcporter call --output json now falls back to JSON.stringify(raw) for raw/isError envelopes instead of util.inspect: src/cli/output-utils.ts plus tests/cli-output-utils.test.ts.
• keep-alive daemon retry diagnostics now go to stderr: src/daemon/runtime-wrapper.ts.

Release: https://github.com/openclaw/mcporter/releases/tag/v0.10.2

[ChrisBot2026]

Thanks @steipete — confirming the fix is good. Verified by reading 0.10.2's dist/result-utils.js, dist/cli/output-utils.js, and dist/daemon/runtime-wrapper.js; all three behaviors match the local patches we'd been carrying since 2026-05-07 (functionally identical fixes).

FYI for fellow openclaw users — integration gotcha hitting mcporter@0.10.x. When we attempted the 0.7.3 → 0.10.2 upgrade in our gateway environment (openclaw 2026.5.7 with memory.backend: qmd), every gateway-driven mcporter call qmd.query … failed with Unknown MCP server 'qmd'., even though direct shell calls worked fine.

Root cause is on the openclaw side, not mcporter: openclaw's qmd-manager builds a shared env with `XDG_CONFIG_HOME=~/.openclaw/agents//qmd/xdg-config` (intended to scope the sibling `qmd` CLI's per-agent data dir) and reuses that env for every child spawn — including mcporter. Pre-0.10 mcporter ignored XDG, so the leak was silent; 0.10's new XDG support correctly honors it, so mcporter looks for `mcporter.json` under each agent's qmd data dir, doesn't find one, and reports the server as unknown.

mcporter is doing the right thing here — the XDG spec doesn't permit a fallback when `$XDG_CONFIG_HOME` is set. Filing a tracker against `openclaw/openclaw` recommending the env be scoped per-spawn target. Until that lands, openclaw users on `memory.backend: qmd` should pin `mcporter@0.7.3`.

Will link the openclaw tracker here once filed.

[ChrisBot2026]

Tracker filed: openclaw/openclaw#79847

[steipete]

Thanks for the precise report. This is fixed on current main and was included in 0.10.2: structured/plain structuredContent is preserved as JSON, --output json falls back to JSON-stringifying raw MCP envelopes such as isError, and daemon retry diagnostics now go to stderr.

Proof checked now:

pnpm exec vitest run tests/cli-output-utils.test.ts tests/result-utils.test.ts
# Test Files 2 passed; Tests 41 passed

The daemon stderr path is also covered in tests/keep-alive-runtime.test.ts (console.log not called; console.error receives the restart diagnostic). Closing as fixed.