esp-workspace-mcp 0.5.0__tar.gz

esp_workspace_mcp-0.5.0/.env.example

@@ -0,0 +1,35 @@
+# ESP-Workspace MCP Server Configuration
+# Copy to .env and fill in your values
+
+# Authentication (required)
+# Generate a random token: python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+MCP_API_TOKEN=
+
+# Network
+MCP_HOST=0.0.0.0
+MCP_PORT=8765
+
+# Logging
+MCP_LOG_LEVEL=INFO
+
+# Filesystem sandbox — comma-separated allowed roots
+MCP_ALLOWED_ROOTS=/home/juergen/AIRcableLLC
+
+# ESP-IDF / EIM configuration
+# Default WISH_PRODUCT value (e.g. TargetS3, TargetC6)
+# Can be overridden per tool call
+MCP_WISH_PRODUCT=TargetS3
+
+# Path to ESP-IDF installation (optional, eim handles env)
+MCP_IDF_PATH=
+
+# Path to eim executable
+MCP_EIM_PATH=eim
+
+# Timeouts and limits
+MCP_DEFAULT_TIMEOUT=30
+MCP_MAX_TIMEOUT=300
+MCP_OUTPUT_LIMIT=51200
+
+# Job TTL in seconds
+MCP_JOB_TTL_SECONDS=3600

esp_workspace_mcp-0.5.0/MANIFEST.in

@@ -0,0 +1,5 @@
+include README.md
+include LICENSE
+include requirements.txt
+include .env.example
+recursive-include esp_workspace_mcp/resources *

esp_workspace_mcp-0.5.0/PKG-INFO

@@ -0,0 +1,190 @@
+Metadata-Version: 2.4
+Name: esp-workspace-mcp
+Version: 0.5.0
+Summary: Full autonomous embedded firmware workspace MCP server for ESP-IDF
+Author: AIRcable LLC
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/aircable/ESP-Workspace-MCP-Server-for-Hermes
+Project-URL: Repository, https://github.com/aircable/ESP-Workspace-MCP-Server-for-Hermes
+Project-URL: Issues, https://github.com/aircable/ESP-Workspace-MCP-Server-for-Hermes/issues
+Keywords: mcp,esp-idf,esp32,firmware,embedded,ai-agent,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Embedded Systems
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.0
+Requires-Dist: fastapi>=0.115
+Requires-Dist: uvicorn>=0.34
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: gitpython>=3.1
+Requires-Dist: pyserial>=3.5
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+
+# 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)` | Create directory recursively |
+| `delete_path(path)` | Delete file or empty directory |
+| `file_stat(path)` | Get file/directory metadata |
+| `glob_search(pattern, path)` | Find files by glob pattern |
+
+### Shell Tools
+
+| Tool | Description |
+|---|---|
+| `run_command(cmd, cwd, timeout)` | Execute command and wait |
+| `start_process(cmd, cwd)` | Start background job |
+| `get_job_output(job_id, offset)` | Read job output |
+| `kill_job(job_id)` | Terminate background job |
+| `list_jobs()` | List all jobs |
+
+### ESP-IDF Tools
+
+All ESP-IDF operations are invoked through `eim run "WISH_PRODUCT=<product> idf.py ..."` which handles environment setup automatically.
+
+| Tool | Description |
+|---|---|
+| `eim_run(commands, project_dir, wish_product)` | Run any `idf.py` command via `eim` |
+| `build_project(project_dir, wish_product, reconfigure)` | Build an ESP-IDF project |
+| `set_target(project_dir, target, wish_product)` | Set target chip (esp32, esp32s3, etc.) |
+| `flash_project(project_dir, port, wish_product)` | Flash firmware to device |
+| `clean_project(project_dir)` | Clean build artifacts |
+| `fullclean_project(project_dir)` | Remove entire build directory |
+| `reconfigure_project(project_dir, wish_product)` | Regenerate sdkconfig + CMake cache |
+
+### Build Step Decision Tree
+
+```
+Is sdkconfig missing or have defaults changed?
+├── YES → eim_run("reconfigure build", project_dir, wish_product)
+└── NO  → eim_run("build", project_dir, wish_product)
+```
+
+## Security
+
+| Control | Implementation |
+|---|---|
+| Filesystem sandbox | All paths validated against `MCP_ALLOWED_ROOTS` |
+| Path traversal prevention | Symlink-resolved, `..` escapes rejected |
+| Shell timeout | Configurable, default 30s, max 300s |
+| Output truncation | 50 KB max per response |
+| Authentication | Bearer token on every request |
+| Credential safety | Tokens in env vars only, never logged |
+
+## Integration with AI Agents
+
+### Hermes
+
+```bash
+hermes mcp add esp-workspace \
+  --url http://host:port/sse \
+  --header "Authorization: Bearer your-token"
+```
+
+### Generic MCP Client
+
+Any MCP-compatible client can connect to the SSE endpoint. The server implements the standard MCP protocol over SSE/HTTP transport.
+
+## Architecture
+
+```
+esp_workspace_mcp/
+├── config.py          # Settings from env, fail-fast validation
+├── server.py          # FastMCP server, tool registration
+├── auth.py            # Bearer token middleware
+├── tools/
+│   ├── filesystem.py  # 8 path-validated file operations
+│   ├── shell.py       # Command execution + background jobs
+│   └── esp_idf.py     # eim-run wrapper, build/flash/clean
+├── utils/
+│   ├── security.py    # Path sandboxing, symlink resolution
+│   └── process.py     # Subprocess management, JobManager
+└── resources/
+    └── project.py     # MCP resources (project status, etc.)
+```
+
+## License
+
+Apache-2.0

