Cloudscape Docs MCP Server

A Model Context Protocol (MCP) server that provides semantic search over AWS Cloudscape Design System documentation. Built for AI agents and coding assistants to efficiently query component documentation.

Features

• Semantic Search - Find relevant documentation using natural language queries powered by Alibaba GTE Multilingual Base model
• Token Efficient - Returns concise file lists first, full content on demand
• Hardware Optimized - Automatic detection of Apple Silicon (MPS), CUDA, or CPU
• Local Vector Store - Uses LanceDB for fast, file-based vector search

Transport

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

Tools

---

Requirements

• Python 3.13+
• ~3GB disk space for the embedding model
• 8GB+ RAM 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:

• .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 will:

• Scan all files in docs/
• Chunk content into ~2000 character segments
• Generate embeddings using Alibaba GTE Multilingual Base embedding model
• Store vectors in data/lancedb/

Note: Running uv run ingest.py multiple times is safe but 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 detectionall documents are re-scanned and re-embedded on every run. This is idempotent (same docs produce the same result) but computationally expensive for large documentation sets.

3. Run the Server

uv run server.py

MCP Client Configuration

Claude Desktop

Add 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 to your MCP settings:

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

Zed

Add 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 Example

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

MIT License - See LICENSE for details.

Acknowledgments

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