import{_ as s,c as a,o as e,a0 as n}from"./chunks/framework.FdfEk_gD.js";const d=JSON.parse('{"title":"Logging Documentation","description":"","frontmatter":{},"headers":[],"relativePath":"dev/LOGGING.md","filePath":"dev/LOGGING.md"}'),t={name:"dev/LOGGING.md"};function l(o,i,r,h,p,g){return e(),a("div",null,[...i[0]||(i[0]=[n(`<h1 id="logging-documentation" tabindex="-1">Logging Documentation <a class="header-anchor" href="#logging-documentation" aria-label="Permalink to &quot;Logging Documentation&quot;">​</a></h1><p>The Vibe Feature MCP Server includes a comprehensive logging system that follows MCP best practices and provides both local debugging capabilities and client notifications.</p><h2 id="mcp-compliance" tabindex="-1">MCP Compliance <a class="header-anchor" href="#mcp-compliance" aria-label="Permalink to &quot;MCP Compliance&quot;">​</a></h2><p>The logging system is fully compliant with MCP requirements:</p><ul><li><strong>stderr only</strong>: All local logging uses <code>stderr</code> (not <code>stdout</code>) to avoid interfering with MCP protocol operation</li><li><strong>Client notifications</strong>: Important events are sent to the MCP client via log message notifications</li><li><strong>Structured logging</strong>: All log messages include structured context data</li><li><strong>Centralized logging</strong>: All logging logic is centralized in <code>logger.ts</code> to avoid duplication</li></ul><h2 id="log-levels" tabindex="-1">Log Levels <a class="header-anchor" href="#log-levels" aria-label="Permalink to &quot;Log Levels&quot;">​</a></h2><p>The server supports four log levels with configurable output:</p><ul><li><strong>DEBUG</strong>: Detailed tracing and execution flow information</li><li><strong>INFO</strong>: Success operations and important milestones (default)</li><li><strong>WARN</strong>: Expected errors and recoverable issues</li><li><strong>ERROR</strong>: Caught but unexpected errors</li></ul><h2 id="configuration" tabindex="-1">Configuration <a class="header-anchor" href="#configuration" aria-label="Permalink to &quot;Configuration&quot;">​</a></h2><p>Set the log level using the <code>LOG_LEVEL</code> environment variable:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Debug level (most verbose)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LOG_LEVEL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">DEBUG</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tsx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> src/index.ts</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Production level (default)</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LOG_LEVEL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">INFO</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> node</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dist/index.js</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Error level only</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LOG_LEVEL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">ERROR</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> node</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> dist/index.js</span></span></code></pre></div><h2 id="logging-components" tabindex="-1">Logging Components <a class="header-anchor" href="#logging-components" aria-label="Permalink to &quot;Logging Components&quot;">​</a></h2><h3 id="local-logging-stderr" tabindex="-1">Local Logging (stderr) <a class="header-anchor" href="#local-logging-stderr" aria-label="Permalink to &quot;Local Logging (stderr)&quot;">​</a></h3><p>All log messages are written to <code>stderr</code> with structured formatting:</p><div class="language- vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang"></span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span>[2025-06-23T06:33:37.372Z] INFO [Server] Phase transition completed {&quot;from&quot;:&quot;idle&quot;,&quot;to&quot;:&quot;requirements&quot;,&quot;reason&quot;:&quot;Starting development&quot;}</span></span></code></pre></div><p>Format: <code>[timestamp] LEVEL [component] message {context}</code></p><h3 id="mcp-client-notifications" tabindex="-1">MCP Client Notifications <a class="header-anchor" href="#mcp-client-notifications" aria-label="Permalink to &quot;MCP Client Notifications&quot;">​</a></h3><p>Important events are automatically sent to the MCP client as enhanced log message notifications:</p><ul><li><strong>Phase transitions</strong>: Formatted as &quot;Phase Transition: Idle → Requirements&quot;</li><li><strong>Server initialization</strong>: Enhanced as &quot;🚀 Vibe Feature MCP Server Ready&quot;</li><li><strong>Error conditions</strong>: When tools fail or encounter issues</li><li><strong>Debug information</strong>: Only sent at DEBUG level</li></ul><p>Client notifications use the MCP <code>notifications/message</code> method with enhanced formatting for better user experience.</p><h2 id="component-loggers" tabindex="-1">Component Loggers <a class="header-anchor" href="#component-loggers" aria-label="Permalink to &quot;Component Loggers&quot;">​</a></h2><p>The system uses component-specific loggers for better organization:</p><ul><li><strong>Server</strong>: Main server operations and tool handlers</li><li><strong>Database</strong>: SQLite operations and state persistence</li><li><strong>ConversationManager</strong>: Conversation context management</li><li><strong>TransitionEngine</strong>: Phase transition analysis and state machine operations</li><li><strong>PlanManager</strong>: Plan file operations and management</li><li><strong>StateMachineLoader</strong>: State machine loading and validation</li><li><strong>InteractionLogger</strong>: Tool interaction logging</li></ul><h2 id="usage-examples" tabindex="-1">Usage Examples <a class="header-anchor" href="#usage-examples" aria-label="Permalink to &quot;Usage Examples&quot;">​</a></h2><h3 id="creating-a-logger" tabindex="-1">Creating a Logger <a class="header-anchor" href="#creating-a-logger" aria-label="Permalink to &quot;Creating a Logger&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">import</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> { createLogger } </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">from</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> &#39;./logger.js&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">;</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> logger</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> createLogger</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;MyComponent&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span></code></pre></div><h3 id="logging-with-context" tabindex="-1">Logging with Context <a class="header-anchor" href="#logging-with-context" aria-label="Permalink to &quot;Logging with Context&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">logger.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">info</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;Operation completed&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  conversationId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;abc123&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  phase: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;requirements&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  operation: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;phase_transition&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">});</span></span></code></pre></div><h3 id="error-logging" tabindex="-1">Error Logging <a class="header-anchor" href="#error-logging" aria-label="Permalink to &quot;Error Logging&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">try</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> {</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">  // some operation</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">} </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">catch</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> (error) {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  logger.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;Operation failed&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, error </span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">as</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> Error</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">, {</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    operation: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;database_query&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">    conversationId: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;abc123&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  });</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h3 id="child-loggers" tabindex="-1">Child Loggers <a class="header-anchor" href="#child-loggers" aria-label="Permalink to &quot;Child Loggers&quot;">​</a></h3><div class="language-typescript vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">typescript</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">const</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;"> childLogger</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> =</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;"> logger.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">child</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;SubComponent&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">childLogger.</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;">debug</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">(</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&#39;Sub-operation started&#39;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">);</span></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;">// Output: [timestamp] DEBUG [MyComponent:SubComponent] Sub-operation started</span></span></code></pre></div><h2 id="client-integration" tabindex="-1">Client Integration <a class="header-anchor" href="#client-integration" aria-label="Permalink to &quot;Client Integration&quot;">​</a></h2><p>When using the MCP server, clients will receive enhanced log notifications for:</p><ol><li><strong>Server initialization</strong>: &quot;🚀 Vibe Feature MCP Server Ready&quot;</li><li><strong>Phase transitions</strong>: &quot;Phase Transition: Requirements → Design&quot;</li><li><strong>Error conditions</strong>: Immediate notification of tool failures or issues</li><li><strong>Debug information</strong>: Detailed tracing (only at DEBUG level)</li></ol><p>Example client notification:</p><div class="language-json vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">json</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">{</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;method&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;notifications/message&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">  &quot;params&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: {</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;level&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;info&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;logger&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Server&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">,</span></span>
<span class="line"><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">    &quot;data&quot;</span><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">: </span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">&quot;Phase Transition: Idle → Requirements {</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">from</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">idle</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">to</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">requirements</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">,</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">reason</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">:</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">Starting development</span><span style="--shiki-light:#005CC5;--shiki-dark:#79B8FF;">\\&quot;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">}&quot;</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">  }</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">}</span></span></code></pre></div><h2 id="architecture-benefits" tabindex="-1">Architecture Benefits <a class="header-anchor" href="#architecture-benefits" aria-label="Permalink to &quot;Architecture Benefits&quot;">​</a></h2><h3 id="centralized-logging" tabindex="-1">Centralized Logging <a class="header-anchor" href="#centralized-logging" aria-label="Permalink to &quot;Centralized Logging&quot;">​</a></h3><ul><li>All logging logic is contained in <code>logger.ts</code></li><li>No duplication between server components</li><li>Single point of configuration and enhancement</li></ul><h3 id="enhanced-user-experience" tabindex="-1">Enhanced User Experience <a class="header-anchor" href="#enhanced-user-experience" aria-label="Permalink to &quot;Enhanced User Experience&quot;">​</a></h3><ul><li>Phase transitions are formatted for readability</li><li>Important events get visual indicators (🚀)</li><li>Context information is preserved but formatted appropriately</li></ul><h3 id="mcp-compliance-1" tabindex="-1">MCP Compliance <a class="header-anchor" href="#mcp-compliance-1" aria-label="Permalink to &quot;MCP Compliance&quot;">​</a></h3><ul><li>All local logs go to stderr as required</li><li>Client notifications use proper MCP protocol</li><li>Graceful fallback when MCP transport is unavailable</li></ul><h2 id="debugging" tabindex="-1">Debugging <a class="header-anchor" href="#debugging" aria-label="Permalink to &quot;Debugging&quot;">​</a></h2><h3 id="enable-debug-logging" tabindex="-1">Enable Debug Logging <a class="header-anchor" href="#enable-debug-logging" aria-label="Permalink to &quot;Enable Debug Logging&quot;">​</a></h3><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LOG_LEVEL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">DEBUG</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tsx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> src/index.ts</span></span></code></pre></div><p>Debug logging includes:</p><ul><li>Detailed execution flow</li><li>State machine operations</li><li>Database queries</li><li>Plan file operations</li><li>Tool parameter validation</li></ul><h3 id="log-file-analysis" tabindex="-1">Log File Analysis <a class="header-anchor" href="#log-file-analysis" aria-label="Permalink to &quot;Log File Analysis&quot;">​</a></h3><p>Since all logs go to <code>stderr</code>, you can capture them for analysis:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Capture logs to file</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LOG_LEVEL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">DEBUG</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tsx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> src/index.ts</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> 2&gt;</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> server.log</span></span>
<span class="line"></span>
<span class="line"><span style="--shiki-light:#6A737D;--shiki-dark:#6A737D;"># Monitor logs in real-time</span></span>
<span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LOG_LEVEL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">DEBUG</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tsx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> src/index.ts</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> 2&gt;&amp;1</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;"> |</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> tee</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> server.log</span></span></code></pre></div><h2 id="best-practices" tabindex="-1">Best Practices <a class="header-anchor" href="#best-practices" aria-label="Permalink to &quot;Best Practices&quot;">​</a></h2><ol><li><strong>Use appropriate log levels</strong>: Debug for tracing, Info for milestones, Warn for recoverable issues, Error for failures</li><li><strong>Include context</strong>: Always provide relevant context data with log messages</li><li><strong>Avoid sensitive data</strong>: Don&#39;t log passwords, tokens, or other sensitive information</li><li><strong>Use structured logging</strong>: Provide context as objects rather than string interpolation</li><li><strong>Component-specific loggers</strong>: Use dedicated loggers for different components</li><li><strong>Centralized logging</strong>: Use the logger module for all logging needs</li></ol><h2 id="performance-considerations" tabindex="-1">Performance Considerations <a class="header-anchor" href="#performance-considerations" aria-label="Permalink to &quot;Performance Considerations&quot;">​</a></h2><ul><li>Log level filtering happens before message formatting for efficiency</li><li>MCP client notifications are sent asynchronously to avoid blocking operations</li><li>Failed MCP notifications fall back to stderr logging</li><li>Context objects are JSON-serialized only when the log level permits output</li><li>Enhanced notifications only process important events to reduce overhead</li></ul><h2 id="troubleshooting" tabindex="-1">Troubleshooting <a class="header-anchor" href="#troubleshooting" aria-label="Permalink to &quot;Troubleshooting&quot;">​</a></h2><h3 id="no-log-output" tabindex="-1">No Log Output <a class="header-anchor" href="#no-log-output" aria-label="Permalink to &quot;No Log Output&quot;">​</a></h3><p>Check the <code>LOG_LEVEL</code> environment variable. Default is <code>INFO</code>.</p><h3 id="mcp-client-not-receiving-notifications" tabindex="-1">MCP Client Not Receiving Notifications <a class="header-anchor" href="#mcp-client-not-receiving-notifications" aria-label="Permalink to &quot;MCP Client Not Receiving Notifications&quot;">​</a></h3><p>Ensure the server is properly initialized and connected to the MCP transport. Client notifications are only sent after successful server initialization. In test environments, &quot;Not connected&quot; errors are expected and harmless.</p><h3 id="performance-issues" tabindex="-1">Performance Issues <a class="header-anchor" href="#performance-issues" aria-label="Permalink to &quot;Performance Issues&quot;">​</a></h3><p>Consider raising the log level to <code>WARN</code> or <code>ERROR</code> in production environments to reduce log volume.</p><h2 id="integration-with-mcp-inspector" tabindex="-1">Integration with MCP Inspector <a class="header-anchor" href="#integration-with-mcp-inspector" aria-label="Permalink to &quot;Integration with MCP Inspector&quot;">​</a></h2><p>When using the MCP Inspector for debugging, set debug logging to see detailed protocol interactions:</p><div class="language-bash vp-adaptive-theme"><button title="Copy Code" class="copy"></button><span class="lang">bash</span><pre class="shiki shiki-themes github-light github-dark vp-code" tabindex="0"><code><span class="line"><span style="--shiki-light:#24292E;--shiki-dark:#E1E4E8;">LOG_LEVEL</span><span style="--shiki-light:#D73A49;--shiki-dark:#F97583;">=</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;">DEBUG</span><span style="--shiki-light:#6F42C1;--shiki-dark:#B392F0;"> npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> @modelcontextprotocol/inspector</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> npx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> tsx</span><span style="--shiki-light:#032F62;--shiki-dark:#9ECBFF;"> src/index.ts</span></span></code></pre></div><p>The enhanced logging system provides comprehensive visibility into the server&#39;s operation while maintaining MCP compliance and optimal performance through centralized, structured logging.</p>`,67)])])}const c=s(t,[["render",l]]);export{d as __pageData,c as default};
