leshan-mcp-server/src/prompts/lwm2mTroubleshootingPrompt.js

A standards-compliant MCP server for Leshan LwM2M, exposing Leshan as Model Context Protocol tools.

import logger from "../utils/loggerConfig.js";

/**
 * LwM2M troubleshooting prompt for diagnosing and resolving device issues
 * @param {Object} params - Prompt parameters
 * @param {string} params.deviceId - Device endpoint with issues
 * @param {string} params.issueType - Type of issue (connectivity, registration, resource, performance)
 * @param {string} params.symptoms - Description of observed symptoms
 * @returns {Promise<Object>} MCP prompt response
 */
export async function lwm2mTroubleshootingPrompt({ deviceId, issueType = "general", symptoms }) {
  const operationId = `lwm2m-troubleshooting-${Date.now()}`;
  
  try {
    logger.info("LwM2M troubleshooting prompt requested", { 
      operationId, 
      deviceId, 
      issueType,
      hasSymptoms: !!symptoms
    });

    const prompt = `# LwM2M Device Troubleshooting Guide

You are an expert LwM2M troubleshooting specialist. Diagnose and resolve issues with device: **${deviceId || '[DEVICE_ID]'}**

## Issue Classification: ${issueType.toUpperCase()}

${symptoms ? `### Reported Symptoms:\n${symptoms}\n` : ''}

## Systematic Troubleshooting Approach

### 1. Initial Assessment
- Verify device registration status in Leshan server
- Check last communication timestamp
- Review device registration parameters
- Confirm network connectivity

### 2. Issue-Specific Diagnostics

#### Connectivity Issues
- **Registration Problems**:
  - Check Security Object (0) configuration
  - Verify server URI and security credentials
  - Review bootstrap configuration
  - Validate network connectivity (IP, port, firewall)

- **Communication Timeouts**:
  - Check device lifetime settings
  - Verify network bearer and signal strength
  - Review CoAP message transmission
  - Analyze packet loss and latency

#### Resource Access Issues
- **Read/Write Failures**:
  - Verify resource permissions and access rights
  - Check resource data types and formats
  - Validate object and resource IDs
  - Review device object model compliance

- **Observation Problems**:
  - Check observation setup and parameters
  - Verify notification settings
  - Review observation token management
  - Analyze notification delivery

#### Performance Issues
- **Slow Response Times**:
  - Monitor device processing capabilities
  - Check memory and CPU usage
  - Review network latency and bandwidth
  - Analyze concurrent request handling

- **Battery Drain**:
  - Review communication frequency
  - Check observation intervals
  - Analyze power management settings
  - Monitor sleep/wake cycles

### 3. Common LwM2M Issues & Solutions

#### Registration Issues
1. **Device Not Registering**:
   - Verify endpoint name uniqueness
   - Check security credentials
   - Validate server URI accessibility
   - Review firewall and NAT settings

2. **Registration Expiry**:
   - Adjust lifetime values
   - Check update frequency
   - Monitor network stability
   - Review device sleep patterns

#### Resource Issues
1. **Resource Not Found (4.04)**:
   - Verify object/instance/resource path
   - Check device object model
   - Validate resource implementation
   - Review access permissions

2. **Method Not Allowed (4.05)**:
   - Check resource operation permissions
   - Verify read/write/execute capabilities
   - Review security policies
   - Validate resource types

#### Communication Issues
1. **Request Timeout**:
   - Increase timeout values
   - Check network connectivity
   - Review device responsiveness
   - Monitor CoAP retransmission

2. **Observation Failures**:
   - Verify observation setup
   - Check notification parameters
   - Review token management
   - Monitor observation lifecycle

### 4. Diagnostic Tools & Commands

Use these MCP tools for troubleshooting:

#### Device Status Check:
\`\`\`
get-device-info --deviceId=${deviceId || '[DEVICE_ID]'}
\`\`\`

#### Resource Diagnostics:
\`\`\`
read-resource --deviceId=${deviceId || '[DEVICE_ID]'} --objectId=3 --instanceId=0 --resourceId=11  # Error Code
read-resource --deviceId=${deviceId || '[DEVICE_ID]'} --objectId=3 --instanceId=0 --resourceId=12  # Reboot Counter
read-resource --deviceId=${deviceId || '[DEVICE_ID]'} --objectId=3 --instanceId=0 --resourceId=9   # Battery Level
\`\`\`

#### Connectivity Testing:
\`\`\`
read-resource --deviceId=${deviceId || '[DEVICE_ID]'} --objectId=4 --instanceId=0 --resourceId=2   # Signal Strength
read-resource --deviceId=${deviceId || '[DEVICE_ID]'} --objectId=4 --instanceId=0 --resourceId=4   # IP Address
\`\`\`

### 5. Resolution Steps

1. **Immediate Actions**:
   - Verify basic connectivity
   - Check critical error indicators
   - Review recent configuration changes
   - Validate security settings

2. **Systematic Investigation**:
   - Follow issue-specific diagnostic procedures
   - Collect relevant resource values
   - Analyze error patterns and trends
   - Test resource operations

3. **Solution Implementation**:
   - Apply targeted fixes based on findings
   - Update device configuration if needed
   - Restart observations or connections
   - Verify resolution effectiveness

4. **Prevention Measures**:
   - Implement monitoring for early detection
   - Set up appropriate alerts
   - Document lessons learned
   - Update troubleshooting procedures

### 6. Escalation Criteria

Escalate to device manufacturer or network provider if:
- Hardware-level failures detected
- Firmware bugs identified
- Network infrastructure issues
- Security certificate problems
- Persistent unexplained behavior

## Troubleshooting Context
${deviceId ? `Target Device: ${deviceId}` : 'Please specify the device endpoint ID.'}
Issue Type: ${issueType}
${symptoms ? `Symptoms: ${symptoms}` : 'Please describe the observed symptoms.'}

Begin troubleshooting by gathering device information and following the systematic diagnostic approach outlined above.`;

    logger.info("LwM2M troubleshooting prompt generated", { 
      operationId, 
      deviceId, 
      issueType 
    });

    return {
      messages: [{
        role: "user",
        content: {
          type: "text",
          text: prompt
        }
      }]
    };

  } catch (error) {
    logger.error("LwM2M troubleshooting prompt failed", {
      operationId,
      deviceId,
      issueType,
      error: error.message
    });

    return {
      messages: [{
        role: "user",
        content: {
          type: "text",
          text: `Error generating LwM2M troubleshooting prompt: ${error.message}`
        }
      }]
    };
  }
}

export default lwm2mTroubleshootingPrompt;