Metadata-Version: 2.5
Name: grok-gadgets-gateway
Version: 0.1.0a10
Summary: Local Grok Gadgets MCP gateway and device protocol
Project-URL: Homepage, https://grokgadgets.org/
Project-URL: Source, https://github.com/adidshaft/grok-gadgets-gateway
Project-URL: Issues, https://github.com/adidshaft/grok-gadgets-gateway/issues
Project-URL: Changelog, https://github.com/adidshaft/grok-gadgets-gateway/blob/main/CHANGELOG.md
Author: adidshaft
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: gadgets,grok,iot,mcp,simulator
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Home Automation
Requires-Python: >=3.11
Requires-Dist: cryptography==50.0.2
Requires-Dist: httpx2==2.13.1
Requires-Dist: jsonschema==4.26.0
Requires-Dist: mcp==2.3.0
Requires-Dist: pyserial==3.5
Description-Content-Type: text/markdown

# Grok Gadgets gateway

The connection point between your Grok Bot and your gadgets: a built-in simulated light,
Linux gadgets and ESP32 devices. It serves six MCP tools. The owner tested USB and Wi-Fi hardware through the gateway.
Grok Bot ran local `rehearse` commands; native MCP access remains unverified ([project status](https://grok-gadgets.pages.dev/doc-docs-public-support-matrix)).
Independent project, not affiliated with SpaceXSI or xAI.

> Writing style: ASD-STE100-inspired English. Use short sentences, active verbs and one instruction per step. This is not certified compliance.

## Quick start

Needs Git and [uv](https://docs.astral.sh/uv/getting-started/installation/).

```sh
git clone https://github.com/adidshaft/grok-gadgets-gateway.git
cd grok-gadgets-gateway
uv sync --locked
uv run grok-gadgets-gateway init
uv run grok-gadgets-gateway serve --simulator
uv run grok-gadgets-gateway rehearse
```

Run `rehearse` in a second terminal while `serve` keeps running. It calls the six tools in the
order Grok Bot will: list the gadgets, set the simulated light blue, read its state. See
[first success in five minutes](docs/first-success.md).

### Install with pip

The package is not on PyPI yet. Each [GitHub release](https://github.com/adidshaft/grok-gadgets-gateway/releases)
has a wheel and `SHA256SUMS`. Install the wheel into a virtual environment with Python 3.11+:

```sh
python3 -m venv .venv
.venv/bin/python -m pip install https://github.com/adidshaft/grok-gadgets-gateway/releases/download/v0.1.0-alpha.10/grok_gadgets_gateway-0.1.0a10-py3-none-any.whl
.venv/bin/grok-gadgets-gateway --help
```

On an Intel Mac, `cryptography` has no prebuilt wheel and needs a Rust toolchain to build.

## How it works

```mermaid
flowchart LR
    B["Grok Bot"] -->|Local command| R["rehearse"]
    R --> G["Gateway<br>Tested Mac setup"]
    G --> S["Simulated light"]
    G --> D["Linux / ESP32 gadgets"]
```

The gateway gives Grok Bot six tools:

| Tool | What it does |
| --- | --- |
| `gadgets_list_devices` | Lists gadgets, their commands and what each one does. Call it first. |
| `gadgets_get_state` | Reads a gadget's last reported state and how fresh it is. |
| `gadgets_command` | Sends a command and waits up to 3 seconds for the result. |
| `gadgets_command_status` | Reads the result of a slower command later. |
| `gadgets_read_events` | Reads button presses and other events in order. |
| `gadgets_diagnostics` | A support report with no tokens, state or arguments. |

A result is the gadget's own report, not proof of a physical effect.

## Connect a gadget

`init` prints two settings blocks with absolute paths. Use the first when the connector starts the gateway itself (`stdio`). Use the second for a running `serve` at `http://127.0.0.1:8766/mcp`, with the bearer token from `~/.config/grok-gadgets/mcp-token`. `init --client http` prints just one.

Gadgets connect to `127.0.0.1:8765` with their own token:

```sh
uv run grok-gadgets-gateway enroll desk-lamp --token-file desk-lamp.token
```

`enroll desk-lamp --rotate` issues a new token for the same gadget. Write gadgets with the
[Linux SDK](https://github.com/adidshaft/grok-gadgets-linux-sdk) or the
[ESP32 SDK](https://github.com/adidshaft/grok-gadgets-esp32-sdk); the Linux SDK's `dev`
command needs no token at all. Both ports are loopback only.
A Wi-Fi gadget on your home network can use the opt-in TLS listener on one private
address, `serve --lan-listen`; see [Wi-Fi devices](docs/wifi-devices.md).

## Grok Bot today

The owner tested Grok Bot local commands on 12 October 2026. Grok Bot ran `rehearse` on the Mac.
Read the [connection evidence](https://github.com/adidshaft/grok-gadgets/blob/dev/docs/verification/grok-local-execution-2026-10-12.md).
Native MCP calls and the public tunnel test remain open ([tracking issue](https://github.com/adidshaft/grok-gadgets/issues/4)).
The Mac must keep the gateway running, including for Wi-Fi devices. `serve` is not an
OAuth server, and a tunnel does not replace the bearer token. Never expose port 8765. Read
[remote access](docs/remote-access.md) and [security](SECURITY.md) first.

## Troubleshooting

| Symptom | Next step |
| --- | --- |
| Not sure which command | Run `grok-gadgets-gateway --help`. Use `serve` for a long-running process; `stdio` is for a connector that starts the gateway itself. |
| No simulated light | Start with `--simulator`. |
| `401` from `rehearse` | Send `Authorization: Bearer <token>` with the exact contents of the token file. |
| Config rejected | Use strict v1 JSON within the [documented bounds](docs/simulator.md). |
| Command still `accepted` or `dispatched` | The gadget is slow. Poll `gadgets_command_status`; never resend with a new command ID. |

## Learn more

- [First success](docs/first-success.md) and the [simulator guide](docs/simulator.md)
- [Keep the gateway running](docs/always-on.md) as a background service.
- [Local operation](docs/local-operation.md), [architecture](docs/architecture.md) and [protocol 0.1.0](protocol/0.1.0/README.md)
- Demo without HTTP: `uv run python -m grok_gadgets_gateway.demo` (uses test-only controls)
- Shared docs and the website: [hub repository](https://github.com/adidshaft/grok-gadgets) and <https://grok-gadgets.pages.dev/>

## Community

Questions, build photos and ideas are welcome on
[r/GrokGadgets](https://www.reddit.com/r/GrokGadgets/). Report bugs and request features in
[GitHub Issues](https://github.com/adidshaft/grok-gadgets-gateway/issues). New here? Pick a
[good first issue](https://github.com/adidshaft/grok-gadgets-gateway/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
and read [CONTRIBUTING](CONTRIBUTING.md). Get help: [SUPPORT](SUPPORT.md).
Contribute on the `dev` branch; `main` holds tagged stable releases ([branches](CONTRIBUTING.md#branches)).

## License and affiliation

Apache-2.0; see [LICENSE](LICENSE) and [NOTICE](NOTICE). Grok Gadgets is an independent
open-source project. It is **not affiliated with, endorsed by or sponsored by SpaceXSI or
xAI**, which make Grok and Grok Bot. We reconstructed the pre-publication commit dates; see the
[history record](https://github.com/adidshaft/grok-gadgets/blob/main/docs/verification/publication-sanitization.md).