esp_workspace_mcp-0.5.0/README.md

@@ -0,0 +1,159 @@
+# 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)` | Create directory recursively |
+| `delete_path(path)` | Delete file or empty directory |
+| `file_stat(path)` | Get file/directory metadata |
+| `glob_search(pattern, path)` | Find files by glob pattern |
+
+### Shell Tools
+
+| Tool | Description |
+|---|---|
+| `run_command(cmd, cwd, timeout)` | Execute command and wait |
+| `start_process(cmd, cwd)` | Start background job |
+| `get_job_output(job_id, offset)` | Read job output |
+| `kill_job(job_id)` | Terminate background job |
+| `list_jobs()` | List all jobs |
+
+### ESP-IDF Tools
+
+All ESP-IDF operations are invoked through `eim run "WISH_PRODUCT=<product> idf.py ..."` which handles environment setup automatically.
+
+| Tool | Description |
+|---|---|
+| `eim_run(commands, project_dir, wish_product)` | Run any `idf.py` command via `eim` |
+| `build_project(project_dir, wish_product, reconfigure)` | Build an ESP-IDF project |
+| `set_target(project_dir, target, wish_product)` | Set target chip (esp32, esp32s3, etc.) |
+| `flash_project(project_dir, port, wish_product)` | Flash firmware to device |
+| `clean_project(project_dir)` | Clean build artifacts |
+| `fullclean_project(project_dir)` | Remove entire build directory |
+| `reconfigure_project(project_dir, wish_product)` | Regenerate sdkconfig + CMake cache |
+
+### Build Step Decision Tree
+
+```
+Is sdkconfig missing or have defaults changed?
+├── YES → eim_run("reconfigure build", project_dir, wish_product)
+└── NO  → eim_run("build", project_dir, wish_product)
+```
+
+## Security
+
+| Control | Implementation |
+|---|---|
+| Filesystem sandbox | All paths validated against `MCP_ALLOWED_ROOTS` |
+| Path traversal prevention | Symlink-resolved, `..` escapes rejected |
+| Shell timeout | Configurable, default 30s, max 300s |
+| Output truncation | 50 KB max per response |
+| Authentication | Bearer token on every request |
+| Credential safety | Tokens in env vars only, never logged |
+
+## Integration with AI Agents
+
+### Hermes
+
+```bash
+hermes mcp add esp-workspace \
+  --url http://host:port/sse \
+  --header "Authorization: Bearer your-token"
+```
+
+### Generic MCP Client
+
+Any MCP-compatible client can connect to the SSE endpoint. The server implements the standard MCP protocol over SSE/HTTP transport.
+
+## Architecture
+
+```
+esp_workspace_mcp/
+├── config.py          # Settings from env, fail-fast validation
+├── server.py          # FastMCP server, tool registration
+├── auth.py            # Bearer token middleware
+├── tools/
+│   ├── filesystem.py  # 8 path-validated file operations
+│   ├── shell.py       # Command execution + background jobs
+│   └── esp_idf.py     # eim-run wrapper, build/flash/clean
+├── utils/
+│   ├── security.py    # Path sandboxing, symlink resolution
+│   └── process.py     # Subprocess management, JobManager
+└── resources/
+    └── project.py     # MCP resources (project status, etc.)
+```
+
+## License
+
+Apache-2.0

