CodeKarma MCP Server

CodeKarma MCP Server

A Model Context Protocol (MCP) server that provides production insights and code analysis capabilities using your Nexus instrumentation data. Analyze real production flows, identify hot methods, generate test cases, and make data-driven decisions about your code.

⚡ Quick Start Reference

🏠 Local Setup (Development)

./setup.sh                    # Install dependencies & setup venv
python3 quick_test.py         # Test all tools with real data
./run_server.sh               # Start local server (stdio)

🌐 Remote Setup (Docker)

cp env-example .env           # Copy environment template
./restart-server.sh           # Build & start Docker container
./generate-config.sh          # Generate client config (interactive)
./test-mcp-server.sh          # Test remote server via HTTP

🔧 Quick Commands

• ./restart-server.sh - Restart Docker container
• ./generate-config.sh - Create MCP client configs (Direct or nginx proxy)
• python3 quick_test.py - Test all 4 tools locally
• curl http://localhost:8547/health - Check Docker server health

🚀 Deployment Options

**🏠 Local Server** (Original)

• Direct Python execution
• Uses stdio transport
• For local development and testing

**🌐 Remote Server** (New!)

• HTTP/JSON-RPC transport with flexible authentication
• Docker containerized
• For shared team access and production use
• Port: 8547 (non-common port)
• Authentication: Two models supported:
  • Direct: ck-domain header (no auth needed)
  • nginx Proxy: Bearer token (nginx validates and adds ck-domain)

🚀 Features

• 🔥 Hot Method Detection - Identify CPU-intensive methods above configurable thresholds
• 📊 Production Usage Analysis - Get real-time insights about method execution patterns
• 🌳 Flow Tree Visualization - View individual and aggregated execution flow trees
• ⚡ Performance Optimization - Get CPU utilization insights and optimization recommendations
• 🎯 Data-Driven Development - Make code changes based on real production usage

📋 Prerequisites

• Python 3.8+
• Nexus service running on http://localhost:8081
• Instrumented Java application with production flow data

⚡ Quick Start

🏠 Local Server Setup

1. **Setup** (One Command)

git clone <your-repo>
cd ck-mcp-server
./setup.sh

2. **Test the Server**

python3 quick_test.py

3. **Configure Claude Desktop**

Add this to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "nexus": {
      "command": "python3",
      "args": ["/absolute/path/to/ck-mcp-server/server.py"],
      "env": {}
    }
  }
}

4. **Start Using**

./run_server.sh

🌐 Remote Server Setup (Recommended for Teams)

1. **Deploy with Docker**

# Copy environment template
cp env-example .env
# Edit .env with your Nexus endpoint if needed

# Start the server
docker-compose up -d --build

# Or use the simple restart script
./restart-server.sh

2. **Generate Client Configuration**

# Interactive configuration generator
./generate-config.sh

Two Connection Models:

1. Direct Connection: Uses ck-domain header, connects directly to MCP server (port 8547)
2. nginx Proxy: Uses Bearer token, connects through nginx (nginx validates token and adds ck-domain)

Options:

• Connection Type: Choose Direct or nginx Proxy
• Client Type: Choose Windsurf or Claude Desktop/Cursor
• Domain Examples: test, production, staging, or custom

Script will output ready-to-use JSON config for your specific deployment!

3. **Verify Connection**

# Health check
curl http://localhost:8547/health

# Test with domain header
curl -X POST http://localhost:8547/mcp \
  -H "Content-Type: application/json" \
  -H "ck-domain: test" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}'

🛠️ Available Tools

1. **`find_service_names`** 🔍

Find service names from a list of class names visible in your IDE. This tool helps discover which services contain the specified classes when the service name is unknown.

Parameters:

• class_names (required): Array of fully qualified class names (e.g., ['com.example.service.UserService', 'com.example.util.DatabaseUtil'])

Usage:

• When you don't know the service name but have class names from your IDE
• Provide 10-20 class names for optimal matching accuracy
• If multiple services are found, the tool will prompt you to ask the user which service to analyze
• Use discovered service names with other production analysis tools

Example Workflows:

Single Service Found:

1. "Find services for these classes: com.example.UserService, com.example.OrderController"
2. → Returns: ["my-microservice"] 
3. "Analyze production usage for my-microservice"

Multiple Services Found:

1. "Find services for these classes: com.example.U