Skip to content
Back to search

pyATS_MCP

An MCP Server for pyATS (experimental)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/automateyournetwork--pyats-mcp/badge.svg)](/listings/automateyournetwork--pyats-mcp)

HTML

<a href="/listings/automateyournetwork--pyats-mcp"><img src="/api/listings/automateyournetwork--pyats-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 1. Clone and install
git clone https://github.com/automateyournetwork/pyATS_MCP
cd pyATS_MCP
pip install -r requirements.txt

# 2. Configure your environment
cp .env.example .env
# Edit .env — see Configuration below

# 3. Run — starts a Streamable HTTP server on 0.0.0.0:8080 by default
python3 pyats_mcp_server.py

The MCP endpoint is then reachable at `http://<host>:<port>/mcp`.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 575 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # pyATS MCP Server
  2. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/automateyournetwork/pyATS_MCP)](https://archestra.ai/mcp-catalog/automateyournetwork__pyats_mcp)
  3. [![Available on CodeGuilds](https://img.shields.io/badge/Available_on-CodeGuilds-6366f1)](https://codeguilds.dev/packages/pyats-mcp)
  4. Cisco pyATS and Genie already know how to talk to a network — parsing show commands, pushing configuration, learning feature state, running declarative tests. What they didn't have was a way for an AI agent to drive any of it directly. This server closes that gap: it wraps pyATS/Genie as a set of structured, guarded MCP tools that an agent like Claude can call against a real testbed, over the Model Context Protocol's current Streamable HTTP transport.
  5. Point an agent at it and it can look up a device, run and parse a show command, apply configuration with a rollback point, learn and diff a feature's state before and after a change, fan a command out across a fleet — one thread pool or one process per device — run a declarative Blitz or Robot Framework test, or call a device's REST/RESTCONF API directly. Every risky path is guarded before it reaches a device, and every call lands in an in-memory audit log the agent can review mid-session.
  6. ---
  7. > [!TIP]
  8. > ### Testbed-free: build testbeds dynamically, in memory
  9. > You don't need a `testbed.yaml`. The `pyats_testbed_*` tools build a pyATS testbed **on the fly** from Itential Inventory Manager (the default source), NetBox, Nautobot, Catalyst Center, any JSON REST API, or inline/file CSV, JSON, YAML and XML, using a declarative field mapping. The testbed lives in server memory, is activated with one call, and every existing tool (`pyats_run_show_command`, `pyats_configure_device`, ...) uses it immediately. Start the server with `PYATS_MCP_DYNAMIC_ONLY=1` and no YAML at all. Credentials stay on the server as `%ENV{}` references and never pass through the model. See [Dynamic Testbeds](#dynamic-testbeds) and the [technical write-up](docs/dynamic-testbeds.md).
  10. ---
  11. ## At a glance
  12. - **Transport** — Streamable HTTP (`mcp>=2.3.0`), stateful or stateless, chosen with one environment variable. STDIO is gone.
  13. - **34 tools** across discovery, show commands, configuration, Genie learn/diff, Genie Clean, declarative testing (Blitz, Robot Framework, AEtest), generic REST/RESTCONF, and Cisco XPresso.
  14. - **Two ways to fan out** a command across many devices — a shared thread pool for everyday use, or one OS process per device (`pyats.async_.pcall`) when you want real isolation at scale.
  15. - **Guardrails, not honor systems** — dangerous commands are blocked before they reach a device, Genie Clean can never run a stage that reboots or reimages one, and destructive actions require an exact confirmation phrase.
  16. - **Nothing hard-coded** — every credential and device detail lives in `.env`, pulled into `testbed.yaml` at runtime via `%ENV{}` substitution.
  17. ---
  18. ## Prerequisites
  19. - Python 3.10+
  20. - A pyATS `testbed.yaml` pointed at real or virtual network devices — a physical lab, Cisco Modeling Labs / VIRL / GNS3, or anything else Unicon can reach over SSH/Telnet. pyATS MCP doesn't simulate a network; it drives one. A static `testbed.yaml` is optional: see [Dynamic Testbeds](#dynamic-testbeds).
  21. - An MCP-capable client to talk to it — see [Connect Your Agent](#connect-your-agent) below.
  22. ---
  23. ## Quick Start
  24. ```bash
  25. # 1. Clone and install
  26. git clone https://github.com/automateyournetwork/pyATS_MCP
  27. cd pyATS_MCP
  28. pip install -r requirements.txt
  29. # 2. Configure your environment
  30. cp .env.example .env
  31. # Edit .env — see Configuration below
  32. # 3. Run — starts a Streamable HTTP server on 0.0.0.0:8080 by default
  33. python3 pyats_mcp_server.py
  34. ```
  35. The MCP endpoint is then reachable at `http://<host>:<port>/mcp`.
  36. ### With [uv](https://docs.astral.sh/uv/)
  37. ```bash
  38. git clone https://github.com/automateyournetwork/pyATS_MCP
  39. cd pyATS_MCP
  40. cp .env.example .env # edit — see Configuration below
  41. uv sync # creates .venv and installs dependencies
  42. uv run python pyats_mcp_server.py # serves http://<host>:<port>/mcp
  43. ```
  44. Requires Python 3.10+ (3.12 or older is the safest fit for `pyats[full]`). For development, add the dev extras with `uv sync --extra dev` and run `uv run pytest`.
  45. ---
  46. ## Configuration
  47. All device details and credentials live in a `.env` file — nothing is hard-coded in the repo.
  48. ### 1. Copy the template
  49. ```bash
  50. cp .env.example .env
  51. ```
  52. ### 2. Set the server variables
  53. ```dotenv
  54. PYATS_TESTBED_PATH=/absolute/path/to/your/testbed.yaml
  55. PYATS_MCP_ARTIFACTS_DIR= # default: ~/.pyats-mcp/artifacts
  56. PYATS_MCP_KEEP_ARTIFACTS=1 # 1 = keep, 0 = delete after each run
  57. PYATS_MCP_TESTBED_CACHE_TTL=30 # seconds before testbed reloads from disk
  58. PYATS_MCP_CONN_CACHE_TTL=0 # seconds to keep connections alive (0 = off)
  59. PYATS_MCP_OP_LOG_MAX=500 # max entries in the in-memory operation log
  60. # Transport (Streamable HTTP only — STDIO is not supported)
  61. PYATS_MCP_TRANSPORT_MODE=stateful # stateful (default) | stateless
  62. PYATS_MCP_HTTP_HOST=0.0.0.0
  63. PYATS_MCP_HTTP_PORT=8080
  64. # Optional — only needed for pyats_xpresso_request
  65. XPRESSO_URL=
  66. XPRESSO_API_TOKEN=
  67. XPRESSO_GROUP=
  68. ```
  69. `PYATS_MCP_TRANSPORT_MODE=stateless` sets `stateless_http=True` on the Streamable HTTP transport, so no server-side session state is retained between requests from clients still negotiating the older, handshake-based protocol. Clients speaking the current MCP protocol (2026-07-28, SEP-2575) are handshake-free by default regardless of this setting — that comes from the `mcp>=2.3.0` SDK itself, not anything configured here.
  70. ### 3. Add a block for each device
  71. Every device in your `testbed.yaml` uses `%ENV{VAR}` substitution, so credentials and connection details are read from `.env` at runtime.
  72. Use the `{DEVICENAME}_{FIELD}` naming convention:
  73. ```dotenv
  74. # Supported os values: iosxe | iosxr | nxos | ios | eos | junos | panos | linux | windows
  75. # Set os=generic and platform="" to let Unicon autodetect on first connect.
  76. CORE1_IP=10.1.1.1
  77. CORE1_PORT=22
  78. CORE1_OS=iosxe
  79. CORE1_PLATFORM=cat9k
  80. CORE1_USERNAME=admin
  81. CORE1_PASSWORD=s3cr3t
  82. CORE1_ENABLE_PASSWORD=s3cr3t
  83. FW1_IP=10.1.1.2
  84. FW1_PORT=22
  85. FW1_OS=panos
  86. FW1_PLATFORM=
  87. FW1_USERNAME=admin
  88. FW1_PASSWORD=s3cr3t
  89. # (no enable password for Palo Alto)
  90. LINUX1_IP=10.1.1.3
  91. LINUX1_PORT=22
  92. LINUX1_OS=linux
  93. LINUX1_PLATFORM=ubuntu
  94. LINUX1_USERNAME=admin
  95. LINUX1_PASSWORD=s3cr3t
  96. # (no enable password for Linux)
  97. ```
  98. If a group of devices shares credentials, define group-level vars and reference them across devices:
  99. ```dotenv
  100. SITE_A_USERNAME=netops
  101. SITE_A_PASSWORD=s3cr3t
  102. SITE_A_ENABLE_PASSWORD=s3cr3t
  103. ```
  104. ### 4. Reference the variables in testbed.yaml
  105. ```yaml
  106. devices:
  107. CORE1:
  108. alias: "Core Switch 1"
  109. type: "switch"
  110. os: "%ENV{CORE1_OS}"
  111. platform: "%ENV{CORE1_PLATFORM}"
  112. credentials:
  113. default:
  114. username: "%ENV{CORE1_USERNAME}"
  115. password: "%ENV{CORE1_PASSWORD}"
  116. enable:
  117. password: "%ENV{CORE1_ENABLE_PASSWORD}"
  118. connections:
  119. cli:
  120. protocol: ssh
  121. ip: "%ENV{CORE1_IP}"
  122. port: "%ENV{CORE1_PORT}"
  123. arguments:
  124. connection_timeout: 360
  125. ```
  126. > For devices with unknown OS, set `os: "%ENV{DEVICE_OS}"` with `DEVICE_OS=generic` in `.env`
  127. > and optionally add `learn_os: true` under `arguments:` — Unicon will detect and cache the OS
  128. > after the first connection.
  129. ---
  130. ## Docker
  131. ### Build
  132. ```bash
  133. docker build -t pyats-mcp-server .
  134. ```
  135. ### Run (pass .env directly)
  136. ```bash
  137. docker run -p 8080:8080 --rm \
  138. --env-file /absolute/path/to/.env \
  139. -v /absolute/path/to/testbed.yaml:/app/testbed.yaml \
  140. pyats-mcp-server
  141. ```
  142. Either way, the server is a long-running process you start once and point clients at — it isn't something an agent spawns per session. See below for exactly how each client connects to it.
  143. ---
  144. ## Connect Your Agent
  145. The server exposes one thing: an MCP endpoint at `http://<host>:<port>/mcp` (Streamable HTTP). Every client below just needs that URL — no `command`/`args`, no local process for the client to manage.
  146. ### Claude Code
  147. ```bash
  148. claude mcp add --transport http pyats http://localhost:8080/mcp
  149. # Behind auth (e.g. a reverse proxy in front of the server)
  150. claude mcp add --transport http pyats http://localhost:8080/mcp \
  151. --header "Authorization: Bearer your-token"
  152. ```
  153. Or drop it straight into `.mcp.json` (project-scoped, committed to the repo) or `~/.claude.json` (user-scoped):
  154. ```json
  155. {
  156. "mcpServers": {
  157. "pyats": { "type": "http", "url": "http://localhost:8080/mcp" }
  158. }
  159. }
  160. ```
  161. ### VS Code (GitHub Copilot Chat)
  162. Add a `.vscode/mcp.json` in the workspace (or run **MCP: Add Server** from the Command Palette):
  163. ```json
  164. {
  165. "servers": {
  166. "pyats": { "type": "http", "url": "http://localhost:8080/mcp" }
  167. }
  168. }
  169. ```
  170. ### OpenAI Codex CLI
  171. ```bash
  172. codex mcp add pyats --url http://localhost:8080/mcp
  173. ```
  174. Or in `~/.codex/config.toml`:
  175. ```toml
  176. [mcp_servers.pyats]
  177. url = "http://localhost:8080/mcp"
  178. ```
  179. ### Claude Desktop
  180. Claude Desktop's `claude_desktop_config.json` is stdio-only — putting a `url` field in it doesn't work (it's a known issue, not a supported path). Remote/HTTP servers are added instead as a **Custom Connector** under Settings → Connectors, and Desktop connects to it from Anthropic's cloud, not your local machine — so it needs a real, publicly-reachable HTTPS URL, not `localhost`.
  181. To point Desktop at a server running on your own machine anyway, bridge it through [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) as a local stdio proxy:
  182. ```json
  183. {
  184. "mcpServers": {
  185. "pyats": {
  186. "command": "npx",
  187. "args": ["-y", "mcp-remote", "http://localhost:8080/mcp", "--transport", "http-only"]
  188. }
  189. }
  190. }
  191. ```
  192. ### Raw Python (LangGraph, custom agents, anything else)
  193. ```python
  194. from mcp import ClientSession
  195. from mcp.client.streamable_http import streamablehttp_client
  196. async def main():
  197. async with streamablehttp_client("http://localhost:8080/mcp") as (read, write, _session_id):
  198. async with ClientSession(read, write) as session:
  199. await session.initialize()
  200. tools = await session.list_tools()
  201. result = await session.call_tool(
  202. "pyats_run_show_command",
  203. arguments={"device_name": "CORE1", "command": "show version"},
  204. )
  205. ```
  206. ---
  207. ## Asynchronous MCP Tasks
  208. MCP supports returning a task handle immediately and retrieving the result later.
  209. This server implements the **2026-07-28 `io.modelcontextprotocol/tasks` extension**
  210. using the Python SDK's extension hooks (`mcp>=2.3.0`). It does not implement the
  211. older experimental 2025-11-25 `tasks/result` / `tasks/list` protocol.
  212. See the [Tasks specification](https://tasks.extensions.modelcontextprotocol.io/specification/2026-07-28/tasks)
  213. and [Python SDK extension API](https://py.sdk.modelcontextprotocol.io/advanced/extensions/).
  214. All 22 device I/O, remote request and test execution tools use tasks when the client
  215. advertises this extension on the request. Device inventory/search, snapshot diffs,
  216. and operation history remain immediate. Existing clients that do not advertise
  217. Tasks keep the ordinary tool result behavior. Client support must match this
  218. extension; merely supporting the older experimental Tasks API is insufficient.
  219. The initial `tools/call` request includes this metadata (alongside `name` and `arguments`):
  220. ```json
  221. {
  222. "_meta": {
  223. "io.modelcontextprotocol/protocolVersion": "2026-07-28",
  224. "io.modelcontextprotocol/clientCapabilities": {
  225. "extensions": {"io.modelcontextprotocol/tasks": {}}
  226. }
  227. }
  228. }
  229. ```
  230. The response has `resultType: "task"`, `taskId`, `status: "working"`, timestamps,
  231. and `pollIntervalMs`. Poll `tasks/get` with `{"taskId": "..."}` and the same metadata.
  232. Its response has `resultType: "complete"`; inspect **status** to determine whether
  233. the work has finished. A completed task contains the original MCP tool response in
  234. `result`. A protocol failure uses `status: "failed"` and `error`; a tool error still
  235. uses `status: "completed"` and preserves the tool's error payload. HTTP requests use
  236. `Mcp-Method` and `Mcp-Name` headers; for task methods `Mcp-Name` is the task ID.
  237. Run the [example polling client](examples/task_client.py):
  238. ```bash
  239. python examples/task_client.py http://localhost:8080/mcp pyats_run_show_command \
  240. '{"device_name":"router-1","command":"show version"}'
  241. ```
  242. `tasks/cancel` acknowledges cancellation intent. Queued work is cancelled before
  243. execution. Once a tool starts, it finishes and retains its result: cancelling an
  244. await cannot safely stop an SSH command, reverse a configuration change, or kill
  245. a test subprocess. `tasks/update` acknowledges and ignores input response keys;
  246. these tools do not request interactive input. Notifications are not implemented;
  247. clients use polling and honor `pollIntervalMs` (1 second).
  248. | Variable | Default | Meaning |
  249. |---|---|---|
  250. | `PYATS_MCP_TASK_DB` | `<artifacts directory>/tasks.sqlite3` | Persistent task/result store |
  251. | `PYATS_MCP_TASK_WORKERS` | `4` | Maximum simultaneous long-running tool calls |
  252. | `PYATS_MCP_TASK_MAX` | `1000` | Maximum retained tasks, including queued/running tasks |
  253. | `PYATS_MCP_TASK_RETENTION` | `86400` | Seconds to retain terminal results |
  254. The worker limit applies to ordinary calls too. Multi-device tools retain their
  255. internal fan-out. Calls targeting the same device are serialized for the full tool
  256. operation, including config snapshots and diffs; independent devices can execute
  257. concurrently. Dynamic Python/Robot tests reserve all testbed devices. Scripts that
  258. connect to devices outside the supplied testbed remain responsible for their own
  259. concurrency. Connection TTL eviction occurs when that device is next used.
  260. Tasks survive HTTP disconnects in both stateful and stateless modes. SQLite commits
  261. the handle before returning it and preserves terminal results across restarts.
  262. Running tasks have `ttlMs: null`; completion sets a TTL measured from creation that
  263. includes the retention period. Expired results are removed on subsequent task
  264. submission. Admission is rejected when the retained-task limit is reached.
  265. On restart, unfinished tasks become failed with an unknown-outcome message; they
  266. are **never automatically replayed**. Inspect device state before retrying changes.
  267. Graceful shutdown cancels queued tasks and drains active operations.
  268. Run **one server process per task database**; a file lock enforces this. For Docker,
  269. mount a persistent directory and point `PYATS_MCP_TASK_DB` into it. Horizontal
  270. replicas require separate stores and routing each task ID back to its owning
  271. replica. This implementation is not a distributed task queue.
  272. The database contains tool results, potentially including configurations, and is
  273. created with owner-only permissions. Authenticated tasks are bound to the verified
  274. client/issuer/subject identity. With this project's default unauthenticated server,
  275. the unguessable task ID acts as a bearer credential; protect it and the database.
  276. ## What To Ask It
  277. Once connected, talk to it like you'd talk to someone who already knows the network:
  278. - *"What devices are in the testbed?"* → `pyats_list_devices`
  279. - *"Show me the BGP summary on CORE1"* → `pyats_run_show_command`, parsed into structured JSON
  280. - *"Snapshot CORE1's OSPF state, then apply this config and show me what changed"* → `pyats_learn_feature` (before) → `pyats_configure_with_diff` → `pyats_learn_feature` (after) → `pyats_diff_learned_snapshots`
  281. - *"Run `show ip interface brief` across every switch"* → `pyats_run_show_command_multi` (or `pyats_pcall_show_command` for process-per-device isolation at real scale)
  282. - *"If that config change breaks anything, roll it back"* → `pyats_rollback_config`
  283. - *"Run this Blitz test against R1 and R2"* / *"Run this Robot Framework suite"* → `pyats_run_blitz` / `pyats_run_robot`
  284. The agent chains these itself — you describe the outcome, it picks the tools.
  285. ---
  286. ## Available Tools
  287. 34 tools, grouped by what they do.
  288. **Discovery**
  289. | Tool | Description |
  290. |------|-------------|
  291. | `pyats_list_devices` | List all devices in the testbed |
  292. | `pyats_search_devices` | Fuzzy-search devices by name or alias |
  293. **Show commands**
  294. | Tool | Description |
  295. |------|-------------|
  296. | `pyats_run_show_command` | Run a validated show command; returns parsed JSON or raw output |
  297. | `pyats_run_show_command_multi` | Run a show command across multiple devices concurrently (thread pool) |
  298. | `pyats_pcall_show_command` | Same, but one OS process per device (`pyats.async_.pcall`) instead of a shared thread pool |
  299. | `pyats_show_running_config` | Retrieve the full running configuration (raw text) |
  300. | `pyats_show_logging` | Retrieve device system logs via `show logging` |
  301. | `pyats_ping_from_network_device` | Execute a ping from a network device |
  302. | `pyats_run_linux_command` | Run a command on a Linux host |
  303. **Configuration**
  304. | Tool | Description |
  305. |------|-------------|
  306. | `pyats_configure_device` | Apply configuration commands with safety guardrails |
  307. | `pyats_configure_devices_multi` | Apply configuration across multiple devices concurrently (thread pool) |
  308. | `pyats_pcall_configure_devices` | Same, but one OS process per device |
  309. | `pyats_configure_with_diff` | Apply config and return a before/after diff |
  310. | `pyats_rollback_config` | Roll back to the last saved configuration snapshot |
  311. **State & diagnostics**
  312. | Tool | Description |
  313. |------|-------------|
  314. | `pyats_device_health` | Snapshot CPU, memory, interfaces, and routing state |
  315. | `pyats_get_neighbors` | Retrieve CDP/LLDP neighbors |
  316. | `pyats_find_interface_by_ip` | Find which interface owns a given IP address |
  317. | `pyats_learn_feature` | Genie `device.learn()` for a whole feature (interface, ospf, bgp, …), optionally saved as a named snapshot |
  318. | `pyats_diff_learned_snapshots` | Diff two snapshots saved by `pyats_learn_feature` |
  319. **Testing & automation**
  320. | Tool | Description |
  321. |------|-------------|
  322. | `pyats_clean_device` | Genie Clean (Kleenex), restricted to non-destructive `connect`+`execute_command` stages; `dry_run=True` by default |
  323. | `pyats_run_blitz` | Run a declarative pyATS Blitz YAML test |
  324. | `pyats_run_robot` | Run a Robot Framework suite using the `pyats.robot`/`genie.libs.robot` keyword libraries |
  325. | `pyats_run_dynamic_test` | Execute a sandboxed pyATS AEtest script |
  326. **APIs**
  327. | Tool | Description |
  328. |------|-------------|
  329. | `pyats_rest_request` | Generic REST/RESTCONF/NX-API call via pyATS's `rest.connector` (a separate connection type from CLI/SSH) |
  330. | `pyats_xpresso_request` | Authenticated call to Cisco XPresso's REST API v2 (test requests, jobs, testbeds, images, …) |
  331. **Dynamic testbeds** — see [Dynamic Testbeds](#dynamic-testbeds)
  332. | Tool | Description |
  333. |------|-------------|
  334. | `pyats_testbed_sources` | Which sources are configured on the server, allow-lists, active testbed |
  335. | `pyats_testbed_source_inventories` | List Itential Inventory Manager inventories with node counts |
  336. | `pyats_testbed_build` | Build an in-memory testbed from Itential, NetBox, Nautobot, Catalyst Center, csv/json/yaml/xml or any REST API |
  337. | `pyats_testbed_validate` | pyATS schema check, credential env check, optional TCP reachability |
  338. | `pyats_testbed_activate` | Switch every other tool to a dynamic testbed (or back to `static`) |
  339. | `pyats_testbed_list` / `pyats_testbed_get` / `pyats_testbed_delete` | Inspect and manage in-memory testbeds |
  340. **Session**
  341. | Tool | Description |
  342. |------|-------------|
  343. | `pyats_get_operation_log` | Retrieve the in-memory operation log |
  344. ---
  345. ## Dynamic Testbeds
  346. Build a testbed **in memory, at runtime, from whatever your source of truth is** — no
  347. `testbed.yaml` round-trip. A testbed is a plain pyATS testbed dict handed straight to
  348. `pyats.topology.loader.load()`; a file is only materialized (mode `0600`) when a
  349. subprocess tool such as `pyats run job` or `pyats clean` needs a path.
  350. ```
  351. pyats_testbed_sources what can I build from, and what is active?
  352. pyats_testbed_source_inventories list Itential Inventory Manager inventories (+ node counts)
  353. pyats_testbed_build fetch -> map -> filter -> build (dry_run / activate / merge_with)
  354. pyats_testbed_validate pyATS schema load + credential env check (+ TCP reachability)
  355. pyats_testbed_activate make every other tool use it ("static" switches back)
  356. pyats_testbed_list / _get / _delete
  357. ```
  358. | `source=` | Reads from | Server config |
  359. |-----------|-----------|---------------|
  360. | `itential_inventory` (default) | Itential Platform **Inventory Manager** (`/inventory_manager/v1`) | `PLATFORM_URL`, `AUTH_METHOD`, `CLIENT_ID`/`CLIENT_SECRET` (oauth) or `PLATFORM_USERNAME`/`PLATFORM_PASSWORD` (local) |
  361. | `netbox` / `nautobot` | `/api/dcim/devices/` | `NETBOX_URL`+`NETBOX_TOKEN` / `NAUTOBOT_URL`+`NAUTOBOT_TOKEN` |
  362. | `catalyst_center` | `/dna/intent/api/v1/network-device` | `CATALYST_CENTER_URL`, `_USERNAME`, `_PASSWORD` |
  363. | `inline` / `file` | csv, json, yaml or xml text / file | file must live under `PYATS_MCP_TESTBED_SOURCE_DIRS` |
  364. | `rest` | any JSON REST API (offset, page or next-URL pagination) | host must be listed in `PYATS_MCP_TESTBED_SOURCE_HOSTS` |
  365. Run more than one Itential Platform (for example a local devstack and a cloud SE
  366. Platform) with named profiles: `ITENTIAL_DEVSTACK_URL`, `ITENTIAL_DEVSTACK_AUTH_METHOD`,
  367. `ITENTIAL_DEVSTACK_CLIENT_ID`, `ITENTIAL_DEVSTACK_CLIENT_SECRET` (or `_USERNAME`/`_PASSWORD`),
  368. then `pyats_testbed_build(..., profile="devstack")`. Set `ITENTIAL_<PROFILE>_VERIFY_TLS=0`
  369. for self-signed lab certificates.
  370. **Mapping.** Presets map each source's records to devices. For anything else pass a
  371. declarative `mapping` — dotted paths (`a.b[0].c`, `tags[*].slug`), templates
  372. (`{site}-{name}`), `literal:` values or `{"path", "map", "regex", "default"}` objects:
  373. ```json
  374. {"name": "build", "source": "inline", "format": "csv",
  375. "data": "host,addr,nos\nr1,10.0.0.1,ios-xe\nr2,10.0.0.2,nx-os\n",
  376. "mapping": {"name": "host", "ip": "addr", "os": "nos"}}
  377. ```
  378. `os` values are normalized to pyATS names (`IOS-XE`→`iosxe`, `NX-OS`→`nxos`, `frr`→`linux`,
  379. ...); use `os_map` for vendor-specific values or `default_os` when the source has no platform
  380. field (several real Itential inventories leave `itential_platform` blank). `filters` and `tags`
  381. narrow large sources, e.g. `tags=["firewall"]` against a 1,340-node inventory.
  382. **Credentials never pass through the model.** Generated devices reference server
  383. environment variables (`%ENV{PYATS_DEVICE_USERNAME}` / `_PASSWORD` / `_ENABLE_PASSWORD` by
  384. default; override with `credentials={"username_env": ..., "password_env": ...}`, or reuse the
  385. static testbed's block with `credentials={"from": "static"}`). Inline secrets are rejected,
  386. source-API tokens come from server env vars, and anything credential-shaped is redacted from
  387. previews. `merge_with="static"` adds the static testbed's devices to a dynamic one.
  388. `pyats_testbed_build` and `pyats_testbed_validate` do network I/O and run as
  389. [Asynchronous MCP Tasks](#asynchronous-mcp-tasks) when the client supports them. Set
  390. `PYATS_MCP_DYNAMIC_ONLY=1` to start the server without any static testbed file.
  391. ---
  392. ## Security
  393. - Show commands are validated — pipes, redirects, and dangerous keywords are blocked.
  394. - Config changes are checked for `reload`, `erase`, `write erase`, `delete`, `format` — the same check runs inside `pyats_clean_device`, `pyats_run_blitz`, and `pyats_run_robot`.
  395. - Dynamic test scripts run in a restricted sandbox (banned imports: `os`, `sys`, `subprocess`, etc.).
  396. - `pyats_clean_device` never runs a real Genie Clean stage that reboots, erases, or reimages a device — only `connect`+`execute_command` are ever generated — and defaults to `dry_run=True`; running for real also requires an exact confirmation phrase.
  397. - Every process-global cache (connection cache, testbed cache, config/learn snapshots, operation log) is protected by a lock, so concurrent HTTP clients can't corrupt shared state.
  398. - All credentials come from `.env` — never stored in the testbed file or source code.
  399. - Dynamic testbeds hold only `%ENV{}` credential references; the generic `rest` source can only call allow-listed hosts, `file` only allow-listed directories, and pagination never follows a `next` link to another host.
  400. ---
  401. ## Project Structure
  402. ```
  403. .
  404. ├── pyats_mcp_server.py # MCP server
  405. ├── pyats_tasks.py # MCP Tasks extension
  406. ├── pyats_testbed_builder.py # Dynamic testbed sources, mapping and registry
  407. ├── test_pyats_mcp_server.py # Unit tests (119 tests)
  408. ├── benchmark/ # Pre/post, stateful/stateless transport benchmark
  409. ├── Dockerfile # Container definition
  410. ├── requirements.txt # Pinned runtime dependencies
  411. ├── requirements-dev.txt # Dev/test dependencies
  412. ├── pyproject.toml # Tool config (black, isort, pytest, mypy)
  413. ├── .env.example # Configuration template — copy to .env
  414. ├── .gitignore
  415. ├── LICENSE
  416. └── CONTRIBUTING.md
  417. ```
  418. ---
  419. ## Development
  420. ```bash
  421. # Install dev dependencies with uv
  422. uv venv .venv && uv pip install -r requirements-dev.txt
  423. # Run tests
  424. .venv/bin/python -m pytest
  425. # Lint and format
  426. .venv/bin/black .
  427. .venv/bin/isort .
  428. .venv/bin/flake8 . --max-line-length=100
  429. ```
  430. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full setup and PR workflow.
  431. ---
  432. ## Benchmark
  433. `benchmark/` compares STDIO (legacy) against Streamable HTTP in both stateful and stateless mode, against a real testbed. See `benchmark/scenarios.py` for the scenario list and `benchmark/aggregate.py` for building the comparison report; `benchmark/results/summary.md` has the most recent run's numbers.
  434. ---
  435. ## License
  436. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.