mcpixir (Ramonlimaramos)

Unified MCP Client Library for Elixir

 ](https://elixir-lang.org/) ](https://hex.pm/packages/mcpixir) ](https://hex.pm/packages/mcpixir)

🌐 Mcpixir是一种开源的连接方式 任何LLM到任何MCP服务器 并构建具有工具访问权限的自定义代理，而无需使用闭源或应用程序客户端。

💡 让开发人员轻松地将任何LLM连接到web浏览、文件操作等工具。

特性

✨ 主要特点

快速启动

添加 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

配置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服务器。此功能对于与基于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这使得需要来自不同服务器的工具的复杂工作流程成为可能，例如与文件操作或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使用允许您限制代理可用的工具，从而提供更好的安全性和对代理功能的控制：

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

路线图

• \[x\] 同时使用多台服务器
• \[x\] 测试远程连接器（http、ws）
• \[ \] ...

贡献

我们热爱贡献！对于bug或功能请求，请随时打开问题。

需求

• 灵丹妙药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

使用shell脚本

./bin/release.sh 0.2.0

这两种方法都将：

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

许可证

麻省理工学院