@edicarlos.lds/businessmap-mcp/docs/LOGGING.md

Model Context Protocol server for BusinessMap (Kanbanize) integration

# Logging System

## Overview

The BusinessMap MCP Server uses a structured logging system that ensures compatibility with the Model Context Protocol (MCP) while providing clear, categorized log output.

## Why STDERR?

The MCP protocol uses **STDOUT exclusively for JSON-RPC communication**. Any output to STDOUT that is not valid JSON-RPC will corrupt the protocol and cause errors like:

```
MCP businessmap: Unexpected token '✅', "✅ Configur"... is not valid JSON
```

Therefore, **all logging must go to STDERR** (`console.error` or `process.stderr.write`).

## Logger Utility

Instead of using raw `console.error` for all messages (which can be misleading), we provide a `logger` utility that categorizes messages while still outputting to STDERR.

### Log Levels

```typescript
export enum LogLevel {
  DEBUG = 0,    // Detailed debugging information
  INFO = 1,     // Informational messages (default)
  WARN = 2,     // Warning messages
  ERROR = 3,    // Error messages
  NONE = 4,     // Disable all logging
}
```

### Usage Examples

```typescript
import { logger } from './utils/logger.js';

// Success messages (shown at INFO level)
logger.success('Successfully connected to BusinessMap API');

// Informational messages (shown at INFO level)
logger.info('🚀 Starting BusinessMap MCP Server v1.0.0');
logger.info('📡 BusinessMap API: https://account.kanbanize.com/api/v2');

// Debug messages (shown at DEBUG level only)
logger.debug('Fetching effective cycle time columns for board 123');

// Warning messages (shown at WARN level and above)
logger.warn('Direct board lookup failed, trying fallback method');

// Error messages (shown at ERROR level and above)
logger.error('Failed to connect to API', errorObject);
```

### Output Format

All log messages include timestamps and clear prefixes:

```
[2025-11-15T10:30:45.123Z] ✅ SUCCESS: Successfully connected to BusinessMap API
[2025-11-15T10:30:45.456Z] ℹ️  INFO: 🚀 Starting BusinessMap MCP Server v1.0.0
[2025-11-15T10:30:46.789Z] 🔍 DEBUG: Fetching effective cycle time columns for board 123
[2025-11-15T10:30:47.012Z] ⚠️  WARN: Direct board lookup failed, trying fallback method
[2025-11-15T10:30:47.345Z] ❌ ERROR: Failed to connect to API
```

## Configuration

Set the `LOG_LEVEL` environment variable to control verbosity:

```bash
# Show all messages including debug
LOG_LEVEL=0 npx @edicarlos.lds/businessmap-mcp

# Show info, warnings, and errors (default)
LOG_LEVEL=1 npx @edicarlos.lds/businessmap-mcp

# Show only warnings and errors
LOG_LEVEL=2 npx @edicarlos.lds/businessmap-mcp

# Show only errors
LOG_LEVEL=3 npx @edicarlos.lds/businessmap-mcp

# Disable all logging
LOG_LEVEL=4 npx @edicarlos.lds/businessmap-mcp
```

### In Claude Desktop Config

```json
{
  "mcpServers": {
    "Businessmap": {
      "command": "npx",
      "args": ["-y", "@edicarlos.lds/businessmap-mcp"],
      "env": {
        "BUSINESSMAP_API_TOKEN": "your_token",
        "BUSINESSMAP_API_URL": "https://account.kanbanize.com/api/v2",
        "LOG_LEVEL": "1"
      }
    }
  }
}
```

## Benefits

### ✅ Clear Message Categorization

Instead of everything being "errors" (when using `console.error`), messages are properly categorized:

- **SUCCESS**: Operations completed successfully
- **INFO**: General informational messages
- **DEBUG**: Detailed debugging information
- **WARN**: Non-critical issues or fallback scenarios
- **ERROR**: Actual errors and failures

### ✅ MCP Protocol Compliance

All output goes to STDERR, keeping STDOUT clean for JSON-RPC:

```typescript
// ❌ BAD - Breaks MCP protocol
console.log('Starting server...');

// ✅ GOOD - Uses STDERR
console.error('Starting server...');

// ✅ BETTER - Categorized and uses STDERR
logger.info('Starting server...');
```

### ✅ Configurable Verbosity

Control what gets logged without changing code:

```bash
# Production: minimal logging
LOG_LEVEL=2

# Development: detailed logging
LOG_LEVEL=0
```

### ✅ Consistent Format

All messages follow the same format with timestamps and clear prefixes, making logs easier to read and parse.

## Migration from console.error

When migrating from `console.error` to the logger utility, choose the appropriate method:

```typescript
// Before
console.error('✅ Successfully connected');
console.error('🔄 Retrying connection...');
console.error('⚠️ Fallback method used');
console.error('❌ Connection failed');

// After
logger.success('Successfully connected');
logger.info('Retrying connection...');
logger.warn('Fallback method used');
logger.error('Connection failed');
```

## Implementation Details

The logger is implemented in `src/utils/logger.ts` and uses a singleton pattern. All methods internally call `console.error` to ensure output goes to STDERR, maintaining MCP protocol compatibility.