Git Netai

网络AI助手

   

用于统一多平台网络基础设施管理的异步MCP（模型上下文协议）服务器。

通过Claude Desktop、Warp AI和任何MCP兼容客户端可访问的统一API，展示网络设备、WiFi控制器、监控系统和数据中心。

______________________________________________________________________

主要特点

100%异步架构

• 异步/等待引擎：所有I/O操作都有杠杆作用 asyncio, asyncssh，以及 httpx 为了获得最佳性能
• 并行执行：本机支持具有超时保护的多设备操作
• 持续会话：具有keepalive的可重用HTTP连接，以最大限度地减少延迟
• 智能JWT缓存：具有自动续订功能的线程安全身份验证令牌管理

10个专用连接器

总计：97个MCP工具 （95个连接器+2个技能工具）

______________________________________________________________________

安装

先决条件

• Python 3.12或更高版本
• 紫外线 包管理器
• Dotenx 用于加密凭据(brew install dotenvx/brew/dotenvx)
• 对目标设备/API的网络访问
• MCP客户端（克劳德桌面、Warp AI等）

使用UV进行安装

# Clone the repository
git clone https://github.com/angoran/git-netai.git
cd git-netai

# Sync dependencies (UV automatically creates virtual environment)
uv sync

# Verify installation
uv run python -c "from server import mcp; print(f'{mcp.name} operational')"

______________________________________________________________________

配置

环境变量

创建一个 .env 项目根目录下的文件，包含以下变量：

# Generic SSH
SSH_USERNAME="admin"
SSH_PASSWORD="your_password"

# MikroTik REST API
MIKROTIK_USERNAME="api_user"
MIKROTIK_PASSWORD="api_password"
MIKROTIK_PORT="443"

# MikroTik SSH (if different from REST)
MIKROTIK_SSH_USERNAME="ssh_user"
MIKROTIK_SSH_PASSWORD="ssh_password"
MIKROTIK_SSH_PORT="22"

# Palo Alto Firewalls
PALOALTO_SSH_USERNAME="admin"
PALOALTO_SSH_PASSWORD="firewall_password"

# Aruba WiFi Controller
ARUBA_IP="10.x.x.x"
ARUBA_USERNAME="admin"
ARUBA_PASSWORD="aruba_password"

# Graylog
GRAYLOG_API_URL="https://graylog.example.com"
GRAYLOG_USERNAME="graylog_user"
GRAYLOG_PASSWORD="graylog_password"

# LibreNMS
LIBRENMS_URL="https://librenms.example.com"
LIBRENMS_API_TOKEN="your_api_token_here"

# Cisco APIC (ACI)
APIC_HOST="https://apic.example.com"
APIC_USERNAME="apic_user"
APIC_PASSWORD="apic_password"
APIC_VERIFY_SSL="false"
APIC_TIMEOUT="30"
APIC_TOKEN_CACHE_DURATION="3540"

# Cisco NDFC
NDFC_HOST="https://ndfc.example.com"
NDFC_USER="ndfc_user"
NDFC_PASSWORD="ndfc_password"
NDFC_DOMAIN="DefaultAuth"
NDFC_VERIFY_SSL="false"
NDFC_TIMEOUT="30"

# Palo Alto Panorama
PANORAMA_URL="https://panorama.example.com/api"
PANORAMA_USERNAME="panorama_user"
PANORAMA_PASSWORD="panorama_password"
PANORAMA_TIMEOUT="30"

安全说明：凭据使用加密方式存储 DotenxThe .env 该文件包含AES-256-GCM加密值。私钥存储在 .env.keys （不包括在版本控制中）。永不承诺 .env.keys 到存储库。

加密凭据

填写您的 .env 文件，用dotenvx加密：

# Encrypt all values in .env (generates .env.keys with the private key)
dotenvx encrypt

# Verify decryption works correctly
dotenvx run -- uv run python -c "from server import mcp; print(f'{mcp.name} operational')"

保持 .env.keys 保护并通过安全通道（密码管理器、秘密库）将其分发给其他用户。加密的 .env 可以安全地共享或提交给版本控制。

______________________________________________________________________

MCP客户端配置

克劳德桌面版

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "netai-o": {
      "command": "dotenvx",
      "args": [
        "run",
        "--env-file", "/absolute/path/to/netai/.env",
        "--",
        "uv",
        "--directory", "/absolute/path/to/netai",
        "run",
        "python",
        "server.py"
      ],
      "env": {
        "DOTENV_PRIVATE_KEY": ""
      }
    }
  }
}

扭曲AI

配置文件： ~/.warp/mcp_config.json

