fix: guard startup logs for wide MCP STDIO compatibility

Author: PatrickSys

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.2.1 (2025-12-31)
+
+### Fixed
+
+- **MCP Protocol Compatibility**: Fixed stderr output during MCP STDIO handshake for strict clients
+  - All startup `console.error` calls now guarded with `CODEBASE_CONTEXT_DEBUG` env var
+  - Zero stderr output during JSON-RPC handshake (required by Warp, OpenCode, MCPJam)
+  - Debug logs available via `CODEBASE_CONTEXT_DEBUG=1` environment variable
+  - Minimal implementation: 2 files changed, 46 insertions, 25 deletions
+  - Reported by [@aolin480](https://github.com/aolin480) in [#2](https://github.com/PatrickSys/codebase-context/issues/2)
+
 ## 1.2.0 (2025-12-29)
 
 ### Features

README.md

@@ -67,6 +67,7 @@ Now the agent checks patterns automatically instead of waiting for you to ask.
 |----------|---------|-------------|
 | `EMBEDDING_PROVIDER` | `transformers` | `openai` (fast, cloud) or `transformers` (local, private) |
 | `OPENAI_API_KEY` | - | Required if provider is `openai` |
+| `CODEBASE_CONTEXT_DEBUG` | - | Set to `1` to enable verbose logging (startup messages, analyzer registration) |
 
 ## Performance Note
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebase-context",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "MCP server for semantic codebase indexing and search - gives AI agents real understanding of your codebase",
   "type": "module",
   "main": "./dist/lib.js",

src/core/analyzer-registry.ts

@@ -16,7 +16,10 @@ export class AnalyzerRegistry {
     this.sortedAnalyzers = Array.from(this.analyzers.values())
       .sort((a, b) => b.priority - a.priority);
 
-    console.error(`Registered analyzer: ${analyzer.name} (priority: ${analyzer.priority})`);
+    // Debug logging guarded by env var - avoids stderr output during MCP STDIO handshake
+    if (process.env.CODEBASE_CONTEXT_DEBUG) {
+      console.error(`[DEBUG] Registered analyzer: ${analyzer.name} (priority: ${analyzer.priority})`);
+    }
   }
 
   unregister(name: string): boolean {

src/index.ts

@@ -39,13 +39,13 @@ function resolveRootPath(): string {
   let rootPath = arg || envPath || process.cwd();
   rootPath = path.resolve(rootPath);
 
-  // Warn if using cwd as fallback
-  if (!arg && !envPath) {
+  // Warn if using cwd as fallback (guarded to avoid stderr during MCP STDIO handshake)
+  if (!arg && !envPath && process.env.CODEBASE_CONTEXT_DEBUG) {
     console.error(
-      `WARNING: No project path specified. Using current directory: ${rootPath}`
+      `[DEBUG] No project path specified. Using current directory: ${rootPath}`
     );
     console.error(
-      `Hint: Specify path as CLI argument or set CODEBASE_ROOT env var`
+      `[DEBUG] Hint: Specify path as CLI argument or set CODEBASE_ROOT env var`
     );
   }
 
@@ -991,14 +991,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
 });
 
 async function main() {
-  console.error("Codebase Context MCP Server");
-  console.error(`Root: ${ROOT_PATH}`);
-  console.error(
-    `Analyzers: ${analyzerRegistry
-      .getAll()
-      .map((a) => a.name)
-      .join(", ")}`
-  );
+  // Server startup banner (guarded to avoid stderr during MCP STDIO handshake)
+  if (process.env.CODEBASE_CONTEXT_DEBUG) {
+    console.error("[DEBUG] Codebase Context MCP Server");
+    console.error(`[DEBUG] Root: ${ROOT_PATH}`);
+    console.error(
+      `[DEBUG] Analyzers: ${analyzerRegistry
+        .getAll()
+        .map((a) => a.name)
+        .join(", ")}`
+    );
+  }
 
   // Validate root path exists and is a directory
   try {
@@ -1014,31 +1017,33 @@ async function main() {
     process.exit(1);
   }
 
-  // Check for package.json to confirm it's a project root
-  try {
-    await fs.access(path.join(ROOT_PATH, "package.json"));
-    console.error(`Project detected: ${path.basename(ROOT_PATH)}`);
-  } catch {
-    console.error(
-      `WARNING: No package.json found. This may not be a project root.`
-    );
+  // Check for package.json to confirm it's a project root (guarded to avoid stderr during handshake)
+  if (process.env.CODEBASE_CONTEXT_DEBUG) {
+    try {
+      await fs.access(path.join(ROOT_PATH, "package.json"));
+      console.error(`[DEBUG] Project detected: ${path.basename(ROOT_PATH)}`);
+    } catch {
+      console.error(
+        `[DEBUG] WARNING: No package.json found. This may not be a project root.`
+      );
+    }
   }
 
   const needsIndex = await shouldReindex();
 
   if (needsIndex) {
-    console.error("Starting indexing...");
+    if (process.env.CODEBASE_CONTEXT_DEBUG) console.error("[DEBUG] Starting indexing...");
     performIndexing();
   } else {
-    console.error("Index found. Ready.");
+    if (process.env.CODEBASE_CONTEXT_DEBUG) console.error("[DEBUG] Index found. Ready.");
     indexState.status = "ready";
     indexState.lastIndexed = new Date();
   }
 
   const transport = new StdioServerTransport();
   await server.connect(transport);
 
-  console.error("Server ready");
+  if (process.env.CODEBASE_CONTEXT_DEBUG) console.error("[DEBUG] Server ready");
 }
 
 // Export server components for programmatic use