Metadata-Version: 2.4
Name: mcp_lcu_server
Version: 0.1.1
Summary: MCP Linux Common Utility Server
Author-email: Lewis Guo <guolisen@gmail.com>
License: MIT License
        
        Copyright (c) 2025 guolisen
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=0.1.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: py-cpuinfo>=9.0.0
Requires-Dist: netifaces>=0.11.0
Requires-Dist: requests>=2.28.0
Requires-Dist: paramiko>=3.0.0
Requires-Dist: pyudev>=0.24.0
Requires-Dist: click>=8.1.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: asyncio>=3.4.3
Requires-Dist: setuptools>=78.1.0
Requires-Dist: wheel>=0.45.1
Requires-Dist: twine>=6.1.0
Requires-Dist: pkginfo>=1.12.1.2
Requires-Dist: urllib3>=2.3.0
Requires-Dist: requests-toolbelt>=1.0.0
Requires-Dist: build>=1.2.2.post1
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Dynamic: license-file

[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
![](https://badge.mcpx.dev?status=on 'MCP Enabled')
![](https://badge.mcpx.dev?type=server 'MCP Server')
![](https://badge.mcpx.dev?type=dev 'MCP Dev')
[![Tests](https://github.com/guolisen/mcp_lcu_server/workflows/Tests/badge.svg)](https://github.com/guolisen/mcp_lcu_server/actions)

# MCP Linux Common Utility Server

The Model Context Protocol (MCP) Linux Common Utility (LCU) Server is a Python-based server that provides access to various Linux system operations and information through the Model Context Protocol.

## Features

- **CPU Operations**: CPU information, usage, load average, etc.
- **Memory Operations**: Memory and swap information, usage statistics.
- **Process/Thread Operations**: Process listing, information, and management.
- **Storage Operations**: Disk, volume, and partition information.
- **Filesystem Operations**: File creation, deletion, updating, and information.
- **Hardware Operations**: Hardware detection and information.
- **Network Operations**: Interface information, connectivity testing, and data transfer.
- **Monitoring Operations**: System status monitoring and health checks.
- **Log Operations**: Access to system logs, log analysis, and statistics across multiple sources.

## Installation

### Prerequisites

- Python 3.10 or higher
- Linux operating system

### Installation Steps

1. Clone the repository:
   ```
   git clone https://github.com/yourusername/mcp_lcu_server.git
   cd mcp_lcu_server
   ```

2. Install the package:
   ```
   uv venv
   source .venv/bin/activate
   python -m build
   ```

## Configuration

The server can be configured using a YAML configuration file. By default, it looks for the configuration file in the following locations:

- `./config.yaml`
- `./config/config.yaml`
- `/etc/mcp-lcu-server/config.yaml`
- `~/.config/mcp-lcu-server/config.yaml`

You can also specify a custom configuration file path using the `--config` command-line option.

### Configuration File Example

```yaml
server:
  name: mcp-lcu-server
  transport: both  # stdio, sse, or both
  port: 8000
  host: 127.0.0.1

monitoring:
  enabled: true
  interval: 30  # seconds
  metrics:
    - cpu
    - memory
    - disk
    - network

filesystem:
  allowed_paths:
    - /
  max_file_size: 10485760  # 10MB

network:
  allow_downloads: true
  allow_uploads: true
  max_download_size: 104857600  # 100MB
  max_upload_size: 10485760  # 10MB
  allowed_domains:
    - "*"  # Allow all domains

process:
  allow_kill: false
  allowed_users: []

logs:
  # Custom log paths (optional)
  paths: 
    # syslog: /var/log/syslog
    # auth: /var/log/auth.log
  max_entries: 1000  # Maximum entries to return
```

## Usage

### Starting the Server

You can start the server using the command-line interface:

```
mcp-lcu-server [OPTIONS]
```

Available options:

- `--config`, `-c`: Path to the configuration file
- `--transport`, `-t`: Transport type (stdio, sse, or both)
- `--port`, `-p`: Port for SSE transport
- `--host`, `-h`: Host for SSE transport
- `--debug`, `-d`: Enable debug logging

### Transport Types

The server supports the following transport types:

- `stdio`: Standard input/output transport
- `sse`: Server-Sent Events transport

### Examples

Start the server with stdio transport:
```
mcp-lcu-server --transport stdio
```

Start the server with SSE transport on port 8000:
```
mcp-lcu-server --transport sse --port 8000
```

Start the server with both transports:
```
mcp-lcu-server --transport both
```

## API Documentation

### Tools

The server provides various tools for interacting with the Linux system:

#### CPU Tools
- `get_cpu_info`: Get detailed CPU information
- `get_cpu_usage`: Get CPU usage percentage
- `get_load_average`: Get system load average
- `analyze_cpu_performance`: Analyze CPU performance

#### Memory Tools
- `get_memory_info`: Get detailed memory information
- `get_memory_usage`: Get memory usage
- `get_swap_info`: Get swap information
- `analyze_memory_performance`: Analyze memory performance

#### Process Tools
- `list_processes`: List all processes
- `get_process_info`: Get detailed information about a process
- `search_processes`: Search for processes
- `analyze_top_processes`: Analyze top processes by CPU and memory usage

#### Storage Tools
- `list_disks`: List physical disks
- `list_partitions`: List disk partitions
- `get_disk_usage`: Get disk usage
- `analyze_storage_usage`: Analyze storage usage

#### Filesystem Tools
- `list_directory`: List contents of a directory
- `read_file`: Read file contents
- `write_file`: Write content to a file
- `delete_file`: Delete a file or directory
- `copy_file`: Copy a file or directory
- `move_file`: Move a file or directory
- `search_files`: Search for files matching a pattern
- `search_file_contents`: Search for files containing a pattern

#### Hardware Tools
- `get_system_info`: Get general system information
- `get_cpu_info`: Get CPU information
- `get_memory_info`: Get memory information
- `get_storage_info`: Get storage information
- `get_pci_devices`: Get PCI device information
- `get_usb_devices`: Get USB device information
- `analyze_hardware`: Analyze hardware configuration

#### Network Tools
- `get_network_interfaces`: Get network interfaces information
- `get_network_connections`: Get network connections
- `get_network_stats`: Get network statistics
- `ping_host`: Ping a host
- `traceroute_host`: Trace route to a host
- `http_get_request`: Perform HTTP GET request
- `download_file_from_url`: Download a file from a URL
- `upload_file_to_url`: Upload a file to a URL
- `analyze_network`: Analyze network configuration and connectivity

#### Monitoring Tools
- `get_system_status`: Get system status
- `check_system_health`: Check system health
- `monitor_resources`: Monitor resource usage
- `get_system_uptime`: Get system uptime
- `get_system_load`: Get system load
- `analyze_system_performance`: Analyze system performance

#### Log Tools
- `log_list_available_logs`: List all available log sources on the system
- `log_get_journal_logs`: Get logs from the systemd journal
- `log_get_system_logs`: Get logs from system log files
- `log_get_dmesg`: Get kernel logs from dmesg
- `log_get_application_logs`: Get logs for a specific application
- `log_get_audit_logs`: Get audit logs
- `log_get_boot_logs`: Get boot logs
- `log_get_service_status_logs`: Get logs related to a specific systemd service
- `log_search_logs`: Search across multiple log sources
- `log_analyze_logs`: Analyze logs to identify patterns and issues
- `log_get_statistics`: Get statistics about log volume and characteristics

### Resources

The server also provides various resources that can be accessed via MCP:

#### System Resources
- `linux://system/info`: System information
- `linux://system/cpu`: CPU information
- `linux://system/memory`: Memory information
- `linux://system/uptime`: System uptime

#### Monitoring Resources
- `linux://monitoring/status`: System status
- `linux://monitoring/health`: System health
- `linux://monitoring/resources`: Resource usage

#### Filesystem Resources
- `linux://fs/dir/{path}`: Directory listing
- `linux://fs/info/{path}`: File information
- `linux://fs/file/{path}`: File contents
- `linux://fs/usage/{path}`: Directory usage analysis

#### Network Resources
- `linux://network/interfaces`: Network interfaces
- `linux://network/connections`: Network connections
- `linux://network/stats`: Network statistics
- `linux://network/ping/{host}`: Ping a host
- `linux://network/traceroute/{host}`: Trace route to a host
- `linux://network/analysis`: Network analysis

#### Log Resources
- `linux://logs/available`: List of available log sources
- `linux://logs/journal/{parameters}`: Logs from systemd journal
- `linux://logs/system/{log_type}/{parameters}`: Logs from system log files
- `linux://logs/kernel/{count}`: Logs from kernel ring buffer (dmesg)
- `linux://logs/application/{app_name}/{parameters}`: Logs for specific applications
- `linux://logs/audit/{parameters}`: Logs from the Linux audit system
- `linux://logs/boot/{count}`: Logs related to system boot
- `linux://logs/service/{service}/{count}`: Logs for specific systemd services
- `linux://logs/search/{query}/{parameters}`: Search across multiple log sources
- `linux://logs/analysis/{parameters}`: Analysis of log patterns and issues
- `linux://logs/statistics/{parameters}`: Statistics about log volume and characteristics

## Security Considerations

The server provides access to various system operations, which can be potentially dangerous if misused. Make sure to:

- Configure the allowed paths for filesystem operations
- Configure the allowed domains for network operations
- Restrict the ability to kill processes
- Run the server with appropriate permissions

### Command Execution Security

The server includes a powerful command execution tool that allows running shell commands on the host system. This feature can pose significant security risks if not properly configured or if used in untrusted environments.

**Warning:** If you don't want to use the command execution functionality, you have two options:
1. Disable it by setting `command.enabled: false` in your configuration file:
   ```yaml
   command:
     enabled: false
   ```
2. Remove the MCP tools related to command execution by modifying your server implementation.

When command execution is enabled, consider these additional security measures:
- Use `allowed_commands` to restrict which commands can be executed
- Use `blocked_commands` to explicitly block dangerous commands
- Set appropriate timeouts and output size limits
- Disable sudo access with `allow_sudo: false` unless absolutely necessary

## License

This project is licensed under the MIT License - see the LICENSE file for details.
