Ollama Hive MCP Server

Ollama Hive MCP Server

LangChain を使用して Ollama モデルと連携する、TypeScript ベースの Model Context Protocol（MCP）サーバーです。このサーバーは、標準化された MCP インターフェースを通じてローカル言語モデルにクエリを実行するためのツールとリソースを提供し、モデルごとの MCP サーバー設定に対応しています。

特徴

• モデル管理：複数の Ollama モデルを設定および管理します
• モデルごとの MCP：各モデルに独自の MCP サーバー群を設定できます
• セッション管理：複数のクエリにわたってコンテキストを維持する会話セッション
• 環境変数のサポート：環境変数を使用してエンドポイントと設定を上書きできます
• LangChain との統合：モデルとのやり取りに LangChain を活用します
• 環境ベースの設定：MCP_CONFIG_PATH から設定を読み込みます
• MCP ツール：モデルへのクエリ、接続テスト、利用可能なモデルの一覧表示
• MCP リソース：モデルの設定とメタデータにアクセスできます
• Stdio トランスポート：シームレスな統合を実現する標準入力／出力通信
• 事前設定済みモデル：固有のエンドポイントと設定を指定したモデルを定義できます
• モデルの事前読み込み：すばやく応答できるよう、すべてのモデルを起動時に読み込みます
• パフォーマンス監視：応答時間の追跡とステータス監視を標準で備えています

NPX ですぐに開始

インストールせずに npx でサーバーを直接実行できます：

# Basic usage
npx ollama-hive-mcp-server

# With custom configuration
MCP_CONFIG_PATH=./my-config.json npx ollama-hive-mcp-server

# With environment overrides
OLLAMA_ENDPOINT=http://localhost:11434 MCP_CONFIG_PATH=./config.json npx ollama-hive-mcp-server

シンプルなインターフェース

サーバーは、すっきりとしたシンプルなインターフェースを提供します：

利用可能なツール

• query_model - オプションのセッションコンテキストを使用して、事前設定済みモデルにクエリを実行します
• test_model - モデルの接続をテストします
• get_model_info - モデルの詳細と MCP 情報を取得します
• list_models - 設定済みのすべてのモデルを一覧表示します
• get_config_summary - 設定の概要を表示します
• get_loading_status - モデルの読み込み状況を表示します
• create_session - コンテキストを維持する会話セッションを作成します
• list_sessions - アクティブな会話セッションをすべて一覧表示します
• get_session - セッションの詳細情報とメッセージ履歴を取得します
• delete_session - 特定の会話セッションを削除します
• clear_sessions - すべての会話セッションを消去します

使用例

{
  "tool": "query_model",
  "arguments": {
    "prompt": "Hello, world!"
  }
}

{
  "tool": "query_model", 
  "arguments": {
    "model": "llama3.2",
    "prompt": "Write a Python function to calculate fibonacci"
  }
}

{
  "tool": "query_model",
  "arguments": {
    "prompt": "Explain quantum computing",
    "createSession": true
  }
}

セッションベースの会話

{
  "tool": "create_session",
  "arguments": {
    "modelName": "llama3.2",
    "title": "Coding Session"
  }
}

{
  "tool": "query_model",
  "arguments": {
    "sessionId": "your-session-id",
    "prompt": "Write a Python function to calculate fibonacci"
  }
}

{
  "tool": "query_model",
  "arguments": {
    "sessionId": "your-session-id", 
    "prompt": "Now add error handling to that function"
  }
}

モデルは、事前設定された設定（temperature、エンドポイント、MCP サーバー）を自動的に使用します。セッションは会話のコンテキストを維持し、自然な複数ターンのやり取りを可能にします。

ドキュメント

• セッション管理ガイド - 会話セッションの使用に関する完全なガイド
• テストガイド - 包括的なテストと検証の手順
• ロギングシステム - MCP 互換ロギングシステムのドキュメント

前提条件

• Node.js 18+
• Ollama がローカルで稼働していること（デフォルト：http://localhost:11434）
• カスタマイズする場合は TypeScript の知識

インストール

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

git clone <repository-url>
cd ollama-hive

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

設定

環境変数

次の環境変数を設定してサーバーを構成します：

# Required: Path to your MCP configuration file
export MCP_CONFIG_PATH=/path/to/your/mcp-config.json

# Optional: Override Ollama endpoint for all models
export OLLAMA_ENDPOINT=http://localhost:11434

# Optional: Enable debug logging
export DEBUG=true

