Groqcloud MCP Server

🚀 Groq MCP Server

このサーバーは、Model Context Protocol (MCP) を用いた高度なソリューションで、アプリケーションと強力なGroq APIをシームレスに統合します。世界で最も高速なAIモデルへの最適化されたアクセスを提供し、クライアント（Claude Desktopなど）がGroqの様々なモデルを使って、テキストの生成、音声の文字起こし、画像分析、バッチ処理などを行うことができます。

✨ 主な機能

🧠 サポートされるモデル

このサーバーは、幅広いGroqモデルを管理し、リクエストをルーティングするように設定されています。以下はサポートされるモデルの一部です。

• テキスト生成 (LLMs):
  • llama-3.1-8b-instant
  • llama-3.3-70b-versatile
  • deepseek-r1-distill-llama-70b
  • qwen/qwen3-32b (数学用に qwen-qwq-32b)
  • compound-beta, compound-beta-mini
  • allam-2-7b, gemma2-9b-it, llama3-70b-8192, llama3-8b-8192
  • mistral-saba-24b
• セキュリティ (Prompt/Content Guard):
  • meta-llama/llama-guard-4-12b
  • meta-llama/llama-prompt-guard-2-22m, meta-llama/llama-prompt-guard-2-86m
• ビジョン (マルチモーダル):
  • meta-llama/llama-4-maverick-17b-128e-instruct
  • meta-llama/llama-4-scout-17b-16e-instruct
• 音声文字起こし (Speech-to-Text):
  • whisper-large-v3, whisper-large-v3-turbo
  • distil-whisper-large-v3-en
• テキスト読み上げ (Text-to-Speech):
  • playai-tts, playai-tts-arabic

⚡ 高度な機能

• インテリジェントルーティング (ModelRouter): 優先度（速度、品質、コスト、推論能力、数学能力、多言語対応など）、プロンプトの複雑さ、特定の機能（ビジョン、音声など）に基づいて、最適なモデルを動的に選択します。
• レート制御: 各モデルに対して、リクエスト数とトークン数の制限（RPM/TPM）を設定可能なインテリジェントな管理システムで、APIの使用を最適化します。
• 最適化されたキャッシュ: メモリ内キャッシュシステムで、TTL（Time-To-Live）を設定可能で、LLMの応答をキャッシュすることで、レイテンシを削減し、APIへの冗長な呼び出しを減らします。
• 詳細なメトリクス: 使用状況、パフォーマンス（レイテンシ、スループット）、エラー、モデルの分布などのメトリクスを収集し、分析とモニタリングに役立てます。
• 強力なエラー処理: APIリクエストに対する自動リトライ機能を備えた集中型エラー処理システムで、システムの耐性を向上させます。
• バッチ処理: Groqのバッチ処理ツールをサポートし、大量のリクエストを効率的に送信し、コストを削減します。
• 構造化ロギングとデバッグ: Winstonを使用したプロフェッショナルなログシステムで、構造化されたログを生成し、開発時には色付きの出力を stderr に送信して、デバッグとモニタリングを容易にします。

📦 インストール

前提条件

• Node.js: バージョン v20.17.0 以上、または v22.9.0 以上。NVM （または nvm-windows）を使用してNode.jsのバージョンを管理することをおすすめします。
• npm: Node.jsのパッケージマネージャー（通常はNode.jsに含まれており、推奨バージョンと互換性があります）。
• TypeScript: バージョン5以上。
• Groq APIキー: Groq APIへのリクエストを認証するために必要です。https://console.groq.com/keys で取得してください。

クイックインストール

