Skip to content

docs: add Espressif Documentation MCP Server guidance to AGENTS.md #369

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Copilot wants to merge 1 commit into
base: mdev
Choose a base branch
from
+77 −0
Draft

docs: add Espressif Documentation MCP Server guidance to AGENTS.md #369

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
77 changes: 77 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -254,3 +254,80 @@ Using AI-generated code can hide the source of the inspiration / knowledge / sou

- **For "is it worth doing?" debates** about proposed reliability, safety, or data-integrity mechanisms (CRC checks, backups, power-loss protection): suggest a software **FMEA** (Failure Mode and Effects Analysis).
Clarify the main feared events, enumerate failure modes, assess each mitigation's effectiveness per failure mode, note common-cause failures, and rate credibility for the typical WLED-MM use case.

## Optional External Resources for AI Agents

### Espressif Documentation MCP Server

An MCP server can provide ESP-IDF API documentation to AI agents more efficiently
than scraping web pages — returning precise, low-noise content directly from the
official corpus.

**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.
Comment on lines +266 to +269

@coderabbitai coderabbitai Bot Jun 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 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:

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-server is accurate (docs show starting the MCP server via idf.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.


#### Which server to use

Two options exist. Choose based on which is available in your agent environment:

| Server | Version pinning | Recommended for WLED-MM |
|---|---|---|
| `mcp.espressif.com` (official) | ❌ Latest docs only — no version param | ⚠️ Avoid for firmware API questions |
| `esp-idf-docs-mcp` (PyPI, community) | ✅ `ESP_IDF_VERSION=v4.4` | ✅ Preferred |

The **official server** (`mcp.espressif.com`) exposes a single tool,
`search_espressif_sources(query, language)`, with no version selector. It always
returns results from the latest ESP-IDF release (currently v5.x / v6.x). Do not
use it to look up firmware APIs, as the answers will silently describe a different
IDF version than what WLED-MM actually uses.

The **community package** (`pip install esp-idf-docs-mcp` /
`uvx esp-idf-docs-mcp`) fetches content directly from the versioned Espressif
documentation site. Configure it with:

```json
{
"mcpServers": {
"esp-idf-docs": {
"command": "uvx",
"args": ["esp-idf-docs-mcp"],
"env": {
"ESP_IDF_VERSION": "v4.4",
"ESP_IDF_CHIP_TARGET": "esp32"
}
}
}
}
```

Available tools: `search_docs`, `read_doc`, `get_doc_structure`,
`find_api_references`.

#### Version-pinning requirement

> **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.
Comment on lines +310 to +312

@coderabbitai coderabbitai Bot Jun 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 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.ini

Repository: 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:

🏁 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 80

Repository: MoonModules/WLED-MM

Length of output: 1584

Fix incorrect arduino-esp32/ESP-IDF mapping in AGENTS.md (lines 310-312).

  • platformio.ini contains no arduino-esp32 2.0.17 pin; it instead selects arduino-esp32 v2.0.9 (and references v2.0.14) via framework-arduinoespressif32.
  • The only “IDF 4.4.8” reference found in platformio.ini is for Tasmota platform-espressif32 (core 2.0.18), not for arduino-esp32 2.0.17.
  • External references indicate arduino-esp32 2.0.17 is 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.

> Using the wrong version produces plausible but incorrect answers.

Additionally:

- Cross-reference results with the arduino-esp32 2.0.x HAL source when the API
is accessed through the Arduino layer — the Arduino wrapper may expose a
different interface than the raw IDF call.
- Do **not** assume ESP-IDF 5.x+ APIs are available in WLED-MM firmware code.

#### What it is useful for

- FreeRTOS primitives, peripheral register maps, partition table layouts, and
other platform details that are stable across minor 4.x releases.
- Answering "does this IDF 4.4 API exist / what are its parameters?" without
manually navigating the archived documentation.

#### What it is not a substitute for

- Reading the arduino-esp32 2.0.x source for HAL-level behaviour.
- Checking `platformio.ini` for board-specific `build_flags` and library
overrides that differ from stock IDF defaults.
Loading