Debug MCP Server

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