Aristadb MCP

Arista文档RAG系统

Arista网络文档的全面RAG（检索增强生成）系统。该系统通过MCP（模型上下文协议）服务器对多个Arista文档源进行抓取、索引和语义搜索。

数据源

总计：约1300+个索引文档

项目结构

scraper/
├── arista_scraper.py       # Scrapes Arista Community Knowledge Base
├── avd_scraper.py          # Scrapes AVD documentation (web + GitHub)
├── pdf_to_rag.py           # Extracts and chunks EOS User Manual PDF
├── EOS-User-Manual.pdf     # Source PDF (not included in repo)
├── arista_data/            # Scraped data storage
│   ├── rag_documents.json  # Combined RAG database (all sources)
│   ├── knowledge_articles.json
│   ├── avd_documents.json
│   └── eos_manual_rag.json
├── aristadb-mcp/           # MCP Server
│   ├── server.py           # Main MCP server
│   ├── lancedb_data/       # Vector database storage
│   ├── pyproject.toml
│   └── requirements.txt
└── venv/                   # Python virtual environment

快速开始

1.初始设置

# Clone/navigate to the project
cd scraper

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install playwright httpx lancedb sentence-transformers mcp[cli] pypdf

# Install Playwright browsers
playwright install chromium

2.运行刮刀（如果需要）

# Scrape Arista Knowledge Base (~1000 articles)
python arista_scraper.py

# Scrape AVD documentation (web + GitHub)
python avd_scraper.py

# Extract EOS Manual PDF (requires EOS-User-Manual.pdf)
python pdf_to_rag.py

3.对数据进行索引

cd aristadb-mcp
python server.py --index

4.配置MCP客户端

将服务器添加到MCP客户端配置中（请参阅 MCP配置 在......下面

______________________________________________________________________

详细用法

Arista知识库刮刀

从Arista社区知识库（基于Salesforce的门户）中抓取文章。

# Scrape all articles (default)
python arista_scraper.py

# Scrape limited pages (for testing)
python arista_scraper.py --max-pages 5

# Run with visible browser (for debugging)
python arista_scraper.py --no-headless

输出文件：

• arista_data/knowledge_articles.json -完整文章数据
• arista_data/knowledge_articles.jsonl -行分隔JSON
• arista_data/knowledge_articles.csv -仅元数据
• arista_data/rag_documents.json -RAG就绪格式

特征：

• 自动分页处理
• 每10篇文章保存一次进度
• 恢复能力（进度文件）
• 多个内容提取回退

AVD文档刮刀

从官方网站和GitHub存储库中删除Arista验证的设计文档。

# Scrape everything (website + GitHub)
python avd_scraper.py

# Skip website, only scrape GitHub
python avd_scraper.py --skip-web

# Skip GitHub, only scrape website
python avd_scraper.py --skip-github

# Run with visible browser
python avd_scraper.py --no-headless

被刮的东西：

*网站（avd.arista.com）：*

• 安装指南
• 如何指导（连接端点、节点类型、PTP、WAN等）
• 示例配置（单dc-l3ls、双dc-l3l、校园结构等）
• 角色文档
• 数据模型参考
• 发行说明

*GitHub（aristanetworks/avd）：*

• 所有README.md文件
• 角色文档（eos_designs、eos_cli_config_gen、cv_deploy等）
• 插件文档
• 示例配置
• 贡献指南

输出文件：

• arista_data/avd_documents.json -仅AVD文件
• arista_data/rag_documents.json -与现有数据合并

EOS手动PDF提取器

提取并分块RAG的EOS用户手册PDF。

# Extract PDF (requires EOS-User-Manual.pdf in project root)
python pdf_to_rag.py

特征：

• 基于章节的组块（检测章节标题）
• 如果未检测到章节，则回退到20个页面组
• 保留页码参考
• 重复运行时的重复数据删除

输出文件：

• arista_data/eos_manual_rag.json -仅PDF格式的数据
• arista_data/rag_documents.json -与现有数据合并

______________________________________________________________________

MCP服务器

启动服务器

MCP服务器作为stdio服务器运行，通常由MCP客户端启动。

cd aristadb-mcp

# Index data (required before first use or after scraping)
python server.py --index

# Run server (normally done by MCP client)
python server.py

可用工具

示例查询

# Semantic search examples
"How do I configure BGP on Arista switches?"
"What is MLAG and how does it work?"
"AVD deployment best practices"
"CloudVision integration setup"

# Keyword search examples
"eos_designs"
"bgp_peer"
"EVPN"
"cv_deploy"

______________________________________________________________________

MCP配置

克劳德桌面版

添加 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aristadb": {
      "command": "/path/to/scraper/venv/bin/python",
      "args": ["/path/to/scraper/aristadb-mcp/server.py"]
    }
  }
}

