Debug MCP Server - Ultra Minimal MVP

AI-powered debugging through structured logging and intelligent analysis.

Quick Start (< 5 minutes)

Option 1: Using Development Scripts (Recommended)

# One-command setup ./scripts/dev.sh setup # Start development server ./scripts/dev.sh start # Or run tests ./scripts/dev.sh test

Option 2: Manual Setup

npm install npm run build npm test

Option 3: Docker Setup

# Build and run with Docker npm run docker:build npm run docker:run # Or use Docker Compose docker-compose up

Development Commands

# Development scripts npm run setup # First-time setup npm run dev:server # Start server with auto-rebuild npm run dev:client # Launch interactive manual client npm run test # Run automated validation tests npm run clean # Clean build artifacts and database npm run reset # Full reset and rebuild # Docker commands npm run docker:build # Build Docker image npm run docker:run # Run in container

MVP Features

Available Tools

write_log - Write structured log entries
{ "app_id": "my-app", "level": "error", "message": "Database connection failed", "metadata": { "error_code": "DB_CONN_ERR" } }
get_logs - Query logs with filtering
{ "app_id": "my-app", "limit": 50, "level_filter": ["error", "warn"] }
analyze_logs - AI-powered error pattern analysis
{ "app_id": "my-app", "hours_back": 1 }

Core Value Demonstration

The MVP demonstrates the core value proposition:

Structured Logging: Apps write structured logs with app_id isolation
Pattern Recognition: AI identifies repeated error patterns automatically
Actionable Insights: Provides specific debugging suggestions
Real State Access: Uses actual runtime data for analysis

Example Usage

// Write logs from your application await mcp.callTool("write_log", { app_id: "ecommerce-api", level: "error", message: "Payment processing failed", metadata: { user_id: "user123", amount: 99.99, payment_method: "credit_card", error_code: "PAYMENT_DECLINED" } }); // Get AI analysis const analysis = await mcp.callTool("analyze_logs", { app_id: "ecommerce-api", hours_back: 2 }); console.log(analysis.suggestions); // ["Most frequent error: Payment processing failed (5 occurrences)", // "This error represents >80% of all errors - focus here first"]

Architecture

Database: SQLite (single file, zero setup)
Transport: stdio only (MCP standard)
AI: Simple pattern matching (no external AI yet)
Auth: None (app_id based isolation)

Development Tools

Interactive Manual Client

Test the server manually with a user-friendly interface:

npm run dev:client

Features:

✅ Write log entries interactively
✅ Query logs with filtering
✅ Run AI analysis
✅ List available tools
✅ Guided prompts for all parameters

Integration Example

See a complete integration example:

cd examples && node simple-app.js

This demonstrates:

📝 Real-time logging to Debug MCP Server
🏗️ Structured metadata capture
📊 Log querying and retrieval
🤖 AI-powered error pattern analysis
💡 Actionable debugging suggestions

Project Structure

├── src/ # TypeScript source code │ ├── server.ts # Main MCP server │ ├── database.ts # SQLite operations │ ├── types.ts # TypeScript interfaces │ └── tools/ # MCP tool implementations ├── scripts/ # Development utilities │ ├── dev.sh # Development helper script │ └── manual-client.js # Interactive testing client ├── examples/ # Integration examples │ └── simple-app.js # Complete usage demonstration ├── data/ # SQLite database storage ├── logs/ # Application logs ├── docker-compose.yml # Local Docker setup └── Dockerfile # Production container

MVP Limitations (By Design)

Single transport: stdio only
Simple AI: Pattern matching, no LLM integration yet
No authentication: Direct app_id access
SQLite only: Not production-scale
Basic analysis: Error frequency and patterns only

Next Steps

This MVP validates the core concept. Phase 2 will add:

Real AI analysis (OpenAI/Claude integration)
PostgreSQL with better performance
Multi-transport support (HTTP, SSE)
Authentication and security
Advanced correlation and trace analysis

Testing

The included test client validates:

✅ Writing logs from multiple apps
✅ Querying logs with filters
✅ Error pattern recognition
✅ AI providing actionable suggestions
✅ End-to-end workflow in <30 seconds

Ultra-minimal MVP - built for rapid iteration and validation

Debug MCP Server