mcp-runner

一个用于运行MCP（模型上下文协议）服务器的TypeScript SDK和CLI工具。

概述

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: '说你好！' }
      ]
    });
    console.log('结果 1:', result1);

    // 第二次调用（使用第一个可用工具）
    const result2 = await runServer('openrouterai', undefined, {
      messages: [
        { role: 'user', content: '你好吗？' }
      ]
    });
    console.log('结果 2:', result2);

    // 所有操作完成后终止服务器
    await terminateServer();
  } catch (error) {
    console.error('错误:', error);
    await terminateServer();
  }
}

错误处理

SDK 包含全面的错误处理：

• 服务器进程错误
• 工具执行错误
• 超时处理以实现优雅终止
• 出现错误时自动清理

API

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

使用提供的参数在指定服务器上运行工具。服务器进程将在显式终止之前被后续调用重用。

参数：

• serverName: 配置中的服务器名称
• params: 传递给服务器工具的参数

返回：解决为服务器响应的Promise

terminateServer()

终止由SDK管理的服务器进程。应在所有操作完成后调用。

返回：服务器终止时解决的Promise

架构

ServerManager

ServerManager类实现为单例，负责MCP服务器进程的生命周期管理。主要职责包括：

• 进程生命周期管理
• 客户端连接处理
• 优雅终止
• 错误处理和日志记录

管理器确保任何时候只有一个服务器进程在运行，并提供启动、重用和终止服务器的方法。

配置

SDK从标准配置目录中的cline_mcp_settings.json读取服务器配置。每个服务器配置包括：

{
  "command": "string",
  "args": "string[]",
  "env": "Record<string, string>",
  "disabled": "boolean",
  "alwaysAllow": "string[]"
}

开发

构建

npm run build

运行测试

npm test

许可证

此项目根据Mozilla Public License 2.0许可 - 详情见LICENSE文件。

贡献

欢迎贡献！请随意提交Pull Request。