Cloudscape Docs MCP

🚀 雲景文檔MCP服務器

雲景文檔MCP服務器是一個基於模型上下文協議（MCP）的服務器，它能對AWS 雲景設計 系統文檔進行語義搜索。該服務器專為AI智能體和編碼助手設計，可讓它們高效地查詢組件文檔。

✨ 主要特性

• 語義搜索：藉助 阿里巴巴GTE多語言基礎 模型，使用自然語言查詢來查找相關文檔。
• 令牌高效：先返回簡潔的文件列表，按需提供完整內容。
• 硬件優化：可自動檢測蘋果硅芯片（MPS）、CUDA或CPU。
• 本地向量存儲：使用LanceDB進行快速的基於文件的向量搜索。

📦 傳輸協議

本服務器使用MCP 標準輸入輸出傳輸 協議。 可流式HTTP傳輸 即將推出。

🛠️ 工具

📋 要求

• Python 3.13及以上版本
• 嵌入模型約需3GB磁盤空間
• 建議8GB以上內存

📥 安裝

# 克隆倉庫
git clone https://github.com/praveenc/cloudscape-docs-mcp.git
cd cloudscape-docs-mcp

# 創建虛擬環境並安裝依賴
uv sync

# 或者使用pip
pip install -e .

⚙️ 設置

1. 添加文檔

將雲景文檔文件放置在 docs/ 目錄下，支持的格式包括：

• .md（Markdown）
• .txt（純文本）
• .tsx / .ts（TypeScript/React）

2. 構建索引

運行攝入腳本以創建向量數據庫：

uv run ingest.py

此操作將：

• 掃描 docs/ 目錄下的所有文件
• 將內容分割成約2000字符的片段
• 使用 阿里巴巴GTE多語言基礎 嵌入模型生成嵌入向量
• 將向量存儲在 data/lancedb/ 目錄中

⚠️ 重要提示

多次運行 uv run ingest.py 是安全的，但每次都會執行 完全重新索引。該腳本使用 mode="overwrite"，會刪除並重新創建數據庫表。沒有增量更新或變更檢測，每次運行都會重新掃描和重新嵌入所有文檔。這是冪等操作（相同的文檔會產生相同的結果），但對於大型文檔集來說計算成本較高。

3. 運行服務器

uv run server.py

🖥️ MCP客戶端配置

Claude桌面版

在 mcp.json 中添加以下內容：

{
  "mcpServers": {
    "cloudscape-docs": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/cloudscape-docs-mcp", "python", "server.py"]
    }
  }
}

Cursor / VS Code / Windsurf / Kiro

在MCP設置中添加以下內容：

{
  "cloudscape-docs": {
    "command": "uv",
    "args": ["run", "--directory", "/path/to/cloudscape-docs-mcp", "python", "server.py"]
  }
}

Zed

在Zed設置（settings.json）中添加以下內容：

{
  "context_servers": {
    "cloudscape-docs": {
      "command": {
        "path": "uv",
        "args": ["run", "--directory", "/path/to/cloudscape-docs-mcp", "python", "server.py"]
      }
    }
  }
}

💻 使用示例

連接後，AI助手可以：

基礎用法

用戶：“如何使用帶有排序功能的表格組件？”
智能體：[調用 cloudscape_search_docs("table sorting")]

高級用法

智能體：[調用 cloudscape_read_doc("docs/components/table/sorting.md")]

📁 項目結構

cloudscape-docs-mcp/
├── server.py          # 帶有搜索/讀取工具的MCP服務器
├── ingest.py          # 文檔索引腳本
├── pyproject.toml     # 項目依賴
├── docs/              # 文檔文件（部分經過整理）
│   ├── components/    # 組件文檔
│   ├── foundations/   # 設計基礎
│   └── genai_patterns/# 生成式AI用戶界面模式
└── data/              # 生成的向量數據庫（已添加到git忽略列表）
    └── lancedb/

⚙️ 配置

server.py 和 ingest.py 中的關鍵設置：

🛠️ 開發

# 安裝開發依賴
uv sync --group dev

# 使用MCP檢查器運行
npx @modelcontextprotocol/inspector uv --directory /path/to/cloudscape_docs run server.py
# 或者，使用mcp命令行工具啟動服務器
mcp dev server.py

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE 文件。

🙏 致謝

• AWS雲景設計系統
• 模型上下文協議
• 阿里巴巴GTE多語言
• LanceDB