manage-bg-mcp

mizunashi-mana/manage-bg-mcp

3.1

If you are the rightful owner of manage-bg-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Background Process Management MCP Server is designed to efficiently manage and monitor background processes using AI agents, providing comprehensive functionality for process management and log retrieval.

Tools
7
Resources
0
Prompts
0

Background Process Management MCP Server

CI npm version npm downloads License

A Model Context Protocol (MCP) server for managing background processes with AI agents.

Overview

This MCP server enables AI agents to efficiently manage and monitor background processes. It provides comprehensive functionality for process startup, termination, log retrieval, and resource management with a unified time-series log system.

Features

  • Process Management: Start, stop, and restart background processes
  • Unified Log Management: Real-time log capture with chronological ordering across stdout/stderr
  • Resource Management: Configurable limits for concurrent processes and log storage
  • MCP Compliant: Full Model Context Protocol implementation
  • Type Safety: Complete TypeScript support with Zod schema validation
  • Production Ready: Designed for reliability and performance

Quick Start

Using with npx (Recommended)

# Run the MCP server directly
npx @mizunashi_mana/manage-bg-mcp

# With options
npx @mizunashi_mana/manage-bg-mcp --help
npx @mizunashi_mana/manage-bg-mcp --version

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "background-process-manager": {
      "command": "npx",
      "args": ["@mizunashi_mana/manage-bg-mcp"]
    }
  }
}
Other MCP Clients

For any MCP client that supports stdio transport:

# Command: npx
# Args: ["@mizunashi_mana/manage-bg-mcp"]
# Transport: stdio
Programmatic Usage
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { spawn } from 'child_process';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['@mizunashi_mana/manage-bg-mcp']
});

Installation for Development

# Clone and install for development
git clone <repository-url>
cd manage-bg-mcp
npm install
npm run build

Environment Variables

  • NODE_ENV: Execution environment (production, development, test)
  • LOG_LEVEL: Logging level (error, warn, info, debug)

MCP Tools

Available Tools

Tool NameDescriptionParameters
startStart a background processcommand, args?, name?, cwd?, env?
stopStop a running processprocessId
restartRestart an existing processprocessId
listList all managed processes-
get_infoGet detailed process informationprocessId
get_logsRetrieve process logsprocessId, lines?
stop_allStop all running processes-

Usage Examples

Once configured with your MCP client, you can use these tools:

// Start a Node.js server
const startResult = await client.callTool('start', {
  command: 'node',
  args: ['server.js'],
  cwd: '/path/to/project',
  name: 'web-server'
});

// List all processes
const processes = await client.callTool('list', {});

// Get recent logs (last 50 lines)
const logs = await client.callTool('get_logs', {
  processId: 'process-uuid',
  lines: 50
});

// Stop a specific process
await client.callTool('stop', {
  processId: 'process-uuid'
});

Log Response Format

The get_logs tool returns unified chronological logs:

{
  "success": true,
  "processId": "process-uuid",
  "logs": {
    "stdout": ["Output line 1", "Output line 2"],
    "stderr": ["Error line 1"],
    "lastUpdated": "2024-01-01T12:00:00.000Z",
    "totalLines": 3
  }
}

Resource Limits

Default resource limits:

  • Maximum concurrent processes: 20
  • Maximum log lines per process: 200
  • Process termination timeout: 5 seconds

Architecture

The server uses a modern dependency injection architecture with unified log management:

  • Unified Log Management: Time-series log storage combining stdout/stderr chronologically
  • Dependency Injection: Inversify-based service container for clean separation of concerns
  • Type Safety: Full TypeScript with Zod schema validation
  • MCP Compliance: Complete implementation of Model Context Protocol
  • Configurable Logging: Environment-aware logging with test mode support

Performance

  • Response time: Less than 50ms for typical operations
  • Concurrent processing: Manage up to 20 processes simultaneously
  • Memory efficiency: Automatic log buffer trimming
  • Scalability: Handles large workloads efficiently

Troubleshooting

Common Issues

Command not found

# Make sure npx is available
npx --version

# Or install globally
npm install -g @mizunashi_mana/manage-bg-mcp
manage-bg-mcp

Permission errors

# Run with explicit npm registry
npx --registry https://registry.npmjs.org @mizunashi_mana/manage-bg-mcp

Process limits The server enforces default limits:

  • Maximum 20 concurrent processes
  • 200 log lines per process
  • 5 second termination timeout

Debugging

Enable debug logging:

NODE_ENV=development npx @mizunashi_mana/manage-bg-mcp

Contributing

Pull requests and issue reports are welcome. Please see for development guidelines.

License

This project is licensed under Apache-2.0 OR MPL-2.0 dual license. You may choose either license that best suits your needs.

Support

Related Projects