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

1. write_log - Write structured log entries

   {
     "app_id": "my-app",
     "level": "error", 
     "message": "Database connection failed",
     "metadata": { "error_code": "DB_CONN_ERR" }
   }

2. get_logs - Query logs with filtering

   {
     "app_id": "my-app",
     "limit": 50,
     "level_filter": ["error", "warn"]
   }

3. analyze_logs - AI-powered error pattern analysis

   {
     "app_id": "my-app", 
     "hours_back": 1
   }

Core Value Demonstration

The MVP demonstrates the core value proposition:

1. Structured Logging: Apps write structured logs with app_id isolation

2. Pattern Recognition: AI identifies repeated error patterns automatically

3. Actionable Insights: Provides specific debugging suggestions

4. 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