# Optional: Set Node environment
export NODE_ENV=production

設定ファイルの形式

次の構造で JSON 設定ファイルを作成します：

{
  "globalEndpoint": "http://localhost:11434",
  "models": [
    {
      "name": "llama3.2",
      "endpoint": "http://custom-endpoint:11434",
      "model": "llama3.2:latest", 
      "temperature": 0.7,
      "maxTokens": 2048,
      "description": "Llama 3.2 model for general purpose tasks",
      "mcps": [
        {
          "name": "filesystem-server",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
          "description": "Filesystem access MCP server",
          "env": {
            "NODE_ENV": "production"
          }
        }
      ]
    }
  ],
  "defaultModel": "llama3.2"
}

設定フィールド

グローバル設定：

• globalEndpoint：すべてのモデルに適用するデフォルトのエンドポイント（任意）
• defaultModel：使用するデフォルトモデルの名前（任意）

モデル設定：

• name：モデルの一意な識別子（必須）
• endpoint：モデル固有のエンドポイントの上書き設定（任意）
• model：Ollama モデル名（必須、例：llama3.2:latest）
• temperature：応答生成時の温度（0.0～2.0）（任意、デフォルト：0.7）
• maxTokens：生成するトークンの最大数（任意）
• description：人が読める説明（任意）
• mcps：このモデル用の MCP サーバーの配列（任意、デフォルト：[]）

MCP サーバー設定：

• name：MCP サーバーの一意な識別子（必須）
• command：サーバーを実行するコマンド（必須）
• args：コマンドライン引数（任意）
• env：サーバーの環境変数（任意）
• description：人が読める説明（任意）

エンドポイント解決の優先順位

サーバーは、次の優先順位でエンドポイントを解決します。

1. OLLAMA_ENDPOINT 環境変数（最優先）
2. モデル固有の endpoint 設定
3. グローバルな globalEndpoint 設定
4. デフォルト：http://localhost:11434（優先度が最も低い）

設定例

複数のモデルと、それぞれに関連付けられた MCP サーバーを含む完全な例については、config/example-mcp-config.json を参照してください。

使用方法

サーバーの起動

# Set configuration path
export MCP_CONFIG_PATH=./config/example-mcp-config.json

# Optional: Override Ollama endpoint
export OLLAMA_ENDPOINT=http://localhost:11434

# Start the server
npm start

開発モード

npm run dev

MCP Inspector の使用

MCP Inspector でサーバーをテストします。

npm run inspector

利用可能なツール

query_model

設定済みの Ollama モデルにプロンプトを送信して問い合わせます。

パラメーター：

• prompt（必須）：モデルに送信するプロンプト
• model（任意）：モデル名（指定しない場合はデフォルトを使用）
• sessionId（任意）：会話のコンテキストに使用するセッション ID
• createSession（任意）：sessionId が指定されていない場合に新しいセッションを自動作成します（会話の継続を自動化します）

例：

{
  "model": "llama3.2",
  "prompt": "Explain the concept of Model Context Protocol",
  "createSession": true
}

セッションの例：

// Auto-create session for conversation continuity
{
  "prompt": "Write a Python function",
  "createSession": true
}

// Use existing session
{
  "prompt": "Now add error handling to that function",
  "sessionId": "existing-session-id"
}

test_model

特定のモデルとその MCP 接続の接続状況をテストします。

パラメーター：

• model（必須）：テストするモデルの名前

例：

{
  "model": "llama3.2"
}

get_model_info

モデルとその MCP サーバーに関する詳細情報を取得します。

パラメーター：

• model（必須）：情報を取得するモデルの名前

例：

{
  "model": "codellama"
}

list_models

利用可能な設定済みモデルを、MCP の数とともに一覧表示します。

パラメーター： なし

get_config_summary

環境変数による上書き設定を含む、設定の概要を取得します。

パラメーター： なし

利用可能なリソース

model://list

解決済みのエンドポイントと利用可能状況を含む、設定済みモデルの一覧を返します。

model://default

デフォルトモデルの設定を返します。

model://{name}

名前を指定して、特定のモデルの設定を返します。

config://summary

環境変数による上書き設定を含む、設定の概要を返します。

config://environment

現在の環境設定を返します。

統合例

Claude Desktop との連携

Claude Desktop の設定に追加します。

{
  "mcpServers": {
    "ollama-hive": {
      "command": "node",
      "args": ["/path/to/ollama-hive/dist/index.js"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/your/config.json",
        "OLLAMA_ENDPOINT": "http://localhost:11434"
      }
    }
  }
}

