@aristanetworks/eos-mcp-server 0.6.1-beta

package/dist/show/runShow.d.ts

@@ -0,0 +1,29 @@
+import type { ResolvedServerConfig } from "../config/schema.js";
+import type { EosCommandResult } from "../eapi/types.js";
+import type { EosDeviceReader } from "../connection/eosDeviceReader.js";
+import type { InventoryModel } from "../inventory/types.js";
+import { type DeviceResultSummary } from "../operations/readExecution.js";
+export interface RunShowOptions {
+    target: string;
+    commands: string[];
+    outputFormat: "auto" | "json" | "text";
+    includeRaw?: boolean;
+}
+export type NormalizedCommandResult = EosCommandResult;
+export interface RunShowResult {
+    target: string;
+    target_type: "host" | "group";
+    requested_output_format: "auto" | "json" | "text";
+    resolved_devices: string[];
+    summary: DeviceResultSummary;
+    results: Array<{
+        inventory_hostname: string;
+        resolved_endpoint: string;
+        status: "success" | "failed";
+        actual_output_format?: "json" | "text";
+        command_results?: NormalizedCommandResult[];
+        error_code?: string;
+        message?: string;
+    }>;
+}
+export declare function runShow(model: InventoryModel, config: ResolvedServerConfig, options: RunShowOptions, reader: EosDeviceReader): Promise<RunShowResult>;

package/dist/show/runShow.js

@@ -0,0 +1,40 @@
+import { AppError } from "../core/errors.js";
+import { normalizeShowCommand } from "../eapi/commands.js";
+import { buildReadDeviceFailure, buildReadDeviceSuccess, buildReadOperationResultEnvelope, enforceShowCommandLimit, executeReadOperation } from "../operations/readExecution.js";
+export async function runShow(model, config, options, reader) {
+    const commands = normalizeShowCommands(options.commands);
+    enforceShowCommandLimit(config, commands.length);
+    const operation = await executeReadOperation(model, config, {
+        target: options.target,
+        operationName: "eos_run_show",
+        run: async (host, signal) => {
+            const commandResults = await reader.runShowCommands(host, commands, options.outputFormat, {
+                signal,
+                includeRawEntries: options.includeRaw === true
+            });
+            const firstResult = commandResults[0];
+            return buildReadDeviceSuccess(host, {
+                actual_output_format: firstResult?.output_format ?? "json",
+                command_results: commandResults
+            });
+        },
+        onError: (host, error) => buildReadDeviceFailure(host, "show_command_failed", error)
+    });
+    return buildReadOperationResultEnvelope(options.target, operation, {
+        extra: {
+            requested_output_format: options.outputFormat
+        },
+        responseSizeLimit: {
+            config,
+            operationName: "eos_run_show",
+            narrowingGuidance: "Reduce the number of target devices, use fewer commands per request, or request text format for more concise output."
+        }
+    });
+}
+function normalizeShowCommands(commands) {
+    if (commands.length === 0) {
+        throw new AppError("show_commands_missing", "runShow requires at least one command");
+    }
+    return commands.map((command) => normalizeShowCommand(command));
+}
+//# sourceMappingURL=runShow.js.map

