lcm2m-caddis-mcp

[!WARNING] This server is deprecated and no longer works. The legacy username/password authentication it relied on has been retired, and this package receives no further updates. Use the official hosted MCP server instead: connect your assistant to https://api.lcm2m.com/mcp — there is nothing to install and no credentials to configure; sign in through your browser on first use. See the MCP Server page in the Caddis Systems documentation for setup instructions.

An MCP server that exposes the LCM2M Caddis VM2M API to LLM tools like Claude Desktop, Claude Code, and Cursor. Read-only wrappers over equipment, runs, cycles, telemetry, alarms, and more — served as TOON so LLM context stays cheap.

Requirements

• An LCM2M account (username and password)
• Node.js 25+ or Docker

Use with an MCP client

The server speaks MCP over stdio and works with any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code (Copilot Chat), Zed, Continue, Cline, Goose, and others. Configure your client to launch npx -y @lcm2m/caddis-mcp with CADDIS_USERNAME and CADDIS_PASSWORD in its env. Concrete examples for the two most common config styles follow.

Claude Code (CLI)

claude mcp add caddis \
  --env [email protected] \
  --env CADDIS_PASSWORD='your-password' \
  -- npx -y @lcm2m/caddis-mcp

Claude Desktop, Cursor, and similar (JSON config)

Most clients accept an mcpServers block in a JSON config file — for example claude_desktop_config.json (Claude Desktop) or .cursor/mcp.json (Cursor):

{
  "mcpServers": {
    "caddis": {
      "command": "npx",
      "args": ["-y", "@lcm2m/caddis-mcp"],
      "env": {
        "CADDIS_USERNAME": "[email protected]",
        "CADDIS_PASSWORD": "your-password"
      }
    }
  }
}

Other clients (Windsurf, VS Code, Zed, Continue, Cline, etc.) use similar formats — consult your client's MCP docs for the exact config path and schema. Restart the client after editing config.

Configuration

| Variable | Default | Description | |---|---|---| | CADDIS_USERNAME | (required) | LCM2M account username/email | | CADDIS_PASSWORD | (required) | LCM2M account password | | CADDIS_COMPANY_ID | (auto) | Required if your user belongs to multiple companies | | CADDIS_MAX_RETRIES | 3 | Max 429 retries per request | | CADDIS_MAX_RETRY_WAIT_MS | 30000 | Max total wait budget per request |

Available tools

All tools are read-only and prefixed with caddis_. Each maps 1:1 to a VM2M route; responses are TOON-encoded (a compact, JSON-equivalent format mixing YAML-style nesting with CSV-style tables).

• Company: get_company
• Devices: list_devices, get_device
• Equipment: list_equipment, get_equipment, get_equipment_utilization, get_equipment_schedule, get_equipment_cycles, get_equipment_statuslogs, get_equipment_telemetry, get_equipment_shift_history, list_equipment_excessive_downtimes, get_equipment_excessive_downtime
• Org units / tree: get_org_unit, get_org_unit_schedule, list_org_unit_excessive_downtimes, get_tree
• Alarms: list_alarms
• Tags: list_tags, get_tag, list_tag_groups, get_tag_group
• Runs: list_runs, get_run, get_run_cycles
• Status reasons: list_status_reasons
• Catalog: list_manufacturers, list_models, list_categories

Troubleshooting

• Missing credentials — CADDIS_USERNAME / CADDIS_PASSWORD aren't reaching the child process. With docker run -e VAR, VAR must also be set in the parent shell.
• This user belongs to multiple companies… — set CADDIS_COMPANY_ID to one of the numeric IDs listed in the error.
• 401 Unauthorized — bad creds. Test with:

  curl -X POST https://api.lcm2m.com/vm2m/sessions \
    -H 'Content-Type: application/json' \
    -d '{"username":"[email protected]","password":"...","company_id":1}'

• Persistent 429 — raise CADDIS_MAX_RETRY_WAIT_MS or back off the client's call rate.
• Blank Inspector page in Firefox — use Chrome/Brave/Edge, or npx @modelcontextprotocol/inspector --cli ....

Alternative install

The MCP client examples above use npx. To run from Docker or a local clone instead, build using one of the methods below and swap the command/args in your client config.

Docker

git clone https://github.com/LCM2M/lcm2m-caddis-mcp.git
cd lcm2m-caddis-mcp
docker build --target runtime -t lcm2m-caddis-mcp .

Command string:

docker run -i --rm -e CADDIS_USERNAME -e CADDIS_PASSWORD lcm2m-caddis-mcp

Local Node

git clone https://github.com/LCM2M/lcm2m-caddis-mcp.git
cd lcm2m-caddis-mcp
npm install
npm run build

Command string: node /absolute/path/to/lcm2m-caddis-mcp/dist/index.js

How it works

• Auth: first call hits POST /vm2m/sessions → JWT, cached and proactively refreshed 30s before expiry. 401 triggers a single re-login + retry. The Authorization header carries the raw JWT (no Bearer prefix).
• Rate limiting: backend enforces 20 req/10s per endpoint and 60 req/10s per user. On 429, the client parses Retry-After, applies ±20% jitter, and retries up to CADDIS_MAX_RETRIES (capped by CADDIS_MAX_RETRY_WAIT_MS).
• Response format: TOON — a token-efficient JSON dialect that mixes YAML-style nesting with CSV-style tables (~40% fewer tokens than JSON). The raw body is passed through, fenced as ```toon ... ``` so the model sees an unambiguous format boundary.
• Errors: 4xx responses surface as isError: true tool results so the LLM can see the backend error body and recover; 5xx rethrow.

Development

# Create .env.local with CADDIS_USERNAME and CADDIS_PASSWORD (gitignored).
npm install
npm run dev                 # MCP Inspector web UI + tsx
npm test                    # node --test via tsx
npm run build               # tsc -> dist/
npm run typecheck
npm run lint                # biome check

npm run dev opens the MCP Inspector in a Chromium browser (Firefox has rendering issues). Edit source, click Restart, re-run the tool.

Project layout

src/
  index.ts         # MCP server entry (stdio)
  config.ts        # zod env config
  client.ts        # CaddisApiClient: login, retry, rate-limit
  tools/
    schemas.ts     # shared zod helpers + runTool error wrapper
    index.ts       # tool registration
    wrappers/      # 1:1 VM2M route wrappers
    composite/     # higher-level multi-call tools