@aristanetworks/eos-mcp-server 0.6.1-beta

package/docs/QUICKSTART.md

@@ -0,0 +1,152 @@
+# Quickstart: eos-mcp-server with Claude Code
+
+This guide gets you from the npm package to a working MCP server inside Claude Code.
+
+## Prerequisites
+
+- Node.js 24+
+- Claude Code installed (`npm install -g @anthropic-ai/claude-code`)
+- One or more Arista EOS devices reachable via eAPI (HTTPS)
+
+## 1. Install the package globally
+
+```bash
+npm install -g @aristanetworks/eos-mcp-server
+```
+
+Verify it's on your PATH:
+
+```bash
+eos-mcp-server --help
+```
+
+## 2. Create an inventory file
+
+Create `inventory.yml` with your EOS devices. Replace the hostnames, IPs, and credentials to match your environment.
+
+```yaml
+all:
+  children:
+    eos:
+      vars:
+        ansible_user: admin
+        ansible_network_os: eos
+        mcp_password_env: EOS_MCP_PASSWORD
+      hosts:
+        leaf1:
+          ansible_host: 192.0.2.11
+        leaf2:
+          ansible_host: 192.0.2.12
+```
+
+If your devices use self-signed certificates, add `mcp_validate_certs: false` (or `ansible_httpapi_validate_certs: false`) under `vars`:
+
+```yaml
+vars:
+  ansible_user: admin
+  ansible_network_os: eos
+  mcp_password_env: EOS_MCP_PASSWORD
+  mcp_validate_certs: false
+```
+
+## 3. Export the password
+
+The `mcp_password_env` value is an environment variable **name**, not the password itself. Export the actual password:
+
+```bash
+export EOS_MCP_PASSWORD='your-device-password'
+```
+
+## 4. Validate and test
+
+Validate the inventory:
+
+```bash
+eos-mcp-server validate-inventory --inventory inventory.yml
+```
+
+Probe a device to confirm connectivity:
+
+```bash
+eos-mcp-server probe --inventory inventory.yml --target leaf1
+```
+
+You should see:
+
+```text
+Probe target: leaf1
+Devices: 1/1 succeeded
+- leaf1: success
+```
+
+## 5. Add the MCP server to Claude Code
+
+```bash
+claude mcp add eos -- eos-mcp-server serve --inventory /absolute/path/to/inventory.yml
+```
+
+Use absolute paths for the inventory file since Claude Code may launch the server from any working directory.
+
+For additional options such as timeouts, request limits, or a default connection, use a [server config file](../README.md#server-config-file) instead and point `--config` at it.
+
+To make it available across all your projects, add `-s user`:
+
+```bash
+claude mcp add -s user eos -- eos-mcp-server serve --inventory /absolute/path/to/inventory.yml
+```
+
+### Passing the password to Claude Code
+
+The simplest approach is to export `EOS_MCP_PASSWORD` in your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) so it's available whenever Claude Code starts the server.
+
+Alternatively, add it inline when registering the server:
+
+```bash
+claude mcp add -e EOS_MCP_PASSWORD=your-device-password eos -- eos-mcp-server serve --inventory /absolute/path/to/inventory.yml
+```
+
+## 6. Verify in Claude Code
+
+Start Claude Code and ask it to use the server:
+
+```
+> List my EOS inventory
+```
+
+```
+> Probe leaf1
+```
+
+```
+> Show me the version on leaf1
+```
+
+Claude will call the `eos_list_inventory`, `eos_probe_devices`, and `eos_run_show` tools automatically.
+
+## Available MCP tools
+
+Once connected, Claude Code has access to these tools:
+
+| Tool                     | Description                              |
+| ------------------------ | ---------------------------------------- |
+| `eos_get_server_info`    | Server runtime summary and capabilities  |
+| `eos_list_inventory`     | List inventory hosts and groups          |
+| `eos_probe_devices`      | Check device reachability                |
+| `eos_run_show`           | Run `show` commands on devices           |
+| `eos_show_logging`       | Retrieve bounded logging output          |
+| `eos_get_facts`          | Collect device facts from `show version` |
+| `eos_get_running_config` | Retrieve running configuration           |
+
+## Troubleshooting
+
+**`npm install -g` fails with permission errors** — Run with `sudo` or configure npm to use a user-writable prefix (`npm config set prefix ~/.npm-global`).
+
+**`Password env var ... is not set`** — Export `EOS_MCP_PASSWORD` before launching Claude Code, or pass it via `-e` when adding the server.
+
+**`Password env var ... does not match any allowed prefix`** — The env var name must start with `EOS_MCP_` by default. Use a name like `EOS_MCP_PASSWORD`, not the password itself.
+
+**Certificate validation failure** — For a lab device, add `mcp_validate_certs: false` (or `ansible_httpapi_validate_certs: false`) to your inventory vars. To trust a real CA instead, set `caFile` in a [server config file](../README.md#server-config-file). See [TLS behavior](../README.md#tls-behavior) for details.
+
+**`Unknown inventory target ...`** — Targets must be inventory host or group names (e.g., `leaf1`), not IP addresses.
+
+See the full [README](../README.md) for detailed configuration options.

package/example-inventories/canonical-fabric.yaml

@@ -0,0 +1,45 @@
+# Canonical Ansible-style inventory for eos-mcp-server.
+#
+# The addresses below use RFC 5737 TEST-NET space and are placeholders.
+# Replace hostnames, addresses, and certificate policy for your environment.
+all:
+  children:
+    FABRIC:
+      vars:
+        ansible_user: admin
+        ansible_network_os: eos
+        mcp_password_env: EOS_MCP_PASSWORD
+        # Useful for labs with self-signed eAPI certificates. Prefer a CA bundle
+        # and certificate validation in production.
+        mcp_validate_certs: false
+      children:
+        SPINES:
+          hosts:
+            spine1:
+              ansible_host: 192.0.2.11
+            spine2:
+              ansible_host: 192.0.2.12
+        LEAFS:
+          children:
+            LEAF_PAIR_1:
+              hosts:
+                leaf1:
+                  ansible_host: 192.0.2.21
+                leaf2:
+                  ansible_host: 192.0.2.22
+            LEAF_PAIR_2:
+              hosts:
+                leaf3:
+                  ansible_host: 192.0.2.23
+                leaf4:
+                  ansible_host: 192.0.2.24
+
+    # These groups intentionally reuse canonical groups defined above. The server
+    # merges repeated group definitions and treats the inventory as authoritative.
+    NETWORK_SERVICES:
+      children:
+        LEAFS:
+
+    CONNECTED_ENDPOINTS:
+      children:
+        LEAFS:

package/example-inventories/multi-password.yaml

@@ -0,0 +1,35 @@
+# Canonical inventory with a different password for every device.
+#
+# Keep passwords out of the inventory. Each mcp_password_env value is the name
+# of an environment variable that must be set before starting the server.
+# The variable names use the default allowed EOS_MCP_ prefix.
+all:
+  children:
+    FABRIC:
+      vars:
+        ansible_user: admin
+        ansible_network_os: eos
+        mcp_validate_certs: false
+      hosts:
+        spine1:
+          ansible_host: 192.0.2.11
+          mcp_password_env: EOS_MCP_SPINE1_PASSWORD
+        spine2:
+          ansible_host: 192.0.2.12
+          mcp_password_env: EOS_MCP_SPINE2_PASSWORD
+        leaf1:
+          ansible_host: 192.0.2.21
+          mcp_password_env: EOS_MCP_LEAF1_PASSWORD
+        leaf2:
+          ansible_host: 192.0.2.22
+          mcp_password_env: EOS_MCP_LEAF2_PASSWORD
+
+      children:
+        SPINES:
+          hosts:
+            spine1:
+            spine2:
+        LEAFS:
+          hosts:
+            leaf1:
+            leaf2:

package/example-inventories/simplified-lab.yaml

@@ -0,0 +1,33 @@
+# Simplified inventory format for eos-mcp-server.
+#
+# The addresses below use RFC 5737 TEST-NET space and are placeholders.
+version: 1
+
+vars:
+  ansible_user: admin
+  mcp_password_env: EOS_MCP_PASSWORD
+  # Useful for labs with self-signed eAPI certificates. Prefer a CA bundle
+  # and certificate validation in production.
+  mcp_validate_certs: false
+
+hosts:
+  leaf1:
+    ansible_host: 198.51.100.11
+    ansible_network_os: eos
+  leaf2:
+    ansible_host: 198.51.100.12
+    ansible_network_os: eos
+  spine1:
+    ansible_host: 198.51.100.21
+    ansible_network_os: eos
+  spine2:
+    ansible_host: 198.51.100.22
+    ansible_network_os: eos
+
+groups:
+  leafs:
+    hosts: [leaf1, leaf2]
+  spines:
+    hosts: [spine1, spine2]
+  fabric:
+    children: [spines, leafs]

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@aristanetworks/eos-mcp-server",
+  "version": "0.6.1-beta",
+  "description": "MCP server for Arista EOS eAPI",
+  "license": "Apache-2.0",
+  "type": "module",
+  "homepage": "https://github.com/aristanetworks/eos-mcp-server#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aristanetworks/eos-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/aristanetworks/eos-mcp-server/issues"
+  },
+  "keywords": [
+    "arista",
+    "eos",
+    "mcp",
+    "model-context-protocol",
+    "network-automation"
+  ],
+  "bin": {
+    "eos-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    "example-inventories",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "lint": "node scripts/static-policy.mjs",
+    "prepack": "npm run build",
+    "static-policy": "node scripts/static-policy.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "yaml": "^2.8.0",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^4.1.8"
+  }
+}