mcp-edge 0.1.0__tar.gz

mcp_edge-0.1.0/.env.example

@@ -0,0 +1,18 @@
+# MCP-Edge example environment variables.
+# Copy to `.env` and fill in your own values. NEVER commit your real `.env`.
+
+# Wokwi CI — firmware-in-the-loop simulation (v0.1-0.2).
+# Create a token at https://wokwi.com/dashboard/ci
+WOKWI_CLI_TOKEN=
+
+# Edge Impulse — Tier-4 inference example (v0.2).
+# Project API key: EI project > Dashboard > Keys tab.
+EI_API_KEY=
+
+# Arduino IoT Cloud — device-source example (v0.2).
+# OAuth2 client credentials: IoT Cloud > API keys.
+ARDUINO_CLIENT_ID=
+ARDUINO_CLIENT_SECRET=
+
+# Note: your PyPI token lives in your own environment / keyring for `twine`.
+# It is never stored in this repository.

mcp_edge-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q --cov=mcp_edge --cov-report=term-missing
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip build
+          python -m build

mcp_edge-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Byte-compiled / optimized / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution / packaging
+.Python
+build/
+dist/
+downloads/
+wheels/
+*.egg-info/
+.eggs/
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Environment files / secrets / credentials
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+*secret*
+*secrets*
+*.eim
+
+# Testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.tox/
+.cache/
+
+# Type checking / linting
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+
+# Editors / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Build / sim artifacts / logs
+*.log
+*.vcd
+screenshot*.png

mcp_edge-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-25
+
+First public release. Alpha: the API is unstable and will change.
+
+### Added
+- Four-tier device taxonomy (`tiers`) mapping RFC 7228 device classes to MCP
+  strategies, with nine reference platforms.
+- CBOR codec (`codec`) for the device link, plus a JSON size-comparison helper.
+- Transport abstraction (`transports`) and an in-process loopback transport.
+- MCP-Lite protocol (`mcplite`): CBOR-framed `tools/list`, `tools/call`,
+  `resources/read`.
+- Device simulator (`devices.SimulatedDevice`) for hardware-free development and tests.
+- Device client layer (`client`): the `DeviceClient` interface and `MCPLiteClient`.
+- Device registry (`registry`) and the aggregating `Gateway`, which exposes every
+  device's tools under a device-prefixed composite namespace and routes calls back.
+- Gateway exposed as an MCP server (`server.build_server`, `run_stdio`) built on the
+  SDK's low-level `Server`.
+- `mcp-edge` CLI with `run [--demo]` to serve a gateway (optionally preloaded with
+  simulated devices) over stdio.
+- Protocol adaptations: schema caching (`schema`), connection pooling (`pool`), and
+  offline request buffering (`buffer`).
+- Health monitor (`health`) that probes devices and updates their connection state.
+
+### Notes
+- Real serial / BLE / Wi-Fi transports (and firmware-in-the-loop testing) arrive in a
+  later release; this version exercises the full path against simulated devices.
+- Performance figures in the MCP-Edge paper are projected estimates, not measurements
+  taken from this code.

