STeLA MCP: Secure System Interface Module

An implementation in Python for a Model Context Protocol (MCP) backend, offering guarded access to underlying machine functionalities through a standardized set of network calls.

STeLA (Simplified Terminal Environment Linkage Agent) MCP operates as a minimal footprint backend service. It adheres to the Model Context Protocol (MCP) specification, establishing a secure, formalized gateway for external clients to interact with local computing resources, including running arbitrary shell instructions and managing persistent storage.

Operational Summary

This service leverages the MCP framework to establish a secure and consistent pathway for decoupled applications to orchestrate local commands and manipulate the file hierarchy. It functions as a crucial isolation layer, receiving authenticated requests via a prescribed API structure, executing operations within defined constraints, and returning structured outcomes.

Core Capabilities

Shell Invocation: Securely execute arbitrary operating system commands with integrated error capture.
Persistence Management: Capabilities for file creation, content modification, and deletion across the local storage.
Structure Mapping: Produce hierarchical, recursive visual representations of directory layouts.
Contextual Execution: Support for specifying the execution context via dedicated working directory parameters.
Resilient Feedback: Comprehensive exception reporting and input validation schemas.
Complete Output Capture: Retrieve and return both standard output (stdout) and standard error (stderr) streams.
Client Interoperability: A straightforward Standard I/O mechanism facilitating plug-and-play integration with diverse consumer applications.
Multi-Scope Definition: Configuration support for multiple authorized directories subject to file operations.
Defense-Oriented Architecture: Rigorous path traversal verification and fine-grained control over process launching.
Asset Discovery: Perform targeted searches for filesystem entities matching specific criteria.
Content Patching: Apply targeted, granular modifications to file contents.
Schema Enforcement: Mandatory static typing enforced using Pydantic schemas for all input contracts.
Traversal Prevention: Enhanced checks against symbolic links and upward directory traversal.

Deployment Instructions

Automated Installation via Smithery

To deploy STeLA for use with Claude Desktop automation through Smithery:

bash npx -y @smithery/cli install @Sachin-Bhat/stela-mcp --client claude

Prerequisites

Python environment (version 3.10 up to 3.12)
A modern package manager (pip or uv)
Pydantic library (version 2.x required)

Setup Procedure

Obtain the source code: bash git clone cd stela-mcp
Establish and activate a clean isolated environment: bash python -m venv .venv source .venv/bin/activate # Windows users: .venv\Scripts\activate
Install necessary packages in editable mode: bash pip install -e .

Creating a Standalone Executable

To generate a single-file binary distribution:

Install the PyInstaller utility: bash pip install pyinstaller
Compile the primary server script: bash pyinstaller --onefile src/stella_mcp//server.py --name stela-mcp

The resulting self-contained executable will reside in the dist/ folder.

Operational Customization

Configuration parameters for STeLA MCP are managed via system environment variables:

File System Access Control

ALLOWED_DIRS (Mandatory): A list, delimited by commas, specifying all root directories permissible for file operations.
Example: /srv/data,/var/log/app
Default: The current working directory (CWD) if unspecified.
Constraint: All entries must be absolute path specifications.
ALLOWED_DIR (Optional): The designated default context directory for initiating shell command execution.
Example: /home/operator/scripts
Default: The first path listed in ALLOWED_DIRS, or the CWD.
Note: This setting is distinct from ALLOWED_DIRS and governs command runtime context.

Command Invocation Safeguards

ALLOWED_COMMANDS (Optional): A comma-separated whitelist of shell utilities permitted for execution.
Example: grep,find,stat,date
Default: ls,cat,pwd,echo
Special Value: all permits any executable (Strongly discouraged for security).
ALLOWED_FLAGS (Optional): A comma-separated list of permissible command-line arguments/switches.
Example: -l,-r,-v
Default: -l,-a,-h,--help
Special Value: all permits any flag (Strongly discouraged).
MAX_COMMAND_LENGTH (Optional): Defines the upper boundary for the total length of an incoming command string.
Example: 2048
Default: 1024 characters.
Rationale: Mitigates potential buffer overflow or injection attempts via overly long inputs.
COMMAND_TIMEOUT (Optional): The maximum duration (in seconds) the system will wait for a command to complete before terminating it.
Example: 120
Default: 60 seconds.
Rationale: Guards against resource exhaustion from indefinitely blocked processes.

