Stela MCP

🚀 STeLA MCP Project Documentation

STeLA MCP is a server that provides command execution and file operation capabilities for local systems. It aims to offer users a secure and configurable interface to manage and manipulate files and directories. Users can control the server's functionality by configuring allowed directories and supported commands.

🚀 Quick Start

✨ Features

• Command Execution: Execute system commands in a controlled environment.
• File System Operations: Manage files and directories, including creation, deletion, moving, and renaming.
• Script Execution: Run predefined scripts.
• Search Functionality: Search for files or directories by name.

📦 Installation

Install from Source

1. Clone the repository:

git clone git@github.com:username/repo.git
cd repo

2. Install dependencies:

pip install -r requirements.txt

3. Start the server:

python server.py

Install from PyPI

pip install stela-mcp

📚 Documentation

Configuration

Before starting the server, basic configuration is required. The main configuration file is server_config.yaml, which contains the following key settings:

Example Configuration

# server_config.yaml

logging:
  level: INFO
  file: mcp.log

allowed_directories:
  - /home/user/data
  - /var/www

enabled_commands:
  - ls
  - cp
  - mv
  - rm

security_rules:
  allow_root: false
  log_access: true

Function Modules

Command Execution Tools

STeLA MCP provides a series of command execution tools that allow users to run system commands in a controlled environment. The main functions include:

• execute_command: Execute a single command.
• script_execution: Run a predefined script.

Usage Examples

curl -X POST http://localhost:8000/api/v1/commands \
  -H "Content-Type: application/json" \
  -d '{"command": "ls -a", "args": []}'

File System Tools

STeLA MCP offers a variety of file and directory operation tools to help users manage the file system efficiently. The main functions include:

• file_operations: Create, delete, move, and rename files.
• directory_management: Create, delete, and list directories.
• search_tools: Search for files or directories by name.

Usage Examples

curl -X POST http://localhost:8000/api/v1/files \
  -H "Content-Type: application/json" \
  -d '{"operation": "create_directory", "path": "/var/www/new_dir"}'

Security Considerations

STeLA MCP provides the ability to execute commands and perform file operations on the local system, so use it with caution. Here are some security recommendations:

⚠️ Important Note

• Permission Control: Avoid running the server as root or an administrator.
• Trusted Environment: Use it only in a trusted environment.
• Configuration Restrictions: Use the strictest configuration to suit the specific scenario.
• Path Validation: Implement strict path checks to prevent unauthorized access.

Platform-Specific Security Considerations

Linux/macOS

• Use a dedicated user account with limited permissions.
• Consider using a chroot environment to limit file system access.
• Use chmod to restrict executable permissions.
• Consider using SELinux or AppArmor for additional protection.

Windows

• Avoid running the server as an administrator.
• Use Windows security features to limit access.
• Set folder and file permissions to prevent access to sensitive directories.
• Consider using Windows Defender Application Control.

Development Guide

Project Structure

The source code structure of STeLA MCP is as follows:

stela-mcp/
├── server.py           # Main server file
├── commands/          # Supported command modules
│   ├── __init__.py
│   └── file_ops.py    # Commands related to file operations
├── config/            # Configuration management module
│   ├── __init__.py
│   └── server_config.yaml.example  # Example configuration file
└── utils/             # Utility functions
    ├── logger.py      # Logging tool
    └── validators.py  # Data validation tool

Development Steps

1. Clone the repository:

git clone git@github.com:username/stela-mcp.git
cd stela-mcp

2. Install dependencies:

pip install -r requirements.txt

3. Start the development server:

python server.py --dev

Documentation History

• Version 1.0: Initial release, including basic command and file operation functions.
• Version 2.0: Introduced directory restrictions and enhanced security mechanisms.
• Version 3.0: Supported script execution and advanced file management functions.

For more information, please refer to STeLA MCP Official Documentation.