Roo Cline（VS代码）

添加到MCP设置（通常 mcp_settings.json):

{
  "mcpServers": {
    "aristadb": {
      "command": "/path/to/scraper/venv/bin/python",
      "args": ["/path/to/scraper/aristadb-mcp/server.py"],
      "disabled": false
    }
  }
}

克劳德代码CLI

添加 .claude/settings.local.json 在您的项目中：

{
  "permissions": {
    "allow": [
      "mcp__aristadb__search_arista_docs",
      "mcp__aristadb__keyword_search_arista",
      "mcp__aristadb__arista_db_stats"
    ]
  },
  "mcpServers": {
    "aristadb": {
      "command": "/path/to/scraper/venv/bin/python",
      "args": ["/path/to/scraper/aristadb-mcp/server.py"]
    }
  }
}

______________________________________________________________________

重新抓取和更新

何时重新刮擦

• 知识库：每月或新文章发表时
• 音频视频设备：新AVD发布后（查看GitHub发布）
• EOS手册：获取新的PDF版本后

完整的重新抓取工作流

# Activate virtual environment
source venv/bin/activate

# 1. Re-scrape Knowledge Base (takes 30-60 minutes)
python arista_scraper.py

# 2. Re-scrape AVD documentation (takes 5-10 minutes)
python avd_scraper.py

# 3. Re-extract PDF if updated
python pdf_to_rag.py

# 4. Re-index the database
cd aristadb-mcp
python server.py --index

# 5. Restart your MCP client to pick up changes

部分更新

# Only update AVD (fastest)
python avd_scraper.py
cd aristadb-mcp && python server.py --index

# Only update Knowledge Base
python arista_scraper.py
cd aristadb-mcp && python server.py --index

自动化（Cron）

每周AVD更新的cron作业示例：

# Add to crontab -e
0 2 * * 0 cd /path/to/scraper && source venv/bin/activate && python avd_scraper.py && cd aristadb-mcp && python server.py --index

______________________________________________________________________

故障排除

刮刀问题

未找到浏览器：

playwright install chromium

知识库超时错误：

• Salesforce门户可能很慢；增加等待时间 arista_scraper.py
• 试着用 --no-headless 看看发生了什么

GitHub速率限制：

• AVD刮刀包括速率限制，但您可能会达到API限制
• 等待一个小时重试，或设置GitHub令牌

页面内容为空：

• 某些页面可能包含无法加载的动态内容
• 刮刀有多种回退提取方法

MCP服务器问题

“未找到结果”错误：

# Make sure data is indexed
cd aristadb-mcp
python server.py --index

服务器无法启动：

# Check dependencies
pip install lancedb sentence-transformers mcp[cli]

# Check Python path in MCP config
which python  # Use this path in your config

第一次查询速度慢：

• 第一个查询加载嵌入模型（~100MB）
• 后续查询速度很快

数据问题

重复文件：

• 刮刀在重新运行时删除重复项（通过ID前缀）
• 如果需要，删除 arista_data/rag_documents.json 并重新运行所有刮板

缺少数据源：

• 检查中是否存在单个数据文件 arista_data/
• 重新运行特定刮刀以查找缺失的源

______________________________________________________________________

技术细节

向量数据库

• 发动机：LanceDB（基于Apache Arrow）
• 嵌入模型: all-MiniLM-L6-v2 （384个维度）
• 存储：中的本地文件 aristadb-mcp/lancedb_data/

文档格式

{
  "id": "avd-github-42",
  "title": "AVD GitHub: eos_designs Role",
  "url": "https://github.com/aristanetworks/avd/...",
  "text": "Full document content...",
  "metadata": {
    "source": "AVD GitHub Repository",
    "category": "AVD Roles",
    "scraped_at": "2024-01-15T10:30:00"
  }
}

ID前缀

______________________________________________________________________

依赖项

Python 包

playwright>=1.40.0      # Web scraping
httpx>=0.25.0          # HTTP client for GitHub API
lancedb>=0.4.0         # Vector database
sentence-transformers>=2.2.0  # Embeddings
mcp[cli]>=1.0.0        # MCP protocol
pypdf>=3.0.0           # PDF extraction

系统要求

• Python 3.10+
• 矢量数据库约500MB磁盘空间
• ~2GB RAM用于嵌入模型
• 用于抓取的互联网接入

______________________________________________________________________

许可证

此项目供内部使用Arista文档。在抓取和使用Arista的内容时，请遵守Arista的服务条款。

贡献

1. 测试更改 --max-pages 2 或 --skip-web 为了更快的迭代
2. 确保抓取的数据遵循RAG文档格式
3. 添加新数据源时更新此README