# MCP Logging Implementation Summary
## Quick Reference Guide
### Current State
- **43+ console.error statements** across 5 files needing migration
- **No structured logging** or client visibility
- **Stderr output only** - not visible to MCP clients
### MCP SDK Logging API (v1.15.0)
```typescript
// Server method available
await server.sendLoggingMessage({
level: "debug" | "info" | "notice" | "warning" | "error" | "critical" | "alert" | "emergency",
logger?: "file-context-server", // Optional logger name
data: message | object // Any JSON serializable content
});
// Client can control logging via:
// logging/setLevel request with desired level
```
### Implementation Architecture
#### LoggingService Interface
```typescript
class LoggingService {
constructor(server: Server, config: LoggingConfig);
// Core methods
async debug(message: string, context?: object): Promise<void>;
async info(message: string, context?: object): Promise<void>;
async warning(message: string, context?: object): Promise<void>;
async error(message: string, error?: Error, context?: object): Promise<void>;
// Configuration
setLevel(level: LoggingLevel): void;
shouldLog(level: LoggingLevel): boolean;
}
```
### Migration Strategy
#### Phase 1: Service Creation (Week 1)
1. Create `src/services/LoggingService.ts`
2. Implement core logging methods with level filtering
3. Add configuration support and fallback to console
#### Phase 2: Server Integration (Week 2)
1. Integrate LoggingService into FileContextServer constructor
2. Handle client `logging/setLevel` requests
3. Add logging to server capabilities
#### Phase 3: Replace Console Logging (Week 3-4)
```typescript
// Before
console.error(`Error reading file ${path}:`, error);
// After
await logger.error("Failed to read file", error, {
filePath: path,
operation: "read_context",
toolName: request.params.name
});
```
### File-by-File Migration Plan
| File | Console Calls | Migration Priority | Context Needed |
|------|---------------|-------------------|----------------|
| `src/index.ts` | 17 | High | Tool name, file paths, request context |
| `src/services/ProfileService.ts` | 13 | Medium | Profile names, config paths |
| `src/services/FileWatcherService.ts` | 9 | Medium | File paths, watcher events |
| `src/services/CodeAnalysisService.ts` | 2 | Low | Analysis type, file info |
| `src/services/TemplateService.ts` | 2 | Low | Template names, render context |
### Key Implementation Points
#### 1. Server Integration
```typescript
// In FileContextServer constructor
private loggingService: LoggingService;
constructor(config: Partial<StreamConfig> = {}) {
// ... existing setup
this.loggingService = new LoggingService(this.server, {
defaultLevel: 'info',
enableConsoleLogging: process.env.NODE_ENV === 'development',
loggerName: 'file-context-server'
});
// Handle client logging requests
this.server.setRequestHandler(SetLevelRequestSchema, async (request) => {
this.loggingService.setLevel(request.params.level);
return {};
});
}
```
#### 2. Service Injection
```typescript
// Pass logging service to all services
this.fileWatcherService = new FileWatcherService(this.loggingService);
this.profileService = new ProfileService(process.cwd(), this.loggingService);
this.templateService = new TemplateService(process.cwd(), this.loggingService);
this.codeAnalysisService = new CodeAnalysisService(this.loggingService);
```
#### 3. Enhanced Error Context
```typescript
// Example enhanced logging
await this.loggingService.error("File access validation failed", error, {
filePath: resolvedPath,
requestedPath: filePath,
operation: "validateAccess",
timestamp: Date.now(),
workingDirectory: process.cwd()
});
```
### Configuration Options
#### Environment Variables
```bash
MCP_LOG_LEVEL=info # Default: info
MCP_LOG_CONSOLE_FALLBACK=true # Default: false in production
MCP_LOG_PERFORMANCE=true # Default: false
```
#### Runtime Configuration
```typescript
interface LoggingConfig {
defaultLevel: LoggingLevel;
enableConsoleLogging: boolean;
loggerName: string;
performance: {
enabled: boolean;
slowOperationThreshold: number; // ms
};
}
```
### Testing Validation
#### Critical Tests Needed
1. **Level Filtering**: Verify only appropriate levels are sent to client
2. **Message Format**: Ensure all logged objects are JSON serializable
3. **Performance**: Measure logging overhead (<5% impact)
4. **Error Handling**: Fallback when sendLoggingMessage fails
5. **Client Integration**: Test with actual MCP clients
#### Manual Verification
1. Start server with MCP client
2. Send `logging/setLevel` request with level "debug"
3. Trigger various operations (file reads, profile changes, etc.)
4. Verify structured log messages appear in client with proper context
### Success Metrics
- ✅ Zero console.error statements remain in production code
- ✅ All log messages include relevant context objects
- ✅ Client can control log levels and see real-time messages
- ✅ Performance impact <5% for typical operations
- ✅ Error messages include stack traces and operational context
### Implementation Checklist
#### Core Service (Week 1)
- [ ] Create LoggingService class with all methods
- [ ] Implement level filtering logic
- [ ] Add JSON serialization with circular reference handling
- [ ] Create configuration interface and defaults
- [ ] Add fallback console logging for development
#### Server Integration (Week 2)
- [ ] Modify FileContextServer to use LoggingService
- [ ] Handle logging/setLevel requests from clients
- [ ] Add logging capability to server initialization
- [ ] Update service constructors to accept LoggingService
#### Migration (Weeks 3-4)
- [ ] Replace all 17 console.error calls in index.ts
- [ ] Replace all 13 console.error calls in ProfileService
- [ ] Replace all 9 console.error calls in FileWatcherService
- [ ] Replace all 2 console.error calls in CodeAnalysisService
- [ ] Replace all 2 console.error calls in TemplateService
- [ ] Add structured context to all log messages
- [ ] Remove console logging dependencies
#### Testing & Documentation
- [ ] Create unit tests for LoggingService
- [ ] Add integration tests with mock MCP client
- [ ] Update README with logging configuration options
- [ ] Create example logging configurations
- [ ] Performance benchmarking and optimization
This implementation will provide professional, structured logging while maintaining all existing functionality and improving debuggability for MCP clients.