mcp-runner

mcp-runner

用于运行 MCP（Model Context Protocol）服务的 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]
# or
npm run cli -- runserver <server-name> [params] [options] # uses first available tool

选项：

• --text：仅输出响应中的文本内容，而不是完整的 JSON

示例：

# Run a specific tool
npm run cli -- runserver sequential-thinking sequentialthinking '{"thought": "Initial thought", "thoughtNumber": 1, "totalThoughts": 5, "nextThoughtNeeded": true}'

# Use first available tool
npm run cli -- runserver sequential-thinking '{"thought": "Initial thought", "thoughtNumber": 1, "totalThoughts": 5, "nextThoughtNeeded": true}'

# Output only text content
npm run cli -- runserver sequential-thinking sequentialthinking '{"thought": "Initial thought", "thoughtNumber": 1, "totalThoughts": 1}' --text

编程用法

基本示例

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

async function main() {
  try {
    // First call (specific tool)
    const result1 = await runServer('openrouterai', 'chat_completion', {
      messages: [
        { role: 'user', content: 'Say hello!' }
      ]
    });
    console.log('Result 1:', result1);

    // Second call (uses first available tool)
    const result2 = await runServer('openrouterai', undefined, {
      messages: [
        { role: 'user', content: 'How are you?' }
      ]
    });
    console.log('Result 2:', result2);

    // Terminate server when done
    await terminateServer();
  } catch (error) {
    console.error('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。