MCP Runner

MCP Runner

用于在本地运行和交互 Model Context Protocol（MCP）服务的 Rust 库。

概述

MCP Runner 为 Rust 应用管理 Model Context Protocol 服务提供了完整的解决方案。它支持：

• 启动和管理 MCP 服务进程
• 通过统一接口配置多个服务
• 使用 JSON-RPC 与 MCP 服务通信
• 列出并调用 MCP 服务提供的工具
• 访问 MCP 服务提供的资源
• 代理 Server-Sent Events（SSE），让客户端能够连接到 MCP 服务

安装

将以下内容添加到你的 Cargo.toml：

[dependencies]
mcp-runner = "0.3.1"

快速入门

以下是使用 MCP Runner 启动服务并调用工具的简单示例：

use mcp_runner::{McpRunner, error::Result};
use serde::{Deserialize, Serialize};
use serde_json::json;

#[tokio::main]
async fn main() -> Result<()> {
    // Create runner from config file
    let mut runner = McpRunner::from_config_file("config.json")?;

    // Start all servers and the SSE proxy if configured
    let (server_ids, proxy_started) = runner.start_all_with_proxy().await;
    let server_ids = server_ids?;

    if proxy_started {
        println!("SSE proxy started successfully");
    }

    // Get client for interacting with a specific server
    let server_id = runner.get_server_id("fetch")?;
    let client = runner.get_client(server_id)?;

    // Initialize the client
    client.initialize().await?;

    // List available tools
    let tools = client.list_tools().await?;
    println!("Available tools:");
    for tool in tools {
        println!("  - {}: {}", tool.name, tool.description);
    }

    // Call the fetch tool with structured input
    let fetch_result = client.call_tool("fetch", &json!({
        "url": "https://modelcontextprotocol.io"
    })).await?;
    println!("Fetch result: {}", fetch_result);

    // Stop the server when done
    runner.stop_server(server_id).await?;

    Ok(())
}

可观测性

此库使用 tracing crate 进行日志记录和诊断。要启用日志记录，请确保已在应用中配置 tracing_subscriber，并设置 RUST_LOG 环境变量。例如：

# Show info level logs for all crates
RUST_LOG=info cargo run --example simple_client

# Show trace level logs specifically for mcp_runner
RUST_LOG=mcp_runner=trace cargo run --example simple_client

配置

MCP Runner 使用 JSON 配置来定义 MCP 服务和可选的 SSE 代理设置。

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    }
  },
  "sseProxy": {
    "address": "127.0.0.1",
    "port": 3000,
    "allowedServers": ["fetch", "filesystem"],
    "authenticate": {
      "bearer": {
        "token": "your-secure-token"
      }
    }
  }
}

你可以通过以下三种方式加载配置：

1. 从文件加载

use mcp_runner::McpRunner;

let runner = McpRunner::from_config_file("config.json")?;

2. 从 JSON 字符串加载

use mcp_runner::McpRunner;

let config_json = r#"{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}"#;
let runner = McpRunner::from_config_str(config_json)?;

3. 以编程方式创建

use mcp_runner::{McpRunner, config::{Config, ServerConfig}};
use std::collections::HashMap;

let mut servers = HashMap::new();

let server_config = ServerConfig {
    command: "uvx".to_string(),
    args: vec!["mcp-server-fetch".to_string()],
    env: HashMap::new(),
};

servers.insert("fetch".to_string(), server_config);
let config = Config { mcp_servers: servers };

// Initialize the runner
let runner = McpRunner::new(config);

错误处理

MCP Runner 使用自定义错误类型，涵盖：

• 配置错误
• 服务生命周期错误
• 通信错误
• 序列化错误

match result {
    Ok(value) => println!("Success: {:?}", value),
    Err(Error::ServerNotFound(name)) => println!("Server not found: {}", name),
    Err(Error::Communication(msg)) => println!("Communication error: {}", msg),
    Err(e) => println!("Other error: {}", e),
}

核心组件

McpRunner

用于管理 MCP 服务的主要入口：

let mut runner = McpRunner::from_config_file("config.json")?;
let server_ids = runner.start_all_servers().await?;

McpClient

用于与 MCP 服务交互：