{
  "mcpServers": {
    "netai-o": {
      "command": "dotenvx",
      "args": ["run", "--", "uv", "run", "python", "server.py"],
      "env": {
        "DOTENV_PRIVATE_KEY": ""
      },
      "working_directory": "/absolute/path/to/netai"
    }
  }
}

______________________________________________________________________

用法

启动服务器

# Launch MCP server in stdio mode (with encrypted .env decryption)
dotenvx run -- uv run python server.py

服务器通过stdio协议公开所有MCP工具。MCP客户端（Claude Desktop、Warp）根据其配置文件自动启动服务器。

示例命令

以下示例演示了可用于Claude Desktop或Warp AI的自然语言命令：

通用SSH操作

Execute "show version" on device 192.168.1.1
Run "show ip route" on devices 192.168.1.1 and 192.168.1.2 in parallel

MikroTik管理

Show BGP sessions on MikroTik router 10.0.0.1
Check route to 8.8.8.8 on MikroTik 10.0.0.1 via SSH
Display interface statistics for 10.0.0.1

Palo Alto防火墙操作

Show VPN status on Palo Alto firewall 10.240.203.241
Execute "show system info" on firewalls 10.240.203.241 and 10.240.203.242 in parallel
Display routing table on firewall 10.240.203.241

Aruba WiFi控制器

List all access points on Aruba controller
Show connected WiFi clients
Detect rogue access points
Display RF channel utilization
Show WLAN configuration

Graylog日志管理

Search for "authentication failure" in logs from the last 2 hours
List available Graylog streams
Show system overview and statistics

LibreNMS网络监控

Show all monitored MikroTik devices
Display health metrics for device router-core-01
List all ports on switch-distro-01
Show temperature sensors for all devices
Retrieve event logs for the last 24 hours

思科APIC（ACI数据中心）

Show overall ACI fabric health
List all APIC tenants
Search for endpoint with IP address 10.1.1.50
Analyze connectivity between EPG web and EPG database
Show top talkers in Production tenant
Display fabric topology
List all contracts in tenant Production

思科NDFC

List all NDFC fabrics
Show switches in fabric DC1
Get critical events from the last 24 hours
Show interface details for switch with serial FDO23460MQC
Display VRFs in fabric DC1
Show network deployment status

帕洛阿尔托全景

Show Panorama system information
List all managed firewalls
Show device groups and their members
Analyze security rules quality for device-group Production
Find rules without security profile in device-group DMZ
Check version compliance across all firewalls
Show configuration audit logs
Find duplicate address objects
Show pending configuration changes

技能（指导工作流程）

调用技能的推荐方法是明确指示代理加载并遵循它：

Load and execute the skill "infrastructure-health-check".
Follow every step of the procedure in order and produce a structured report.

Use skills_list to find the most appropriate skill, then load it with skills_load
and execute it step by step.
Task: BGP sessions on router 10.0.0.1 are flapping since this morning.

# Discovery and filtering
List all available skills
List skills for platform ACI
List skills tagged with "change-management"

# Monitoring and NOC
Run an infrastructure health check across all platforms
Perform a WiFi health monitoring report on the Aruba controller
Do a deep dive on device router-wan-01

# Troubleshooting
Diagnose BGP on MikroTik router 10.0.0.1
Track endpoint with IP 10.1.2.50 in the ACI fabric
Run a full ACI fabric health diagnostic
Check connectivity between device A and device B

# Compliance and Audit
Run a Panorama security audit on device-group Production
Check software version compliance and certificate expiry across all firewalls
Audit the ACI configuration for tenant Prod

# Change Management
Perform a pre-check before the maintenance window for change CHG0012345
Validate the post-change state and compare with the pre-check baseline
Detect any unauthorized configuration changes in the last 48 hours

# Inventory and Capacity
Generate a consolidated multi-vendor inventory
Map the physical network topology using LLDP discovery
Produce a capacity planning report for the infrastructure

# Incident Response
Correlate events and logs to identify the root cause of the incident
reported at 14:30 UTC — application servers cannot reach the database

技能是Markdown中一步一步的操作过程。LLM电话 skills_list() 要发现按平台或标签筛选的可用程序，则 skills_load() 检索完整的过程，并按照顺序调用引用的MCP工具。每项技能都包括一个决策矩阵、企业级报告的输出标准和一个包含运营最佳实践的注释部分。

______________________________________________________________________

技术架构

项目结构

