sylvia-iot-mcp

An MCP server that exposes sylvia-iot-core management APIs as tools for AI assistants (Claude, etc.).

Note: This project is a practice ground for AI-assisted development using Claude Code with a spec-driven workflow powered by OpenSpec.

Features

66 tools across 10 capability areas:

Category	Tools
Auth	auth_tokeninfo, user_get, user_update
OAuth2 Clients	client_create/count/list/get/update/delete
Units	unit_create/count/list/get/update/delete
Applications	application_create/count/list/get/update/delete/stats, application_send_dldata
Networks	network_create/count/list/get/update/delete/stats, network_send_uldata
Devices	device_create/count/list/get/update/delete, bulk and range create/delete
Device Routes	device_route_create/count/list/delete, bulk and range create/delete
Network Routes	network_route_create/count/list/delete
Downlink Buffer	dldata_buffer_count/list/delete
Data	application/network uplink/downlink data counts and lists, coremgr operation logs

Requirements

• Node.js >= 18
• A running sylvia-iot-core instance
• An OAuth2 client with client_credentials grant enabled

Setup

1. Create an OAuth2 client

The MCP server authenticates to sylvia-iot-core using the client_credentials grant. You need a private (confidential) client with this grant enabled.

If you have admin access, you can create one via the sylvia-iot-auth API or management UI.

2. Configure environment variables

Copy .env.example to .env and fill in your values:

cp .env.example .env

SYLVIA_IOT_AUTH_URL=http://your-host/auth
SYLVIA_IOT_COREMGR_URL=http://your-host/coremgr
SYLVIA_IOT_DATA_URL=http://your-host/data
SYLVIA_IOT_CLIENT_ID=your-client-id
SYLVIA_IOT_CLIENT_SECRET=your-client-secret

The URL defaults point to a local sylvia-iot-core instance started with default settings.

3. Run the server

npm install
node src/index.js

Claude Code / Claude Desktop Integration

Add the server to your MCP config (e.g. ~/.claude.json for Claude Code).

Via npx (no installation required):

{
  "mcpServers": {
    "sylvia-iot": {
      "command": "npx",
      "args": ["-y", "github:woofdogtw/sylvia-iot-mcp"],
      "env": {
        "SYLVIA_IOT_AUTH_URL": "http://your-host/auth",
        "SYLVIA_IOT_COREMGR_URL": "http://your-host/coremgr",
        "SYLVIA_IOT_DATA_URL": "http://your-host/data",
        "SYLVIA_IOT_CLIENT_ID": "your-client-id",
        "SYLVIA_IOT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Via local checkout:

{
  "mcpServers": {
    "sylvia-iot": {
      "command": "node",
      "args": ["/path/to/sylvia-iot-mcp/src/index.js"],
      "env": {
        "SYLVIA_IOT_AUTH_URL": "http://your-host/auth",
        "SYLVIA_IOT_COREMGR_URL": "http://your-host/coremgr",
        "SYLVIA_IOT_DATA_URL": "http://your-host/data",
        "SYLVIA_IOT_CLIENT_ID": "your-client-id",
        "SYLVIA_IOT_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Once connected, you can manage your IoT platform conversationally:

"List all units", "Create a new application for unit X", "Show me the latest uplink data from network Y"

Authentication

The server uses OAuth2 client_credentials grant to obtain a bearer token. The token is cached in memory and refreshed automatically on expiry or 401 responses. No user login is required.

Development

# Watch mode
npm run dev

# Run end-to-end tests (requires running sylvia-iot-core)
node test-mcp.mjs