Cloudscape Docs MCP

🚀 Cloudscape Docs MCP Server

このModel Context Protocol (MCP)サーバーは、AWS Cloudscape Designシステムのドキュメントに対する意味検索を提供します。AIエージェントやコーディングアシスタントがコンポーネントのドキュメントを効率的にクエリできるように構築されています。

✨ 主な機能

• 意味検索 - Alibaba GTE Multilingual Baseモデルを使用した自然言語クエリで関連するドキュメントを検索します。
• トークン効率 - まず簡潔なファイルリストを返し、必要に応じて全文を提供します。
• ハードウェア最適化 - Apple Silicon (MPS)、CUDA、またはCPUを自動検出します。
• ローカルベクトルストア - LanceDBを使用して、高速なファイルベースのベクトル検索を行います。

📦 トランスポート

このサーバーはMCP stdio transportプロトコルを使用しています。
Streamable HTTP transportも近日追加予定です。

🛠️ ツール

📋 要件

• Python 3.13以上
• 埋め込みモデルに約3GBのディスクスペースが必要
• 8GB以上のRAMを推奨

📦 インストール

# リポジトリをクローン
git clone https://github.com/praveenc/cloudscape-docs-mcp.git
cd cloudscape-docs-mcp

# 仮想環境を作成し、依存関係をインストール
uv sync

# またはpipを使用する場合
pip install -e .

⚙️ セットアップ

1. ドキュメントの追加

Cloudscapeのドキュメントファイルをdocs/ディレクトリに配置します。サポートされる形式は以下の通りです。

• .md (Markdown)
• .txt (プレーンテキスト)
• .tsx / .ts (TypeScript/React)

2. インデックスの構築

インジェストスクリプトを実行してベクトルデータベースを作成します。

uv run ingest.py

これにより以下のことが行われます。

• docs/内のすべてのファイルをスキャンします。
• 内容を約2000文字のセグメントに分割します。
• Alibaba GTE Multilingual Base埋め込みモデルを使用して埋め込みを生成します。
• ベクトルをdata/lancedb/に保存します。

⚠️ 重要提示

uv run ingest.pyを複数回実行することは安全ですが、毎回完全な再インデックス作成が行われます。このスクリプトはmode="overwrite"を使用しており、データベーステーブルを削除して再作成します。増分更新や変更検出は行われず、毎回すべてのドキュメントが再スキャンされ、再埋め込みされます。これは冪等性があり（同じドキュメントでは同じ結果が得られます）、大規模なドキュメントセットに対しては計算コストが高くなります。

3. サーバーの起動

uv run server.py

📄 MCPクライアントの設定

Claude Desktop

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アシスタントは以下のことができます。

基本的な使用法

1. コンポーネントの検索

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

2. 特定のドキュメントの読み取り

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

📁 プロジェクト構造

cloudscape-docs-mcp/
├── server.py          # MCPサーバーと検索/読み取りツール
├── ingest.py          # ドキュメントインデックス作成スクリプト
├── pyproject.toml     # プロジェクトの依存関係
├── docs/              # ドキュメントファイル (一部整理済み)
│   ├── components/    # コンポーネントのドキュメント
│   ├── foundations/   # デザインの基礎
│   └── genai_patterns/# GenAI UIパターン
└── data/              # 生成されたベクトルデータベース (gitignored)
    └── lancedb/

⚙️ 設定

server.pyとingest.pyの主要な設定は以下の通りです。

🛠️ 開発

# 開発用の依存関係をインストール
uv sync --group dev

# MCPインスペクターで実行
npx @modelcontextprotocol/inspector uv --directory /path/to/cloudscape_docs run server.py
# または、mcp cliを使用してサーバーを起動
mcp dev server.py

📄 ライセンス

MITライセンス - 詳細はLICENSEを参照してください。

🙏 謝辞

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