Tailwind Svelte Assistant MCP Server

Tailwind Svelte Assistant MCP Server

セキュリティとパフォーマンスに優れた Model Context Protocol（MCP）サーバーです。強化されたセキュリティ、適切な TypeScript 実装、包括的なエラー処理により、完全な SvelteKit および Tailwind CSS のドキュメント（カバー率 100％）とコードスニペットを提供します。

✨ 新機能（v0.1.1）

📚 完全なドキュメントカバー率

• Svelte/SvelteKit のカバー率 100％：LLM 向けに最適化された公式ドキュメント（1.04 MB）
• Tailwind CSS のカバー率 100％：Repomix による抽出でドキュメント全体を収録（2.1 MB、249 ファイル）
• インテリジェント検索：コンテキスト付きでドキュメント全体を検索
• 12.5〜25 倍の向上：カバー率を 4〜8％から 100％に向上

🚀 主な改善点（v0.1.1）

🔒 セキュリティ強化

• パストラバーサル対策：包括的な入力サニタイズにより、ディレクトリトラバーサル攻撃を防止
• 入力検証：パターンマッチングと長さ制限による厳格なパラメーター検証
• 安全なファイル操作：パス検証とサイズ制限を適用した範囲内のファイルアクセス
• 監査ログ：監視用の構造化されたセキュリティイベントログ

🏗️ アーキテクチャの改善

• モジュール設計：関心事を専用のサービスとユーティリティに分割
• 優れた TypeScript 対応：適切なインターフェースを使用した完全な型安全性を実現し、any 型は不使用
• ES モジュール：適切なインポートを備えた最新の JavaScript モジュールシステム
• エラー処理：包括的なエラー分類と安全なエラーメッセージ

⚡ パフォーマンスの最適化

• コンテンツキャッシュ：応答時間を短縮する、タイムアウト設定可能な LRU キャッシュ
• ファイルサイズ制限：設定可能な制限により、リソースの枯渇を防止
• 非同期処理：同時実行性を高めるノンブロッキングのファイル操作
• メモリ管理：キャッシュの自動クリーンアップとガベージコレクション

📁 プロジェクト構成

src/
├── index.ts                 # Main server with security hardening
├── types.ts                 # TypeScript type definitions
├── services/
│   └── fileService.ts       # Secure file operations with caching
└── utils/
    ├── security.ts          # Input validation and path sanitization
    └── errorHandler.ts      # Comprehensive error handling

🚀 クイックスタート

Smithery 経由でインストール（推奨）

この MCP サーバーをインストールする最も簡単な方法は、Smithery を利用することです。

npx -y @smithery/cli install @CaullenOmdahl/tailwind-svelte-assistant --client claude

これにより、以下が自動的に実行されます。

• サーバーをインストール
• Claude Desktop 用に設定
• 必要な依存関係をすべてセットアップ

直接 URL 経由でインストール

その他の MCP クライアントでは、サーバーの直接 URL を使用してください。

https://server.smithery.ai/@CaullenOmdahl/tailwind-svelte-assistant/mcp

これを MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "tailwind-svelte-assistant": {
      "url": "https://server.smithery.ai/@CaullenOmdahl/tailwind-svelte-assistant/mcp",
      "transport": "http"
    }
  }
}

🛠️ 手動インストールとセットアップ

前提条件

• Node.js 20 以降（ES モジュールのサポートと依存関係に必要）
• npm または yarn
• Git（リポジトリのクローンに使用）

依存関係のインストール

npm install

サーバーのビルド

npm run build

開発モード

npm run watch

🔧 設定

サーバーは安全なデフォルト設定を使用しますが、ServerConfig インターフェースで設定できます。

const CONFIG: ServerConfig = {
  maxFileSize: 3 * 1024 * 1024,    // 3MB max file size (for full docs)
  cacheTimeout: 5 * 60 * 1000,     // 5 minutes cache timeout
  contentBasePath: './content',
  svelteFullDocsPath: './content/docs/svelte-sveltekit-full.txt',
  tailwindFullDocsPath: './content/docs/tailwind-docs-full.txt',
  // ... other paths
};

ドキュメントの更新

ドキュメントは自動的にダウンロードされ、更新されます。

# Update all documentation (Svelte + Tailwind)
npm run update-content

このスクリプトは以下を実行します。

• LLM 向けに最適化された公式 Svelte ドキュメント（svelte.dev/llms-full.txt）をダウンロード
• Repomix を使用して GitHub から Tailwind のドキュメント全体を抽出
• コンポーネントスニペットのタイムスタンプを更新
• コンテンツの概要を生成

ソース：

• Svelte/SvelteKit：LLM 向けに最適化された公式テキストファイル（カバー率 100％）
• Tailwind CSS：Repomix による抽出を使用した GitHub リポジトリ（249 個の MDX ファイル）
• スニペット：厳選したローカルのコンポーネント例（43 ファイル）

🛡️ セキュリティ機能

入力検証

