# Machinechat JEDI MCP Gateway

The JEDI MCP Gateway is a resilient protocol proxy that bridges the gap between **stdio-based** AI clients and JEDI's **SSE-based** Model Context Protocol (MCP) server.

Modern AI agents often communicate using the Model Context Protocol. While JEDI provides a native SSE (Server-Sent Events) interface for web-based connectivity, many desktop applications like **Claude Desktop** are restricted to the 'stdio' transport—meaning they can only interact with AI servers by launching a local command. The JEDI MCP Gateway solves this by acting as a local representative for your JEDI server.

## Why use the MCP Gateway?

*   **Universal Compatibility**: Enables Claude Desktop and other stdio-only clients to control JEDI.
*   **Protocol Translation**: Transparently maps standard input/output to JEDI's web-based SSE streams.
*   **Automatic Resilience**: Features built-in exponential backoff and auto-reconnection logic. If JEDI restarts or the network drops, the gateway automatically restores the link without crashing your AI session.
*   **Structured Diagnostics**: Includes integrated logging (via `mcp-gateway.log`) to help troubleshoot connectivity and protocol issues.

## Direct Connection vs. Gateway

| Feature | Direct Connection (SSE) | Gateway Connection (Stdio) |
| :--- | :--- | :--- |
| **Best For** | **Claude Code**, **Gemini**, Web Agents | **Claude Desktop**, CLI Tools |
| **Setup** | Enter a URL or JSON config | **Requires Gateway Binary** |
| **Performance** | Native web performance | Local process overhead |
| **Resilience** | Agent-dependent | **Auto-reconnect built-in** |

---

## Configuration Examples

### 1. Direct Connection (Recommended)
If your AI agent supports the **SSE** transport, you do not need the gateway tool. Connect directly to JEDI using the following endpoint:

**Endpoint URL**: `http://localhost:9124/mcp`

#### Example: Claude Code / Gemini CLI
Add JEDI to your `.mcp.json` file (usually located in your project root or home directory):

```json
{
  "mcpServers": {
    "jedi": {
      "type": "sse",
      "url": "http://localhost:9124/mcp"
    }
  }
}
```

> **Note for Gemini CLI and Codex**: While the JSON structure above is universal, the exact filename and location vary by tool. For example, **Claude Code** and **Gemini CLI** often look for `.mcp.json` in the project root, while other tools may use internal configuration menus. Always verify your specific tool's documentation for its preferred config path.

#### Example: Gemini (via Google AI Studio)
When adding a new MCP server in the Google AI Studio interface:
1.  Select **SSE** as the Transport Type.
2.  Enter `http://localhost:9124/mcp` as the URL.

---

### 2. Gateway Connection (for Claude Desktop)
Claude Desktop only supports "stdio" transport. Use the **JEDI MCP Gateway** binary as a bridge.

#### Step 1: Prepare the Gateway
Ensure the gateway binary has execution permissions:
```bash
chmod +x ./mcp-gateway
```

#### Step 2: Configure Claude Desktop
Open your configuration file:
*   **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
*   **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add JEDI to the `mcpServers` section. **Replace `/YOUR/PATH/` with the absolute path to the gateway binary.**

```json
{
  "mcpServers": {
    "jedi": {
      "command": "/YOUR/PATH/mcp-gateway",
      "args": ["-server", "http://localhost:9124/mcp"]
    }
  }
}
```

#### Step 3: Restart Claude Desktop
Fully quit and restart Claude Desktop to activate the tools.

---

## JEDI MCP Server Surface

Once connected, your AI agent has direct access to JEDI's data engine through the following tools:

| Tool Name | Capability |
| :--- | :--- |
| `list_metrics` | Discover all available nodes and sensors. |
| `search_metrics` | Filter sensors by name or pattern (e.g., "temperature"). |
| `get_metric_latest_values` | Real-time status check of current sensor values. |
| `get_metric_history` | Retrieve time-series data for analysis. |
| `get_metric_aggregations` | Perform statistical analysis (Min/Max/Avg). |
| `compare_metric_periods` | Identify trends between different time frames. |
| `write_metric_data` | Programmatically inject data points into JEDI. |
| `list_jedi_dashboards` | Browse existing UI visualizations. |
| `create_jedi_dashboard` | **AI-Powered**: Instantly generate new web dashboards. |

## Advanced Gateway Configuration

The gateway supports several flags for fine-tuning performance and logging:

*   `-server`: The URL of the JEDI MCP server (default: `http://localhost:9124/mcp`).
*   `-log-level`: Set to `debug` for verbose protocol tracing.
*   `-initial-retry`: Delay before first reconnection attempt (default: `2s`).
*   `-max-retry`: Maximum delay for exponential backoff (default: `30s`).

## Handling Restarts
If JEDI is restarted, the gateway will attempt to reconnect. 
*   **Claude Desktop**: Since the session ID changes on restart, you may need to **Restart Claude Desktop** if the agent reports a "session refresh needed" error.
*   **Direct SSE Clients**: Use your agent's "reconnect" or "refresh" command to restore the session.
