cylera-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server for Cylera that provides read-only access to the Cylera Partner API. It enables LLMs to access device inventory, threat information, risk data, and utilization metrics from Cylera's IoT security platform.

Architecture

The codebase has a simple three-layer architecture:

1. cylera_client.py: REST API client for the Cylera Partner API

   • CyleraClient: Handles authentication (token-based with auto-refresh) and HTTP requests
   • Helper classes (Inventory, Utilization, Network, Risk, Threat): Organize API endpoints by domain
   • All API methods return Dict[str, Any] containing the raw JSON response from Cylera

2. server.py: MCP server implementation using FastMCP

   • Exposes 13 MCP tools that wrap the Cylera API client: get_device, get_procedures, get_device_attributes, get_risk_mitigations, get_subnets, get_vulnerabilities, search_for_devices, search_excluded_devices, get_threats, get_organization, get_available_organizations, switch_organization, reset_organization
   • Formats API responses into human-readable strings or structured dictionaries
   • Tool functions are decorated with @mcp.tool() and called by LLM clients

3. Test files:

   • test_mcp_server.py: Component tests that verify the MCP server using a test client
   • Note: cylera_client.py was moved to a separate shared package; its tests live there

Development Commands

Running Tests

All tests depend on the demo environment. Configure .env file with:

TEST_CYLERA_BASE_URL="https://partner.demo.cylera.com"
CYLERA_BASE_URL="https://partner.demo.cylera.com/"

Run all tests:

uv run pytest -v

Run tests with verbose output:

uv run pytest -v -s

Run all tests including Docker smoke test:

./test.sh

Run all tests with Doppler secrets management:

./test.sh --use-doppler