Cursor IDE との連携

Cursor の MCP 設定で構成します。

{
  "servers": {
    "ollama-hive": {
      "command": "node",
      "args": ["/path/to/ollama-hive/dist/index.js"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/your/config.json",
        "OLLAMA_ENDPOINT": "http://localhost:11434"
      }
    }
  }
}

環境ファイルの設定

プロジェクトのルートに .env ファイルを作成します。

MCP_CONFIG_PATH=./config/example-mcp-config.json
OLLAMA_ENDPOINT=http://localhost:11434
DEBUG=false
NODE_ENV=development

モデル固有の MCP

各モデルに独自の MCP サーバーを設定できるため、用途に合わせたツールセットを利用できます。

• 汎用モデル：ファイルシステム、ウェブ検索、メモリーツール
• コードモデル：GitHub 連携、コード用ファイルシステム、ドキュメントツール
• リサーチモデル：ウェブ検索、学術データベース、参考資料ツール
• クリエイティブモデル：画像生成、クリエイティブライティングツール

これにより、各モデルの想定用途に合わせて利用可能なツールを調整できます。

エラー処理

サーバーには包括的なエラー処理が含まれています。

• 設定エラー：無効な JSON、または必須フィールドの不足
• 環境エラー：環境変数の不足、または無効な環境変数
• モデルエラー：接続の失敗、または無効なモデル名
• MCP エラー：MCP サーバーへの接続、またはツール実行の失敗
• ツールエラー：無効なパラメーター、または実行の失敗

すべてのエラーは、詳細なエラーメッセージを含む標準化された形式で返されます。

開発

プロジェクト構成

src/
├── index.ts           # Main server implementation
├── config.ts          # Configuration loader with environment support
├── langchain-manager.ts # LangChain model management with MCP integration
└── types.ts           # TypeScript type definitions

config/
└── example-mcp-config.json # Example configuration

ビルド

npm run build

変更の監視

npm run watch

型チェック

このプロジェクトでは、包括的な型安全性を備えた厳格な TypeScript 設定を使用しています。

セキュリティに関する考慮事項

• モデルへのアクセス：設定済みのモデルのみアクセスできます
• MCP の分離：各モデルの MCP は、ほかのモデルから分離されています
• 設定の検証：すべての設定は Zod スキーマを使用して検証されます
• 環境変数のセキュリティ：機密データは環境変数を介して渡すことができます
• エラーのサニタイズ：情報漏えいを防ぐため、エラーメッセージはサニタイズされます

パフォーマンス

• 接続の再利用：リクエスト間でモデル接続を再利用します
• 遅延読み込み：モデルと MCP は、初めてアクセスされたときにのみ初期化されます
• 環境のキャッシュ：環境設定は起動時にキャッシュされます
• メモリー管理：適切なクリーンアップにより、メモリーを効率的に使用します

トラブルシューティング

よくある問題

1. 「Configuration not loaded」エラー

   • MCP_CONFIG_PATH が正しく設定されていることを確認してください
   • 設定ファイルが存在し、有効な JSON であることを確認してください

2. 「Model not found」エラー

   • 設定済みのエンドポイントで Ollama が実行されていることを確認してください
   • モデル名が Ollama のモデル名と完全に一致していることを確認してください
   • エンドポイントの解決順序を確認してください

3. 接続のタイムアウト

   • Ollama サーバーにアクセスできることを確認してください
   • リモートエンドポイントを使用している場合は、ファイアウォールの設定を確認してください
   • OLLAMA_ENDPOINT 環境変数が設定されている場合は、その値を確認してください

4. MCP サーバーへの接続の問題

   • MCP サーバーのコマンドと引数を確認してください
   • MCP サーバーの環境変数を確認してください
   • MCP パッケージがインストールされていることを確認してください

デバッグモード

デバッグログを有効にします。

export DEBUG=true
npm start

貢献

1. リポジトリをフォークします
2. 機能ブランチを作成します
3. 変更を加えます
4. 該当する場合はテストを追加します
5. プルリクエストを送信します

ライセンス

MIT ライセンスです。詳細は LICENSE ファイルを参照してください。

関連プロジェクト

• Model Context Protocol
• MCP TypeScript SDK
• LangChain
• Ollama

サポート

質問やサポートについては、以下をご利用ください。

• リポジトリに issue を作成する
• MCP ドキュメントを確認する
• LangChain ドキュメントを確認する