Add dev stacks

stacks/network-mcp/README.md

@@ -0,0 +1,105 @@
+# Network MCP
+
+A "source of truth" for network devices and ports, backed by Elasticsearch, OPNsense, and Nmap.
+
+## Architecture
+
+- **Elasticsearch**: Stores current state (`network-hosts`) and historical events (`network-events-*`).
+- **OPNsense Collector**: Fetches DHCP/ARP/DNS data to discover hosts.
+- **Nmap Collector**: Scans discovered hosts for open ports and OS info.
+
+## Setup
+
+1. **Environment Config**
+   Copy `.env.example` to `.env` and fill in your details:
+   ```bash
+   cp .env.example .env
+   # Edit .env
+   ```
+
+2. **Bootstrap Elastic**
+   Run the bootstrap script (requires `requests` installed locally, or you can run it inside a container):
+   ```bash
+   python3 scripts/bootstrap_indices.py
+   ```
+   *Note: Ensure you have connectivity to your Elasticsearch instance.*
+
+3. **Start Services**
+   ```bash
+   docker-compose up -d --build
+   ```
+   This brings up the collectors and the lightweight frontend (reachable on port `5001`).
+
+## Configuration
+
+- **Static Metadata**: Edit `static/host_metadata.json` to add manual notes, roles, or tags to hosts (keyed by `mac:xx:xx...`).
+- **Intervals**: Adjust polling intervals in `.env`.
+- **VLAN Discovery (default on)**: Discovery sweeps (`nmap -sn`) run periodically across the OPNsense interfaces listed in `NMAP_DISCOVERY_VLANS`. Adjust the list (or set the flag to `false`) if you only want targeted subnets.
+- **Quick vs Full Port Scans**: Each collector loop runs a fast, common-port sweep (`NMAP_QUICK_EXTRA_ARGS`, `NMAP_QUICK_BATCH_SIZE`) while a deeper service scan (`NMAP_PORT_RANGE`, `NMAP_BATCH_SIZE`) is triggered once per `NMAP_FULL_INTERVAL_SECONDS` (default daily). Tune these env vars to balance coverage vs. runtime.
+- **Inventory Overlay**: Entries in `./inventory_targets.yml` are mounted into the OPNsense collector and merged by IP—offline/static hosts from that file (names, notes, expected ports) now appear in `network-hosts` with `source: inventory`.
+
+## Data Model
+
+- **`network-hosts`**: Current state of every known host.
+- **`network-events-YYYY.MM.DD`**: Immutable log of scans and discovery events.
+
+## Usage
+
+Query `network-hosts` for the latest view of your network:
+```json
+GET network-hosts/_search
+{
+  "query": {
+    "match_all": {}
+  }
+}
+```
+
+### Quick Frontend
+
+A minimal Flask frontend is bundled in docker-compose (service `frontend`) and is exposed on port `5001` so it can be reached from other machines:
+
+```bash
+docker-compose up -d frontend
+```
+
+Then visit `http://<host-ip>:5001/` to see the merged view (inventory entries are marked with `source: inventory`). If you prefer to run it without Docker for debugging, follow the steps below:
+
+```bash
+cd network-mcp
+python3 -m venv .venv && source .venv/bin/activate
+pip install -r frontend/requirements.txt
+python frontend/app.py
+```
+
+### MCP / API Endpoints
+
+The frontend doubles as a Model Context Protocol server. It exposes the manifest at `/.well-known/mcp.json` (or `/api/mcp`) and supports the standard JSON-RPC handshake (`initialize`, `tools/list`, `tools/call`) on the same URL. Agents can either use the RPC tools below or hit the underlying REST endpoints directly.
+
+- MCP Resources are also available (`resources/list`, `resources/read`, `resources/templates/list`) for clients that prefer resource-style access to snapshots and queries.
+
+- `GET /api/hosts` – merged host list (supports `limit`, `source`, and repeated `q` params to fuzzy search names, hostnames, IPs, or MACs in a single call).
+- `GET /api/hosts/<host_id>` – single host document with optional `include_events=true`.
+- `GET /api/events` – recent scan/discovery events (`limit`, `host_id`, `type`, `since` filters).
+- `GET /api/hosts/<host_id>/events` – scoped events for a host.
+- `GET /api/map` – high-level “network map” grouping hosts by detected /24 (IPv4) or /64 (IPv6).
+
+RPC tool names (mirrored in the manifest) are:
+
+- `list_hosts` – accepts `{limit, source, terms}` and returns the merged host list.
+- `network_map` – optional `{limit}` for building /24-/64 summaries.
+- `get_host` – requires `{host_id}` plus optional `include_events`, `events_limit`.
+- `list_events` – `{limit, host_id, type, since}`.
+- `host_events` – requires `{host_id}` plus optional `limit`, `type`, `since`.
+
+Resource URI examples:
+
+- `network://hosts?q=seele&limit=50`
+- `network://host/mac:dc:a6:32:67:55:dc?include_events=true&events_limit=50`
+- `network://events?type=discovery&limit=100`
+
+All RPC and REST calls share the Elasticsearch credentials from `.env`, so an agent only needs HTTP access to port `5001` to query hosts, notes, and event timelines. Registering the MCP with Codex looks like:
+
+```bash
+codex mcp install network-mcp http://<host>:5001/.well-known/mcp.json
+```