Unified MCP Client Library for Elixir

Elixir 向け統合 MCP クライアントライブラリ

🌐 Mcpixir は、クローズドソースのアプリケーションクライアントを使わずに、あらゆる LLM をあらゆる MCP サーバーに接続し、ツールにアクセスできるカスタムエージェントを構築するためのオープンソースの方法です。

💡 開発者が、ウェブ閲覧やファイル操作などのツールにあらゆる LLM を簡単に接続できるようにします。

機能

✨ 主な機能

機能	説明
🔄 使いやすさ	MCP 対応エージェントは、わずか 6 行のコードで作成できます
🤖 LLM の柔軟性	ツール呼び出しに対応するあらゆる LLM（OpenAI、Anthropic など）で動作します
🌐 HTTP サポート	特定の HTTP ポートで稼働する MCP サーバーに直接接続できます
⚙️ サーバーの動的選択	エージェントは、利用可能なサーバープールからタスクに最適な MCP サーバーを動的に選択できます
🧩 マルチサーバー対応	1 つのエージェントで複数の MCP サーバーを同時に使用できます
🛡️ ツールの制限	ファイルシステムやネットワークアクセスなど、潜在的に危険なツールを制限できます

クイックスタート

mix.exs の依存関係リストに mcpixir を追加します。

def deps do
  [
    {:mcpixir, "~> 0.1.0"}
  ]
end

または、ソースからインストールします。

git clone https://github.com/yourusername/mcpixir.git
cd mcpixir
mix deps.get
mix compile

LLM プロバイダーの設定

Mcpixir はさまざまな LLM プロバイダーに対応しています。アプリケーションで使用する LLM を設定する必要があります。使用するプロバイダーの API キーを環境変数に追加してください。

export OPENAI_API_KEY=your_openai_key_here
export ANTHROPIC_API_KEY=your_anthropic_key_here

重要：Mcpixir で使用できるのは、ツール呼び出し機能を備えたモデルのみです。選択したモデルが関数呼び出しまたはツール使用に対応していることを確認してください。

エージェントを起動する

# Create configuration dictionary
config = %{
  mcpServers: %{
    playwright: %{
      command: "npx",
      args: ["@playwright/mcp@latest"],
      env: %{
        DISPLAY: ":1"
      }
    }
  }
}

# Create MCP client from configuration dictionary
client = Mcpixir.new_client(config)

# Configure LLM
llm_config = %{
  provider: :openai,
  model: "gpt-4o"
}

# Create agent
{:ok, agent} = Mcpixir.new_agent(%{
  llm: llm_config,
  client: client
})

# Run the query
{:ok, result, updated_agent} = Mcpixir.run(agent, "Find the best restaurant in San Francisco")
IO.puts("\nResult: #{result}")

次のように、設定ファイルからサーバー設定を追加することもできます。

config_path = Path.join("path/to", "browser_mcp.json")
{:ok, config_data} = File.read(config_path)
{:ok, config} = Jason.decode(config_data)

client = Mcpixir.new_client(config)

設定ファイルの例（browser_mcp.json）：

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "DISPLAY": ":1"
      }
    }
  }
}

その他の設定、モデルなどについては、ドキュメントをご覧ください。

使用例

Playwright によるウェブ閲覧

# Create configuration
config = %{
  mcpServers: %{
    playwright: %{
      command: "npx",
      args: ["@playwright/mcp@latest"],
      env: %{
        DISPLAY: ":1"
      }
    }
  }
}

# Create the MCP client
client = Mcpixir.new_client(config)

# Configure LLM
llm_config = %{
  provider: :openai,
  model: "gpt-4o"
  # Alternative models:
  # provider: :anthropic, model: "claude-3-5-sonnet"
  # provider: :groq, model: "llama3-8b-8192"
}

# Create agent
{:ok, agent} = Mcpixir.new_agent(%{
  llm: llm_config,
  client: client
})

# Run the query
{:ok, result, updated_agent} = Mcpixir.run(agent, "Find the best restaurant in San Francisco USING GOOGLE SEARCH")
IO.puts("\nResult: #{result}")

# Ensure we clean up resources properly
Mcpixir.Client.stop_all_sessions(client)

Airbnb の検索

# Create configuration with Airbnb
config = %{
  mcpServers: %{
    airbnb: %{
      command: "npx",
      args: ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
    }
  }
}

# Create the MCP client
client = Mcpixir.new_client(config)

# Configure LLM
llm_config = %{
  provider: :anthropic,
  model: "claude-3-5-sonnet"
}

# Create agent
{:ok, agent} = Mcpixir.new_agent(%{
  llm: llm_config,
  client: client
})

# Run a query to search for accommodations
query = """
Find me a nice place to stay in Barcelona for 2 adults
for a week in August. I prefer places with a pool and
good reviews. Show me the top 3 options.
"""