mcp_edge-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muntaser Syed, Sheikh Abujar, and Sharun Akter
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_edge-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: mcp-edge
+Version: 0.1.0
+Summary: Extend the Model Context Protocol (MCP) to edge and IoT devices: a bridging gateway, a lightweight MCP-Lite server, and a four-tier device taxonomy.
+Project-URL: Homepage, https://github.com/jemsbhai/mcp-edge
+Project-URL: Repository, https://github.com/jemsbhai/mcp-edge
+Project-URL: Issues, https://github.com/jemsbhai/mcp-edge/issues
+Author: Muntaser Syed, Sheikh Abujar, Sharun Akter
+License: MIT
+License-File: LICENSE
+Keywords: agents,edge,embedded,gateway,iot,llm,mcp,model-context-protocol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.10
+Requires-Dist: cbor2>=5.6
+Requires-Dist: mcp<2,>=1.4
+Provides-Extra: all
+Requires-Dist: bleak>=0.22; extra == 'all'
+Requires-Dist: pyserial>=3.5; extra == 'all'
+Requires-Dist: zeroconf>=0.131; extra == 'all'
+Provides-Extra: ble
+Requires-Dist: bleak>=0.22; extra == 'ble'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == 'serial'
+Provides-Extra: wifi
+Requires-Dist: zeroconf>=0.131; extra == 'wifi'
+Description-Content-Type: text/markdown
+
+# MCP-Edge
+
+[![CI](https://github.com/jemsbhai/mcp-edge/actions/workflows/ci.yml/badge.svg)](https://github.com/jemsbhai/mcp-edge/actions/workflows/ci.yml)
+
+**Extend the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) to edge and IoT devices.**
+
+MCP-Edge lets cloud LLM agents discover and invoke physical hardware through the same
+tool interface they already use for software APIs. It provides:
+
+- a **gateway** that bridges cloud-native MCP transports (SSE / HTTP) to constrained
+  device channels (UART, BLE, local Wi-Fi), presenting every downstream device as a
+  standard MCP tool provider;
+- **MCP-Lite**, a lightweight MCP server for devices with as little as ~512 KB of RAM;
+- a **four-tier device taxonomy** (constrained MCUs, smart IoT nodes, BLE-only
+  wearables, Linux-class edge computers) that maps an MCP strategy to each tier;
+- protocol adaptations for constrained links: CBOR encoding, schema caching,
+  connection pooling, and offline request buffering.
+
+> **Status: alpha, under active development.** The public API is unstable and will
+> change. This repository is a *reference implementation* of the framework described in
+> the MCP-Edge paper (IEEE Cloud Summit 2026). Performance figures reported in the paper
+> are projected estimates, not measurements taken from this codebase. This release
+> exercises the full gateway path against *simulated* devices; real serial/BLE/Wi-Fi
+> transports arrive in a later version.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install mcp-edge
+```
+
+For development, install from source:
+
+```bash
+git clone https://github.com/jemsbhai/mcp-edge
+cd mcp-edge
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+**Run a demo gateway** — an MCP server exposing two simulated devices over stdio:
+
+```bash
+mcp-edge run --demo
+```
+
+This serves a simulated sensor (`read_temp`, `read_humidity`) and a simulated ring
+(`heart_rate`), each tool namespaced by device (`sensor-01/read_temp`, ...). To drive it
+from an MCP client such as the MCP Inspector or Claude Desktop, configure a stdio server
+with command `mcp-edge` and arguments `["run", "--demo"]`. The process logs to stderr and
+waits for a client on stdin.
+
+**Use the gateway as a library:**
+
+```python
+import asyncio
+
+from mcp_edge.client import MCPLiteClient
+from mcp_edge.devices import SimulatedDevice
+from mcp_edge.gateway import Gateway
+from mcp_edge.registry import DeviceRegistry
+from mcp_edge.tiers import Tier
+from mcp_edge.transports import LoopbackTransport
+
+
+async def main() -> None:
+    device = SimulatedDevice("sensor-01")
+    device.add_tool("read_temp", lambda args: {"celsius": 21.5})
+
+    transport = LoopbackTransport(device.handle)
+    await transport.open()
+
+    registry = DeviceRegistry()
+    registry.register("sensor-01", MCPLiteClient(transport), Tier.SMART_NODE)
+
+    gateway = Gateway(registry)
+    print([tool["name"] for tool in await gateway.list_tools()])  # ['sensor-01/read_temp']
+    print(await gateway.call_tool("sensor-01/read_temp", {}))     # {'celsius': 21.5}
+
+
+asyncio.run(main())
+```
+
+## Roadmap
+
+- [x] **v0.1** — gateway core, in-process (loopback) transport, protocol adaptations
+      (CBOR, schema caching, connection pooling, offline buffering), device simulator,
+      health monitor, CLI, hermetic CI
+- [ ] **v0.2** — real transports (`pyserial` UART/USB, BLE, Wi-Fi/mDNS) and
+      [Wokwi](https://wokwi.com) firmware-in-the-loop tests (Arduino / ESP32 / RP2040)
+- [ ] **v0.2+** — Edge Impulse (inference as an MCP tool) and Arduino IoT Cloud
+      (properties as MCP) integration examples; Renode / QEMU backends
+
+## Development
+
+```powershell
+pip install -e ".[dev]"
+pytest -q
+ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_edge-0.1.0/README.md

@@ -0,0 +1,107 @@
+# MCP-Edge
+
+[![CI](https://github.com/jemsbhai/mcp-edge/actions/workflows/ci.yml/badge.svg)](https://github.com/jemsbhai/mcp-edge/actions/workflows/ci.yml)
+
+**Extend the [Model Context Protocol (MCP)](https://modelcontextprotocol.io) to edge and IoT devices.**
+
+MCP-Edge lets cloud LLM agents discover and invoke physical hardware through the same
+tool interface they already use for software APIs. It provides:
+
+- a **gateway** that bridges cloud-native MCP transports (SSE / HTTP) to constrained
+  device channels (UART, BLE, local Wi-Fi), presenting every downstream device as a
+  standard MCP tool provider;
+- **MCP-Lite**, a lightweight MCP server for devices with as little as ~512 KB of RAM;
+- a **four-tier device taxonomy** (constrained MCUs, smart IoT nodes, BLE-only
+  wearables, Linux-class edge computers) that maps an MCP strategy to each tier;
+- protocol adaptations for constrained links: CBOR encoding, schema caching,
+  connection pooling, and offline request buffering.
+
+> **Status: alpha, under active development.** The public API is unstable and will
+> change. This repository is a *reference implementation* of the framework described in
+> the MCP-Edge paper (IEEE Cloud Summit 2026). Performance figures reported in the paper
+> are projected estimates, not measurements taken from this codebase. This release
+> exercises the full gateway path against *simulated* devices; real serial/BLE/Wi-Fi
+> transports arrive in a later version.
+
+## Installation
+
+Requires Python 3.10+.
+
+```bash
+pip install mcp-edge
+```
+
+For development, install from source:
+
+```bash
+git clone https://github.com/jemsbhai/mcp-edge
+cd mcp-edge
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+**Run a demo gateway** — an MCP server exposing two simulated devices over stdio:
+
+```bash
+mcp-edge run --demo
+```
+
+This serves a simulated sensor (`read_temp`, `read_humidity`) and a simulated ring
+(`heart_rate`), each tool namespaced by device (`sensor-01/read_temp`, ...). To drive it
+from an MCP client such as the MCP Inspector or Claude Desktop, configure a stdio server
+with command `mcp-edge` and arguments `["run", "--demo"]`. The process logs to stderr and
+waits for a client on stdin.
+
+**Use the gateway as a library:**
+
+```python
+import asyncio
+
+from mcp_edge.client import MCPLiteClient
+from mcp_edge.devices import SimulatedDevice
+from mcp_edge.gateway import Gateway
+from mcp_edge.registry import DeviceRegistry
+from mcp_edge.tiers import Tier
+from mcp_edge.transports import LoopbackTransport
+
+
+async def main() -> None:
+    device = SimulatedDevice("sensor-01")
+    device.add_tool("read_temp", lambda args: {"celsius": 21.5})
+
+    transport = LoopbackTransport(device.handle)
+    await transport.open()
+
+    registry = DeviceRegistry()
+    registry.register("sensor-01", MCPLiteClient(transport), Tier.SMART_NODE)
+
+    gateway = Gateway(registry)
+    print([tool["name"] for tool in await gateway.list_tools()])  # ['sensor-01/read_temp']
+    print(await gateway.call_tool("sensor-01/read_temp", {}))     # {'celsius': 21.5}
+
+
+asyncio.run(main())
+```
+
+## Roadmap
+
+- [x] **v0.1** — gateway core, in-process (loopback) transport, protocol adaptations
+      (CBOR, schema caching, connection pooling, offline buffering), device simulator,
+      health monitor, CLI, hermetic CI
+- [ ] **v0.2** — real transports (`pyserial` UART/USB, BLE, Wi-Fi/mDNS) and
+      [Wokwi](https://wokwi.com) firmware-in-the-loop tests (Arduino / ESP32 / RP2040)
+- [ ] **v0.2+** — Edge Impulse (inference as an MCP tool) and Arduino IoT Cloud
+      (properties as MCP) integration examples; Renode / QEMU backends
+
+## Development
+
+```powershell
+pip install -e ".[dev]"
+pytest -q
+ruff check .
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_edge-0.1.0/pyproject.toml

@@ -0,0 +1,81 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-edge"
+dynamic = ["version"]
+description = "Extend the Model Context Protocol (MCP) to edge and IoT devices: a bridging gateway, a lightweight MCP-Lite server, and a four-tier device taxonomy."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Muntaser Syed" },
+    { name = "Sheikh Abujar" },
+    { name = "Sharun Akter" },
+]
+keywords = ["mcp", "model-context-protocol", "edge", "iot", "llm", "agents", "gateway", "embedded"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Internet",
+    "Topic :: System :: Hardware",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "mcp>=1.4,<2",
+    "cbor2>=5.6",
+]
+
+[project.optional-dependencies]
+serial = ["pyserial>=3.5"]
+ble = ["bleak>=0.22"]
+wifi = ["zeroconf>=0.131"]
+all = ["mcp-edge[serial,ble,wifi]"]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "mypy>=1.10",
+    "build>=1.2",
+    "twine>=5.0",
+]
+
+[project.scripts]
+mcp-edge = "mcp_edge.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/jemsbhai/mcp-edge"
+Repository = "https://github.com/jemsbhai/mcp-edge"
+Issues = "https://github.com/jemsbhai/mcp-edge/issues"
+
+[tool.hatch.version]
+path = "src/mcp_edge/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_edge"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "W"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+warn_unused_ignores = true

mcp_edge-0.1.0/src/mcp_edge/__init__.py

@@ -0,0 +1,12 @@
+"""MCP-Edge: extend the Model Context Protocol (MCP) to edge and IoT devices.
+
+An early, in-development reference implementation of the MCP-Edge framework:
+a gateway that bridges cloud-native MCP transports to constrained-device
+channels, a lightweight MCP-Lite server, and a four-tier device taxonomy.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

mcp_edge-0.1.0/src/mcp_edge/buffer.py

@@ -0,0 +1,60 @@
+"""Offline request buffering.
+
+When a device is briefly unreachable, the gateway can buffer operations destined for it
+and replay them in order once it returns, rather than dropping them. The buffer is a
+bounded FIFO; on overflow it raises rather than silently discarding, and a flush that
+fails part-way leaves the failed item (and the rest) queued for the next attempt.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Awaitable, Callable
+from typing import Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class BufferFull(RuntimeError):
+    """Raised when enqueuing onto a full buffer."""
+
+
+class OfflineBuffer(Generic[T]):
+    """A bounded FIFO buffer of operations for a temporarily unreachable device."""
+
+    def __init__(self, *, max_size: int = 128) -> None:
+        self.max_size = max_size
+        self._items: deque[T] = deque()
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    @property
+    def is_full(self) -> bool:
+        return len(self._items) >= self.max_size
+
+    def enqueue(self, item: T) -> None:
+        """Append ``item``; raises :class:`BufferFull` if the buffer is full."""
+        if self.is_full:
+            raise BufferFull(f"buffer is full (max_size={self.max_size})")
+        self._items.append(item)
+
+    async def flush(self, handler: Callable[[T], Awaitable[None]]) -> int:
+        """Apply ``handler`` to each item in FIFO order, removing it on success.
+
+        Returns the number flushed. If ``handler`` raises, the failed item stays at the
+        front (and the remaining items stay queued) so the operation can be retried.
+        """
+        count = 0
+        while self._items:
+            await handler(self._items[0])
+            self._items.popleft()
+            count += 1
+        return count
+
+    def clear(self) -> None:
+        """Discard all buffered items."""
+        self._items.clear()
+
+
+__all__ = ["OfflineBuffer", "BufferFull"]