CodeKarma 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.UserService, com.example.OrderController" 
2. → Returns: ["my-microservice", "order-service", "user-service"]
3. → LLM asks: "I found 3 services... Which service would you like to analyze?"
4. User responds: "Let's analyze my-microservice"
5. "Analyze production usage for my-microservice"

2. get_production_usage

Get production usage information for methods including throughput and activity status.

Parameters:

• service_name (required): Name of the service (e.g., 'codetrails')
• class_name (required): Full class name
• method_name (optional): Specific method name
• step (optional): Time window (default: '1m')

3. get_production_call_flows

Analyze production method call patterns and flows with aggregated performance metrics and hot method annotations.

Parameters:

• service_name (required): Name of the service
• class_name (required): Full class name
• method_name (optional): Specific method name
• step (optional): Time window (default: '1m')

4. get_hot_methods 🔥

Get details about hot methods that have high CPU utilization in production (above 1% CPU threshold).

Parameters:

• service_name (required): Name of the service
• step (optional): Time window (default: '1m')

💡 Usage Examples

Service Discovery (New!)

"I can see these classes in my IDE: UserService, OrderController, PaymentService, DatabaseUtil. Which services do they belong to?"

• Automatically discovers service names from class names
• No need to manually know service names
• Sets up other tools for further analysis

Complete Workflow (Unknown Service)

1. "Find services for: com.example.UserService, com.example.OrderController"
2. "Analyze production usage for [discovered-service] UserService class"
3. "Show hot methods in [discovered-service]"

• Start with class names from your IDE
• Discover services automatically
• Dive into production analysis

Hot Method Analysis

"Show me all hot methods in the codetrails service"

• Identifies CPU-intensive methods
• Shows CPU utilization percentages
• Provides optimization recommendations

Production Flow Analysis

"Analyze the production usage for OrderUtil class in codetrails service"

• Shows QPS, error rates, latency for each method
• Identifies active vs inactive methods
• Highlights HTTP endpoints

Execution Tree Visualization

"Show me the call flows for OrderController in codetrails"

• Displays aggregated flow trees
• Shows CPU annotations for hot methods (🔥)
• Includes flow IDs and metrics

Combined Analysis

"Get the call flows for OrderUtil and highlight any hot methods"

• Shows comprehensive flow analysis
• Annotates hot methods with CPU utilization
• Provides context about flow patterns

🎯 Key Features in Detail

🔥 Hot Method Detection

• CPU Threshold: Automatically detects methods above 1% CPU utilization
• Performance Impact: Shows actual CPU consumption percentages
• Optimization Targeting: Prioritizes optimization efforts on high-impact methods
• Visual Indicators: Hot methods marked with 🔥 in flow trees

📊 Flow Tree Annotations

• Individual Flows: Shows hot methods in each execution path
• Unified Trees: Aggregates CPU data across all flows
• Visual Clarity: CPU: X.XX% 🔥 annotations in tree output
• Context Aware: Matches methods by className + methodName

⚡ Production Insights

• Real-time Data: Live production metrics from Nexus
• HTTP Endpoints: Shows which endpoints trigger hot methods
• Error Correlation: Combines CPU usage with error rates
• Throughput Analysis: QPS/QPM data alongside CPU metrics

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Claude UI     │────│   MCP Server     │────│   Nexus API     │
│                 │    │                  │    │                 │
│ Natural Lang    │    │ - Tool Handlers  │    │ - Flow Data     │
│ Queries         │    │ - Hot Methods    │    │ - CPU Metrics   │
│                 │    │ - Tree Builders  │    │ - Production    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Components:

• NexusClient: Async HTTP client for Nexus API calls
• Hot Methods Engine: CPU threshold detection and annotation
• Tree Builders: Flow tree construction and visualization
• Analysis Functions: Production usage insights and recommendations

🧪 Testing

Local Testing

# Test all tools with real API
python3 quick_test.py

# Test raw APIs only  
python3 quick_test.py --raw

What Gets Tested:

• ✅ All 4 MCP tools (service discovery, usage analysis, call flows, hot methods)
• ✅ Raw Nexus API connectivity (find-service-name, mpks, flows, flow-details, hot-methods)
• ✅ Service discovery from class names
• ✅ Hot method detection and annotation
• ✅ Real production data integration

Sample Test Output:

🚀 Quick MCP Tools Test
==========================================

0️⃣ SERVICE DISCOVERY TOOL
------------------------------

# Service Name Discovery

## Input Classes (4)
1. `OrderUtil` (Full: `com.example.codetrails.orders.util.OrderUtil`)
2. `OrderServiceImpl` (Full: `com.example.codetrails.orders.service.impl.OrderServiceImpl`)
3. `OrderController` (Full: `com.example.codetrails.orders.controller.OrderController`)
4. `RequestLogFilter` (Full: `com.example.codetrails.config.RequestLogFilter`)

## Discovery Results
✅ **Service Names Found:** 1 matching service(s)
**Domain:** test

### Matching Services:
1. `codetrails`

### Next Steps
You can now use these service name(s) with other production analysis tools:
- `get_production_usage(service_name="codetrails", class_name="...")`
- `get_production_call_flows(service_name="codetrails", class_name="...")`
- `get_hot_methods(service_name="codetrails")`

==================================================

3️⃣ HOT METHODS TOOL
------------------------------

# Hot Methods Report
**Service:** codetrails
**CPU Threshold:** ≥ 1.0%

## Hot Methods Found (1)