• パターンマッチング：英数字、ハイフン、アンダースコア、ピリオドのみを許可
• 長さ制限：入力の最大長を設定可能
• パスのサニタイズ：ディレクトリトラバーサルの試みを除去
• 境界チェック：ファイルアクセスが許可されたディレクトリ内に収まることを確認

エラー処理

• 安全なエラーメッセージ：クライアントに機密情報を公開しません
• 構造化ログ：セキュリティ監視用の JSON 形式の監査ログ
• エラー分類：エラーの種類に応じて異なる処理を行います
• グレースフルデグラデーション：重要度の低い障害に対するフォールバック応答

ファイルシステムのセキュリティ

• パスの検証：解決されたパスがベースディレクトリ内にあることを確認します
• ファイルサイズ制限：リソース枯渇攻撃を防止します
• 読み取り専用操作：クライアントに公開する書き込み操作はありません
• キャッシュの分離：コンテンツのキャッシュによってファイルシステムの構造が公開されることはありません

📊 パフォーマンス機能

キャッシュシステム

// Automatic content caching with configurable timeout
const fileService = new SecureFileService(
  1024 * 1024,    // Max file size
  5 * 60 * 1000   // Cache timeout (5 minutes)
);

リソース管理

• メモリ制限：ファイルサイズの制限により、メモリ枯渇を防止します
• キャッシュのクリーンアップ：期限切れのキャッシュエントリを自動的に削除します
• 非同期 I/O：ブロックしないファイル操作
• エラー回復：リソース制限にグレースフルに対処します

🔍 利用可能なツール

🆕 完全なドキュメントツール（推奨）

• get_svelte_full_docs - Svelte と SvelteKit のドキュメント全体を取得します（1MB、カバー率 100%）

  • パラメーターは不要です
  • LLM に最適化された単一ファイルでドキュメント全体を返します
  • Svelte チームによる公式フォーマットです

• get_tailwind_full_docs - Tailwind CSS のドキュメント全体を取得します（2.1MB、カバー率 100%）

  • パラメーターは不要です
  • 249 件のドキュメントファイルすべてを含みます
  • すべてのユーティリティクラスと概念を網羅しています

• search_svelte_docs - Svelte／SvelteKit のドキュメントを検索します

  • パラメーター：query（文字列）、limit（任意、デフォルト：5）
  • 一致するセクションとその前後のコンテキストを返します
  • メモリ内で高速に検索します

• search_tailwind_docs - Tailwind CSS のドキュメントを検索します

  • パラメーター：query（文字列）、limit（任意、デフォルト：5）
  • 一致するセクションとその前後のコンテキストを返します
  • すべてのユーティリティクラスを網羅しています

レガシードキュメントツール

注：これらのツールがカバーするのは、利用可能なドキュメントの約 4～8% のみです。完全に網羅するには、上記の完全なドキュメントツールを使用してください。

• get_sveltekit_doc - SvelteKit の特定のドキュメントトピックを取得します
• get_tailwind_info - Tailwind CSS の特定の情報を取得します
• list_sveltekit_topics - 利用可能な SvelteKit ドキュメントを一覧表示します（一部のみ）
• list_tailwind_info_topics - Tailwind のドキュメントを一覧表示します（一部のみ）

コンポーネントツール

• get_component_snippet - Svelte コンポーネントのコードを取得します
• list_snippet_categories - コンポーネントのカテゴリを一覧表示します
• list_snippets_in_category - カテゴリ内のスニペットを一覧表示します

強化されたツールスキーマ

すべてのツールに次の機能が含まれています：

• 正規表現の制約によるパターン検証
• 入力パラメーターの長さ制限
• 使用例を含む包括的な説明
• 入力のサニタイズを強化したセキュリティ対策

📝 使用例

MCP クライアントの設定

オプション 1：Smithery ホスト型（推奨）

{
  "mcpServers": {
    "tailwind-svelte-assistant": {
      "url": "https://server.smithery.ai/@CaullenOmdahl/tailwind-svelte-assistant/mcp",
      "transport": "http"
    }
  }
}

オプション 2：ローカルインストール

{
  "mcpServers": {
    "tailwind-svelte-assistant": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {}
    }
  }
}

ツールの使用方法

推奨：完全なドキュメント

// Get complete Svelte/SvelteKit documentation (1MB, 100% coverage)
await client.callTool("get_svelte_full_docs", {});

// Get complete Tailwind CSS documentation (2.1MB, 100% coverage)
await client.callTool("get_tailwind_full_docs", {});

// Search within Svelte documentation
await client.callTool("search_svelte_docs", {
  query: "load function",
  limit: 5  // optional
});

// Search within Tailwind documentation
await client.callTool("search_tailwind_docs", {
  query: "padding utilities",
  limit: 3  // optional
});

レガシー：特定のトピック（一部のみ）

// Get specific SvelteKit topic (only covers ~8% of docs)
await client.callTool("get_sveltekit_doc", { topic: "routing" });

// Get specific Tailwind info (only covers ~4% of docs)
await client.callTool("get_tailwind_info", { query: "padding" });