package/dist/show/runShow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runShow.js","sourceRoot":"","sources":["../../src/show/runShow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAE7C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAI3D,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,gCAAgC,EAChC,uBAAuB,EACvB,oBAAoB,EAErB,MAAM,gCAAgC,CAAC;AA4BxC,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,KAAqB,EACrB,MAA4B,EAC5B,OAAuB,EACvB,MAAuB;IAEvB,MAAM,QAAQ,GAAG,qBAAqB,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzD,uBAAuB,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAEjD,MAAM,SAAS,GAAG,MAAM,oBAAoB,CAAmC,KAAK,EAAE,MAAM,EAAE;QAC5F,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,aAAa,EAAE,cAAc;QAC7B,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE;YAC1B,MAAM,cAAc,GAAG,MAAM,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,YAAY,EAAE;gBACxF,MAAM;gBACN,iBAAiB,EAAE,OAAO,CAAC,UAAU,KAAK,IAAI;aAC/C,CAAC,CAAC;YACH,MAAM,WAAW,GAAG,cAAc,CAAC,CAAC,CAAC,CAAC;YAEtC,OAAO,sBAAsB,CAAC,IAAI,EAAE;gBAClC,oBAAoB,EAAE,WAAW,EAAE,aAAa,IAAI,MAAM;gBAC1D,eAAe,EAAE,cAAc;aAChC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,EAAE,qBAAqB,EAAE,KAAK,CAAC;KACrF,CAAC,CAAC;IAEH,OAAO,gCAAgC,CAAC,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE;QACjE,KAAK,EAAE;YACL,uBAAuB,EAAE,OAAO,CAAC,YAAY;SAC9C;QACD,iBAAiB,EAAE;YACjB,MAAM;YACN,aAAa,EAAE,cAAc;YAC7B,iBAAiB,EAAE,sHAAsH;SAC1I;KACF,CAAC,CAAC;AACL,CAAC;AAED,SAAS,qBAAqB,CAAC,QAAkB;IAC/C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,QAAQ,CAAC,uBAAuB,EAAE,uCAAuC,CAAC,CAAC;IACvF,CAAC;IAED,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;AAClE,CAAC"}

package/dist/utils/json.d.ts

@@ -0,0 +1 @@
+export declare function prettyJson(value: unknown): string;

package/dist/utils/json.js

@@ -0,0 +1,4 @@
+export function prettyJson(value) {
+    return JSON.stringify(value, null, 2);
+}
+//# sourceMappingURL=json.js.map

package/dist/utils/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/utils/json.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/utils/path.d.ts

@@ -0,0 +1,2 @@
+export declare function resolvePathFromConfig(configPath: string, value: string): string;
+export declare function resolvePathFromCwd(value: string): string;

package/dist/utils/path.js

@@ -0,0 +1,14 @@
+import path from "node:path";
+export function resolvePathFromConfig(configPath, value) {
+    if (path.isAbsolute(value)) {
+        return value;
+    }
+    return path.resolve(path.dirname(configPath), value);
+}
+export function resolvePathFromCwd(value) {
+    if (path.isAbsolute(value)) {
+        return value;
+    }
+    return path.resolve(process.cwd(), value);
+}
+//# sourceMappingURL=path.js.map

package/dist/utils/path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"path.js","sourceRoot":"","sources":["../../src/utils/path.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,UAAU,qBAAqB,CAAC,UAAkB,EAAE,KAAa;IACrE,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAa;IAC9C,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;AAC5C,CAAC"}

package/dist/utils/value.d.ts

@@ -0,0 +1,6 @@
+export declare function readString(value: unknown): string | undefined;
+export declare function readNonEmptyString(value: unknown): string | undefined;
+export declare function readBoolean(value: unknown): boolean | undefined;
+export declare function readNumber(value: unknown): number | undefined;
+export declare function readPositiveInteger(value: unknown): number | undefined;
+export declare function isObject(value: unknown): value is Record<string, unknown>;

package/dist/utils/value.js

