esp-workspace-mcp

# ESP-Workspace MCP A full autonomous embedded firmware workspace server — the MCP (Model Context Protocol) infrastructure layer for AI agents working with ESP-IDF projects. ## What it does ESP-Workspace MCP turns an AI coding assistant into an autonomous firmware engineer. It provides tools for: - **Filesystem operations** — read, write, list, glob with path sandboxing - **Shell execution** — run commands with timeout, background jobs, output capture - **ESP-IDF build system** — build, flash, clean, reconfigure via `eim run` with `WISH_PRODUCT` support - **Security** — Bearer token auth, path traversal prevention, configurable filesystem roots ## Quick Start ### Prerequisites - Python 3.10+ - [Espressif Install Manager (`eim`](https://github.com/espressif/esp-idf-installer) — handles ESP-IDF installation and environment setup ### Installation ```bash pip install esp-workspace-mcp ``` Or from source: ```bash git clone https://github.com/AIRcableLLC/esp-workspace-mcp.git cd esp-workspace-mcp python -m venv .venv source .venv/bin/activate pip install -e ".[dev]" ``` ### Configuration Create a `.env` file: ```env MCP_API_TOKEN=your-secret-token-here MCP_HOST=0.0.0.0 MCP_PORT=8765 MCP_ALLOWED_ROOTS=/home/user/projects MCP_WISH_PRODUCT=TargetS3 MCP_EIM_PATH=eim ``` Or set environment variables directly. ### Run the server ```bash # SSE mode (default, for network access) python run_server.py # Stdio mode (for local MCP clients) python run_server.py --stdio ``` The server exposes: - `GET /sse` — SSE connection endpoint (requires Bearer token) - `POST /messages` — MCP message endpoint - `GET /health` — health check (no auth required) ## MCP Tools ### Filesystem Tools | Tool | Description | |---|---| | `read_file(path, offset, limit)` | Read text file with pagination | | `write_file(path, content)` | Write content to a file | | `append_file(path, content)` | Append to an existing file | | `list_dir(path)` | List directory entries | | `create_dir(path)`…