MCP Adapter for SuzieQ Telemetry Interface

This implementation serves as a Model Context Protocol (MCP) server, bridging language models and other compatible clients with an active SuzieQ observability deployment via its exposed Application Programming Interface (API).

Core Functionality

The server exposes the primary capabilities of the SuzieQ interface as distinct MCP functionalities:

• run_suzieq_show: Provides direct access to query detailed, stateful network data structures (e.g., routing tables, interface status).
• run_suzieq_summarize: Facilitates the retrieval of pre-calculated aggregations and statistical overviews from the network data.

These methods empower clients (such as Claude Desktop) to systematically inspect diverse network artifacts—including BGP peer status, routing entries, or port configurations—applying specified constraints to narrow the returned information.

Setup Requirements

• Python Environment: Version 3.8 or newer is strongly recommended for optimal operation.
• Package Manager: Utilization of uv is advised for swift dependency resolution and installation.
• Active SuzieQ Instance: A running SuzieQ component with its attendant web service API enabled and network reachable.
• Authentication Details: Necessary credentials include the complete SuzieQ API URI (e.g., http://your-suzieq-host:8000/api/v2) and an authorization token (access_token).

Installation Procedures

Deployment via Smithery

For automated integration with Claude Desktop using Smithery:

bash npx -y @smithery/cli install @PovedaAqui/suzieq-mcp --client claude

Manual Compilation

1. Acquire Source Code: Download the necessary files (main.py, server.py) or clone this repository into a designated workspace.

2. Initialize Virtual Environment: Navigate to the project root directory and establish an isolated environment using uv: bash uv venv

3. Activate Context: Enter the virtual environment:

4. Unix-like systems (Linux/macOS): bash source .venv/bin/activate

5. Windows (Command Prompt/PowerShell): bash .venv\Scripts\activate

6. Install Dependencies: Use uv to install required libraries: bash uv pip install mcp httpx python-dotenv

7. mcp: The Model Context Protocol Software Development Kit.

8. httpx: The asynchronous HTTP client utilized for API calls to SuzieQ.
9. python-dotenv: Employed for sourcing configuration parameters from environment files.

Configuration of API Access

Access credentials must be provided to the server. A file named .env is the prescribed method for secure configuration:

1. Create .env: Place a file named .env in the top-level project directory (co-located with main.py).

2. Populate Credentials: Input your SuzieQ endpoint URL and security key. Crucially, do not wrap the values in quotation marks unless the actual token/URL contains them. dotenv # .env SUZIEQ_API_ENDPOINT=http://your-suzieq-host:8000/api/v2 SUZIEQ_API_KEY=your_actual_api_key

Substitute the placeholder strings with your operational values.

1. Secret Protection: Update your version control ignore file to exclude this file: bash echo ".env" >> .gitignore

2. Runtime Loading: The server.py script is programmed to automatically ingest these variables upon initialization via the python-dotenv library.

Server Execution

Ensure your virtual environment is active. The server initialization relies on the configuration found in the local .env file.

1. Direct Launch

Execute the primary Python file via the environment's runner:

bash uv run python main.py

The server will initialize, log a startup message (e.g., Starting SuzieQ MCP Server...), and await MCP communication over standard I/O streams. Successful API interaction will generate corresponding [INFO] logs. Terminate execution with Ctrl+C.

2. Debugging with MCP Inspector

If you have installed the MCP command-line utilities (uv pip install "mcp[cli]"), you can use the integrated debugger:

bash uv run mcp dev main.py

This opens an interactive debugging console. Navigate to the 'Tools' section, select run_suzieq_show, specify arguments (e.g., table: "device"), and invoke the tool to validate functionality.

Integration with Claude Desktop

For integration into the Claude Desktop application, modify its configuration file:

1. Locate Configuration: Find the claude_desktop_config.json file. Paths typically are:
2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Windows: %APPDATA%\Claude\claude_desktop_config.json

4. Create the necessary directory structure and file if absent.

5. Modify JSON Structure: Inject a definition for this server. It is mandatory to use the absolute filesystem path to main.py.

{ "mcpServers": { "suzieq-server": { // Specify 'uv' if it's globally accessible by Claude's execution context, // otherwise, use the full file system path to the 'uv' binary. "command": "uv", "args": [ "run", "python", // --- ABSOLUTE PATH REQUIRED HERE --- "/full/path/to/your/project/mcp-suzieq-server/main.py" ], // Setting this assists the process in locating the necessary .env file. "workingDirectory": "/full/path/to/your/project/mcp-suzieq-server/" } // Potential entries for other MCP instances } }

• Ensure the path specified points precisely to your main.py location.
• Setting workingDirectory is highly recommended as it ensures the server correctly locates the configuration held within the .env file.
• If uv is not found, replace the command with its explicit path (determined via which uv or where uv).

• For Windows users experiencing encoding issues, consider adding "env": { "PYTHONUTF8": "1" } to the server configuration block.

• Reload Application: Perform a full restart of Claude Desktop.

• Verification: Observe the MCP interface icon (hammer symbol 🔨) within Claude Desktop. It should now list both run_suzieq_show and run_suzieq_summarize as available instruments.

Function Signature: run_suzieq_show

run_suzieq_show(table: str, filters: Optional[Dict[str, Any]] = None) -> str

• table: (Mandatory String) The specific SuzieQ data structure identifier (e.g., "interface", "bgp", "device").
• filters: (Optional Dictionary) A mapping of attributes to target values for result pruning (e.g., {"hostname": "leaf01"}). Provide {} or omit if no filtering is needed.
• Output: Returns the query results as a JSON formatted string, or an error report.

Usage Illustration (Conceptual):

Retrieve all entries for the device table:

{ "table": "device" }

Isolate BGP sessions pertaining only to the device named 'spine01':

{ "table": "bgp", "filters": { "hostname": "spine01" } }

Query interfaces in the 'default' VRF that possess an 'up' operational state:

{ "table": "interface", "filters": { "vrf": "default", "state": "up" } }

Function Signature: run_suzieq_summarize

run_suzieq_summarize(table: str, filters: Optional[Dict[str, Any]] = None) -> str

• table: (Mandatory String) The SuzieQ table upon which to compute a summary (e.g., "interface", "bgp").
• filters: (Optional Dictionary) Constraints applied prior to summarization (e.g., {"hostname": "leaf01"}).
• Output: Returns the aggregated summary data encoded as a JSON string, or an error message.

Usage Illustration (Conceptual):

Generate a summary across the entire device inventory:

{ "table": "device" }

Summarize BGP adjacency status specifically for the host 'spine01':

{ "table": "bgp", "filters": { "hostname": "spine01" } }

Aggregate the counts of interface statuses within the 'default' VRF context:

{ "table": "interface", "filters": { "vrf": "default" } }

Troubleshooting Guide

Failure Log: "SuzieQ API endpoint or key missing..."

• Confirm the .env artifact resides in the same directory as main.py.
• Validate that the variable identifiers (SUZIEQ_API_ENDPOINT, SUZIEQ_API_KEY) are spelled correctly and hold valid credentials within .env.
• If using Claude Desktop, verify that the workingDirectory setting in claude_desktop_config.json correctly resolves to the directory containing .env.

Communication Failures (HTTP 4xx/5xx Responses)

• Inspect the provided SUZIEQ_API_KEY for authenticity (relevant for 401/403 access denials).
• Confirm the network path to the configured SUZIEQ_API_ENDPOINT is open and that the SuzieQ API service is operational.

WIKIPEDIA: Cloud computing is defined by ISO as "a paradigm for enabling network access to a scalable and elastic pool of shareable physical or virtual resources with self-service provisioning and administration on-demand." This concept is commonly referred to as "the cloud."

== Defining Attributes == In 2011, the United States National Institute of Standards and Technology (NIST) formalized five "essential characteristics" for systems classified as cloud-based. These foundational descriptors are:

On-demand self-service: A consumer possesses the capability to provision computational assets, such as compute cycles or persistent storage, autonomously without requiring intervention from the service provider's personnel. Broad network accessibility: Services must be reachable across a network via established protocols, supporting a wide array of client devices (e.g., smartphones, laptops, workstations). Resource pooling: The vendor aggregates its computational assets to support numerous clients concurrently, often utilizing a multi-tenant architecture where virtual and physical resources are dynamically allocated based on aggregated user demand. Rapid elasticity: Computational capabilities can be scaled up or down quickly—sometimes automatically—to precisely match fluctuating workload requirements. From the user's perspective, the available capacity often seems infinite and instantly attainable. Measured utility: Resource consumption (like storage volume, processing time, or data throughput) is automatically quantified and controlled by the provider at an abstraction layer relevant to the specific service type. This metering ensures transparency regarding utilization for both the vendor and the client. By 2023, the International Organization for Standardization (ISO) had expanded and refined this enumeration.

== Genesis ==

The conceptual roots of cloud computing trace back to the 1960s, coinciding with the rise of time-sharing concepts disseminated through remote job entry (RJE) systems. During this period, mainframe utilization was often managed via a "data center" structure where users submitted tasks to dedicated operators. This era was marked by efforts to maximize the accessibility and efficiency of expensive, large-scale computational power for a broader user base. The actual metaphorical use of "the cloud" to signify virtualized services originated in 1994, employed by General Magic to describe the accessible virtual space for mobile agents operating within their Telescript framework. David Hoffman, a communications specialist at General Magic, is generally credited with popularizing this term, drawing from its prior, established usage in telecommunications diagrams. The phrase "cloud computing" gained broader traction in 1996 following internal documentation at Compaq Computer Corporation detailing future Internet-based computation strategies. The company aimed to centralize software delivery and delivery infrastructure.