# Agentic PID Tuner (via MCP)

An interactive, real-time PID controller dashboard integrated with the **Model Context Protocol (MCP)**. This project allows AI agents (like Claude) to actively read, analyze, and tune a simulated control loop using natural language commands, with changes reflecting instantly in the web browser.

![Dashboard Screenshot](assets/Dashboard_screenshot.png)

## ✨ Features
* **Real-time Web Dashboard:** Adjust $K_p$, $K_i$, and $K_d$ gains manually using UI sliders.
* **Live Waveform Visualization:** See overshoot, settling time, and system response instantly (powered by `simple-pid` and `matplotlib`).
* **AI-Agent Control:** Includes an MCP server that exposes tools for LLMs to read current gains and push new ones.
* **Bi-directional Sync:** If you move a slider, the AI sees the new value. If the AI changes a value, your browser updates automatically within 1 second.

## 🛠️ Prerequisites
* Python 3.8+
* [Claude](https://claude.ai/download) or [Cursor Desktop App](https://cursor.com/download) (for MCP integration) 

## 🚀 Installation

1. **Clone the repository:**

```bash
gh repo clone SuriyaMurthy/agentic-pid-controller
cd agentic-pid-controller

```

2. **Create and activate a virtual environment:**

```bash
python -m venv .venv

# On Windows:
.venv\Scripts\activate
# On Mac/Linux:
source .venv/bin/activate

```


3. **Install dependencies:**
```bash
pip install -r requirements.txt

```



## 🎮 Usage

### 1. Start the Web Dashboard

Run the Flask server to host the simulation and web interface:

```bash
python app.py

```

Open your browser and navigate to `http://127.0.0.1:5000`.

### 2. Connect to Claude Desktop (MCP)

To let Claude interact with your dashboard, add the MCP server to your Claude Desktop configuration.

Open your Claude Desktop config file:

* **Linux:** `~/.cursor/mcp.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`


Add the following configuration. **IMPORTANT:** You must replace with the actual full paths on your computer!

```json
{
  "mcpServers": {
    "pid_controller": {
      "command": "/absolute/path/to/mcp-pid-tuner/.venv/bin/python3",
      "args": [
        "/absolute/path/to/mcp-pid-tuner/mcp_server_pid.py"
      ]
    }
  }
}

```

*Note for Windows users: Use your `.venv\Scripts\python.exe` path and ensure backslashes are escaped (`\\`).*

**Restart Claude Desktop** after saving the file.

### 3. Talk to the AI

With the Flask app running, open Claude Desktop. You can now use prompts like:

* *"Check the current PID parameters on my dashboard."*
* *"The system has too much overshoot. Can you adjust the parameters to bring the overshoot below 5%?"*
* *"Increase the proportional gain by 0.5 and tell me how it affects the settling time."*

Watch the web dashboard automatically update as Claude tunes the system!

## 📂 Project Structure

* `app.py`: The Flask web server, PID simulation loop, and API endpoints.
* `mcp_server_pid.py`: The FastMCP server that exposes `get_pid_parameters` and `update_pid_parameters` tools to the LLM over standard I/O.
* `requirements.txt`: Python dependencies (`flask`, `mcp`, `simple-pid`, `matplotlib`).