Unified MCP Client Library for Elixir

适用于 Elixir 的统一 MCP 客户端库

🌐 Mcpixir 是一种开源方式，可连接任意大模型与任意 MCP 服务，并构建可使用工具的自定义 Agent，无需使用闭源客户端或应用客户端。

💡 让开发者轻松将任意大模型连接到网页浏览、文件操作等工具。

功能

✨ 主要功能

功能	描述
🔄 易于使用	只需 6 行代码即可创建首个支持 MCP 的 Agent
🤖 大模型灵活性	适用于任何支持工具调用的大模型（OpenAI、Anthropic 等）
🌐 HTTP 支持	直接连接到运行在指定 HTTP 端口上的 MCP 服务
⚙️ 动态服务选择	Agent 可从可用服务池中动态选择最适合当前任务的 MCP 服务
🧩 多服务支持	在单个 Agent 中同时使用多个 MCP 服务
🛡️ 工具限制	限制可能有危险的工具，例如文件系统或网络访问

快速开始

将 mcpixir 添加到 mix.exs 的依赖列表中：

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

或者从源代码安装：

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

配置大模型提供商

Mcpixir 适用于多种大模型提供商。你需要在应用中配置首选的大模型。在环境变量中添加所需提供商的 API 密钥：

export OPENAI_API_KEY=your_openai_key_here
export ANTHROPIC_API_KEY=your_anthropic_key_here

重要：只有支持工具调用的模型才能与 Mcpixir 一起使用。请确保你选择的模型支持函数调用或工具使用。

启动你的 Agent：

# 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 服务。此功能对于集成基于 Web 的 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 模块提供了用于管理与多个服务连接的函数。创建 Agent 时，可以提供配置了多个服务的客户端。

默认情况下，Agent 可以使用所有已配置服务中的工具。如果需要针对特定任务使用特定服务，可以在创建 Agent 时指定服务参数。

# 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)

动态选择服务（服务管理器）

为提高效率，并减少 Agent 在处理来自不同服务的大量工具时可能产生的困惑，你可以使用内置的服务管理器功能。

启用后，Agent 会根据大模型为特定步骤选择的工具，智能地选择正确的 MCP 服务。这可以最大限度地减少不必要的连接，并确保 Agent 使用适合任务的工具。

# 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 支持限制 Agent 可用的工具，从而更好地保障安全并控制 Agent 的能力：

# 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 任务，用于演示该库的不同功能。这些任务使用真实的大模型和 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 - 通过 HTTP 连接 MCP 服务
• 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] - 要使用的大模型提供商
• --model=MODEL - 要使用的特定大模型
• --query=QUERY - 要发送给大模型的查询

API 密钥

这些示例需要 OpenAI 或 Anthropic 的 API 密钥。请在环境中设置：

# For OpenAI
export OPENAI_API_KEY=your-openai-key

# For Anthropic
export ANTHROPIC_API_KEY=your-anthropic-key

调试

Mcpixir 提供内置日志记录，帮助诊断 Agent 实现中的问题。

配置日志记录

配置日志记录有几种方式：

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）
• ...

贡献

欢迎参与贡献！如发现错误或有功能请求，请随时提交问题。

要求

• Elixir 1.15+
• Erlang/OTP 25+
• MCP 实现（例如 Playwright MCP）
• 大模型 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

使用 shell 脚本

./bin/release.sh 0.2.0

两种方式都会：

1. 检查工作目录是否干净
2. 更新 mix.exs 中的版本
3. 使用新版本更新 CHANGELOG.md
4. 运行测试，确保一切正常
5. 编译文档
6. 创建 git 提交和标签
7. 发布到 Hex.pm

许可证

MIT