# Kura MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Eclipse Kura IoT gateways through their REST APIs. This server enables AI assistants and other MCP clients to interact with Kura instances for device management, configuration, and monitoring tasks.

## Features

- **Comprehensive Kura API Integration**: Access system properties, configurations, cloud connections, deployment packages, services, and security features
- **Multi-Instance Support**: Connect to multiple Kura instances simultaneously
- **Robust Authentication**: Secure session management with automatic re-authentication
- **Flexible Configuration**: JSON files, environment variables, or multiple configuration sources
- **Docker Support**: Containerized deployment with Docker and Docker Compose
- **Type Safety**: Full TypeScript implementation with Zod validation
- **Retry Logic**: Automatic retry mechanisms for network resilience
- **Health Checking**: Built-in health checks for monitoring

## Installation

### From Source

```bash
# Clone the repository
git clone <repository-url>
cd kura-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start
```

### Using Docker

```bash
# Build and run with Docker Compose
docker-compose up -d

# Or build and run with Docker directly
docker build -t kura-mcp-server .
docker run -p 3000:3000 -v $(pwd)/kura-mcp-config.json:/etc/kura-mcp/config.json kura-mcp-server
```

### Development Mode

```bash
# Run in development mode with auto-reload
npm run dev
```

## Configuration

The server supports multiple configuration methods in order of precedence:

1. Environment variable `KURA_MCP_CONFIG` pointing to a config file
2. `./kura-mcp-config.json` in the current directory
3. `~/.kura-mcp-config.json` in the home directory
4. `/etc/kura-mcp/config.json` system-wide configuration
5. Environment variables for individual settings

### Configuration File Format

Create a `kura-mcp-config.json` file:

```json
{
  "port": 3000,
  "logLevel": "info",
  "maxRequestSize": 1048576,
  "requestTimeout": 30000,
  "kuraInstances": {
    "local-kura": {
      "name": "Local Kura Development",
      "host": "localhost",
      "port": 8080,
      "protocol": "http",
      "username": "admin",
      "password": "admin",
      "timeout": 30000,
      "retryAttempts": 3,
      "retryDelay": 1000,
      "validateSSL": false
    },
    "production-kura": {
      "name": "Production Kura Gateway",
      "host": "192.168.1.100",
      "port": 443,
      "protocol": "https",
      "username": "admin",
      "password": "your-secure-password",
      "timeout": 30000,
      "retryAttempts": 3,
      "retryDelay": 1000,
      "validateSSL": true
    }
  }
}
```

### Environment Variables

Configure the server using environment variables:

```bash
# Server settings
export KURA_MCP_PORT=3000
export KURA_MCP_LOG_LEVEL=info

# Kura instance configuration (replace LOCAL with your instance name)
export KURA_INSTANCE_LOCAL_HOST=localhost
export KURA_INSTANCE_LOCAL_PORT=8080
export KURA_INSTANCE_LOCAL_PROTOCOL=http
export KURA_INSTANCE_LOCAL_USERNAME=admin
export KURA_INSTANCE_LOCAL_PASSWORD=admin
export KURA_INSTANCE_LOCAL_VALIDATE_SSL=false
```

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `port` | number | 3000 | MCP server port |
| `logLevel` | string | 'info' | Log level (debug, info, warn, error) |
| `maxRequestSize` | number | 1048576 | Maximum request size in bytes |
| `requestTimeout` | number | 30000 | Request timeout in milliseconds |
| `kuraInstances` | object | {} | Kura instance configurations |

#### Kura Instance Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `name` | string | - | Human-readable instance name |
| `host` | string | - | Kura gateway hostname or IP |
| `port` | number | 8080 | Kura web interface port |
| `protocol` | string | 'http' | Protocol (http or https) |
| `username` | string | - | Kura username |
| `password` | string | - | Kura password |
| `timeout` | number | 30000 | Request timeout in milliseconds |
| `retryAttempts` | number | 3 | Number of retry attempts |
| `retryDelay` | number | 1000 | Delay between retries in milliseconds |
| `validateSSL` | boolean | true | Whether to validate SSL certificates |

## Available MCP Tools

The server provides the following tools for interacting with Kura instances:

### System Information
- `kura_get_kura_properties` - Get system properties
- `kura_get_framework_properties` - Get OSGi framework properties
- `kura_test_connection` - Test connection to a Kura instance