git-netai/
├── server.py                    # MCP entry point (FastMCP stdio transport)
├── skills_engine.py             # Skills index + loader (in-memory, YAML frontmatter)
├── connectors/                  # Asynchronous connector modules
│   ├── ssh_c.py                # Generic SSH connector (asyncssh)
│   ├── mikrotik_c.py           # MikroTik REST API connector (httpx)
│   ├── mikrotik_ssh_c.py       # MikroTik SSH connector (asyncssh)
│   ├── paloalto_c.py           # Palo Alto SSH PTY connector (asyncssh)
│   ├── panorama_c.py           # Palo Alto Panorama REST API connector (httpx + XML→JSON)
│   ├── aruba_c.py              # Aruba WiFi REST API connector (httpx)
│   ├── graylog_c.py            # Graylog REST API connector (httpx)
│   ├── librenms_c.py           # LibreNMS REST API connector (httpx)
│   ├── apic_c.py               # Cisco APIC REST API connector (httpx + JWT cache)
│   └── ndfc_c.py               # Cisco NDFC REST API connector (httpx + JWT cache)
├── skills/                      # Diagnostic skills (Markdown procedures with YAML frontmatter)
│   ├── TEMPLATE.md                          # Template and frontmatter reference for new skills
│   ├── bgp-diagnostic-mikrotik.md           # BGP session diagnostic on MikroTik
│   ├── connectivity-check.md                # End-to-end connectivity check
│   ├── multicast-diagnostic-aci.md          # ACI multicast diagnostic
│   ├── infrastructure-health-check.md       # Multi-platform health overview (NOC/shift handover)
│   ├── wifi-health-monitoring.md            # Aruba WiFi fleet health and RF audit
│   ├── device-deep-dive.md                  # Deep investigation of a single device (LibreNMS)
│   ├── aci-endpoint-tracking.md             # Locate and diagnose an endpoint in ACI
│   ├── aci-fabric-health-diagnostic.md      # ACI fabric degradation investigation
│   ├── aci-configuration-audit.md           # ACI logical config consistency audit
│   ├── aci-traffic-analysis.md              # ACI top talkers and interface utilization
│   ├── panorama-security-audit.md           # Firewall security rules quality audit
│   ├── compliance-versions-certificates.md  # Software versions and certificate expiry check
│   ├── change-pre-check.md                  # Baseline capture before a planned change
│   ├── change-post-check.md                 # Regression validation after a change
│   ├── configuration-drift-detection.md     # Unauthorized change detection (multi-source)
│   ├── multi-vendor-inventory.md            # Consolidated inventory across all platforms
│   ├── network-topology-mapping.md          # LLDP-based physical topology discovery
│   ├── ndfc-deployment-validation.md        # NDFC network/VRF deployment validation
│   ├── incident-root-cause-correlation.md   # Multi-source incident correlation and timeline
│   └── capacity-planning-report.md          # Infrastructure capacity assessment
├── pyproject.toml              # UV project configuration and dependencies
├── uv.lock                     # UV dependency lockfile
├── .env                        # Environment variables (not version controlled)
├── .gitignore                  # Git ignore rules
└── README.md                   # Project documentation

技能体系

