@stellarwp/mcp-logger

📝 Logger (@stellarwp/mcp-logger)

A universal logging solution for both Node.js and browser environments, built on Pino.

📦 What is this?

This package provides a consistent logging interface that works seamlessly across Node.js and browser environments, with special optimizations for MCP servers to ensure proper JSON-RPC output.

✨ Features

• 🌐 Cross-Platform: Works in both Node.js and browser environments
• 🚀 High Performance: Built on Pino for blazing-fast logging
• 🎨 Pretty Output: Beautiful, colorized logging in development
• 🔧 MCP Optimized: Designed specifically for MCP server environments (logs to stderr when run in a Node.js environment)
• 📊 Structured Logging: JSON-based logging with custom formatters
• 🔄 Automatic Environment Detection: Automatically selects the right implementation for your environment

🚀 Getting Started

Prerequisites

• Node.js 18+ or Bun 1.2.20+
• For browser: Modern browser with ES modules support

Installation

# Install the package
bun add @stellarwp/mcp-logger

# Or with npm
npm install @stellarwp/mcp-logger

🔧 Usage

Basic Logging

import { logger } from '@stellarwp/mcp-logger';

// Different log levels
logger.debug('Debug message');
logger.info('Info message');
logger.warn('Warning message');
logger.error('Error message');

// With additional context
logger.info({ user: 'john', action: 'login' }, 'User logged in');

Custom Logger Creation

import { createLogger } from '@stellarwp/mcp-logger';

// Create a custom logger with a specific name
const customLogger = createLogger({ name: 'MyApp' });
customLogger.info('Custom logger initialized');

// Create a logger with custom options
const debugLogger = createLogger({ 
  name: 'DebugModule',
  level: 'trace' 
});
debugLogger.trace('Detailed trace information');

Node.js Environment

import { logger } from '@stellarwp/mcp-logger';

// In Node.js, logs go to stderr with pretty formatting
logger.info('Server started on port 3000');
logger.error({ err: new Error('Connection failed') }, 'Database connection failed');

Browser Environment

import { logger } from '@stellarwp/mcp-logger';

// In browser, logs use console methods with custom prefixing
logger.info('Page loaded successfully');
logger.warn('Deprecated API used');

MCP Server Integration

import { logger } from '@stellarwp/mcp-logger';

// Logger automatically detects MCP server environment
// and routes output to stderr to avoid JSON-RPC conflicts
logger.info('MCP tool registered successfully');
logger.debug({ tool: 'wordpress-fetch' }, 'Tool configuration loaded');

📚 API Reference

Logger Instance

The logger instance provides standard Pino methods:

Log Levels

• logger.trace() - Trace level logging
• logger.debug() - Debug level logging
• logger.info() - Info level logging
• logger.warn() - Warning level logging
• logger.error() - Error level logging
• logger.fatal() - Fatal level logging

Methods

• logger.child(bindings) - Create child logger with additional context
• logger.level - Get or set log level
• logger.isLevelEnabled(level) - Check if level is enabled

createLogger Function

The createLogger(options) function allows you to create custom logger instances:

createLogger(options?: pino.LoggerOptions): pino.Logger

Options

• name - Logger name (defaults to 'MCP Server')
• level - Log level (defaults to 'debug')
• formatters - Custom log formatters
• Any other valid Pino options

🏗️ Architecture

Environment Detection

The package automatically selects the right implementation:

• Node.js: Uses logger.node.js with full Pino + pino-pretty functionality
• Browser: Uses logger.browser.js with console method fallbacks
• Unknown: Defaults to Node.js implementation

Node.js Environment

• Uses Pino with pino-pretty transport
• Outputs to stderr when run on node (file descriptor 2) to avoid MCP server conflicts
• Automatic colorization when TTY is available
• Structured JSON logging with custom formatters

Browser Environment

• Falls back to console methods with custom prefixing (🌀 symbol)
• Maintains consistent API with Node.js version
• No external dependencies in browser bundle
• Structured logging with object serialization

📦 Bundle Information

The package provides different builds for different environments:

• Node.js: logger.node.js - Full Pino functionality with pino-pretty
• Browser: logger.browser.js - Console-based fallback with custom prefixing
• Types: logger.d.ts - TypeScript definitions

🔗 Related Links

• Pino - High-performance Node.js logger
• pino-pretty - Pretty printing for Pino
• Model Context Protocol - MCP specification
• StellarWP - WordPress development tools