### Configuration Management
- `kura_get_configurations` - Get all component configurations
- `kura_get_configuration` - Get a specific component configuration
- `kura_update_configuration` - Update component configuration

### Snapshot Management
- `kura_get_snapshots` - Get all configuration snapshots
- `kura_create_snapshot` - Create a new configuration snapshot
- `kura_rollback_snapshot` - Rollback to a specific snapshot

### Cloud Connectivity
- `kura_get_cloud_connections` - Get all cloud connections
- `kura_connect_cloud` - Connect a cloud connection
- `kura_disconnect_cloud` - Disconnect a cloud connection

### Package Management
- `kura_get_packages` - Get installed deployment packages
- `kura_install_package` - Install a deployment package

### Service Management
- `kura_get_services` - Get all OSGi services

### Security Management
- `kura_get_users` - Get all users
- `kura_get_certificates` - Get certificates from keystore

## Usage Examples

### Using with Claude Desktop

Add this server to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "kura": {
      "command": "node",
      "args": ["/path/to/kura-mcp-server/dist/index.js"],
      "env": {
        "KURA_INSTANCE_LOCAL_HOST": "localhost",
        "KURA_INSTANCE_LOCAL_USERNAME": "admin",
        "KURA_INSTANCE_LOCAL_PASSWORD": "admin"
      }
    }
  }
}
```

### Basic Operations

Once connected through an MCP client, you can:

1. **Check system status**:
   ```
   Use kura_get_kura_properties with instance "local-kura" to get system information
   ```

2. **Manage configurations**:
   ```
   Use kura_get_configurations with instance "local-kura" to list all component configurations
   ```

3. **Create configuration backups**:
   ```
   Use kura_create_snapshot with instance "local-kura" to create a configuration snapshot
   ```

4. **Monitor cloud connectivity**:
   ```
   Use kura_get_cloud_connections with instance "local-kura" to check cloud connection status
   ```

## Development

### Project Structure

```
src/
├── types/           # TypeScript type definitions
│   ├── config.ts    # Configuration types
│   └── kura.ts      # Kura API types
├── services/        # Core service implementations
│   ├── ConfigService.ts  # Configuration management
│   ├── KuraClient.ts     # Kura REST API client
│   └── McpServer.ts      # MCP server implementation
└── index.ts         # Application entry point
```

### Adding New Tools

To add a new MCP tool:

1. Add the tool definition in `McpServer.ts` `setupHandlers()` method
2. Implement the handler logic in the `handleToolCall()` method
3. Add corresponding API methods to `KuraClient.ts` if needed
4. Update type definitions in `types/kura.ts` as required

### Testing

```bash
# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run linting
npm run lint
```

## Security Considerations

- **Credential Management**: Store sensitive credentials securely using environment variables or secure configuration files
- **SSL/TLS**: Enable SSL validation in production environments
- **Network Security**: Ensure proper network segmentation between the MCP server and Kura instances
- **Access Control**: Use proper authentication and authorization for Kura instances
- **Container Security**: Run containers with non-root users and minimal privileges

## Troubleshooting

### Common Issues

1. **Connection Failed**: Check network connectivity, credentials, and Kura instance status
2. **Authentication Errors**: Verify username/password and ensure the Kura user has proper permissions
3. **SSL Certificate Errors**: Set `validateSSL: false` for development or add proper certificates
4. **Timeout Errors**: Increase timeout values in configuration

### Debug Mode

Enable debug logging:

```bash
export KURA_MCP_LOG_LEVEL=debug
npm start
```

### Health Checks

Test server health:

```bash
# Check if server is responsive
curl -f http://localhost:3000/health || echo "Server not healthy"
```

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'feat: add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

### Commit Convention

Use conventional commits:
- `feat:` for new features
- `fix:` for bug fixes
- `docs:` for documentation changes
- `refactor:` for code refactoring
- `test:` for test-related changes
- `chore:` for maintenance tasks

## License

This project is licensed under the Eclipse Public License 2.0 - see the [LICENSE](LICENSE) file for details.

## Support

For issues, questions, or contributions:

1. Check existing [issues](../../issues)
2. Create a new issue with detailed information
3. Consider contributing improvements via pull requests

## Related Projects

- [Eclipse Kura](https://github.com/eclipse/kura) - The IoT gateway framework
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol specification
- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) - TypeScript SDK for MCP