let client = runner.get_client(server_id)?;
client.initialize().await?;

// Call tools
let result = client.call_tool("fetch", &json!({
    "url": "https://example.com",
})).await?;

SSE 代理

SSE（Server-Sent Events）代理允许客户端通过 HTTP 连接到 MCP 服务，并使用 Server-Sent Events 协议接收实时更新。它基于 Actix Web 构建，提供统一的 JSON-RPC over HTTP 接口，具备高性能、高可靠性和易维护性。

功能

• 统一的 JSON-RPC API：通过单一端点使用 JSON-RPC 与 MCP 服务进行所有交互
• 身份验证：可选的 Bearer 令牌身份验证，确保访问安全
• 服务访问控制：限制可通过代理访问的服务
• 事件流：通过 SSE 将 MCP 服务的实时更新发送给客户端
• 跨域支持：内置 CORS 支持，适用于 Web 浏览器客户端
• JSON-RPC 兼容性：全面支持双向 JSON-RPC 2.0 消息
• 高效的事件广播：使用 Tokio 广播通道高效分发事件

启动代理

你可以在启动服务时自动启动 SSE 代理：

// Start all servers and the proxy if configured
let (server_ids, proxy_started) = runner.start_all_with_proxy().await;
let server_ids = server_ids?;

if proxy_started {
    println!("SSE proxy started successfully");
}

也可以在配置服务后手动启动：

if runner.is_sse_proxy_configured() {
    runner.start_sse_proxy().await?;
    println!("SSE proxy started manually");
}

代理配置

在配置文件中配置 SSE 代理：

{
  "mcpServers": { /* server configs */ },
  "sseProxy": {
    "address": "127.0.0.1",  // Listen address (localhost only) - default if omitted
    "port": 3000,            // Port to listen on - default if omitted
    "workers": 4,            // Number of worker threads - default is 4 if omitted
    "allowedServers": [      // Optional: restrict which servers can be accessed
      "fetch",
      "filesystem"
    ],
    "authenticate": {        // Optional: require authentication
      "bearer": {
        "token": "your-secure-token-here"
      }
    }
  }
}

代理 API 端点

SSE 代理提供以下 HTTP 端点：

端点	方法	描述
/sse	GET	用于接收实时更新的 SSE 事件流端点（发送 endpoint 和 message 事件）
/sse/messages	POST	用于向 MCP 服务发送请求的 JSON-RPC 端点（支持 initialize、tools/list、tools/call、ping）

示例

更多用法示例请参阅 examples/ 目录：

• simple_client.rs：客户端 API 的基本用法

  # Run with info level logging
  RUST_LOG=info cargo run --example simple_client
  

• sse_proxy.rs：使用 SSE 代理向 Web 客户端提供 MCP 服务的示例

  # Run with info level logging
  RUST_LOG=info cargo run --example sse_proxy
  

  此示例使用 examples/sse_config.json 中的配置来启动服务和 SSE 代理， 让 Web 客户端能够通过 HTTP 和 SSE 连接并与 MCP 服务交互。

  JavaScript 客户端示例：

  // Connect to the event stream
  const eventSource = new EventSource('http://localhost:3000/sse');
  
  // First you'll receive the endpoint information
  eventSource.addEventListener('endpoint', (event) => {
    console.log('Received endpoint path:', event.data);
  });
  
  // Then you'll receive JSON-RPC responses
  eventSource.addEventListener('message', (event) => {
    const response = JSON.parse(event.data);
    console.log('Received JSON-RPC response:', response);
  });
  
  // Make a tool call
  async function callTool() {
    const response = await fetch('http://localhost:3000/sse/messages', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': 'Bearer your-secure-token-here'
      },
      body: JSON.stringify({
        jsonrpc: '2.0',
        id: 1,
        method: 'tools/call',
        params: {
          server: 'fetch',
          tool: 'fetch',
          arguments: {
            url: 'https://modelcontextprotocol.io'
          }
        }
      })
    });
    const result = await response.json();
    console.log('Tool call initiated:', result);
    // Actual response will come through the SSE event stream
  }
  

参与贡献

欢迎参与贡献！欢迎提交 Pull Request。

许可证

本项目根据 LICENSE 文件中的条款授权。