MCP Runner

🚀 mcp-runner

mcp-runner 是一個基於 TypeScript 的 SDK 和 CLI 工具，用於運行 MCP（模型上下文協議）服務器。它能簡化 MCP 服務器的運行流程，支持進程複用和優雅清理，可通過命令行或作為庫在項目中使用。

🚀 快速開始

mcp-runner 旨在簡化根據 cline_mcp_settings.json 配置文件運行 MCP 服務器的過程。它支持服務器進程的複用和優雅清理，允許多次操作使用同一個服務器實例。你既可以從命令行調用它，也可以將其作為庫在你的 TypeScript 項目中使用，甚至可以用於其他 MCP 服務器。

✨ 主要特性

• 服務器進程複用
• 帶超時處理的優雅終止
• 自動管理服務器生命週期
• 支持 TypeScript
• 全面的錯誤處理和日誌記錄

📦 安裝指南

npm install

💻 使用示例

基礎用法

CLI 使用方法

該包包含一個命令行接口，用於與 MCP 服務器交互。

列出工具

列出指定 MCP 服務器的所有可用工具：

npm run cli -- list-tools <server-name>

示例：

npm run cli -- list-tools sequential-thinking

運行服務器

運行指定的 MCP 服務器，可選指定工具名稱和參數：

npm run cli -- runserver <server-name> [tool-name] [params] [options]
# 或
npm run cli -- runserver <server-name> [params] [options] # 使用第一個可用工具

選項：

• --text：僅輸出響應中的文本內容，而非完整的 JSON

示例：

# 運行特定工具
npm run cli -- runserver sequential-thinking sequentialthinking '{"thought": "初始思考", "thoughtNumber": 1, "totalThoughts": 5, "nextThoughtNeeded": true}'

# 使用第一個可用工具
npm run cli -- runserver sequential-thinking '{"thought": "初始思考", "thoughtNumber": 1, "totalThoughts": 5, "nextThoughtNeeded": true}'

# 僅輸出文本內容
npm run cli -- runserver sequential-thinking sequentialthinking '{"thought": "初始思考", "thoughtNumber": 1, "totalThoughts": 1}' --text

高級用法

程序化使用

import { runServer, terminateServer } from 'mcp-runner';

async function main() {
  try {
    // 第一次調用（指定工具）
    const result1 = await runServer('openrouterai', 'chat_completion', {
      messages: [
        { role: 'user', content: 'Say hello!' }
      ]
    });
    console.log('結果 1:', result1);

    // 第二次調用（使用第一個可用工具）
    const result2 = await runServer('openrouterai', undefined, {
      messages: [
        { role: 'user', content: 'How are you?' }
      ]
    });
    console.log('結果 2:', result2);

    // 完成時終止服務器
    await terminateServer();
  } catch (error) {
    console.error('錯誤:', error);
    await terminateServer();
  }
}

📚 詳細文檔

API 文檔

runServer(serverName: string, params: Record<string, unknown>)

在指定服務器上運行工具，使用提供的參數。服務器進程會在後續調用中複用，直到顯式終止。

參數：

• serverName：從配置文件中獲取的服務器名稱
• params：傳遞給工具的參數

terminateServer()

立即停止當前正在運行的服務器進程。

架構說明

ServerManager 類

ServerManager 是一個單例類，負責管理 MCP 服務器的生命週期。它會加載配置文件，創建和終止服務器實例，並處理錯誤。

ConfigurationLoader 類

ConfigurationLoader 負責從 cline_mcp_settings.json 文件中加載配置信息。它提供對服務器配置的讀取和更新功能。

配置文件格式

cline_mcp_settings.json 是一個 JSON 文件，定義了 MCP 服務器的相關配置：

{
  "servers": [
    {
      "name": "server1",
      "url": "http://localhost:8080",
      "tools": [
        {
          "name": "tool1",
          "command": "node tool1.js"
        }
      ]
    }
  ]
}

錯誤處理

所有操作都會在 ServerManager 中進行錯誤捕捉，並通過日誌記錄工具輸出詳細的錯誤信息。

示例

假設我們有一個名為 my_server 的服務器，配置如下：

{
  "servers": [
    {
      "name": "my_server",
      "url": "http://localhost:8000",
      "tools": [
        {
          "name": "tool_a",
          "command": "node tool_a.js"
        }
      ]
    }
  ]
}

運行服務器並使用工具 tool_a：

npm run cli -- runserver my_server tool_a '{"input": "data"}'

參考文檔

• MCP 協議
• Node.js 文檔
• 配置文件規範

📄 許可證

[項目許可證信息]