@@ -0,0 +1,28 @@
+export function readString(value) {
+    return typeof value === "string" ? value : undefined;
+}
+export function readNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function readBoolean(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
+export function readNumber(value) {
+    return typeof value === "number" ? value : undefined;
+}
+export function readPositiveInteger(value) {
+    if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    if (typeof value === "string" && value.length > 0) {
+        const parsed = Number(value);
+        if (Number.isInteger(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return undefined;
+}
+export function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=value.js.map

package/dist/utils/value.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"value.js","sourceRoot":"","sources":["../../src/utils/value.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,KAAc;IACxC,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAc;IACvC,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACvD,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QACtE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7B,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3C,OAAO,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/docs/CHECKPOINT.md

@@ -0,0 +1,46 @@
+# EOS MCP Server Checkpoint
+
+## Current state
+
+The server is a test-backed, read-only MCP service for Arista EOS eAPI. The product boundary is permanent: configuration-changing operations are outside the implementation and specification.
+
+## Implemented surface
+
+### MCP tools
+
+- `eos_get_server_info`
+- `eos_list_inventory`
+- `eos_probe_devices`
+- `eos_run_show`
+- `eos_show_logging`
+- `eos_get_facts`
+- `eos_get_running_config`
+
+### Local commands
+
+- `serve`
+- `validate-inventory`
+- `print-server-info`
+- `probe`
+
+## Safety and operational controls
+
+- Inventory-only host and group targeting.
+- Explicit EOS eligibility and inherited read-policy enforcement.
+- Fail-closed groups containing ineligible or read-denied hosts.
+- Strict password-source and environment-prefix checks.
+- HTTPS with certificate validation by default and optional custom CA support.
+- Validated show commands and bounded logging/running-configuration queries.
+- Read-operation concurrency, target, response-size, and timeout controls.
+- Sanitized result envelopes with stable machine-readable errors.
+
+## Re-entry reading
+
+1. [`README.md`](../README.md) for operator usage.
+2. [`docs/DESIGN.md`](DESIGN.md) for the authoritative specification.
+3. [`docs/CODE_WALKTHROUGH.md`](CODE_WALKTHROUGH.md) for source navigation.
+4. [`src/operations/readExecution.ts`](../src/operations/readExecution.ts) for shared device operation controls.
+
+## Validation
+
+Run `npm test`, `npm run typecheck`, and `npm run build` after changes. Optional integration tests require the configured cEOS environment.

package/docs/CODE_WALKTHROUGH.md

@@ -0,0 +1,112 @@
+# Code Walkthrough
+
+## Top Level
+
+This repository is a single TypeScript/Node package.
+
+- `src/` contains all source code.
+- `test/` contains Vitest tests.
+- `dist/` is generated build output from `tsc`.
+- `docs/` contains project documentation (design, checkpoint, implementation plan, etc.).
+- `Makefile` wraps build, lint/static policy checks, test, typecheck, clean, and packaging.
+- `package.json` defines scripts: `npm test`, `npm run typecheck`, `npm run lint`, and `npm run build`. The package `prepack` hook runs `npm run build`.
+- `scripts/static-policy.mjs` performs lightweight source policy checks for banned patterns such as plain `throw new Error`, `@ts-ignore`, `eslint-disable`, and `as any`.
+
+## Runtime Entry
+
+Execution starts at `src/index.ts`. It parses CLI args, loads config, then dispatches one of four commands:
+
+- `serve`: load inventory, validate startup credentials, start MCP stdio server.
+- `validate-inventory`: validate inventory and print the result.
+- `print-server-info`: print sanitized server metadata.
+- `probe`: run the same probe logic as the MCP probe tool.
+
+CLI parsing lives in `src/cli.ts`. The app name and version are read from `package.json` at runtime via `src/core/version.ts`. Shared error handling lives in `src/core/errors.ts`, which defines `AppError` and the stable machine-readable error codes used across the CLI and MCP layers.
+
+## Config And Inventory
+
+Config loading is in `src/config/loadConfig.ts`, with Zod schemas in `src/config/schema.ts`. It merges optional config-file values with CLI overrides and resolves paths.
+
+`src/inventory/loadInventory.ts` orchestrates inventory loading. It supports simplified YAML and canonical Ansible-style YAML by delegating to a pipeline: parsing (`src/inventory/parse.ts`), schema detection and normalization (`src/inventory/normalize.ts`), structural and variable-type validation (`src/inventory/validateNormalized.ts`, `src/inventory/varValidation.ts`), and model construction (`src/inventory/buildModel.ts`). Together these validate structure, build effective host vars, resolve groups, and produce an `InventoryModel`.
+
+Supporting inventory modules:
+
+- `src/inventory/types.ts`: public inventory model types.
+- `src/inventory/internalTypes.ts` / `src/inventory/internalUtils.ts`: shared types and helpers used across the parsing/normalization/validation pipeline.
+- `src/inventory/effectiveVars.ts`: global/group/host variable inheritance and same-depth conflict handling.
+- `src/inventory/graph.ts`: group parent maps, group depths, host lineage, direct memberships, and resolved group hosts.
+- `src/inventory/policy.ts`: EOS eligibility and read access evaluation, including the `mcp_read_allowed` fail-closed check.
+- `src/inventory/resolveTarget.ts`: host/group target resolution and policy fail-closed checks.
+- `src/inventory/listInventoryView.ts`: sanitized inventory view for MCP output.
+
+## Connection And eAPI
+
+Connection resolution is in `src/connection/resolveConnection.ts`. It turns effective host vars plus server config into an eAPI connection: endpoint, username, password, TLS flags, CA file, timeout, eAPI output version, and response-size limit.
+
+`src/connection/eosDeviceReader.ts` defines the host-oriented `EosDeviceReader` interface. Its `EapiDeviceReader` adapter owns per-host connection resolution and delegates command execution to the low-level eAPI runner.
+
+Startup credential validation is in `src/connection/validateStartupConnections.ts`.
+
+eAPI protocol and transport are split:
+
+- `src/eapi/client.ts`: builds JSON-RPC `runCmds` requests using the connection's `eapiVersion` (`"latest"` by default, `1` when pinned in config), handles HTTP errors, invalid JSON, JSON-RPC errors, and unexpected result counts. Supports opt-in enable mode (`{ enable: true }`) for privileged commands by prepending `enable` to the wire commands and stripping the extra result entry transparently. Per-request timeout and caller cancellation are combined with `AbortSignal`.
+- `src/eapi/transport.ts`: production HTTPS transport and test-friendly fetch transport. The production transport enforces `maxResponseSizeBytes` while chunks are received, before buffering an oversized device response.
+- `src/eapi/types.ts`: shared eAPI types, the low-level `EosCommandRunner` interface used by `EapiDeviceReader`, `EapiCommandOptions`, and helpers for validating/drilling into eAPI JSON-RPC response payloads.
+
+## Read Tool Services
+
+The core read behavior is implemented as service modules:
+
+- `src/probe/probeDevices.ts`: runs `show version` to verify readiness.
+- `src/eapi/commands.ts`: normalizes single-line EOS command inputs, rejects risky CLI modifiers/metacharacters, and validates `show` command boundaries.
+- `src/show/runShow.ts`: validates strict `show` commands and runs them with `auto`, `json`, or `text` behavior.
+- `src/logging/loggingQuery.ts`: validates Log Severity and message-count inputs, applies logging defaults/limits, and builds the EOS logging command.
+- `src/logging/showLogging.ts`: executes the bounded Logging Query and returns unparsed log text.
+- `src/facts/getFacts.ts`: collects fixed facts from `show version`.
+- `src/configuration/getRunningConfig.ts`: returns running config text, requiring `section` for group targets. Uses enable mode since `show running-config` requires privileged access.
+
+All device-facing read services accept an `EosDeviceReader` (defined in `src/connection/eosDeviceReader.ts`). They provide inventory hosts and command intent; the eAPI adapter resolves each host's connection before executing commands.
+
+Shared read orchestration lives in `src/operations/readExecution.ts`. It centralizes target resolution, target limits, concurrency, overall timeout cancellation, common per-device result fields, result summaries (including the shared `DeviceResultSummary` type used by all result interfaces), final result-envelope response-size enforcement, and per-device `AppError.code` preservation.
+
+Shared type-narrowing utilities (`isObject`, `readString`, `readBoolean`, `readNumber`, etc.) live in `src/utils/value.ts`.
+
+## MCP Layer
+
+The MCP server is assembled in `src/mcp/createServer.ts`. It creates the official SDK `McpServer`, registers seven read-only tools, and connects over stdio.
+
+Tool adapters live under `src/mcp/tools/`:
+
+- `getServerInfo.ts`
+- `listInventory.ts`
+- `probeDevices.ts`
+- `runShow.ts`
+- `showLogging.ts`
+- `getFacts.ts`
+- `getRunningConfig.ts`
+
+These adapters define Zod input schemas, call the service layer, and return both text JSON and structured MCP content.
+
+## Server Info And Commands
+
+Server metadata is built by `src/serverInfo/buildServerInfo.ts`, with types in `src/serverInfo/types.ts`.
+
+Local CLI commands live in `src/commands/`:
+
+- `validateInventory.ts`
+- `printServerInfo.ts`
+- `probe.ts`
+
+## Tests
+
+Tests mirror the source layout:
+
+- CLI and config: `cli.test.ts`, `loadConfig.test.ts`, `validateInventoryCommand.test.ts`
+- Inventory and target behavior: `inventory.test.ts`, `targetResolution.test.ts`
+- eAPI and connection behavior: `eapiClient.test.ts`, `eosDeviceReader.test.ts`, `startupValidation.test.ts`, `responseSize.test.ts`
+- Read services and orchestration: `probeDevices.test.ts`, `runShow.test.ts`, `loggingQuery.test.ts`, `showLogging.test.ts`, `getFacts.test.ts`, `getRunningConfig.test.ts`, `readExecution.test.ts`
+- Server info and errors: `buildServerInfo.test.ts`, `errors.test.ts`, `errorTaxonomy.test.ts`
+- MCP adapters and stdio: `readToolsMcp.test.ts`, `probeDevicesTool.test.ts`, `listInventoryTool.test.ts`, `mcpStdioSmoke.test.ts`
+- Package/static policy: `packagePolicy.test.ts`, `packageSmoke.test.ts`
+- Optional cEOS integration (requires a configured lab): `integration.test.ts`
+- Shared test helpers: `test/helpers.ts`

package/docs/DESIGN.md

@@ -0,0 +1,56 @@
+# EOS MCP Server Design Specification
+
+## Scope
+
+EOS MCP Server is an ESM TypeScript MCP server that provides inventory-scoped, read-only access to Arista EOS devices over eAPI (HTTPS). It runs over stdio MCP transport and is permanently read-only: the implementation exposes operational inspection and diagnostics only, and never exposes configuration-changing operations.
+
+## Tool surface
+
+| Tool | Purpose |
+| --- | --- |
+| `eos_get_server_info` | Sanitized runtime, limits, and inventory summary |
+| `eos_list_inventory` | Eligible hosts and groups |
+| `eos_probe_devices` | Connectivity, authentication, and harmless command check |
+| `eos_run_show` | Validated single-line `show` commands |
+| `eos_show_logging` | Bounded logging retrieval |
+| `eos_get_facts` | Fixed device facts |
+| `eos_get_running_config` | Running configuration retrieval, with a required section selector for groups |
+
+Local CLI commands provide inventory validation, server-info output, and probing.
+
+## Target boundary
+
+- A target is exactly one inventory host or group name.
+- Address, hostname, pattern, and ad-hoc targets are rejected.
+- Host and group names use `^[A-Za-z0-9_.-]+$` and cannot collide.
+- Group hosts are deduplicated and ordered alphabetically.
+- Canonical inventories merge repeated group declarations with host/child union and later-wins variables.
+
+## Inventory and policy
+
+Canonical Ansible-style YAML and simplified YAML are supported. Structural keys are strict; arbitrary variables remain permitted. EOS eligibility requires `ansible_network_os: eos` or `mcp_platform: arista_eos`; conflicting declarations fail validation.
+
+`mcp_read_allowed` defaults to `true` for eligible EOS hosts and follows inherited inventory variable precedence. Operational requests fail closed when any resolved host is ineligible or read-denied — a mixed or ineligible target fails as a whole, and devices are never silently skipped. The inventory is the only policy source.
+
+## Connection security
+
+- HTTPS is required.
+- Certificate validation defaults to enabled; inventory may set an explicit lab override and server config may provide a CA bundle.
+- A host resolves exactly one password source: `mcp_password_env` or `ansible_password`. The environment reference is preferred and must match a configured prefix (`EOS_MCP_` by default).
+- Startup validation verifies connection data for all eligible hosts.
+
+## Command safety
+
+`eos_run_show` accepts only trimmed, single-line commands beginning with `show`. It rejects control characters, shell metacharacters, and CLI output modifiers. `eos_get_running_config.section` uses the same single-line restrictions. Enable mode is used only as needed to retrieve running configuration.
+
+## Runtime controls
+
+Read requests have configured per-device timeout, optional overall timeout, device concurrency, target-count, command-count, logging-message, and response-size limits. The overall timeout aborts in-flight requests and halts further scheduling. Device HTTP responses and final serialized tool results are size-limited.
+
+## Result and error model
+
+Device-facing tools return target metadata, resolved devices, summary counts, and per-device results. Request-level failures and known device failures use `AppError` machine-readable codes. Supported diagnostic tools expose raw eAPI payloads only through an explicit `include_raw` option.
+
+## Compatibility and validation
+
+The read surface is validated against cEOS 4.34.3M. EOS 4.20 is the documented minimum for supported read operations. Changes must preserve strict TypeScript checks and pass the unit, stdio smoke, and package-policy test suites.

package/docs/DEVELOPMENT.md

@@ -0,0 +1,72 @@
+# Developer workflow
+
+This guide is for contributors and for users who need to build `eos-mcp-server` from a source checkout. For a normal installation, download a package from the [latest GitHub release](https://github.com/aristanetworks/eos-mcp-server/releases/latest) and follow the [README](../README.md).
+
+## Requirements
+
+- Node.js 24+
+- npm
+
+## Build from source
+
+From the repository root:
+
+```bash
+npm install
+make build
+```
+
+Run the built CLI directly:
+
+```bash
+node dist/index.js serve --inventory path/to/inventory.yml
+```
+
+For development without compiling first:
+
+```bash
+npm run dev -- serve --inventory path/to/inventory.yml
+```
+
+## Make a local installation
+
+To expose the command from a checkout:
+
+```bash
+npm install
+make build
+npm link
+```
+
+Or install the checkout directly:
+
+```bash
+npm install -g /absolute/path/to/eos-mcp-server
+```
+
+Remove a linked installation later with:
+
+```bash
+npm unlink -g @aristanetworks/eos-mcp-server
+```
+
+## Package a release artifact
+
+```bash
+make pack
+```
+
+This performs a clean build and produces `aristanetworks-eos-mcp-server-<version>.tgz`, which can be installed with `npm install -g ./aristanetworks-eos-mcp-server-<version>.tgz`. `npm pack` also rebuilds through the `prepack` hook.
+
+## Publish to npm
+
+The package is published as `@aristanetworks/eos-mcp-server`. Pushing a `v*` tag runs `.github/workflows/release.yml`, which tests, packs, publishes to npm through [trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC, no token secret), and creates the GitHub release. Tags containing `-alpha`, `-beta`, or `-rc` publish under the `next` dist-tag; other tags publish as `latest`. Published versions carry npm provenance attestations.
+
+## Verify changes
+
+```bash
+make test
+make typecheck
+```
+
+The repository's [AGENTS.md](../AGENTS.md) lists all common commands and architectural guidance.

package/docs/EXAMPLES.md

@@ -0,0 +1,178 @@
+# EOS MCP Server — Example Prompts
+
+These examples show how to interact with the EOS MCP server through Claude. All examples are drawn from a real cEOSLab testlab session.
+
+This assumes `eos-mcp-server` is already installed and you have an inventory file — see [Install and get started](../README.md#install-and-get-started) or the [Quickstart](QUICKSTART.md) if not.
+
+---
+
+## Setup
+
+### Add the MCP server from `.mcp.json`
+
+As an alternative to `claude mcp add` (see the README's [Connect to an MCP client](../README.md#connect-to-an-mcp-client)), place a `.mcp.json` file in your project directory — Claude Code auto-discovers it without any import command:
+
+```json
+{
+  "mcpServers": {
+    "eos": {
+      "command": "eos-mcp-server",
+      "args": [
+        "serve",
+        "--inventory",
+        "./ansible-inventory.yml"
+      ],
+      "env": {
+        "EOS_MCP_PASSWORD": "replace-with-device-password"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Inventory
+
+### List all devices and groups
+
+> What devices are in the inventory?
+
+> List the inventory
+
+### Check connectivity to all devices
+
+> Probe all the EOS devices in inventory
+
+Example output: 8/8 devices reachable, showing hostname, endpoint IP, and EOS version.
+
+---
+
+## Device Facts
+
+### Collect facts across the entire fabric
+
+> Get facts for all the EOS devices
+
+Returns model, EOS version, serial number, uptime, and system MAC for every host.
+
+---
+
+## Topology
+
+### Generate a topology diagram from LLDP
+
+> Create a topology diagram for all the devices using LLDP neighbors
+
+Claude queries `show lldp neighbors` across all devices, infers the topology, and renders a Mermaid diagram. Example output for a 2-tier spine-leaf lab:
+
+```mermaid
+graph TB
+    subgraph tier1["Tier 1 — Spine"]
+        node1-1["node1-1\n172.20.20.2"]
+        node1-2["node1-2\n172.20.20.6"]
+    end
+
+    subgraph tier2["Tier 2 — Leaf"]
+        node2-1["node2-1\n172.20.20.4"]
+        node2-2["node2-2\n172.20.20.5"]
+        node2-3["node2-3\n172.20.20.9"]
+        node2-4["node2-4\n172.20.20.7"]
+        node2-5["node2-5\n172.20.20.3"]
+        node2-6["node2-6\n172.20.20.8"]
+    end
+
+    node1-1 -- "Et1 ↔ Et1" --- node2-1
+    node1-1 -- "Et2 ↔ Et1" --- node2-2
+    node1-1 -- "Et3 ↔ Et1" --- node2-3
+    node1-1 -- "Et4 ↔ Et1" --- node2-4
+    node1-1 -- "Et5 ↔ Et1" --- node2-5
+    node1-1 -- "Et6 ↔ Et1" --- node2-6
+
+    node1-2 -- "Et1 ↔ Et2" --- node2-1
+    node1-2 -- "Et2 ↔ Et2" --- node2-2
+    node1-2 -- "Et3 ↔ Et2" --- node2-3
+    node1-2 -- "Et4 ↔ Et2" --- node2-4
+    node1-2 -- "Et5 ↔ Et2" --- node2-5
+    node1-2 -- "Et6 ↔ Et2" --- node2-6
+```
+
+---
+
+## VXLAN
+
+### Check VXLAN status across all leaf switches
+
+> Check on the VXLAN status for all the leaf switches
+
+Claude runs `show vxlan vtep`, `show vxlan vni`, and `show interfaces Vxlan1` and summarizes:
+
+- VTEP source IP and interface per leaf
+- VNI-to-VLAN mappings
+- Replication mode (headend VCS vs multicast)
+- Flood list membership
+- Interface line protocol status
+
+### Example findings
+
+```
+node2-1  VTEP 192.168.2.3  Loopback1  VNI 1100 → VLAN 100  up
+node2-2  VTEP 192.168.2.4  Loopback1  VNI 1100 → VLAN 100  up
+node2-3  VTEP 192.168.2.5  Loopback1  VNI 1100 → VLAN 100  up
+node2-4  VTEP 192.168.2.6  Loopback1  VNI 1100 → VLAN 100  up
+node2-5  VTEP 192.168.2.7  Loopback1  VNI 1100 → VLAN 100  up
+node2-6  VTEP 192.168.2.8  Loopback1  VNI 1100 → VLAN 100  up
+```
+
+---
+
+## BGP EVPN
+
+### Check EVPN session and route state
+
+> Check on EVPN
+
+Claude runs `show bgp evpn summary` and `show bgp evpn` across all leaves and summarizes:
+
+- Session state per peer (Established / Idle / etc.)
+- Prefixes received and advertised per peer
+- EVPN route types present (Type-2 MAC/IP, Type-3 IMET, etc.)
+- ECMP path count per remote VTEP
+- AS path to identify route reflectors and leaf ASNs
+
+### Example findings
+
+All 6 leaves peered to both spines (AS 65000), each leaf with a unique ASN (65001–65006). Only Type-3 IMET routes present — flood list built from EVPN, dual-path ECMP via both spines confirmed.
+
+---
+
+## VLANs
+
+### Inspect a specific VLAN across all leaves
+
+> What can you tell me about VLAN 100?
+
+Claude runs `show vlan 100`, `show mac address-table vlan 100`, and `show interfaces Vlan100` across all leaves and reports:
+
+- VLAN name and status on each leaf
+- Which ports are members (access ports, trunk ports, VXLAN tunnel)
+- MAC address table entries (learned hosts)
+- Whether an SVI exists and its IP/state
+
+### Example findings
+
+VLAN 100 (`VLAN100`) active on all leaves, member of `Vx1` only, empty MAC table, no SVI — fully provisioned L2 overlay segment with no hosts connected yet.
+
+---
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `eos_probe_devices` | Validate connectivity, auth, and eAPI reachability |
+| `eos_list_inventory` | Show eligible hosts and groups from the loaded inventory |
+| `eos_get_facts` | Collect model, version, serial, uptime, system MAC |
+| `eos_get_running_config` | Retrieve running config (full for hosts, section for groups) |
+| `eos_run_show` | Run arbitrary `show ...` commands; returns JSON or text |
+| `eos_show_logging` | Retrieve bounded logging output with minimum severity threshold |
+| `eos_get_server_info` | Show server capabilities, runtime mode, inventory summary |

package/docs/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,32 @@
+# EOS MCP Server Implementation Plan
+
+## Product boundary
+
+The server is a permanent read-only MCP service. Scope is limited to inventory inspection, device probing, validated EOS `show` commands, bounded logging, facts, and running-configuration retrieval.
+
+## Implemented work
+
+- TypeScript ESM CLI and stdio MCP server.
+- Canonical Ansible-style and simplified YAML inventories.
+- Strict inventory validation, inherited variables, EOS eligibility, and fail-closed read policy.
+- Inventory-authoritative host/group target resolution.
+- HTTPS eAPI client with TLS validation, custom CA support, credential validation, request cancellation, and response-size limits.
+- Seven MCP tools: server info, inventory, probe, show, logging, facts, and running configuration.
+- Local `validate-inventory`, `print-server-info`, and `probe` commands.
+- Bounded concurrency, target counts, command counts, logging messages, device responses, and aggregate tool responses.
+- Unit, MCP stdio smoke, package-policy, and optional cEOS integration coverage.
+
+## Ongoing priorities
+
+1. Preserve the read-only tool boundary in schemas, CLI, inventory model, and MCP registration.
+2. Maintain strict input validation and stable `AppError` codes.
+3. Expand read-side test coverage when adding supported EOS query behavior.
+4. Keep operator documentation synchronized with the tool and configuration surface.
+5. Validate supported read behavior against maintained EOS/cEOS versions.
+
+## Completion criteria
+
+- Every registered MCP tool is read-only and inventory-scoped.
+- All device-facing paths use the shared target, connection, timeout, and result-envelope safeguards.
+- Documentation lists only supported tools and configuration fields.
+- `npm test`, `npm run typecheck`, and `npm run build` pass.