关键词

LLM代理上下文桥接OAuth认证AI工具管理Stdio转HTTP

项目简介

'Beeper MCP远程连接器'（'@beeper/mcp-remote'）是一个功能强大的代理工具，旨在弥合本地MCP客户端（如Claude Desktop、Raycast等，它们通常只支持通过标准输入/输出Stdio进行本地MCP服务器通信）与部署在远端的MCP服务器之间的连接鸿沟。它作为一个中间桥梁，将本地客户端的请求转发到远程MCP服务器，并将远程服务器的响应传回给本地客户端。更重要的是，它集成了OAuth 2.0认证流程，使得本地客户端能够安全地访问需要身份验证的远程MCP服务，并处理了网络传输协议的转换（如从Stdio到SSE/HTTP）。

主要功能点

  • 本地到远程的协议转换：将本地MCP客户端的Stdio（标准输入/输出）通信无缝转换为与远程MCP服务器交互所需的HTTP或SSE（Server-Sent Events）协议。
  • OAuth 2.0 认证支持：处理与远程MCP服务器的安全认证过程，包括客户端注册、令牌获取和刷新，确保客户端能够安全地访问受保护的资源。
  • 透明的MCP通信代理：在本地客户端和远程服务器之间透明地转发MCP协议的JSON-RPC请求和响应，允许LLM客户端像与本地服务器一样调用远程工具和访问上下文。
  • 工具过滤与管理：支持根据配置过滤或隐藏远程MCP服务器提供的特定工具，允许管理员或用户对可用的LLM工具进行细粒度控制。
  • 多实例协调：通过智能锁机制，确保当多个客户端实例尝试连接同一远程MCP服务器时，只有一个实例会发起OAuth认证流程，避免重复操作和冲突。
  • 灵活的传输策略：支持配置不同的传输连接策略（如优先使用SSE或HTTP），以适应不同的网络环境和远程服务器能力。

安装步骤

  1. 确保Node.js环境已准备就绪：'@beeper/mcp-remote' 是一个基于Node.js的包，请确保您的系统已安装Node.js（推荐LTS版本）和npm（或yarn）。
  2. 安装'@beeper/mcp-remote'包：通过npm或yarn全局安装此包，以便在命令行中方便地调用。 
    npm install -g @beeper/mcp-remote
# 或者使用 yarn
yarn global add @beeper/mcp-remote
    您也可以选择使用 'npx @beeper/mcp-remote ...' 直接运行而不进行全局安装。

服务器配置 (面向MCP客户端)

在您的MCP客户端配置文件中（例如，'claude_desktop_config.json' 或 Raycast 的扩展配置），您需要将 '@beeper/mcp-remote' 配置为连接到远程MCP服务器的中间代理。 通常，这会涉及以下几个关键配置项，它们将在客户端启动时调用此代理：

  • 服务器名称 (server name)：您为该MCP服务器连接定义的名称，例如 "Beeper Remote"。
  • 命令 (command)：用于启动此代理进程的命令，通常是 'npx'。
  • 参数 (args)：一个字符串数组，包含了传递给 'npx' 命令的参数。这些参数将指导代理如何运行和连接到远程服务器。
    • '@beeper/mcp-remote': 这是指定启动代理的核心包名称。
    • 远程MCP服务器URL (Remote MCP Server URL): 这是您的实际远程MCP服务器的完整地址，例如 'https://api.beeper.com/v0/mcp'。
    • 回调端口 (Callback Port): 可选参数，指定OAuth认证流程使用的本地监听端口。如果省略，代理将自动选择一个可用端口。
    • '--client <client-name>': 可选参数，用于告知代理当前使用的MCP客户端类型，例如 'claude-desktop' 或 'raycast'，以便代理可以针对特定客户端优化用户体验或回调行为。
    • '--header "Name: Value"': 可选参数，用于在向远程MCP服务器发起请求时添加自定义HTTP请求头，例如用于API密钥或特定的认证信息。
    • '--allow-http': 可选参数，如果您需要连接非HTTPS的远程服务器（除非是本地'localhost'地址），则需要提供此标志。
    • '--ignore-tool <tool-pattern>': 可选参数，指定一个或多个需要从远程MCP服务器返回的工具列表中隐藏的工具名称模式（支持通配符'*'）。

例如，对于Claude Desktop的'claude_desktop_config.json'文件，在'mcpServers'部分，您可能会看到类似如下的参数配置逻辑：

{
  "mcpServers": {
    "BeeperRemote": {
      "command": "npx",
      "args": [
        "@beeper/mcp-remote",
        "https://api.beeper.com/v0/mcp", 
        "--client", "claude-desktop",
        "--ignore-tool", "dangerousTool*"
      ],
      "env": {
        "BEEPER_DESKTOP_BASE_URL": "http://localhost:23373" 
      }
    }
  }
}

（注意：上方仅为JSON参数示意，实际客户端配置可能有所不同，请参照您的MCP客户端的官方文档。）

基本使用方法

当您的MCP客户端（例如Claude Desktop）启动并尝试连接到您配置的MCP服务器时，它实际上会启动 '@beeper/mcp-remote' 代理。

  1. 自动启动与认证：代理启动后，如果需要OAuth认证，它会自动在您的默认浏览器中打开一个授权页面。
  2. 完成浏览器认证：您需要在浏览器中完成远程MCP服务器的登录和授权过程。
  3. 连接成功：认证成功后，浏览器页面会显示连接成功的提示，代理将自动捕获授权码并完成令牌交换。
  4. 透明使用：一旦认证完成，您的本地MCP客户端就可以像连接到本地MCP服务器一样，通过 '@beeper/mcp-remote' 代理与远程MCP服务器进行交互，调用其工具和访问上下文信息。

如果过程中出现错误或需要调试，代理会在标准错误输出（stderr）中打印日志信息。在调试模式下（通过 '--debug' 参数启动），还会生成详细的日志文件。

信息

分类

AI与计算

访问项目