stela-mcp

🚀 STeLA MCP 项目文档

STeLA MCP 是一个服务器，它提供对本地系统进行命令执行和文件操作的功能。该项目旨在为用户打造一个安全且可配置的接口，以实现对文件及目录的管理与操作。用户能通过配置允许访问的目录和受支持的命令，来灵活控制服务器功能。

🚀 快速开始

STeLA MCP 提供了便捷的安装方式，你可以从源码安装，也能直接从 PyPI 安装。

从源码安装

1. 克隆仓库：

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

2. 安装依赖项：

pip install -r requirements.txt

3. 启动服务器：

python server.py

从 PyPI 安装

pip install stela-mcp

✨ 主要特性

STeLA MCP 具备丰富的功能模块，涵盖命令执行和文件系统操作等多个方面。

命令执行工具

提供了一系列命令执行工具，可让用户在受控环境中运行系统命令。

• execute_command：执行单个命令。
• script_execution：运行预定义脚本。

文件系统工具

拥有丰富的文件和目录操作工具，助力用户高效管理文件系统。

• file_operations：包含创建、删除、移动和重命名文件。
• directory_management：包含创建、删除和列出目录。
• search_tools：支持按名称搜索文件或目录。

📦 安装指南

从源码安装

1. 克隆仓库：

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

2. 安装依赖项：

pip install -r requirements.txt

3. 启动服务器：

python server.py

从 PyPI 安装

pip install stela-mcp

💻 使用示例

命令执行工具基础用法

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

文件系统工具基础用法

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

📚 详细文档

配置说明

在启动服务器前，需进行基本配置。主要配置文件为 server_config.yaml，其中包含以下关键设置：

• allowed_directories：允许访问的目录列表。
• enabled_commands：支持执行的命令列表。
• security_rules：安全相关的配置，如用户权限和日志记录。

示例配置

# 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

安全注意事项

STeLA MCP 提供对本地系统执行命令和文件操作的功能，使用时需谨慎。以下是一些安全建议：

• 权限控制：避免以 root 或管理员身份运行服务器。
• 受信任环境：仅在可信环境中使用。
• 配置限制：使用最严格的配置以适应具体场景。
• 路径验证：实施严格的路径检查，防止越权访问。

平台特定安全注意事项

Linux/macOS

• 使用专用用户账户并授予有限权限。
• 考虑使用 chroot 环境来限制文件系统访问。
• 使用 chmod 限制可执行权限。
• 考虑采用 SELinux 或 AppArmor 进行额外保护。

Windows

• 避免以管理员身份运行服务器。
• 使用 Windows 安全功能限制访问。
• 设置文件夹和文件的权限，防止访问敏感目录。
• 考虑使用 Windows Defender 应用控制。

开发指南

项目结构

STeLA MCP 的源码结构如下：

stela-mcp/
├── server.py           # 主服务器文件
├── commands/          # 支持的命令模块
│   ├── __init__.py
│   └── file_ops.py    # 文件操作相关命令
├── config/            # 配置管理模块
│   ├── __init__.py
│   └── server_config.yaml.example  # 示例配置文件
└── utils/             # 工具函数
    ├── logger.py      # 日志记录工具
    └── validators.py  # 数据验证工具

开发步骤

1. 克隆仓库：

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

2. 安装依赖：

pip install -r requirements.txt

3. 启动开发服务器：

python server.py --dev

文档历史

• 版本 1.0：初始发布，包含基本命令和文件操作功能。
• 版本 2.0：引入了目录限制和增强的安全机制。
• 版本 3.0：支持脚本执行和高级文件管理功能。

如需更多信息，请参考 STeLA MCP 官方文档。