{:ok, result, updated_agent} = Mcpixir.run(agent, query)
IO.puts("\nResult: #{result}")

# Ensure we clean up resources properly
Mcpixir.Client.stop_all_sessions(client)

設定ファイルの例（airbnb_mcp.json）：

{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@openbnb/mcp-server-airbnb"]
    }
  }
}

Blender による 3D 制作

# Create configuration with Blender
config = %{
  mcpServers: %{
    blender: %{
      command: "uvx",
      args: ["blender-mcp"]
    }
  }
}

# Create the MCP client
client = Mcpixir.new_client(config)

# Configure LLM
llm_config = %{
  provider: :anthropic,
  model: "claude-3-5-sonnet"
}

# Create agent
{:ok, agent} = Mcpixir.new_agent(%{
  llm: llm_config,
  client: client
})

# Run the query
{:ok, result, updated_agent} = Mcpixir.run(agent, "Create an inflatable cube with soft material and a plane as ground.")
IO.puts("\nResult: #{result}")

# Ensure we clean up resources properly
Mcpixir.Client.stop_all_sessions(client)

設定オプション

MCP-Use は設定ファイルからの初期化に対応しており、さまざまな MCP サーバー構成の管理や切り替えを簡単に行えます。

# Load configuration from file
config_path = Path.join("path/to", "mcp-config.json")
{:ok, config_data} = File.read(config_path)
{:ok, config} = Jason.decode(config_data)

# Create an MCP client from config
client = Mcpixir.new_client(config)

# Create and initialize a session
{:ok, client, session} = Mcpixir.Client.create_session(client, "http://localhost:8000")

# Use the session...

# Disconnect when done
Mcpixir.Client.stop_session(client, session.id)

HTTP 接続の例

Mcpixir は HTTP 接続に対応しているため、特定の HTTP ポートで稼働する MCP サーバーに接続できます。この機能は、ウェブベースの MCP サーバーとの統合に特に役立ちます。

HTTP 接続機能の使用例を以下に示します。

# Configuration with HTTP connection
config = %{
  mcpServers: %{
    http: %{
      url: "http://localhost:8931/sse"
    }
  }
}

# Create the MCP client
client = Mcpixir.new_client(config)

# Configure LLM
llm_config = %{
  provider: :openai,
  model: "gpt-4o"
}

# Create agent
{:ok, agent} = Mcpixir.new_agent(%{
  llm: llm_config,
  client: client
})

# Run the query
{:ok, result, updated_agent} = Mcpixir.run(agent, "Find the best restaurant in San Francisco USING GOOGLE SEARCH")
IO.puts("\nResult: #{result}")

この例では、特定の HTTP ポートで稼働する MCP サーバーへの接続方法を示します。この例を実行する前に、MCP サーバーを起動してください。

マルチサーバー対応

Mcpixir では、Mcpixir.Client を使用して複数の MCP サーバーを同時に設定し、接続できます。これにより、ウェブ閲覧とファイル操作、または 3D モデリングなど、異なるサーバーのツールを必要とする複雑なワークフローを実現できます。

設定

設定ファイルでは、複数のサーバーを設定できます。

{
  "mcpServers": {
    "airbnb": {
      "command": "npx",
      "args": ["-y", "@openbnb/mcp-server-airbnb", "--ignore-robots-txt"]
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {
        "DISPLAY": ":1"
      }
    }
  }
}

使用方法

Mcpixir.Client モジュールは、複数のサーバーへの接続を管理する関数を提供します。エージェントを作成する際に、複数のサーバーを設定したクライアントを渡すことができます。

デフォルトでは、エージェントは設定済みのすべてのサーバーのツールを利用できます。特定のタスクで特定のサーバーを対象にする必要がある場合は、エージェントの作成時にサーバーのパラメーターを指定できます。

# Create client with multiple servers
config = load_multi_server_config()
client = Mcpixir.new_client(config)

# Example: Running a query that may use tools from both servers
{:ok, agent} = Mcpixir.new_agent(%{
  llm: llm_config,
  client: client
})

# Query combining different capabilities
query = """
Search for a nice place to stay in Barcelona on Airbnb,
then use Google to find nearby restaurants and attractions.
"""

{:ok, result, _updated_agent} = Mcpixir.run(agent, query)

動的なサーバー選択（サーバーマネージャー）

異なるサーバーの多数のツールを扱う際の効率を高め、エージェントが混乱する可能性を減らすには、組み込みのサーバーマネージャー機能を利用できます。

この機能を有効にすると、LLM が特定のステップで選択したツールに基づいて、エージェントが適切な MCP サーバーをインテリジェントに選択します。これにより、不要な接続を最小限に抑え、タスクに適したツールをエージェントが確実に使用できます。

# Create client with multiple servers
config = load_multi_server_config()
client = Mcpixir.new_client(config)