Configuration Example

bash

Defining access zones

export ALLOWED_DIRS="/app/config,/app/runtime" export ALLOWED_DIR="/app/config"

Setting execution policies

export ALLOWED_COMMANDS="grep,stat" export ALLOWED_FLAGS="-l" export MAX_COMMAND_LENGTH=2048 export COMMAND_TIMEOUT=120

Internal Architecture

stela-mcp/ ├── src/ │ ├── stela_mcp/ │ │ ├── init.py │ │ ├── shell.py # OS command execution logic │ │ ├── filesystem.py # Local storage manipulation routines │ │ └── security.py # Policy and restriction enforcement module │ └── server.py # Core MCP endpoint listener ├── pyproject.toml # Dependency and build manifest └── README.md

Operational Use

Launching the Backend

Initiate the service listener using: bash uv run python -m src.stella_mcp.server

The service immediately begins monitoring standard input/output streams for connection requests.

Integration with Claude Desktop

To establish connectivity with the Claude Desktop environment:

Method A: Direct Python Invocation
Start the server process as shown above.
Within Claude Desktop's configuration panel:
- Navigate to 'Tools' settings.
- Select 'Register New Tool'.
- Choose 'MCP Server' type.
- Configure as follows:
- Identifier: STeLA MCP
- Executable Path: Full path to your Python interpreter (e.g., /path/to/.venv/bin/python)
- Arguments: -m src.stela_mcp.server
- Execution Context: Path to the root of your STeLA MCP repository folder
Method B: Using the Self-Contained Binary
Ensure the compiled binary (dist/stela-mcp) is placed within a directory listed in the system's PATH environment variable.
Within Claude Desktop's configuration panel:
- Register a new tool of type 'MCP Server'.
- Configure as follows:
- Identifier: STeLA MCP
- Executable Path: Absolute path to the binary (e.g., /usr/local/bin/stela-mcp)
- Arguments: (Leave blank)
- Execution Context: (Leave blank)
After successful configuration, conversational prompts like "Display the contents of the root directory" or "Provision a new file named 'log.tmp'" will trigger the relevant underlying STeLA MCP functions, presenting the results directly in the dialogue flow.

Available Service Endpoints (Tools)

Command Execution Interfaces

execute_command

Executes system-level shell instructions.

Parameters Schema: * command (Text, Mandatory): The complete string representing the shell instruction. * working_dir (Text, Optional): The specific directory context for command runtime.

Return Schema: * Success: Standard output stream content. * Failure: Detailed error narrative concatenated with any captured standard error.

change_directory

Alters the active working directory context.

Parameters Schema: * path (Text, Mandatory): The filesystem target to switch the context to.

Return Schema: * Success: Confirmation message indicating the new active path. * Failure: Descriptive error message.

Persistence Layer Interfaces

read_file

Retrieves the textual content of a specified file.

Parameters Schema: * path (Text, Mandatory): Locator for the file whose contents are required.

Return Schema: * Success: The entire file payload as a string. * Failure: Error description.

read_multiple_files

Fetches content from several files concurrently.

Parameters Schema: * paths (List[Text], Mandatory): A collection of file paths to access.

Return Schema: * Success: Concatenated string of all file contents. * Failure: Error report alongside any successfully retrieved partial data.

write_file

Persists new data to a designated file path.

Parameters Schema: * path (Text, Mandatory): The target location for file creation/overwrite. * content (Text, Mandatory): The data payload to be written.

Return Schema: * Success: Operation acknowledged message. * Failure: Error report.

edit_file

Applies precise, delimited modifications within an existing file.

Parameters Schema: * path (Text, Mandatory): The file subject to alteration. * edits (List[Struct], Mandatory): A sequence of required transformations, each containing oldText and newText segments. * dryRun (Boolean, Optional): If true, output the intended diff without committing changes.

Return Schema: * Success: A patch-style (diff) representation of the applied changes. * Failure: Error details.

list_directory

Enumerates the contents of a specified directory.

Parameters Schema: * path (Text, Mandatory): The directory target for listing.

Return Schema: * Success: A structured inventory of contained files and subdirectories. * Failure: Error message.

create_directory

Provisions a new directory structure.

Parameters Schema: * path (Text, Mandatory): The full path specification for the directory to be instantiated.

