docs: add Espressif Documentation MCP Server guidance to AGENTS.md#369
docs: add Espressif Documentation MCP Server guidance to AGENTS.md#369Copilot wants to merge 1 commit into
Conversation
- Documents the two available MCP server options (official vs community) - Official mcp.espressif.com is latest-only; warns agents not to use it for WLED-MM firmware API lookups - Community esp-idf-docs-mcp (PyPI) supports ESP_IDF_VERSION=v4.4, which matches arduino-esp32 2.0.17 = ESP-IDF 4.4.8 - Clarifies that idf.py mcp-server build/flash tools are incompatible (requires IDF 6.0 + CMake project; WLED-MM uses PlatformIO/Arduino) - Adds version-pinning requirement and usage guidance
|
@coderabbitai are other changes needed to make esp-idf-docs-mcp operational? |
|
@coderabbitai full review |
✅ Action performedFull review finished. |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
cat AGENTS.mdLength of output: 17681 🌐 Web query:
Length of output: 9895
The install is a one-liner: # Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Once A suggested addition to the #### Prerequisites
`uvx` is provided by [uv](https://docs.astral.sh/uv/). Install it once:
```bash
# Linux / macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
Everything else in AGENTS.md ( |
WalkthroughAdds documentation to AGENTS.md describing optional MCP server access to ESP-IDF API reference for AI agents, including server selection guidance, version pinning requirements, tool names, and usage boundaries. ChangesExternal Documentation Resources for AI Agents
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 266-269: Update the AGENTS.md wording around "idf.py mcp-server":
clarify that ESP-IDF v6.0 does provide the idf.py mcp-server command but that
the MCP server tooling expects an ESP-IDF CMake-style project (mcp-server) and
therefore cannot be used directly with PlatformIO/Arduino project flows; add or
link to an authoritative source (ESP-IDF docs or release notes) that states the
MCP server requires an ESP-IDF CMake project, and adjust the sentence to remove
the blanket "incompatible" claim by specifying the exact limitation (requires
CMake-style ESP-IDF project) and how that affects PlatformIO/Arduino users.
- Around line 310-312: The AGENTS.md statement incorrectly maps arduino-esp32
versions to ESP-IDF; inspect platformio.ini and update or remove the claim that
"WLED-MM uses arduino-esp32 2.0.17 ... ESP-IDF 4.4.8": replace that mapping with
the actual pinned core/version from platformio.ini (or delete the ESP-IDF
version justification), and correct the arduino-esp32 → ESP-IDF mapping (e.g.
note that framework-arduinoespressif32 in this repo selects arduino-esp32 v2.0.9
/ references v2.0.14 and that arduino-esp32 2.0.17 corresponds to ESP-IDF 4.4.7
if you must mention it); also remove or correct the reference to
platform-espressif32 core 2.0.18 if used only for Tasmota.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| **Use it only for documentation lookups — not for build or flash operations.** | ||
| The `idf.py mcp-server` build/flash tooling introduced in ESP-IDF 6.0 is | ||
| **incompatible** with WLED-MM: the project is built with PlatformIO and the | ||
| Arduino framework, not a native ESP-IDF CMake project. |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Does ESP-IDF 6.0 introduce an idf.py mcp-server command for MCP server functionality?
💡 Result:
Yes. ESP-IDF v6.0 introduces an MCP server command in idf.py: the documentation explicitly states you can start the server with idf.py mcp-server (optionally idf.py -C <project> mcp-server) to enable ESP-IDF MCP server functionality.[1][2]
Citations:
- 1: https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/tools/idf-py.html
- 2: https://developer.espressif.com/blog/2026/04/esp-idf-tools-mcp-server/
Fix the idf.py mcp-server wording in AGENTS.md (it exists in IDF v6.0)
- AGENTS.md’s statement that ESP-IDF v6.0 provides
idf.py mcp-serveris accurate (docs show starting the MCP server viaidf.py mcp-server/idf.py -C <project> mcp-server). - The “incompatible with PlatformIO/Arduino” claim needs a source explicitly stating the MCP server/tooling requires an ESP-IDF CMake-style project setup (or otherwise can’t be used in PlatformIO/Arduino flows).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@AGENTS.md` around lines 266 - 269, Update the AGENTS.md wording around
"idf.py mcp-server": clarify that ESP-IDF v6.0 does provide the idf.py
mcp-server command but that the MCP server tooling expects an ESP-IDF
CMake-style project (mcp-server) and therefore cannot be used directly with
PlatformIO/Arduino project flows; add or link to an authoritative source
(ESP-IDF docs or release notes) that states the MCP server requires an ESP-IDF
CMake project, and adjust the sentence to remove the blanket "incompatible"
claim by specifying the exact limitation (requires CMake-style ESP-IDF project)
and how that affects PlatformIO/Arduino users.
| > **Always use `ESP_IDF_VERSION=v4.4`.** WLED-MM uses arduino-esp32 2.0.17, | ||
| > which is based on ESP-IDF **4.4.8**. ESP-IDF 5.x / 6.x introduced breaking | ||
| > changes to `esp_netif`, the timer API, `esp_wifi`, and other subsystems. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check arduino-esp32 version in platformio.ini and verify ESP-IDF version mapping
# Find arduino-esp32 version specification in platformio.ini
echo "=== Checking arduino-esp32 version in platformio.ini ==="
rg -n "platform.*espressif32" platformio.ini
# Also check for any ESP-IDF version specifications
echo -e "\n=== Checking for ESP-IDF version references ==="
rg -n "ESP_IDF|esp-idf|ESP-IDF" platformio.iniRepository: MoonModules/WLED-MM
Length of output: 3754
🌐 Web query:
What version of ESP-IDF does arduino-esp32 version 2.0.17 use?
💡 Result:
Arduino-esp32 version 2.0.17 is based on ESP-IDF v4.4.7 [1][2]. This is documented in the official release notes for the 2.0.17 version on the Espressif GitHub repository [1].
Citations:
- 1: https://github.com/espressif/arduino-esp32/releases/tag/2.0.17
- 2: https://mygit.top/release/157052940
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "=== Search for arduino-esp32 2.0.17 references in platformio.ini ==="
rg -n "arduino-esp32\s*2\.0\.17|2\.0\.17" platformio.ini || true
echo -e "\n=== Search for 4.4.8 references in platformio.ini ==="
rg -n "4\.4\.8" platformio.ini || true
echo -e "\n=== Search for framework-arduinoespressif32 pins around any 2.0.x ==="
rg -n "framework-arduinoespressif32\s*@|arduino-esp32 v2\.[0-9]+" platformio.ini | head -n 80Repository: MoonModules/WLED-MM
Length of output: 1584
Fix incorrect arduino-esp32/ESP-IDF mapping in AGENTS.md (lines 310-312).
platformio.inicontains noarduino-esp32 2.0.17pin; it instead selectsarduino-esp32 v2.0.9(and referencesv2.0.14) viaframework-arduinoespressif32.- The only “IDF 4.4.8” reference found in
platformio.iniis for Tasmotaplatform-espressif32(core 2.0.18), not forarduino-esp32 2.0.17. - External references indicate
arduino-esp32 2.0.17is based on ESP-IDF 4.4.7, not 4.4.8.
Update the documentation to match the actual pinned core/version in platformio.ini (or remove/adjust the ESP-IDF mapping justification).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@AGENTS.md` around lines 310 - 312, The AGENTS.md statement incorrectly maps
arduino-esp32 versions to ESP-IDF; inspect platformio.ini and update or remove
the claim that "WLED-MM uses arduino-esp32 2.0.17 ... ESP-IDF 4.4.8": replace
that mapping with the actual pinned core/version from platformio.ini (or delete
the ESP-IDF version justification), and correct the arduino-esp32 → ESP-IDF
mapping (e.g. note that framework-arduinoespressif32 in this repo selects
arduino-esp32 v2.0.9 / references v2.0.14 and that arduino-esp32 2.0.17
corresponds to ESP-IDF 4.4.7 if you must mention it); also remove or correct the
reference to platform-espressif32 core 2.0.18 if used only for Tasmota.
softhack007
added
the
AI
Agents querying the official
mcp.espressif.comserver for ESP-IDF APIs will silently receive v5.x/v6.x answers — incompatible with WLED-MM's arduino-esp32 2.0.17 (= ESP-IDF 4.4.8). This was confirmed by live probing: the official toolsearch_espressif_sources(query, language)has no version parameter.Changes
## Optional External Resources for AI Agentsat the end ofAGENTS.mdesp-idf-docs-mcp(PyPI), which supportsESP_IDF_VERSION=v4.4by fetching from versioned Espressif docs URLs (confirmed live for v4.4.8)idf.py mcp-server(IDF 6.0, CMake-only) is incompatible with WLED-MM's PlatformIO/Arduino build{ "mcpServers": { "esp-idf-docs": { "command": "uvx", "args": ["esp-idf-docs-mcp"], "env": { "ESP_IDF_VERSION": "v4.4", "ESP_IDF_CHIP_TARGET": "esp32" } } } }Summary by CodeRabbit