esp_workspace_mcp-0.5.0/esp_workspace_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""ESP-Workspace MCP — Full autonomous embedded firmware workspace server."""
+__version__ = "0.5.0"

esp_workspace_mcp-0.5.0/esp_workspace_mcp/__main__.py

@@ -0,0 +1,3 @@
+"""Allow running as: python -m esp_workspace_mcp"""
+from esp_workspace_mcp.cli import main
+main()

esp_workspace_mcp-0.5.0/esp_workspace_mcp/auth.py

@@ -0,0 +1,74 @@
+"""SSE transport with Bearer token authentication."""
+import logging
+from functools import wraps
+from typing import Optional
+
+from fastapi import Request, Response
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+def _mask_token(token: str, show: int = 4) -> str:
+    if not token:
+        return ""
+    if len(token) <= show:
+        return "*" * len(token)
+    return f"***{token[-show:]}"
+
+
+class BearerAuthMiddleware(BaseHTTPMiddleware):
+    """Middleware that enforces Bearer token authentication."""
+    
+    def __init__(self, app, api_token: str, exempt_paths: Optional[list] = None):
+        super().__init__(app)
+        self.api_token = api_token
+        self.exempt_paths = exempt_paths or ["/health"]
+    
+    async def dispatch(self, request: Request, call_next):
+        # Allow health check without auth
+        if request.url.path in self.exempt_paths:
+            logger.debug("Auth: exempt path %s", request.url.path)
+            return await call_next(request)
+        
+        # Check Authorization header
+        auth = request.headers.get("Authorization", "")
+        provided_token = None
+        if auth.startswith("Bearer "):
+            provided_token = auth[7:]
+
+        # Debug logging (masked tokens only)
+        logger.debug(
+            "Auth check: path=%s method=%s auth_header=%s provided=%s expected=%s",
+            request.url.path,
+            request.method,
+            auth[:7] + "..." if auth else "",
+            _mask_token(provided_token),
+            _mask_token(self.api_token),
+        )
+
+        if not provided_token or provided_token != self.api_token:
+            logger.warning(
+                "Unauthorized access attempt on %s: provided=%s expected=%s",
+                request.url.path,
+                _mask_token(provided_token),
+                _mask_token(self.api_token),
+            )
+            return JSONResponse(
+                status_code=401,
+                content={"error": "Unauthorized: invalid or missing Bearer token"},
+                headers={"WWW-Authenticate": "Bearer"},
+            )
+        
+        return await call_next(request)
+
+
+def require_token(api_token: str):
+    """Decorator for requiring Bearer token on a specific endpoint."""
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            return await func(*args, **kwargs)
+        return wrapper
+    return decorator