leshan-mcp-server/README.md

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

# Leshan MCP Server

A **standards-compliant Model Context Protocol (MCP) server** for [Leshan LwM2M](https://www.eclipse.org/leshan/), exposing Leshan device management as MCP tools. This server allows you to connect Leshan-managed IoT devices to any MCP-compatible client (e.g., Claude Desktop, Cursor, etc.).

## Features
- Standards-compliant MCP server implementation
- Exposes Leshan LwM2M device management as MCP tools
- Easy CLI usage via `npx` or as a global tool
- Configurable Leshan backend connection
- Proper error handling and timeout protection
- Comprehensive logging with development/production modes
- Built-in health checks and connection monitoring

## Installation

### With npx (recommended):
```bash
npx leshan-mcp-server
```

### As a global CLI:
```bash
npm install -g leshan-mcp-server
leshan-mcp-server
```

### As a local dependency:
```bash
npm install leshan-mcp-server
npx leshan-mcp-server
```

## Configuration

Configure the Leshan backend URL with environment variables:

```bash
export LESHAN_HOST="localhost"
export LESHAN_PORT="8084"
export LESHAN_API_BASE="/api"
```

Default values:
- `LESHAN_HOST`: `localhost`
- `LESHAN_PORT`: `8080`
- `LESHAN_API_BASE`: `/api`
- `LESHAN_TIMEOUT`: `30000` (30 seconds)
- `MAX_CONCURRENT_REQUESTS`: `10`

## Usage

### Production Mode (MCP Compliant - No Logging):
```bash
npx leshan-mcp-server
```

### Development Mode (With Debug Logging):
```bash
NODE_ENV=development npx leshan-mcp-server
```

### With Custom Configuration:
```bash
LESHAN_HOST=192.168.1.100 LESHAN_PORT=8084 npx leshan-mcp-server
```

## MCP Client Integration

### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "leshan": {
      "command": "npx",
      "args": ["leshan-mcp-server"],
      "env": {
        "LESHAN_HOST": "localhost",
        "LESHAN_PORT": "8084"
      }
    }
  }
}
```

### Testing with MCP Inspector
```bash
npx @modelcontextprotocol/inspector npx leshan-mcp-server
```

## Available Tools

### list-devices
List all registered LwM2M devices
- **Parameters:** None
- **Returns:** Array of device information

### get-device-info
Get detailed information about a specific device
- **Parameters:** `{ deviceId: string }`
- **Returns:** Device details including registration info

### read-resource
Read a resource value from a device
- **Parameters:** `{ deviceId: string, objectId: string, instanceId: string, resourceId: string }`
- **Returns:** Resource value and metadata

### write-resource
Write a value to a device resource
- **Parameters:** `{ deviceId: string, objectId: string, instanceId: string, resourceId: string, value: any }`
- **Returns:** Write operation result

### observe-resource
Start observing a resource for changes
- **Parameters:** `{ deviceId: string, objectId: string, instanceId: string, resourceId: string }`
- **Returns:** Observation setup confirmation

### cancel-observation
Cancel an active observation
- **Parameters:** `{ deviceId: string, objectId: string, instanceId: string, resourceId: string }`
- **Returns:** Cancellation confirmation

### execute-resource
Execute a resource on a device
- **Parameters:** `{ deviceId: string, objectId: string, instanceId: string, resourceId: string, arguments?: any }`
- **Returns:** Execution result

## Available Prompts

### device-diagnostics
Generate comprehensive device diagnostic reports
- **Parameters:** `{ deviceId: string }`

### device-monitoring
Set up monitoring dashboards for devices
- **Parameters:** `{ deviceIds: string[], monitoringType: string }`

### lwm2m-troubleshooting
Troubleshoot LwM2M connectivity and protocol issues
- **Parameters:** `{ deviceId: string, issueType: string }`

### device-configuration
Configure device settings and parameters
- **Parameters:** `{ deviceId: string, configurationType: string }`

## Error Handling

The server includes comprehensive error handling:
- Connection timeouts and retries
- Proper HTTP status code handling
- Detailed error logging in development mode
- Graceful degradation for network issues

## Logging

- **Production**: Silent operation (MCP compliant)
- **Development**: Detailed JSON logs with timestamps
- **Health checks**: Automatic connection monitoring
- **Request tracking**: Operation IDs for debugging

## Requirements

- Node.js 16+ 
- Access to a running Leshan LwM2M server
- Network connectivity to Leshan server

## Troubleshooting

### Connection Issues
1. Verify Leshan server is running: `curl http://localhost:8084/api/clients`
2. Check environment variables are set correctly
3. Ensure network connectivity between MCP server and Leshan

### 404 Errors
- Verify `LESHAN_API_BASE` matches your Leshan server configuration
- Check if Leshan server uses different API endpoints

### MCP Inspector Issues
- Use CLI inspector: `npx @modelcontextprotocol/inspector npx leshan-mcp-server`
- Web inspector may have connection issues with stdio transport

## License
MIT

## Contributing
Pull requests and issues are welcome! Please ensure all tests pass and follow the existing code style.

## Repository
https://github.com/yourusername/leshan-mcp-server