# Create agent with server manager enabled
{:ok, agent} = Mcpixir.new_agent(%{
  llm: llm_config,
  client: client,
  use_server_manager: true  # Enable the Server Manager
})

# Run a query that uses tools from multiple servers
{:ok, result, _updated_agent} = Mcpixir.run(agent, """
  Search for a nice place to stay in Barcelona on Airbnb,
  then use Google to find nearby restaurants and attractions.
""")

ツールアクセス制御

MCP-Use では、エージェントが利用できるツールを制限できるため、エージェントの機能に対するセキュリティと制御を強化できます。

# Create client
config = load_config()
client = Mcpixir.new_client(config)

# Create agent with restricted tools
{:ok, agent} = Mcpixir.new_agent(%{
  llm: llm_config,
  client: client,
  disallowed_tools: ["file_system", "network"]  # Restrict potentially dangerous tools
})

# Run a query with restricted tool access
{:ok, result, _updated_agent} = Mcpixir.run(agent, "Find the best restaurant in San Francisco")

サンプルの実行

ライブラリのさまざまな機能を紹介する Mix タスクを用意しています。これらのタスクでは、実際の LLM と MCP サーバーを使用して、すべての機能を紹介します。

Mix タスク

mix mcp を実行すると、利用可能なすべてのサンプルを確認できます。

mix mcpixir

利用可能なサンプル：

• mix mcpixir.chat - ツールを使ったシンプルなチャットのやり取り
• mix mcpixir.airbnb - Airbnb との連携を紹介するサンプル
• mix mcpixir.blender - Blender 3D ソフトウェアを操作するサンプル
• mix mcpixir.browser - Playwright を使ったウェブ閲覧
• mix mcpixir.filesystem - ファイルシステムの操作
• mix mcpixir.http - MCP サーバーへの HTTP 接続
• mix mcpixir.multi - 複数の MCP サーバーを組み合わせて使用

特定のサンプルのヘルプを表示するには、次のコマンドを実行します。

mix help mcpixir.chat

サンプルの実行

各サンプルは、次の形式で実行できます。

# Basic usage
mix mcpixir.chat

# With options
mix mcpixir.browser --provider=anthropic --query="Find the top 5 Elixir packages on Hex.pm"

共通オプション

ほとんどのサンプルでは、次の共通オプションを利用できます。

• --provider=[openai|anthropic] - 使用する LLM プロバイダー
• --model=MODEL - 使用する特定の LLM モデル
• --query=QUERY - LLM に送信するクエリ

API キー

これらのサンプルでは、OpenAI または Anthropic の API キーが必要です。環境変数に設定してください。

# For OpenAI
export OPENAI_API_KEY=your-openai-key

# For Anthropic
export ANTHROPIC_API_KEY=your-anthropic-key

デバッグ

Mcpixir には、エージェントの実装に関する問題の診断に役立つロギング機能が組み込まれています。

ロギングの設定

ロギングを設定する方法はいくつかあります。

1. 環境変数

MCP_USE_LOG_LEVEL 環境変数を使ってログレベルを設定します。

export MCP_USE_LOG_LEVEL=debug  # Options: debug, info, warn, error

2. プログラムによるログレベルの設定

コード内でログレベルを直接設定できます。

# Set global log level
Mcpixir.Logging.set_level(:debug)  # Options: :debug, :info, :warning, :error

3. mix.exs または config.exs での設定

# In config/config.exs
config :mcpixir,
  log_level: :debug

ロードマップ

• 複数のサーバーを同時に利用
• リモートコネクター（http、ws）のテスト
• ...

コントリビューション

コントリビューションを歓迎します。バグや機能リクエストについては、お気軽に Issue を作成してください。

要件

• Elixir 1.15+
• Erlang/OTP 25+
• MCP の実装（Playwright MCP など）
• LLM API へのアクセス（OpenAI、Anthropic など）

コントリビューション

開発プロセス

このプロジェクトをより良くするためのコントリビューションを歓迎します。始めるには、次の手順に従ってください。

# Clone the repository
git clone https://github.com/yourusername/mcp-use-elixir.git
cd mcp-use-elixir

# Install dependencies
mix deps.get

# Run tests
mix test

# Run the code formatter
mix format

# Run the linter
mix credo

リリースプロセス

このプロジェクトではセマンティックバージョニングを採用し、体系化されたリリースプロセスを使用しています。新しいバージョンは、次のいずれかの方法でリリースできます。

Mix タスクを使用する

mix mcp.release 0.2.0

シェルスクリプトを使用する

./bin/release.sh 0.2.0

どちらの方法でも、次の処理が行われます。

1. 作業ディレクトリがクリーンであることを確認する
2. mix.exs のバージョンを更新する
3. CHANGELOG.md を新しいバージョンに更新する
4. すべてが正常に動作することを確認するため、テストを実行する
5. ドキュメントをコンパイルする
6. git コミットとタグを作成する
7. Hex.pm に公開する

ライセンス

MIT