🚀 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 文档
• 配置文件规范

📄 许可证

[项目许可证信息]