MMaiero/kura-mcp-server

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

# 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

# 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

# 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:

{
  "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:

# 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

Kura Instance Configuration

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:

{
  "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

# 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:

export KURA_MCP_LOG_LEVEL=debug
npm start

Health Checks

Test server health:

# 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 file for details.

Support

For issues, questions, or contributions:

1. Check existing
2. Create a new issue with detailed information
3. Consider contributing improvements via pull requests

Related Projects

• Eclipse Kura - The IoT gateway framework
• Model Context Protocol - The protocol specification
• MCP SDK - TypeScript SDK for MCP