Auvik

Auvik MCP Server

用于 Auvik 网络监控 API 的 MCP 服务。此服务提供与 Auvik 网络监控平台交互的工具，让你能够管理设备、网络、警报等。

功能

• 多租户支持 - 支持单租户和网关模式
• 全面的 API 覆盖 - 提供 25+ 个工具，涵盖所有主要的 Auvik API 端点
• 传输方式灵活 - 支持 HTTP 和 stdio 传输
• 类型安全 - 使用 TypeScript 构建，并通过 Zod 进行验证
• 支持 Docker - 可作为容器化解决方案使用

可用工具

状态和导航

• auvik_status - 检查服务状态和配置
• auvik_navigate - 获取指向 Auvik UI 和文档的导航链接

租户

• auvik_tenants_list - 列出所有可访问的租户
• auvik_tenants_get - 获取租户基本信息
• auvik_tenants_detail - 获取租户详细信息

设备

• auvik_devices_list - 列出网络设备
• auvik_devices_get - 获取设备基本信息
• auvik_devices_get_details - 获取设备详细信息
• auvik_devices_get_warranty - 获取设备保修信息
• auvik_devices_get_lifecycle - 获取设备生命周期信息

网络

• auvik_networks_list - 列出已发现的网络
• auvik_networks_get - 获取网络信息

接口

• auvik_interfaces_list - 列出网络接口

配置

• auvik_configurations_list - 列出设备配置
• auvik_configurations_get - 获取指定配置

实体

• auvik_entities_list_notes - 列出实体备注
• auvik_entities_list_audits - 列出实体审计日志

警报

• auvik_alerts_list - 列出警报历史记录。使用 filter_detectedTimeAfter/filter_detectedTimeBefore（ISO 8601）限定最近的警报；使用 filter_status/filter_severity 筛选；通过 pageSize + pageAfter 按游标分页（使用返回的 nextPageAfter）。sort 会尽力透传。
• auvik_alerts_get - 获取指定警报
• auvik_alerts_dismiss - 忽略/确认警报

统计数据

• auvik_statistics_device - 获取设备性能指标
• auvik_statistics_interface - 获取接口性能指标
• auvik_statistics_service - 获取服务性能指标
• auvik_statistics_snmp_poller - 获取 SNMP 轮询器指标

计费

• auvik_billing_client_usage - 获取客户端计费使用量
• auvik_billing_device_usage - 获取设备计费使用量

原始请求

• auvik_raw_request - 向任意 Auvik 端点发送原始请求（method 为 GET/POST，包含 path，以及可选的 query/body）。返回未经修改的 JSON:API 响应。适用于类型化工具未公开的端点或参数。

安装

环境变量

单租户模式（stdio/直接连接）：

AUVIK_USERNAME=your_auvik_username
AUVIK_API_KEY=your_auvik_api_key
AUVIK_REGION=us1  # Optional: us1, us2, us3, us4, us5, us6, lnx, eu1, eu2, au1, ca1

stdio 传输会读取这些变量，不受 HTTP 服务间身份验证的影响。

HTTP 传输：

必须设置 CONDUIT_S2S_SECRET。如果该变量为空，HTTP 服务会记录错误并以非零状态码退出。服务绝不会打印该密钥。仅在本地开发时设置 MCP_ALLOW_INSECURE_DEV=1，即可在未设置密钥的情况下启动；进程会记录醒目的警告、不检查 X-Gateway-S2S，并且仅绑定到 127.0.0.1。在该模式下，非回环地址的 MCP_HTTP_HOST（包括 0.0.0.0）会被忽略，并记录此覆盖行为。

未设置 MCP_HTTP_HOST 时，其默认值为 127.0.0.1。仅在设置了 CONDUIT_S2S_SECRET 时才将其设为 0.0.0.0。容器镜像会执行此设置，并设置 AUTH_MODE=gateway。

网关模式（AUTH_MODE=gateway）：

每个 /mcp 请求都必须包含：

• x-auvik-username
• x-auvik-api-key
• x-auvik-region（可选）

缺少用户名或 API 密钥的请求会收到 401，且不会回退到进程环境中的 AUVIK_USERNAME / AUVIK_API_KEY。设置了 CONDUIT_S2S_SECRET 时，请求还必须包含有效的 X-Gateway-S2S 标头。

单租户 HTTP（AUTH_MODE=env）：