Return Schema: * Success: Confirmation of creation. * Failure: Error report.

move_file

Relocates or renames existing files or folders.

Parameters Schema: * source (Text, Mandatory): The original location identifier. * destination (Text, Mandatory): The intended new location identifier.

Return Schema: * Success: Confirmation of relocation. * Failure: Error details.

search_files

Scans a directory tree for items matching a naming criterion.

Parameters Schema: * path (Text, Mandatory): The root directory to commence the search from. * pattern (Text, Mandatory): The glob expression defining the desired filenames/directory names. * excludePatterns (List[Text], Optional): Glob patterns designating directories/files to ignore.

Return Schema: * Success: A collection of paths matching the criteria. * Failure: Error notification.

directory_tree

Generates a nested, hierarchical map of a directory structure.

Parameters Schema: * path (Text, Mandatory): The starting point for the tree generation.

Return Schema: * Success: A JSON object accurately modeling the directory hierarchy. * Failure: Error message.

get_file_info

Retrieves detailed metadata (permissions, timestamps, size) for a filesystem object.

Parameters Schema: * path (Text, Mandatory): The locator for the metadata subject.

Return Schema: * Success: A record containing file/directory attributes. * Failure: Error report.

list_allowed_directories

Exposes the list of directories explicitly permitted by configuration.

Parameters Schema: * None

Return Schema: * Success: An array listing all authorized filesystem roots. * Failure: Error report.

show_security_rules

Displays the currently enforced security policy settings.

Parameters Schema: * None

Return Schema: * Success: A detailed dump of active security configuration parameters. * Failure: Error message.

Safety Protocol Notes

Given that STeLA MCP grants privileged execution capabilities over the host machine, adherence to rigorous safety practices is paramount:

Principle of Least Privilege: Operate the server process using the lowest necessary user credentials (avoid root/Administrator).
Trusted Environments: Deploy exclusively within controlled, verified operational settings.
External Authorization: For production deployments, integrate an external authorization layer atop this service.
Scope Limitation: Strictly define the directories where command execution and persistence modifications are permitted.
Path Sanitization: Implement robust path validation logic to obstruct access to unauthorized system areas.
Configuration Minimalism: Adopt the most restrictive settings compatible with the immediate workload.
Auditing: Regularly inspect and refresh the lists of permitted commands and accessible directories.
Symlink Integrity: Verify symbolic links to ensure they do not resolve outside the sanctioned access boundaries.
Upward Traversal Defense: Enforce boundary checks, especially during file creation operations, against traversing parent directories.

Platform-Specific Safety Guidance

Linux/macOS

Execute using a non-privileged, dedicated service account.
Investigate enclosing operations within a restricted execution environment (e.g., chroot jail).
Utilize file permissions (chmod) to limit execution rights on arbitrary files.
Employ Mandatory Access Control systems like SELinux or AppArmor for enhanced isolation.

Windows

Run the service under a standard user account, bypassing administrative privileges.
Leverage built-in Windows security features to constrain service access.
Utilize NTFS permissions to strictly limit access rights on sensitive paths.
Consider employing Windows Defender Application Control (WDAC) for application execution whitelisting.

Contribution Guide

Adding New Tool Endpoints

To extend STeLA MCP's functionality, utilize the following architectural template:

Define the necessary input data structure as a Pydantic schema within server.py.
Implement the core logic for the new capability within a method in shell.py or filesystem.py.
Register the new interface via the @server.call_tool() decorator in server.py.
Ensure the handler method includes thorough exception handling and returns the specified output type.

Example Structure: python from pydantic import BaseModel, Field

class MyToolInput(BaseModel): param1: str = Field(description="Description of param1") param2: int = Field(description="Description of param2")

@server.call_tool() async def my_tool(request: Request[MyToolInput, str], arguments: MyToolInput) -> Dict[str, Any]: """Description of the tool.""" try: # Core implementation logic result = await do_something(arguments.param1, arguments.param2) return {"status": "completed", "data": result} except Exception as e: return {"status": "failed", "reason": str(e)}

Licensing

Distributed under the Apache-2.0 License.

Acknowledgements

Developed utilizing the official MCP Python Software Development Kit

stela-mcp-sys-interface

Author

Sachin-Bhat

Quick Info

Actions

Tags