1. リポジトリをクローンします。

   git clone [https://github.com/AyrtonFelipe/GroqCloud-MCP_server.git]
   cd groq-mcp-server
   

2. プロジェクトの依存関係をインストールします。

   npm install
   # ZodスキーマをJSONスキーマに変換するためのライブラリもインストールします。
   npm install zod-to-json-schema
   

3. 環境変数を設定します。 プロジェクトのルートに .env ファイルを作成します（存在しない場合は、.env.example からコピーできます）。

   cp .env.example .env
   

   .env ファイルを編集して、Groq APIキーを設定します。

   GROQ_API_KEY="ここにあなたのGroq APIキーを入力"
   

   （オプション: LOG_LEVEL などの他の環境変数も必要に応じて設定してください。）

4. src/config/models.json を更新します。 このファイルは、サーバーが使用するGroqモデルを定義します。

   • 削除: 利用できなくなった、または使用したくないモデルのエントリを削除します（Groqコンソールの最新リストを確認してください）。
   • 追加: "サポートされるモデル" のリストにあるが、まだ存在しないすべてのモデルを追加します。新しいモデルごとに、すべてのプロパティ（名前、説明、機能、costPer1kTokens, rateLimits など）を Groqの公式ドキュメント を参照して正確な値を入力してください。
   • 調整: models.json の modelSelectionRules と complexityThresholds セクションを調整して、持っているモデルと希望する選択ロジック（例: reasoning, mathematical, multilingual の優先度）を反映させます。

5. src/config/constants.ts を更新します。

   • RATE_LIMITS 定数を models.json のモデルと同期します。models.json の各モデルに対応する RATE_LIMITS エントリがあり、正確な rpm（1分あたりのリクエスト数）と tpm（1分あたりのトークン数）が設定されていることを確認してください（最新の値はGroqのドキュメントを参照）。
   • ツールファイル（src/tools/*.ts）の z.enum を更新して、クライアントに公開したい新しいモデルを含めます。

6. プロジェクトをコンパイルします。

   npm run build
   

7. サーバーを起動します。

   npm start
   

   サーバーが起動し、stdin/stdout を介して接続を待機します。

💻 使用例

Claude Desktopでの使用

サーバーがローカルで起動している場合、Claude Desktopはサーバーを検出し、そのツールを使用できます。

1. Claude Desktopを起動します。
2. ツールを確認します。 Claude Desktopのインターフェイス（通常はツールメニューまたは統合メニュー）に、Groqのツール（groq_text_completion, groq_audio_transcription, groq_vision_analysis, groq_batch_processing）が有効になっているはずです。
3. 対話を開始します。 Claudeと会話を始め、ツールを使用するように依頼します。例:
   • groq_text_completionを使用して、GroqのAI機能についてのテキストを生成してください。
   • groq_text_completionツールで、金融データ { データ: [100, 250, 80, 400] } を分析し、llama-3.3-70b-versatile モデルを使用してください。
   • groq_audio_transcription: 'whisper-large-v3-turbo' を使用して、'caminho/para/seu/audio.mp3' の音声を文字起こししてください。
   • groq_vision_analysis: 'meta-llama/llama-4-scout-17b-16e-instruct' を使用して、'https://example.com/sua-imagem.jpg' の画像を説明してください。

📚 ドキュメント

プロジェクト構造

.
├── src/
│   ├── config/
│   │   ├── constants.ts         # システム定数 (RATE_LIMITS, API_ENDPOINTS, etc.)
│   │   └── models.json          # Groqモデルの詳細定義
│   ├── tools/
│   │   ├── audio-transcription.ts # 音声文字起こしツール
│   │   ├── batch-processing.ts    # バッチ処理ツール
│   │   ├── model-router.ts        # モデル選択の中心ロジック
│   │   ├── text-completion.ts     # テキスト生成ツール
│   │   └── vision-analysis.ts     # ビジョン分析ツール
│   │   └── ... (Text-to-Speechなどの新しいツールが実装された場合)
│   ├── types/
│   │   └── groq-types.ts          # GroqモデルのTypeScript型定義
│   ├── utils/
│   │   ├── cache-manager.ts       # キャッシュマネージャー
│   │   ├── error-handler.ts       # 集中型エラー処理とリトライ
│   │   ├── logger.ts              # Winstonによるログ設定
│   │   ├── metrics-tracker.ts     # 使用状況とパフォーマンスのメトリクス収集
│   │   └── rate-limiter.ts        # レート制限の実装
│   └── server.ts                  # MCPサーバーのメインエントリポイント
├── dist/                          # TypeScriptコンパイルの出力
├── logs/                          # アプリケーションのログ
├── .env                           # 環境変数 (例: GROQ_API_KEY)
├── .gitignore                     # Gitが無視するファイルとディレクトリ
├── package.json                   # プロジェクトのメタデータと依存関係
├── tsconfig.json                  # TypeScriptコンパイラの設定
└── README.md                      # このファイル

🔧 技術詳細

ウェブへの拡張（次のステップ）

このプロジェクトは、StdioServerTransport を使用したローカルでの使用を想定しています。ウェブサーバー環境（例: 本番環境）に拡張する場合、以下の点が重要です。

• 通信トランスポート: StdioServerTransport から、Server-Sent Events (SSE) やWebSocketなどのウェブトランスポートに移行して、ウェブクライアントとの通信を可能にします。
• 起動メカニズム: サーバーのライフサイクルを、HTTP/HTTPSポートでリッスンするウェブフレームワーク（例: Express, Fastify）に適応させます。
• プロトコル: MCPのJSON-RPC呼び出しに対応するHTTPルートを実装します。
• セキュリティ: 認証（例: JWT）、承認、HTTPS、CORS設定を追加して、サーバーを保護します。
• 拡張性: 複数のクライアントと高トラフィックを処理するための戦略（例: ロードバランシング、Node.jsクラスター、CacheManager と RateLimiter のためのRedisなどの分散キャッシュ）を実装します。

開発者: Ayrton Felipe