### 1. `OrderServiceImpl.compareCharactersExpensively` 🔥
**CPU Utilization:** 1.611%
**Throughput (QPS):** 1,723,283.72
**Optimization Target:** Primary candidate for performance improvement

📁 Project Structure

ck-mcp-server/
├── server.py                   # Local MCP server (stdio)
├── remote_server.py            # Remote MCP server (HTTP/JSON-RPC)
├── quick_test.py               # Comprehensive testing script  
├── setup.sh                    # One-command local setup
├── restart-server.sh           # Simple Docker container restart
├── test-mcp-server.sh          # Remote server testing script
├── run_server.sh               # Local server runner  
├── requirements.txt            # Python dependencies
├── Dockerfile                  # Docker image configuration
├── docker-compose.yml          # Docker Compose setup
├── .dockerignore              # Docker build exclusions
├── env-example                 # Environment variables template
├── mcp-config.json            # Local MCP configuration (uses env vars)
├── generate-config.sh         # Interactive MCP client config generator
├── README.md                   # This documentation
└── nexus-api.md               # API reference

Key Configuration Files:

• mcp-config.json: For local server (Claude Desktop) - sets CK_NEXUS_ENDPOINT env var
• generate-config.sh: Interactive script to generate remote MCP client configs
• .env: Docker Compose environment variables

🔧 Configuration

Logging Level

Control the verbosity of server logs using the LOG_LEVEL environment variable:

Available Levels: DEBUG, INFO, WARNING, ERROR, CRITICAL

Default: INFO (shows INFO, WARNING, ERROR, CRITICAL)

To see debug logs:

# For Docker/remote server - add to .env file:
LOG_LEVEL=DEBUG

# For local server:
export LOG_LEVEL=DEBUG
./run_server.sh

What each level shows:

• DEBUG: All logs including debug messages (most verbose)
• INFO: Informational messages and above (default)
• WARNING: Warning messages and above
• ERROR: Error messages only
• CRITICAL: Critical errors only

Domain-Based Routing

The server uses the ck-domain header to determine which Nexus API path to use:

Generate MCP Client Configuration:

# Use the interactive generator
./generate-config.sh

# Example output for direct connection:
{
  "mcpServers": {
    "codekarma-insights": {
      "url": "http://localhost:8547/mcp",
      "headers": {
        "ck-domain": "production"  // ← Direct to MCP server
      }
    }
  }
}

# Example output for nginx proxy:
{
  "mcpServers": {
    "codekarma-insights": {
      "url": "https://nginx-proxy.com/mcp",
      "headers": {
        "Authorization": "Bearer mcp_xxx"  // ← nginx validates this
      }
    }
  }
}

Domain → API Path Mapping:

• ck-domain: "test" → Nexus calls to /test/api/method-graph-paths/...
• ck-domain: "production" → Nexus calls to /production/api/method-graph-paths/...
• ck-domain: "staging" → Nexus calls to /staging/api/method-graph-paths/...

Nexus Connection

Default: AWS ELB endpoint (see server.py)

Recommended: Set via environment variable:

export CK_NEXUS_ENDPOINT="http://your-nexus-server:8081"

Docker/Kubernetes:

# In your .env file or Helm values
CK_NEXUS_ENDPOINT=http://your-nexus-server:8081

Alternative: Modify directly in server.py:

class NexusClient:
    def __init__(self, base_url: str = "http://your-nexus:8081"):

CPU Threshold

Default: 1.0% for hot method detection

To change, modify in server.py:

hot_methods = await client.get_hot_methods(service_name, cpu_threshold=2.0)

🐛 Troubleshooting

Connection Issues

❌ Error: Connection refused

Solution: Ensure Nexus is running on localhost:8081

No Hot Methods Found

No hot methods found (no methods exceed 1% CPU utilization threshold)

Solution: Check that your application has CPU-intensive operations or lower the threshold

Empty Flow Trees

No production data found for ClassName

Solution: Verify class name exists and has production traffic

Missing CPU Annotations

Flow trees show but no 🔥 indicators

Solution: Ensure hot methods API is working: curl http://localhost:8081/{domain}/api/method-graph-paths/hot-methods?serviceName=yourservice&cpuThreshold=1

🚀 Next Steps

1. Deploy to Production: Use with your production Nexus instance
2. Custom Thresholds: Adjust CPU thresholds for your environment
3. Integration: Add to CI/CD pipelines for performance monitoring
4. Optimization: Use hot method data to prioritize performance improvements
5. Monitoring: Set up alerts for new hot methods in production

🤝 Contributing

1. Add New Tools: Extend handle_list_tools() and handle_call_tool()
2. Enhance Analysis: Add new metrics and insights to existing tools
3. Improve Visualization: Enhance tree rendering and annotations
4. Testing: Add test cases to quick_test.py

📊 API Endpoints Used

The server integrates with these Nexus endpoints (domain dynamically set via ck-domain header):

• POST /{domain}/api/method-graph-paths/find-service-name - Service discovery from class names
• GET /{domain}/api/method-graph-paths/mpks - Method summary with profiling info
• GET /{domain}/api/method-graph-paths/flows - Flow IDs for methods
• GET /{domain}/api/method-graph-paths/flow-details - Detailed flow trees
• GET /{domain}/api/method-graph-paths/hot-methods - CPU-intensive methods

Examples:

• With ck-domain: test → /test/api/method-graph-paths/mpks
• With ck-domain: production → /production/api/method-graph-paths/mpks

---

🔥 Ready to optimize your production code with data-driven insights!

Start by running ./setup.sh and then python3 quick_test.py to see your hot methods in action.