MCP Runner

🚀 mcp-runner

A TypeScript-based SDK and CLI tool for running MCP (Model Context Protocol) servers.

mcp-runner simplifies the process of running MCP servers based on the cline_mcp_settings.json configuration file. It supports server process reuse and graceful cleanup, allowing multiple operations to use the same server instance. You can either call it from the command line or use it as a library in your TypeScript project, even for other MCP servers.

🚀 Quick Start

mcp-runner aims to streamline the operation of MCP servers according to the cline_mcp_settings.json configuration file. It supports server process reuse and graceful termination, enabling multiple operations to share the same server instance. You can invoke it via the command line or integrate it as a library into your TypeScript project, and it's also applicable to other MCP servers.

✨ Features

• Server process reuse
• Graceful termination with timeout handling
• Automatic server lifecycle management
• TypeScript support
• Comprehensive error handling and logging

📦 Installation

npm install

💻 Usage Examples

CLI Usage

This package includes a command-line interface for interacting with MCP servers.

Commands

List Tools

List all available tools for a specified MCP server:

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

Example:

npm run cli -- list-tools sequential-thinking

Run Server

Run a specified MCP server, optionally specifying the tool name and parameters:

npm run cli -- runserver <server-name> [tool-name] [params] [options]
# or
npm run cli -- runserver <server-name> [params] [options] # Use the first available tool

Options:

• --text: Output only the text content from the response, rather than the full JSON.

Examples:

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

# Use the 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

Programmatic Usage

Basic Example

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

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

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

    // Terminate the server when done
    await terminateServer();
  } catch (error) {
    console.error('Error:', error);
    await terminateServer();
  }
}

Error Handling

The SDK provides comprehensive error handling:

• Server process errors
• Tool execution errors
• Graceful termination with timeout handling
• Automatic cleanup on error

📚 Documentation

API

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

Run a tool on a specified server, passing the provided parameters. The server process will be reused for subsequent calls until explicitly terminated.

Parameters:

• serverName: The server name retrieved from the configuration file.
• params: The parameters passed to the tool.

terminateServer()

Immediately stop the currently running server process.

Architecture

ServerManager Class

The ServerManager is a singleton class responsible for managing the lifecycle of MCP servers. It loads the configuration file, creates and terminates server instances, and handles errors.

ConfigurationLoader Class

The ConfigurationLoader is responsible for loading configuration information from the cline_mcp_settings.json file. It provides read and update capabilities for server configurations.

Configuration File Format

cline_mcp_settings.json is a JSON file that defines the relevant configurations for MCP servers:

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

Error Handling

All operations are error-captured in the ServerManager, and detailed error information is output via the logging tool.

Example

Suppose we have a server named my_server with the following configuration:

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

Run the server and use the tool tool_a:

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

Reference Documents

• MCP Protocol
• Node.js Documentation
• Configuration File Specification

📄 License

[Project license information]