/mcp 仍需要有效的 X-Gateway-S2S 标头。如果请求中没有 x-auvik-username 和 x-auvik-api-key，则会从 AUVIK_* 环境变量中获取供应商凭据。

Docker

# Pull from GitHub Container Registry
docker pull ghcr.io/wyre-ai/auvik-mcp:latest

# Run with the gateway S2S secret. The image sets AUTH_MODE=gateway and
# MCP_HTTP_HOST=0.0.0.0; publish the port on loopback unless a proxy sits in front.
docker run -d \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  ghcr.io/wyre-ai/auvik-mcp:latest

Docker Compose

仓库中提供的 Compose 服务采用网关模式。它不会设置 AUVIK_USERNAME 或 AUVIK_API_KEY，也不会使用 env_file，因此项目 .env 无法向容器注入静态供应商凭据。Compose 仍会从该文件插值获取 CONDUIT_S2S_SECRET 和 AUVIK_REGION。

version: '3.8'
services:
  auvik-mcp:
    image: ghcr.io/wyre-ai/auvik-mcp:latest
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - AUTH_MODE=gateway
      - AUVIK_REGION=${AUVIK_REGION:-us1}
      - CONDUIT_S2S_SECRET=${CONDUIT_S2S_SECRET:?set CONDUIT_S2S_SECRET}
      - MCP_HTTP_HOST=0.0.0.0

Docker 中的单租户 HTTP（AUTH_MODE=env）

仅在凭据位于进程环境变量中的单个租户场景下使用。此模式与上文的网关 Compose 服务相互独立。

services:
  auvik-mcp:
    image: ghcr.io/wyre-ai/auvik-mcp:latest
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - AUTH_MODE=env
      - AUVIK_USERNAME=${AUVIK_USERNAME:?set AUVIK_USERNAME}
      - AUVIK_API_KEY=${AUVIK_API_KEY:?set AUVIK_API_KEY}
      - AUVIK_REGION=${AUVIK_REGION:-us1}
      - CONDUIT_S2S_SECRET=${CONDUIT_S2S_SECRET:?set CONDUIT_S2S_SECRET}
      - MCP_HTTP_HOST=0.0.0.0

本地开发

git clone https://github.com/WYRE-AI/auvik-mcp.git
cd auvik-mcp
npm install
npm run build

# Run with stdio transport
npm start

# Run with HTTP transport (refuses to start until CONDUIT_S2S_SECRET is set)
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 npm run start:http

用法

搭配 MCP 网关使用

此服务旨在与 WYRE 的 MCP 网关配合使用。网关负责处理身份验证和路由：

// Gateway automatically injects credentials and the X-Gateway-S2S proof
const response = await fetch('http://gateway:8080/mcp', {
  method: 'POST',
  headers: {
    'x-gateway-s2s': '<proof signed with CONDUIT_S2S_SECRET>',
    'x-auvik-username': 'your_username',
    'x-auvik-api-key': 'your_api_key',
    'x-auvik-region': 'us1',
    'content-type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/call',
    params: {
      name: 'auvik_devices_list',
      arguments: {}
    }
  })
});

直接使用（stdio）

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"auvik_status","arguments":{}}}' | npm start

API 区域

Auvik 在多个区域提供服务。请设置相应的区域：

• us1 - 美国东部（默认）
• us2 - 美国西部
• us3 - 美国中部
• us4 - 美国南部
• us5 - 美国（较新的集群）
• us6 - 美国东部（俄亥俄州）
• lnx - 美国东部（俄亥俄州）
• eu1 - 欧洲西部
• eu2 - 欧洲中部
• au1 - 澳大利亚
• ca1 - 加拿大

错误处理

此服务实现了全面的错误处理：

• 无效凭据会返回 401 错误
• 资源缺失时会返回说明性的“未找到”消息，并设置 isError: true
• API 速率限制和服务错误会得到适当映射
• 所有响应都包含结构化错误信息

健康检查

此服务在 /health 提供健康检查端点，始终返回 200 OK。此端点无需身份验证，不会读取供应商凭据，适用于容器健康检查。

开发

# Install dependencies
npm install

# Run in development mode with file watching
npm run dev

# Run tests
npm test

# Type checking
npm run typecheck

# Lint
npm run lint

# Build
npm run build

贡献

贡献指南请参阅 CONTRIBUTING.md。

许可证

根据 Apache License 2.0 许可。详情请参阅 LICENSE。

支持

• GitHub 问题
• Auvik API 文档
• MCP 协议文档