rustmistmcp

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/mechub-mark.svg">
    <img src="docs/assets/mechub-mark-light.svg" width="72" alt="mechub mark">
  </picture>
</p>

<h1 align="center">rustmistmcp</h1>

<p align="center"><strong>Async Rust Model Context Protocol server for the HPE Juniper Mist cloud</strong><br>
<em>a mechub project — sovereign network-security automation</em></p>

> **Unofficial / community project.** This is an independent community project
> and does not claim affiliation with or endorsement by Hewlett Packard
> Enterprise or Juniper Networks. Product names and trademarks are used only to
> identify the systems with which the software interoperates.

---

`rustmistmcp` exposes the **Juniper Mist cloud** — orgs, sites, APs, switches,
gateways, WLANs, clients, SLE, and Marvis — to MCP clients as a bounded,
auditable tool surface.

Where [`rustjunosmcp`](https://github.com/mechubsec/rustjunosmcp) talks
NETCONF to individual SRX devices and
[`rustpanosmcp`](https://github.com/mechubsec/rustpanosmcp) talks XML-API to
individual PAN-OS firewalls, this server talks to a **multi-tenant cloud control
plane**. One org-scoped call can reach every site and every access point in an
estate, so scoping, bounded responses, and change control are not garnish here;
they are the design.

The functional target is the Mist half of
[`nowireless4u/hpe-networking-mcp`](https://github.com/nowireless4u/hpe-networking-mcp)
— site health and SLE, device inventory and stats, WLAN/SSID management, client
connectivity, events and alarms, audit logs, RRM and rogue detection, firmware,
NAC/policy, guest access, webhooks, floor plans, and Marvis — reimplemented in
Rust on the `mecmcp` foundation rather than as a Python spec-driven registry.
That project registers on the order of a thousand generated tools; this one
deliberately will not. A curated, scoped, individually-documented surface is the
whole point of doing it again.

## Relationship to `mecmcp`

[`mecmcp`](https://github.com/mechubsec/mecmcp) is the vendor-neutral Rust
foundation shared by the mechub MCP server family. This repository is a
**consumer** of that foundation, not a fork of it:

| Concern | Where it lives |
|---|---|
| Token mint/digest/verify, `tokens.json`, scopes, grants, caller context | `mecmcp-auth` |
| Attribution, audit events, redaction, sinks | `mecmcp-audit` |
| Streamable-HTTP transport, host/Origin checks, rate + concurrency limits | `mecmcp-transport` |
| CLI skeleton, TLS bootstrap, signals, graceful shutdown | `mecmcp-runtime` |
| Plan → digest → approve → apply → verify change control | `mecmcp-changeset` |
| Org/site/tenant registry | `mecmcp-inventory` |
| **Mist REST client, API-token auth, response models, tool surface** | **this repo** |

Everything that is *not* specific to the Mist API is upstream. If you find
yourself writing generic auth or transport code here, it belongs in `mecmcp`.
There is currently no temporary exception: the one the ledger at
[`docs/UPSTREAM_COMPATIBILITY.md`](docs/UPSTREAM_COMPATIBILITY.md) recorded — a
Mist-typed token lifecycle adapter — was deleted when its removal condition was
met. Any new exception must be recorded there with an objective removal
condition.

## The API

Mist publishes a versioned REST API under `/api/v1`, served from per-region
cloud endpoints. The org's home region determines the host:

| Region | Endpoint |
|---|---|
| Global 01 | `api.mist.com` |
| EU 01 | `api.eu.mist.com` |
| GovCloud | `api.gc1.mist.com` |

Additional regional clouds exist; the authoritative list is Juniper's *API
Endpoints and Global Regions* table, and the region must be operator-configured
rather than guessed.

The Mist vendor API supports API tokens and external OAuth 2.0. API tokens are
sent as `Authorization: Token <token>`, may be minted per user or organization,
and inherit the privileges of the account that created them. rustmistmcp v1 intentionally implements API-token authentication only; it does not accept OAuth
credentials. HTTP Basic authentication with Juniper Mist login credentials is
**deprecated as of September 2026** and will not be implemented here.

Primary references:

- [RESTful API Overview](https://www.juniper.net/documentation/us/en/software/mist/automation-integration/topics/concept/restful-api-overview.html)
- [Create API Tokens](https://www.juniper.net/documentation/us/en/software/mist/automation-integration/topics/task/create-token-for-rest-api.html)
- [Mist API Reference](https://www.juniper.net/documentation/us/en/software/mist/api/http/guides/overview/mist-apis)

The concrete endpoint map, pagination, and rate-limit semantics are being vetted
directly against the live API reference before any client code lands — this
README will not restate a surface it has not verified.

## Status

**Foundation built; read-only live-tenant acceptance passed.** The workspace has
an audited operation catalog, strict profile metadata, authorization models, and
a catalog-bound `MistClient` contract that validates Mist operation inputs and
binds opaque cursors to a configured origin. `mecmcp#90` has closed, so
`HttpMistClient` — the concrete HTTPS implementation over `mecmcp-http` — is
built by `MistHandler::from_config` on the production path.

A lab deployment has reached a real Mist org. On 2026-08-10, through a
loopback-bound endpoint and a grant-scoped bearer token, `get_mist_self`
(`getSelf`), `get_mist_org` (`getOrg`), and `list_mist_sites` (`listOrgSites`)
each returned tenant data with `result: ok` in 92–325 ms. That was issue #11's
gate, and it closed.

What is *not* done, and must not be described as done:

- **That run is not full packaging acceptance.** It was loopback-only with no
  TLS, one org, one token, three read tools. The checklist in
  [`docs/PACKAGING_ACCEPTANCE.md`](docs/PACKAGING_ACCEPTANCE.md) — TLS hostname
  and chain, anonymous and bad-bearer rejection, exact Host/Origin enforcement —
  is not complete.
- **No `/api/v1/self` *startup* identity probe.** The `get_mist_self` tool works
  against a live tenant; nothing probes `/self` during startup, and
  `LIVE_MIST_BLOCKER` still names that gap.
- **Mutations exist only for batch-1 WAN edge objects.** Batch-1 covers create
  and update for networks, services, service policies, gateway templates, and
  device profiles, reachable only through the plan → digest → approve → apply
  lifecycle. Delete operations and `mist_configured` device-profile
  assignment/unassignment remain out of reach. No live-tenant apply has been
  performed.

A handler constructed without a credential uses `BlockedMistClient`, which
performs no I/O; `LIVE_MIST_BLOCKER` is the message it refuses with.

### Site discovery

Site-scoped tools refuse any site the handler does not already know (see
"The API"). At startup, the server calls `listOrgSites` for every allowlisted
org to populate that map before it begins serving. `--site-refresh-interval-secs`
(default `300`) controls a background task that repeats this walk on an
interval, so a site added or removed on the Mist side is picked up without a
restart; `0` disables the background task and discovers once at startup only.

This refresh is idle polling against the operator-configured Mist origin —
`listOrgSites` requests every `site-refresh-interval-secs`, independent of
tool traffic, over the same catalog-validated `MistClient` every other read
uses. It bypasses the per-tool audit trail, since it is a read that updates
internal server state rather than a client-initiated call. A request failure
or hitting the tracked-site ceiling for one org during a refresh keeps that
org's previously known sites rather than dropping them; it does not affect
other orgs' sites.

Shared `TokenSecret`, cancellation, and changeset primitives are reused, not
rebuilt. Mist header names, catalog policy, request/response schemas, terminal
states, retry classification, and deployment remain in this repository.

## Pre-release packaging and deployment boundary

The checked-in Docker, archive, systemd, and LXC assets are **pre-release
packaging only**. A lab LXC built from them has served live read-only tenant
traffic (issue #11), which is not the same as packaging acceptance: that run
used no TLS and no off-loopback bind, so the TLS, Host/Origin, and bad-bearer
rows of `docs/PACKAGING_ACCEPTANCE.md` remain unproven. The `/api/v1/self`
startup probe is unimplemented, and mutations exist only for batch-1 WAN edge
objects behind the change-set lifecycle; no live-tenant apply has been performed.
No v1 release label may be claimed until that checklist is complete.

The OCI image is a multi-stage build with a digest-pinned Rust builder and a
digest-pinned distroless Debian 13 runtime. It runs only
`/usr/local/bin/rustmistmcp` as UID/GID `65532`; the runtime image has no shell,
package manager, or runtime fetcher. Its CA data comes from the distroless base.
Use an immutable image digest, never a mutable tag. The supplied compose example
is read-only, drops every capability, uses no-new-privileges, bounds PIDs and
`/tmp`, mounts `/etc/rustmistmcp` read-only, and mounts
`/var/lib/rustmistmcp` read-write. Do not place Mist or bearer secrets in image
layers, compose environment, or command arguments.

The checked-in service and OCI command use the shared CLI's exact loopback HTTP
contract: `/etc/rustmistmcp/mist.json`, the bearer store, port `30030`, JSON
audit with HMAC redaction, and direct journald delivery for systemd. OCI audit
goes to JSON stderr and does not mount the host journal socket. There is no
mutation-state flag or live-Mist readiness check. `--version` reports this
binary's name and version now that `mecmcp#159` has closed, so release identity
is verified with `--version`, `--help`, `BUILD-INFO`, and artifact/deployed
SHA-256 values.

The compose example is Linux-only: host networking makes the container's
`127.0.0.1:30030` listener reachable from the same host without