STeLA MCP 项目文档

项目简介

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

安装指南

从源码安装

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

配置说明

在启动服务器之前，需要进行基本的配置。主要配置文件是 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 提供了一系列命令执行工具，允许用户在受控的环境中运行系统命令。主要功能包括：

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

使用示例

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

文件系统工具

STeLA MCP 提供了丰富的文件和目录操作工具，帮助用户高效管理文件系统。主要功能包括：

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

使用示例

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

安全注意事项

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 官方文档。