// List available topics (limited)
await client.callTool("list_tailwind_info_topics", {});

コンポーネントのスニペット

// Get a component snippet
await client.callTool("get_component_snippet", {
  component_category: "headers",
  snippet_name: "navbar-default"
});

// List snippet categories
await client.callTool("list_snippet_categories", {});

🧪 テストと品質保証

セキュリティ監査

npm run security-audit

依存関係の確認

npm run outdated-check

MCP Inspector

npm run inspector

🐳 Docker デプロイ

付属の Dockerfile は、安全なマルチステージビルドを提供します。

# Multi-stage build with security hardening
FROM node:18-alpine AS builder
# ... build process

FROM node:18-alpine AS release
# ... production setup with non-root user

セキュリティ機能

• マルチステージビルドにより攻撃対象領域を縮小します
• Alpine Linux により最小限のフットプリントを実現します
• 非 root ユーザーによりコンテナーのセキュリティを確保します
• 本番環境用の依存関係のみ

📈 監視とログ

構造化ログ

すべての操作は、解析しやすい構造化 JSON 形式で記録されます。

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "level": "info",
  "operation": "tool_request",
  "tool": "get_sveltekit_doc",
  "topic": "routing"
}

監査イベント

• パラメーターを含むツールリクエスト
• セキュリティ違反およびブロックされたリクエスト
• 分類情報を含むエラー状態
• パフォーマンス指標とキャッシュヒット

🔄 v0.1.0 からの移行

破壊的変更

• ES Modules：require の代わりに import／export を使用するよう更新しました
• TypeScript：厳密な型付けにより、一部のケースで型アサーションが必要になる場合があります
• エラーメッセージ：より安全で、詳細を抑えたエラーメッセージになりました

互換性

• ツールインターフェース：既存のすべてのツールが、改善された検証機能で動作します
• コンテンツ構造：コンテンツの構成に変更はありません
• Docker：ベースイメージを更新し、セキュリティを強化しました

🤝 コントリビューション

開発ガイドライン

1. セキュリティを最優先：すべての変更でセキュリティレビューに合格する必要があります
2. 型安全性：厳密な TypeScript 準拠を維持してください
3. テストカバレッジ：新しい機能にはテストを含めてください
4. ドキュメント：API を変更する場合は README を更新してください

コードレビューチェックリスト

• すべてのユーザー入力を検証している
• 安全なエラーメッセージでエラーを処理している
• any を使わずに TypeScript の型を指定している
• パス操作のセキュリティ監査を実施している
• パフォーマンスへの影響を評価している

📚 ドキュメント

• MCP 仕様
• セキュリティのベストプラクティス
• TypeScript SDK

🐛 トラブルシューティング

よくある問題

ビルドエラー

# Clear dist and rebuild
rm -rf dist && npm run build

権限エラー

# Ensure executable permissions
chmod +x dist/index.js

インポートエラー

• ES モジュールをサポートする Node.js 18 以降を使用してください
• package.json の "type": "module" を確認してください

セキュリティに関する懸念

セキュリティの脆弱性を発見した場合は、GitHub の issue から security ラベルを付けて報告してください。

📄 ライセンス

このプロジェクトは、元の Tailwind-Svelte-Assistant プロジェクトと同じライセンスを継承しています。

---

⚡ パフォーマンスベンチマーク

変更前と変更後（v0.1.1）

• ドキュメントカバレッジ：🔴 4-8% → 🟢 100%（12.5 倍～25 倍の改善）
• セキュリティ：🔴 重大な脆弱性 → 🟢 強化済み
• 型安全性：🟡 混在した型 → 🟢 厳密な TypeScript
• パフォーマンス：🟡 キャッシュなし → 🟢 5 分間の LRU キャッシュ
• アーキテクチャ：🔴 モノリシック → 🟢 モジュール化されたサービス
• エラー処理：🟡 基本的 → 🟢 包括的な分類

ドキュメントの指標

• Svelte/SvelteKit：1,065,921 bytes（1.04 MB）
• Tailwind CSS：2,197,160 bytes（2.1 MB、249 ファイル）
• 合計トークン数：606,587 tokens（Tailwind）
• 更新方法：npm スクリプトによる自動化

キャッシュのパフォーマンス

• コールドスタート：ファイルの読み取りあたり約 50～100 ms
• キャッシュヒット：応答時間約 1～5 ms
• メモリ使用量：キャッシュされたドキュメント全体あたり約 1～3 MB
• キャッシュ効率：一般的な使用で 80～95% のヒット率
• 検索パフォーマンス：メモリ内検索で 10 ms 未満

ドキュメントのソース

• Svelte：Svelte チームが提供する公式の LLM 向け最適化形式
• Tailwind：公式 GitHub リポジトリから Repomix を使って抽出
• 更新：フォールバック機構を備えた自動化スクリプト

このアップグレードされた MCP サーバーは、元のプロトタイプを、完全なドキュメントカバレッジ、エンタープライズグレードのセキュリティ、パフォーマンス、保守性を備えた本番環境対応サービスへと進化させます。