技能是存储为Markdown文件的逐步诊断和操作程序 skills/*.md每个文件都携带一个YAML frontmatter头（标题、平台、标签、所需工具），在服务器启动时解析为内存索引。两个专用的MCP工具暴露了系统。

它是如何工作的：

1. LLM电话 skills_list() 发现可用技能——只返回元数据（名称、标题、平台、标签、描述、所需工具），从不返回内容
2. 可选过滤器： skills_list(platform="mikrotik") 或 skills_list(tag="bgp")
3. LLM电话 skills_load("bgp-diagnostic-mikrotik") 检索完整过程——支持部分和不区分大小写的名称匹配；两者 skill_name 和 name 参数已被接受
4. Markdown内容描述了每个步骤：调用哪个MCP工具、预期结果和决策逻辑
5. LLM自主地遵循程序，按顺序调用引用的工具
6. 每一项技能都强制执行 输出标准：结构化的部分、专业的语气、适用于事故单、审计文件或管理简报的企业级报告

创造新技能：

1. 复制 skills/TEMPLATE.md 到 skills/{subject}-{platform}.md
2. 填写YAML frontmatter（标题、平台、标签、工具、描述）
3. 参考现有MCP工具编写程序步骤
4. 呼叫 skills_list(reload=True) 刷新索引--无需重新启动服务器

Frontmatter模式 （每个技能档案中都需要）：

---
title: BGP Diagnostic on MikroTik
platform: mikrotik  # mikrotik | aruba | aci | graylog | librenms | paloalto | panorama | generic
tags: [bgp, routing, peering, sessions]
tools: [get_mikrotik_bgp_sessions, get_mikrotik_bgp_connections]
description: One-sentence description of what this skill diagnoses.
---

可用技能（20）：

异步设计模式

1.持久HTTP会话

REST API连接器（Aruba、Graylog、LibreNMS）使用持久HTTP连接来最大限度地减少连接开销：

async with httpx.AsyncClient(timeout=30) as client:
    response = await client.get(url, headers=headers)
    # HTTP session is automatically reused for subsequent requests

2.线程安全JWT令牌缓存

APIC和NDFC连接器实现了具有自动续订功能的线程安全JWT令牌缓存：

_token_cache = {"token": None, "expires_at": 0, "lock": asyncio.Lock()}

async def _get_token():
    async with _token_cache["lock"]:
        if time.time() `, `telnet  
`.检查防火墙规则和路由。增加超时值 `.env`. |
| **SSL/TLS证书错误** |自签名证书或不受信任的CA |开发：设置 `VERIFY_SSL=false`生产：安装正确的CA证书或使用 `certifi` 捆绑。 |
| **JWT令牌已过期（APIC/NDFC）** |超过令牌寿命|令牌续订是自动的。如果持续存在，请验证凭据并检查APIC/NFC身份验证日志。 |
| **MCP服务器无法启动** |缺少依赖项或Python版本不匹配|检查 `uv --version` 和 `python --version` （必须为3.12+）。重新运行 `uv sync` 重新安装依赖关系。 |
| **Palo Alto会话超时** |PAN-OS攻击性会话超时|增加 `timeout` 工具调用中的参数。考虑实现保活数据包。 |
| **Librenms API 401错误** |API令牌无效或过期|根据用户设置在LibreNMS web界面中重新生成API令牌。更新 `LIBRENMS_API_TOKEN` 在 `.env`. |
| **禁止使用APIC/NDFC 403** |帐户权限不足|验证帐户是否具有所需的角色分配（管理员或结构管理员可获得完全访问权限）。 |

### 启用调试日志记录

添加以下内容 `server.py` 有关详细的日志输出：

import logging logging.basicConfig( level=logging.DEBUG, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' )

对于生产环境，将日志记录配置为外部syslog或SIEM：

import logging from logging.handlers import SysLogHandler

handler = SysLogHandler(address=('syslog.example.com', 514)) logging.basicConfig(handlers=[handler], level=logging.INFO)

______________________________________________________________________

## 路线图

### 当前实现

- \[x\] 100%异步架构（asyncio/asyncssh/httpx）
- \[x\] 10个连接器（SSH、MikroTik REST+SSH、Aruba、Palo Alto SSH、Panorama、Graylog、LibreNMS、APIC、NDFC）
- \[x\] 97个暴露的MCP工具（95个连接器+2个技能工具）
- \[x\] 智能JWT缓存，可自动续订
- \[x\] 带有keepalive的持久HTTP会话
- \[x\] 具有超时保护的并行执行
- \[x\] 对Palo Alto PAN-OS的PTY支持
- \[x\] 现代紫外线管理（pyproject.toml+UV.lock）
- \[x\] 使用dotenvx（AES-256-GCM）进行加密凭据管理
- \[x\] Panorama API与XML的集成→JSON转换
- \[x\] 具有内存索引、YAML frontmatter、平台/标签过滤和模糊名称匹配的技能系统
- \[x\] 7个运营类别（监控、故障排除、合规性、变更管理、库存、容量、事件响应）的20项专业技能
- \[x\] 企业产出标准在每项技能中都得到了执行（结构化报告、专业语气、企业就绪）

### 计划中的增强功能

**附加平台支持和更多端点：**

- \[\]添加更多LibreNMS端点（警报、设备组、库存）
- \[\]添加更多APIC端点（故障排除、变更管理）
- \[\]扩展Aruba功能（射频分析、热图）
- \[\]扩展全景功能（策略推送、提交操作）

**技能：**

- \[\]OSPF诊断技能（MikroTik/通用）
- \[\]VPN隧道诊断技能（Palo Alto）
- \[\]WiFi客户端故障排除技能（阿鲁巴）
- \[\]事故后验尸报告技能

______________________________________________________________________

## 许可证

该项目根据MIT许可证获得许可。请参阅 [许可证](LICENSE) 提交完整的条款和条件。

______________________________________________________________________

## 致谢

- **FastMCP** -高性能MCP服务器框架
- **异步ssh** -生产级异步SSH实现
- **httpx** -支持HTTP/2的现代异步HTTP客户端
- **紫外线** -Rust内置的下一代Python包管理器
- **Anthropic** -模型上下文协议规范和参考实现

______________________________________________________________________

## 支持

对于问题、疑问或贡献：

- **问题追踪**: 
- **讨论**: 

______________________________________________________________________

**面向企业环境的专业网络自动化**