fix(stdio): keep logs off JSON-RPC stdout

Author: Mochxd

README.md

@@ -538,6 +538,8 @@ const server = await createAppiumMcpServer({
 await server.start({ transportType: 'stdio' });
 ```
 
+`start({ transportType: 'stdio' })` keeps Appium and WebDriver logs off stdout so JSON-RPC stays intact. httpStream is unchanged.
+
 Plugin lifecycle:
 
 - `register(registry, core)`: called during server construction. Register custom tools, prompts, resources, and resource templates here.

src/cli/index.ts

@@ -1,12 +1,17 @@
-import log from '../logger.js';
+import log, {configureStdioTransportLogging} from '../logger.js';
 
 export async function runCli(args: string[] = process.argv.slice(2)): Promise<void> {
   const command = args[0];
   if (command === '--help' || command === '-h' || command === 'help') {
     printHelp();
-  } else {
-    await startServer(args);
+    return;
   }
+
+  if (!args.includes('--httpStream')) {
+    configureStdioTransportLogging();
+  }
+
+  await startServer(args);
 }
 
 function printHelp(): void {

src/core.ts

@@ -7,6 +7,7 @@
  */
 export {createAppiumMcpServer} from './create-server.js';
 export type {CreateAppiumMcpServerOptions} from './create-server.js';
+export {configureStdioTransportLogging} from './logger.js';
 export {evaluatePolicyTarget} from './policy.js';
 export type {AppiumMcpPolicy, PolicyDecision, PolicyDecisionReason, PolicyTargetKind} from './policy.js';
 export {AppiumMcpCore, formatVerificationReport, McpRegistry, PluginManager, verifyAppiumMcpNames} from './plugin.js';

src/create-server.ts

@@ -16,7 +16,7 @@
 import {FastMCP} from 'fastmcp';
 
 import pkg from '../package.json' with {type: 'json'};
-import log from './logger.js';
+import log, {configureStdioTransportLogging} from './logger.js';
 import {PluginManager} from './plugin.js';
 import type {AppiumMcpPlugin} from './plugin.js';
 import {installPolicy, type AppiumMcpPolicy} from './policy.js';
@@ -118,6 +118,7 @@ export async function createAppiumMcpServer(options: CreateAppiumMcpServerOption
       enabled: false,
     },
   });
+  wrapStartForStdioLogging(server);
 
   installPolicy(server, policy);
   try {
@@ -263,6 +264,16 @@ export async function createAppiumMcpServer(options: CreateAppiumMcpServerOption
   return server;
 }
 
+function wrapStartForStdioLogging(server: FastMCP): void {
+  const originalStart = server.start.bind(server);
+  server.start = (async (startOptions) => {
+    if ((startOptions?.transportType ?? 'stdio') === 'stdio') {
+      configureStdioTransportLogging();
+    }
+    return originalStart(startOptions);
+  }) as FastMCP['start'];
+}
+
 function disconnectSessionPolicyFromEnv(): DisconnectSessionPolicy {
   const raw = process.env.APPIUM_MCP_ON_CLIENT_DISCONNECT?.trim().toLowerCase();
   if (raw === 'skip') {

src/logger.ts

@@ -1,7 +1,30 @@
 import {logger} from '@appium/support';
 
+import {isStdioTransportLoggingConfigured, markStdioTransportLoggingConfigured} from './stdio-logging-state.js';
+
 const log = logger.getLogger('appium-mcp');
 
+/** npmlog must not write to stdout (stdio JSON-RPC). Skip if the host already set a custom stream. */
+export function ensureLoggerWritesToStderr(): void {
+  const root = log.unwrap();
+  if (root.stream === process.stdout) {
+    root.stream = process.stderr;
+  }
+}
+
+/** stdio transport: drop info/debug so they cannot sit on stdout. */
+export function configureStdioTransportLogging(): void {
+  if (isStdioTransportLoggingConfigured()) {
+    return;
+  }
+  markStdioTransportLoggingConfigured();
+  ensureLoggerWritesToStderr();
+  log.level = 'warn';
+  if (!process.env.WDIO_LOG_LEVEL) {
+    process.env.WDIO_LOG_LEVEL = 'warn';
+  }
+}
+
 export default log;
 export {log};
 

src/stdio-logging-state.ts

@@ -0,0 +1,9 @@
+let stdioLoggingConfigured = false;
+
+export function isStdioTransportLoggingConfigured(): boolean {
+  return stdioLoggingConfigured;
+}
+
+export function markStdioTransportLoggingConfigured(): void {
+  stdioLoggingConfigured = true;
+}

src/tests/__mocks__/@appium/support.ts

@@ -2,13 +2,19 @@ import {constants, existsSync, promises as fsPromises} from 'node:fs';
 
 const noop = () => {};
 
+const npmlog = {
+  stream: process.stderr as NodeJS.WritableStream | null,
+};
+
 export const logger = {
   getLogger: (_name: string) => ({
     debug: noop,
     info: noop,
     warn: noop,
     error: noop,
     trace: noop,
+    level: 'info' as string,
+    unwrap: () => npmlog,
   }),
 };
 

src/tests/create-server.test.ts

@@ -93,6 +93,8 @@ class MockFastMCP {
       await handler(event);
     }
   }
+
+  async start(_options?: unknown): Promise<void> {}
 }
 
 await jest.unstable_mockModule('fastmcp', () => ({
@@ -147,13 +149,16 @@ await jest.unstable_mockModule('../session-store', () => ({
   safeDeleteAllSessions,
 }));
 
+const configureStdioTransportLogging = jest.fn();
+
 await jest.unstable_mockModule('../logger', () => ({
   default: {
     debug: jest.fn(),
     info: jest.fn(),
     warn: jest.fn(),
     error: jest.fn(),
   },
+  configureStdioTransportLogging,
 }));
 
 const {createAppiumMcpServer} = await import('../create-server.js');
@@ -167,6 +172,7 @@ afterEach(() => {
   jest.mocked(log.error).mockReset();
   jest.mocked(log.info).mockReset();
   jest.mocked(log.warn).mockReset();
+  configureStdioTransportLogging.mockReset();
   delete process.env.APPIUM_MCP_ON_CLIENT_DISCONNECT;
 });
 
@@ -195,6 +201,24 @@ describe('createAppiumMcpServer plugin lifecycle', () => {
     expect(log.info).toHaveBeenCalledWith('fastmcp log');
   });
 
+  test('stdio start quiets logging; httpStream does not', async () => {
+    const server = await createAppiumMcpServer();
+
+    await server.start();
+    expect(configureStdioTransportLogging).toHaveBeenCalledTimes(1);
+
+    configureStdioTransportLogging.mockClear();
+    await server.start({transportType: 'stdio'});
+    expect(configureStdioTransportLogging).toHaveBeenCalledTimes(1);
+
+    configureStdioTransportLogging.mockClear();
+    await server.start({
+      transportType: 'httpStream',
+      httpStream: {port: 8080},
+    });
+    expect(configureStdioTransportLogging).not.toHaveBeenCalled();
+  });
+
   test('registers plugin capabilities during construction but initializes lazily', async () => {
     let registerCalled = false;
     let initialized = false;

src/tests/logger.test.ts

@@ -0,0 +1,73 @@
+import {afterEach, describe, expect, test} from '@jest/globals';
+
+import {configureStdioTransportLogging, ensureLoggerWritesToStderr, log} from '../logger.js';
+import {isStdioTransportLoggingConfigured, markStdioTransportLoggingConfigured} from '../stdio-logging-state.js';
+import {QUIET_WEBDRIVER_LOG_LEVEL, withQuietWebDriverLogging} from '../utils/webdriver-client-options.js';
+
+describe('stdio transport logging', () => {
+  const originalWdioLogLevel = process.env.WDIO_LOG_LEVEL;
+
+  afterEach(() => {
+    if (originalWdioLogLevel === undefined) {
+      delete process.env.WDIO_LOG_LEVEL;
+    } else {
+      process.env.WDIO_LOG_LEVEL = originalWdioLogLevel;
+    }
+  });
+
+  test('ensureLoggerWritesToStderr only replaces stdout', () => {
+    log.unwrap().stream = process.stdout;
+    ensureLoggerWritesToStderr();
+    expect(log.unwrap().stream).toBe(process.stderr);
+  });
+
+  test('ensureLoggerWritesToStderr leaves stderr and custom sinks in place', () => {
+    log.unwrap().stream = process.stderr;
+    ensureLoggerWritesToStderr();
+    expect(log.unwrap().stream).toBe(process.stderr);
+
+    const custom = {write: () => {}} as unknown as NodeJS.WriteStream;
+    log.unwrap().stream = custom;
+    ensureLoggerWritesToStderr();
+    expect(log.unwrap().stream).toBe(custom);
+  });
+
+  test('withQuietWebDriverLogging is a no-op until stdio logging is configured', () => {
+    expect(isStdioTransportLoggingConfigured()).toBe(false);
+    expect(
+      withQuietWebDriverLogging({
+        hostname: '127.0.0.1',
+        port: 4723,
+      }),
+    ).toEqual({
+      hostname: '127.0.0.1',
+      port: 4723,
+    });
+  });
+
+  test('configureStdioTransportLogging quiets info logs and WDIO when unset', () => {
+    delete process.env.WDIO_LOG_LEVEL;
+    log.unwrap().stream = process.stdout;
+
+    configureStdioTransportLogging();
+
+    expect(isStdioTransportLoggingConfigured()).toBe(true);
+    expect(log.unwrap().stream).toBe(process.stderr);
+    expect(log.level).toBe('warn');
+    expect(process.env.WDIO_LOG_LEVEL).toBe('warn');
+  });
+
+  test('withQuietWebDriverLogging sets warn after stdio logging is configured', () => {
+    markStdioTransportLoggingConfigured();
+    expect(
+      withQuietWebDriverLogging({
+        hostname: '127.0.0.1',
+        port: 4723,
+      }),
+    ).toEqual({
+      hostname: '127.0.0.1',
+      port: 4723,
+      logLevel: QUIET_WEBDRIVER_LOG_LEVEL,
+    });
+  });
+});

src/tools/session/create-session.ts

@@ -12,6 +12,7 @@ import {setSession, listSessions} from '../../session-store.js';
 import {createUIResource, createSessionDashboardUI, addUIResourceToResponse} from '../../ui/mcp-ui-utils.js';
 import {findFreePort, releaseReservedPorts} from '../../utils/ports.js';
 import {getPortFromUrl} from '../../utils/url.js';
+import {withQuietWebDriverLogging} from '../../utils/webdriver-client-options.js';
 import {errorResult, textResult, toolErrorMessage} from '../tool-response.js';
 import {clearSelectedDevice, getSelectedLocalDevice} from './select-device.js';
 
@@ -355,14 +356,16 @@ export async function createSessionAction(args: {
       log.info(
         `Sending capabilities to remote server: ${protocol}://${remoteUrl.hostname}:${port}${remoteUrl.pathname}`,
       );
-      const client = await WebDriver.newSession({
-        protocol,
-        hostname: remoteUrl.hostname,
-        port,
-        path: remoteUrl.pathname,
-        ...(user && key ? {user, key} : {}),
-        capabilities: finalCapabilities,
-      });
+      const client = await WebDriver.newSession(
+        withQuietWebDriverLogging({
+          protocol,
+          hostname: remoteUrl.hostname,
+          port,
+          path: remoteUrl.pathname,
+          ...(user && key ? {user, key} : {}),
+          capabilities: finalCapabilities,
+        }),
+      );
       sessionId = client.sessionId;
       await setSession(client, client.sessionId, finalCapabilities, 'owned', args.remoteServerUrl);
     } else {