Cloudscape Docs MCP

🚀 Cloudscape Docs MCP Server

This is a Model Context Protocol (MCP) server that offers semantic search over AWS Cloudscape Design System documentation. It is specifically designed for AI agents and coding assistants to efficiently query component documentation.

✨ Features

• Semantic Search: Use natural language queries powered by the Alibaba GTE Multilingual Base model to find relevant documentation.
• Token Efficient: First return concise file lists and provide full content upon demand.
• Hardware Optimized: Automatically detect Apple Silicon (MPS), CUDA, or CPU.
• Local Vector Store: Utilize LanceDB for fast, file - based vector search.

🚚 Transport

This server uses the MCP stdio transport protocol. The Streamable HTTP transport is coming soon.

🛠️ Tools

⚙️ Requirements

• Python 3.13+
• Approximately 3GB of disk space for the embedding model
• 8GB+ RAM is recommended

📦 Installation

# Clone the repository
git clone https://github.com/praveenc/cloudscape-docs-mcp.git
cd cloudscape-docs-mcp

# Create virtual environment and install dependencies
uv sync

# Or with pip
pip install -e .

⚙️ Setup

1. Add Documentation

Place your Cloudscape documentation files in the docs/ directory. Supported formats include:

• .md (Markdown)
• .txt (Plain text)
• .tsx / .ts (TypeScript/React)

2. Build the Index

Run the ingestion script to create the vector database:

uv run ingest.py

This script will:

• Scan all files in docs/
• Split the content into segments of approximately 2000 characters
• Generate embeddings using the Alibaba GTE Multilingual Base embedding model
• Store vectors in data/lancedb/

⚠️ Important Note

Running uv run ingest.py multiple times is safe, but it performs a full re - index each time. The script uses mode="overwrite", which drops and recreates the database table. There is no incremental update or change detection; all documents are re - scanned and re - embedded on every run. This is idempotent (the same docs produce the same result), but it is computationally expensive for large documentation sets.

3. Run the Server

uv run server.py

📝 MCP Client Configuration

Claude Desktop

Add the following to your mcp.json:

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

Cursor / VS Code / Windsurf / Kiro

Add the following to your MCP settings:

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

Zed

Add the following to your Zed settings (settings.json):

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

💻 Usage Examples

Basic Usage

Once connected, an AI assistant can:

1. Search for components:

User: "How do I use the Table component with sorting?"
Agent: [calls cloudscape_search_docs("table sorting")]

2. Read specific documentation:

Agent: [calls cloudscape_read_doc("docs/components/table/sorting.md")]

📁 Project Structure

cloudscape-docs-mcp/
├── server.py          # MCP server with search/read tools
├── ingest.py          # Documentation indexing script
├── pyproject.toml     # Project dependencies
├── docs/              # Documentation files (partially curated)
│   ├── components/    # Component documentation
│   ├── foundations/   # Design foundations
│   └── genai_patterns/# GenAI UI patterns
└── data/              # Generated vector database (gitignored)
    └── lancedb/

⚙️ Configuration

Key settings in server.py and ingest.py:

🛠️ Development

# Install dev dependencies
uv sync --group dev

# Run with MCP inspector
npx @modelcontextprotocol/inspector uv --directory /path/to/cloudscape_docs run server.py
# Alternatively, use mcp cli to launch the server
mcp dev server.py

📄 License

This project is under the MIT License. See LICENSE for details.

🙏 Acknowledgments

• AWS Cloudscape Design System
• Model Context Protocol
• Alibaba GTE Multilingual
• LanceDB