Expose Knowledge Base MCP debug flag via NEO_DEBUG

Context

Operator request on 2026-06-02: ai/mcp/server/knowledge-base/config.template.mjs => and mc => can we create a ticket to expose debug logs via an env var?

Verify-before-assert evidence:

• ai/mcp/server/knowledge-base/config.template.mjs:41-45 declares the Knowledge Base MCP debug flag as leaf(false) with no env var binding.
• ai/mcp/server/knowledge-base/config.template.mjs:148-159 declares KB logger policy as an always-on file sink plus debug-gated stderr, so debug controls whether stderr emits debug-level operational traces.
• ai/mcp/server/knowledge-base/mcp-server.mjs:17-24 supports --debug and mutates aiConfig.debug = true, but this requires CLI/config-file control rather than an env toggle.
• ai/mcp/server/memory-core/config.template.mjs:59-62 already exposes the same MCP debug flag through NEO_DEBUG.
• ai/config.template.mjs:52-55 also exposes the global AI debug flag through NEO_DEBUG.

Duplicate sweep:

• Knowledge Base semantic ticket sweep for ticket debug logging env var NEO_DEBUG Knowledge Base MCP Memory Core MCP surfaced related closed tickets (#10582, #11878, #10184) but no open KB env-var parity ticket.
• Local issue/discussion grep for NEO_DEBUG, debug logs, debug logging, and KB/MC logger terms found historical logger/diagnostic tickets, not an active KB NEO_DEBUG parity ticket.
• Live GitHub open-issue search for NEO_DEBUG debug logging Knowledge Base MCP returned [].

The Problem

Knowledge Base MCP debug stderr can be enabled through --debug or local config mutation, but the committed template does not let operators enable it with the same env-var path used by Memory Core and the global AI config.

That asymmetry matters during MCP debugging because env vars are the fastest, least-invasive control surface for desktop harnesses, daemon wrappers, and cloud deployment shells. Operators should not have to edit a gitignored config.mjs overlay or remember a KB-only CLI flag when MC already honors NEO_DEBUG at config resolution time.

The Architectural Reality

This is a config-surface parity ticket, not a logger rewrite.

The shared MCP logger already reads aiConfig.debug lazily through per-server config policy. KB's logger block already uses stderrMode: 'debug'; the missing surface is only the template binding for the KB debug leaf. Memory Core is the direct sibling precedent: same MCP server family, same debug-gated stderr policy, and already env-bound via leaf(false, 'NEO_DEBUG', 'boolean').

The implementation should keep runtime .mjs code importing config files rather than hardcoding values. Tests that verify defaults should import the template, not the gitignored local config overlay.

The Fix

1. Update ai/mcp/server/knowledge-base/config.template.mjs so debug uses the same env-bound leaf shape as MC/global AI config:
   • debug: leaf(false, 'NEO_DEBUG', 'boolean')
2. Add or update focused config completeness/unit coverage proving:
   • default KB template debug remains false;
   • NEO_DEBUG=true resolves to true for the KB template/config path;
   • invalid boolean values preserve the existing BaseConfig env parsing behavior.
3. Keep the CLI --debug path in ai/mcp/server/knowledge-base/mcp-server.mjs intact.
4. Document in the PR body that active KB MCP processes need restart to pick up a changed env/config module, while new processes read the env at boot.

Contract Ledger Matrix

Decision Record Impact

Decision Record impact: none. This aligns with the existing MCP config-template pattern and does not challenge an accepted ADR.

Acceptance Criteria

• Knowledge Base MCP debug in ai/mcp/server/knowledge-base/config.template.mjs is env-bound via NEO_DEBUG with boolean parsing.
• Default behavior remains debug-off when NEO_DEBUG is unset.
• NEO_DEBUG=true enables KB debug mode through config/template resolution without requiring --debug or local config.mjs edits.
• Existing --debug CLI behavior remains intact.
• Focused tests cover the template default and env override using template imports, not the gitignored local config overlay.
• PR body includes MCP config-template clone-sync guidance for active local config.mjs overlays and restart expectations.
• No Memory Core behavior changes are introduced unless a verified drift is found during implementation; MC is the precedent for KB parity.

Out of Scope

• Rewriting the shared MCP logger primitive.
• Changing file-sink behavior or log rotation.
• Adding server-specific env vars such as NEO_KB_DEBUG unless implementation proves NEO_DEBUG would violate an existing contract.
• Changing Memory Core debug semantics; it already exposes NEO_DEBUG.
• Running the full integration suite unless focused tests or CI indicate a broader regression.

Avoided Traps

• Do not hardcode process.env.NEO_DEBUG in runtime server code. Use the config template/import pattern and leaf() env binding.
• Do not commit gitignored config.mjs overlays.
• Do not broaden this into a logger refactor; #11878 already delivered the shared MCP logger primitive.
• Do not remove the CLI --debug path; env var support complements it.
• Do not treat historical MC identity/debug tickets as duplicates; they were closed and targeted a different diagnostic incident.

Related

• Historical logger symmetry: #10582
• Shared MCP logger primitive: #11878
• Historical MC debug diagnostic incident: #10184
• Active PR opened before this ticket: #12369 (existing-ticket backlog reduction, not this ticket's implementation)

Origin Session ID: a605f115-e0f6-42f6-a0f1-42c2fee9410d

Handoff Retrieval Hints:

• Search terms: Knowledge Base MCP NEO_DEBUG, config.template.mjs debug leaf false, MC debug NEO_DEBUG precedent, MCP config-template change guide.
• Start from ai/mcp/server/knowledge-base/config.template.mjs and sibling ai/mcp/server/memory-core/config.template.mjs before editing.