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