MCP Runner

MCP Runner

Rust ライブラリを使用して、Model Context Protocol（MCP）サーバーをローカルで実行し、操作できます。

概要

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 クレートを使用します。ログを有効にするには、アプリケーションで 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 では、MCP サーバーとオプションの SSE プロキシ設定を JSON で定義します。

{
  "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"
      }
    }
  }
}

設定は、次の 3 つの方法で読み込めます。

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 を基盤としており、高いパフォーマンス、信頼性、保守性を備えた、統一された HTTP 経由の JSON-RPC インターフェースを提供します。

機能

• 統一された JSON-RPC API：JSON-RPC を介したすべての MCP サーバーとのやり取りに使える単一のエンドポイント
• 認証：安全なアクセスのためのオプションの Bearer トークン認証
• サーバーアクセス制御：プロキシ経由でアクセスできるサーバーを制限
• イベントストリーミング：SSE を介して MCP サーバーからクライアントへリアルタイム更新を配信
• クロスオリジン対応：ウェブブラウザーのクライアント向けに CORS を標準でサポート
• 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 プロキシを使用して MCP サーバーをウェブクライアントに公開する例

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

  この例では、examples/sse_config.json の設定を使用してサーバーと SSE プロキシを起動し、 ウェブクライアントが 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
  }
  

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

ライセンス

このプロジェクトは、LICENSE ファイルに記載された条件に基づいてライセンスされています。