Fledge AI Interaction Gateway

This document details the Model Context Protocol (MCP) intermediary, designed to bridge Fledge infrastructure components with the Cursor AI cognitive engine, allowing instruction execution via conversational prompts.

Necessary Preconditions

• A functional Fledge deployment, either local or reachable via its REST interface (default target: http://localhost:8081).
• Installation of the Cursor AI environment.
• Python runtime environment, version 3.8 or newer.

Deployment Procedure

1. Obtain the source repository:

git clone https://github.com/Krupalp525/fledge-mcp.git
cd fledge-mcp

1. Establish required dependencies:

pip install -r requirements.txt

Server Initialization Sequence

1. Ensure the upstream Fledge data acquisition service is active:

fledge start

1. Launch the primary MCP service endpoint:

python mcp_server.py

For deployments necessitating secure endpoint access via token validation:

python secure_mcp_server.py

1. Confirm operational status by querying the readiness probe:

curl http://localhost:8082/health

Successful response should yield: "Fledge MCP Server is running"

Cursor AI Configuration

1. Navigate to Cursor's configuration menu: Settings > MCP Servers.
2. Initiate the addition of a new connection profile:
3. Endpoint URL: http://localhost:8082/tools

4. Tool Manifest File: Specify the path to the included tools.json or its local location.

5. If utilizing the secured variant, configure the request header named "X-API-Key" utilizing the secret token documented in the api_key.txt file generated upon secure server startup.

6. Verification Test: Engage the Composer interface (Ctrl+I) within Cursor and input a directive like, "Ascertain Fledge API accessibility." The system should trigger the validate_api_connection tool invocation.

Exposed Toolset Catalog

Data Acquisition & Administration

1. get_sensor_data: Retrieve sensor readings, supporting temporal boundary definition and result quantity capping.
2. list_sensors: Enumerate all registered sensor devices within Fledge.
3. ingest_test_data: Inject synthetic data payloads into Fledge, optionally specifying batch size.

System Component Management

1. get_service_status: Report on the operational state of all constituent Fledge processes.
2. start_stop_service: Command the initiation or termination of a specific service type.
3. update_config: Modify configuration settings persisting within the Fledge registry.

Presentation Layer Artifact Generation

1. generate_ui_component: Produce React code artifacts suitable for visualizing Fledge metrics.
2. fetch_sample_frontend: Obtain boilerplate frontend templates compatible with various presentation frameworks.
3. suggest_ui_improvements: Leverage AI analysis to propose enhancements for existing user interface code.

Real-Time Telemetry Streams

1. subscribe_to_sensor: Establish a persistent link for receiving asynchronous updates from specified sensors.
2. get_latest_reading: Fetch the most recent measured value for a designated sensor identifier.

Diagnostic and Integrity Checks

1. validate_api_connection: Perform a connectivity check against the primary Fledge interface.
2. simulate_frontend_request: Execute simulated HTTP interactions to benchmark API behavior.

Metadata Retrieval and Schema Inspection

1. get_api_schema: Obtain descriptive metadata regarding accessible Fledge API routes.
2. list_plugins: List all installed Fledge extension modules.

Advanced Synthetic Data Generation

1. generate_mock_data: Create artificially generated, contextually relevant sensor datasets for validation scenarios.

API Execution Verification

Execute the accompanying verification scripts to test server functionality:

# Standard unsecured endpoint test
python test_mcp.py

# Secured endpoint test requiring key management
python test_secure_mcp.py

Security Protocols

The hardened server variant (secure_mcp_server.py) enforces authentication via an API key:

1. The initial invocation generates a unique secret key stored in api_key.txt.
2. All subsequent API calls mandate the inclusion of this key within the X-API-Key request header.
3. The /health endpoint remains publicly accessible without token validation.

Sample HTTP Tool Invocation (POST to /tools)

# Verify connectivity
curl -X POST -H "Content-Type: application/json" -d '{"name": "validate_api_connection"}' http://localhost:8082/tools

# Request synthetic data generation
curl -X POST -H "Content-Type: application/json" -d '{"name": "generate_mock_data", "parameters": {"sensor_id": "temp1", "count": 5}}' http://localhost:8082/tools

# Request dynamic UI component generation
curl -X POST -H "Content-Type: application/json" -d '{"name": "generate_ui_component", "parameters": {"component_type": "chart", "sensor_id": "temp1"}}' http://localhost:8082/tools

# Secure server invocation requires key header
curl -X POST -H "Content-Type: application/json" -H "X-API-Key: YOUR_API_KEY" -d '{"name": "list_sensors"}' http://localhost:8082/tools

System Expansion Guidelines

To integrate novel functionalities: 1. Define the new function's metadata within the tools.json manifest. 2. Implement the corresponding handler logic within both mcp_server.py and secure_mcp_server.py files.

Production Deployment Considerations

For enterprise-grade deployment environments: - Mandate secure transport (HTTPS/TLS). - Place the service behind a robust intermediary such as Nginx or an equivalent load balancer. - Adopt advanced authorization schemas (e.g., JWT, OAuth 2.0). - Integrate traffic throttling mechanisms to mitigate abuse. - Establish durable persistence mechanisms for managing subscriptions state.

Deployment on Smithery.ai Platform

The Fledge MCP Server architecture is compatible with Smithery.ai for scaling and high availability:

1. Prerequisites Checklist
2. Docker runtime installed.
3. Active Smithery.ai subscription.

4. Local installation of the Smithery Command Line Interface (CLI).

5. Image Building and Distribution ```bash # Create the executable Docker image docker build -t fledge-mcp .

# Initiate deployment workflow to the platform smithery deploy ```

1. Configuration Blueprint (smithery.json) This file dictates runtime parameters:
2. WebSocket communication secured on port 8082.
3. Parameterizable URL for the target Fledge API.
4. Tool definitions catalog and their accepted parameter structures.

5. Connection timeout settings.

6. Environment Variables Setup Configure the following secrets/settings within the Smithery.ai portal:

7. FLEDGE_API_URL: The accessible endpoint address for the Fledge instance.

8. API_KEY: The required secret credential if operating in authentication mode.

9. Operational Status Check Confirm successful platform instantiation: bash smithery status fledge-mcp

10. Performance Oversight Utilize the Smithery.ai control panel for ongoing monitoring:

11. Real-time log stream access.
12. Visualization of performance benchmarks.
13. Error tracing and alerting.

14. Resource consumption tracking (CPU, memory).

15. Updating the Service To roll out new iterations: ```bash # Rebuild the container artifact docker build -t fledge-mcp .

# Push the updated version to the cluster smithery deploy --update ```

JSON-RPC 2.0 Protocol Specification

The server adheres to the JSON-RPC 2.0 specification, typically utilizing WebSocket transport for tool invocation. Supported remote procedure calls (RPCs) include:

1. initialize Request Payload Example: json { "jsonrpc": "2.0", "method": "initialize", "params": {}, "id": "1" } Expected Successful Response Structure: json { "jsonrpc": "2.0", "result": { "serverInfo": { "name": "fledge-mcp", "version": "1.0.0", "description": "Fledge Model Context Protocol (MCP) Server", "vendor": "Fledge", "capabilities": { "tools": true, "streaming": true, "authentication": "api_key" } }, "configSchema": { "type": "object", "properties": { "fledge_api_url": { "type": "string", "description": "Fledge API URL", "default": "http://localhost:8081/fledge" } } } }, "id": "1" }

2. tools/list Request Payload Example: json { "jsonrpc": "2.0", "method": "tools/list", "params": {}, "id": "2" } Response: Delivers a comprehensive manifest detailing all functions and their input parameters.

3. tools/call Request Payload Example (Executing a specific function): json { "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "get_sensor_data", "parameters": { "sensor_id": "temp1", "limit": 10 } }, "id": "3" }

Error Code Mapping

Standard JSON-RPC 2.0 error specifications are observed for signaling issues:

• -32700: Denotes a structural parsing failure in the incoming message payload.
• -32600: Invalid Request structure.
• -32601: The requested method name does not correspond to an implemented function.
• -32602: Input parameters provided do not match the function signature requirements.
• -32000: General internal server execution fault.