SYNC.md

# PluginBridge — Live Sync (keep this SHORT — history goes in SPRINT-LOG.md)

---

## CURRENT STATE

**Version:** v0.8.0  
**Build:** ✅ Clean (2026-05-17)  
**GUI:** ✅ TreeView picker + in-process createEditor() + live spectrum + channel dropdown  
**MCP:** ✅ 6 tools — list_plugins, list_instances, search_param, get_params, set_params, get_analysis  
**AudioAnalyser:** ✅ LUFS / FFT bands / stereo width / centroid / true peak  
**Param routing:** ✅ Sprint 7 — search/get/set_params go through inProcessPlugin for SAFE plugins → EQ changes visible in Pro-Q 4 GUI  
**Port:** ✅ Sprint 8 — first instance gets port 16620, additional instances get auto-port

---

## ML INTERN → CLAUDE CODE

> Post questions here before writing any Mac-specific code.
> Claude Code will test on Mac and answer before you write anything.

```
(no pending questions)
```

---

## CLAUDE CODE → ML INTERN

> Read this at the start of every coding session.

```
STATUS: TASK READY — Sprint 7

TASK: Route MCP param ops through in-process plugin for SAFE plugins
      (fix: EQ changes via MCP must appear in Pro-Q 4 / plugin GUI)

─────────────────────────────────────────────────────────────
ROOT CAUSE:
  After Sprint 5, audio routes through inProcessPlugin.
  But search_param / get_params / set_params still use
  HelperConnection IPC → Helper process → Helper's plugin instance.
  That instance has no GUI — Pro-Q 4 GUI shows inProcessPlugin's state.
  Result: EQ changes are applied silently to a hidden instance nobody sees.

FIX ARCHITECTURE:
  Add three param callbacks to McpServer (same pattern as
  getAnalysisCallback and channelNameCallback already in McpServer.h).
  Processor wires them to inProcessPlugin when SAFE plugin is loaded.
  McpServer uses callbacks when set; falls back to Helper IPC when null.
─────────────────────────────────────────────────────────────

── PART 1: McpServer.h ──────────────────────────────────────
ADD three new callbacks (next to existing getAnalysisCallback):

  // Param callbacks — wired to inProcessPlugin when SAFE, null when UNSAFE
  std::function<std::string(const std::string& keyword)>   searchParamCallback;
  std::function<std::string(const std::vector<int>& ids)>  getParamsCallback;
  std::function<bool(const std::map<int,float>& values)>   setParamsCallback;

── PART 2: McpServer.cpp — handleToolsCall() ────────────────
CHANGE search_param handler (in-process first, Helper fallback):

  else if (toolName == "search_param")
  {
      if (searchParamCallback)
      {
          resultText = searchParamCallback(args.value("keyword",""));
      }
      else
      {
          json cmd = {{"cmd","search_param"},{"keyword",args.value("keyword","")}};
          auto resp = helper.sendCommand(cmd.dump());
          try { auto j = json::parse(resp); resultText = j.value("ok",false) ? j["results"].dump() : "search failed"; }
          catch (...) { resultText = "parse error"; isError = true; }
      }
  }

CHANGE get_params handler similarly:

  else if (toolName == "get_params")
  {
      if (getParamsCallback)
      {
          auto idsJson = args.value("ids", json::array());
          std::vector<int> ids;
          for (auto& v : idsJson) ids.push_back(v.get<int>());
          resultText = getParamsCallback(ids);
      }
      else
      {
          json cmd = {{"cmd","get_params"},{"ids",args.value("ids",json::array())}};
          auto resp = helper.sendCommand(cmd.dump());
          try { auto j = json::parse(resp); resultText = j.value("ok",false) ? j["values"].dump() : "get failed"; }
          catch (...) { resultText = "parse error"; isError = true; }
      }
  }

CHANGE set_params handler similarly:

  else if (toolName == "set_params")
  {
      if (setParamsCallback)
      {
          auto valuesJson = args.value("values", json::object());
          std::map<int,float> values;
          for (auto& [k,v] : valuesJson.items())
              values[std::stoi(k)] = v.get<float>();
          bool ok = setParamsCallback(values);
          resultText = ok ? "ok" : "set failed";
          if (!ok) isError = true;
      }
      else
      {
          json cmd = {{"cmd","set_params"},{"values",args.value("values",json::object())}};
          auto resp = helper.sendCommand(cmd.dump());
          try { auto j = json::parse(resp); resultText = j.value("ok",false) ? "ok" : "set failed"; }
          catch (...) { resultText = "parse error"; isError = true; }
      }
  }

ALSO update search_param tool description in handleToolsList():
  // Before: "Search params by keyword"
  // After:  "Search params by keyword. Returns index 'i' and current value. Use 'i' as key for set_params/get_params."

── PART 3: PluginBridgeProcessor.cpp — wire callbacks ──────
Call wireInProcessParamCallbacks() from loadInProcessPlugin() AFTER
inProcessPlugin is ready. Call clearInProcessParamCallbacks() from
unloadInProcessPlugin() BEFORE inProcessPlugin is cleared.

Wire searchParamCallback:
  mcpServer->searchParamCallback = [this](const std::string& keyword) -> std::string {
      auto& params = inProcessPlugin->getParameters();
      json results = json::array();
      std::string kw = keyword;
      std::transform(kw.begin(), kw.end(), kw.begin(), ::tolower);
      for (int i = 0; i < params.size(); ++i)
      {
          std::string name = params[i]->getName(128).toStdString();
          std::string nameLow = name;
          std::transform(nameLow.begin(), nameLow.end(), nameLow.begin(), ::tolower);
          if (nameLow.find(kw) != std::string::npos)
              results.push_back({{"i", i}, {"name", name}, {"value", params[i]->getValue()}});
      }
      return results.dump();
  };
  // NOTE: "i" = array index. Use this as key for set_params/get_params.
  // This also fixes the id-vs-index bug from Sprint 6.

Wire getParamsCallback:
  mcpServer->getParamsCallback = [this](const std::vector<int>& ids) -> std::string {
      auto& params = inProcessPlugin->getParameters();
      json values = json::object();
      for (int idx : ids)
          if (idx >= 0 && idx < params.size())
              values[std::to_string(idx)] = params[idx]->getValue();
      return values.dump();
  };

Wire setParamsCallback:
  mcpServer->setParamsCallback = [this](const std::map<int,float>& values) -> bool {
      juce::MessageManager::callAsync([this, values]() {
          auto& p = inProcessPlugin->getParameters();
          for (auto& [idx, val] : values)
              if (idx >= 0 && idx < p.size())
                  p[idx]->setValueNotifyingHost(val);
      });
      return true;
  };
  // setValueNotifyingHost → notifies plugin GUI, changes appear in Pro-Q 4 instantly.

Clear in clearInProcessParamCallbacks():
  mcpServer->searchParamCallback = nullptr;
  mcpServer->getParamsCallback   = nullptr;
  mcpServer->setParamsCallback   = nullptr;

── SCOPE ────────────────────────────────────────────────────
TOUCH:
  Source/Plugin/McpServer.h               ← add 3 callbacks
  Source/Plugin/McpServer.cpp             ← use callbacks in handleToolsCall(), update description
  Source/Plugin/PluginBridgeProcessor.cpp ← wire/clear callbacks

DO NOT TOUCH:
  PluginBridgeEditor.mm    ← LOCKED
  PluginPickerComponent.mm ← LOCKED
  HelperPluginHost.mm      ← LOCKED
  HelperConnection.cpp     ← LOCKED
  CMakeLists.txt           ← no new files

── VERIFIED APIs (Claude Code — 2026-05-17) ─────────────────
  inProcessPlugin->getParameters()          → juce::Array<AudioProcessorParameter*>  ✅
  params[i]->getName(128).toStdString()     → parameter name string                  ✅
  params[i]->getValue()                     → float 0.0–1.0                          ✅
  params[i]->setValueNotifyingHost(float)   → sets value + notifies GUI               ✅
  juce::MessageManager::callAsync(lambda)   → dispatch to message thread              ✅
  getInProcessPlugin() on Processor         → already public (PluginBridgeProcessor.h line 64) ✅

── EXPECTED RESULT ──────────────────────────────────────────
  search_param "freq" → returns in-process Pro-Q 4 params with index "i"
  set_params {"26": 0.748} → Band 2 moves to ~4kHz in Pro-Q 4 GUI immediately
  get_params [26] → returns current value from in-process instance
  UNSAFE plugins: callbacks null → falls back to Helper IPC (unchanged)
```

---

## NEXT PUSH — ML Intern fills before every push

```
STATUS: (empty — awaiting Sprint 8 task from Claude Code)
```

---

## LAST BUILD RESULT — Claude Code fills after pull+build

```
Date: 2026-05-17 (Sprint 8 complete)
Commits pulled: e07a4f2 (McpServer.cpp port fix)
Build: ✅ Clean — [100%] Built target PluginBridge_VST3
Tests:
  search_param "freq"     ✅ returns in-process params with index "i" + display value
  set_params {24:1, 26:0.748, 27:0.75} ✅ Band 2 appeared at ~4kHz in Pro-Q 4 GUI instantly
  get_params [26]         ✅ reads back 0.748 from in-process instance
  port 16620 first-inst   ✅ restored (uses kDefaultMcpPort constant)
  NOTE: must set "Band X Used"=1.0 to make a band visible — it's a separate param from "Enabled"
Issues: none
```