STeLA MCP
](https://smithery.ai/server/@Sachin-Bhat/stela-mcp)
模型上下文协议服务器的Python实现，通过标准化的API接口提供对本地系统操作的安全访问。
STeLA（简单终端语言助手）MCP是一种轻量级服务器，通过标准化的API接口提供对本地机器命令和文件操作的安全访问。它充当应用程序和本地系统之间的桥梁，实现模型上下文协议（MCP）架构。
概述
STeLA MCP实现了模型上下文协议（MCP）架构，为应用程序在本地机器上执行命令和执行文件操作提供了一种安全、标准化的方式。它作为一个中间层，通过定义良好的API接受请求，在受控环境中执行操作，并返回格式化的结果。
特性
- 命令执行：在本地系统上运行shell命令，并进行适当的错误处理
- 文件操作：读取、写入和管理本地系统上的文件
- 目录可视化：生成文件系统的递归树视图
- 工作目录支持：在特定目录中执行命令
- 稳健的错误处理：详细的错误消息和验证
- 综合产出：捕获并返回stdout和stderr
- 简单集成：标准I/O接口，便于与各种客户端集成
- 多目录支持：为文件操作配置多个允许的目录
- 安全第一设计：严格的路径验证和命令执行控制
- 文件搜索：搜索与模式匹配的文件
- 文件编辑：对文件进行选择性编辑
- 类型安全：使用Pydantic模型对所有工具输入进行强类型检查
- 路径验证：增强的符号链接和父目录验证
安装
通过Smithery安装
通过以下方式自动安装STeLA for Claude Desktop 史密瑟里:
npx -y @smithery/cli install @Sachin-Bhat/stela-mcp --client claude先决条件
- Python 3.10-3.12
- pip或uv包管理器
- Pydantic v2.x
安装步骤
- 克隆存储库：
git clone
cd stela-mcp- 创建并激活虚拟环境：
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate- 安装依赖项：
pip install -e .创建二进制分布
要创建自包含的二进制文件：
- 安装PyInstaller：
pip install pyinstaller- 创建二进制文件：
pyinstaller --onefile src/stella_mcp//server.py --name stela-mcp二进制文件将在 dist 目录。
配置
STeLA MCP可以使用环境变量进行配置：
目录访问控制
ALLOWED_DIRS（必需）：以逗号分隔的允许文件操作的目录列表
- 例子： /home/user/project,/home/user/docs - 默认值：如果未指定，则为当前工作目录 - 注意：所有路径必须是绝对路径
ALLOWED_DIR（可选）：命令执行上下文的主目录
- 例子： /home/user/project - 默认值：第一个目录 ALLOWED_DIRS 或当前工作目录 - 注：这与 ALLOWED_DIRS 并控制命令执行上下文
命令执行安全
ALLOWED_COMMANDS（可选）：逗号分隔的允许shell命令列表
- 例子： ls,cat,pwd,echo - 违约： ls,cat,pwd,echo - 特殊值： all 允许任何命令（不推荐）
ALLOWED_FLAGS（可选）：逗号分隔的允许命令标志列表
- 例子： -l,-a,-h,--help - 违约： -l,-a,-h,--help - 特殊值： all 允许任何标志（不推荐）
MAX_COMMAND_LENGTH（可选）：命令字符串的最大长度
- 例子： 1024 - 违约： 1024 - 注意：防止通过过长的字符串注入命令
COMMAND_TIMEOUT（可选）：命令的最大执行时间（秒）
- 例子： 60 - 违约： 60 - 注意：防止挂起命令
配置示例
# Directory access
export ALLOWED_DIRS="/home/user/project,/home/user/docs"
export ALLOWED_DIR="/home/user/project"
# Command execution
export ALLOWED_COMMANDS="ls,cat,pwd,echo"
export ALLOWED_FLAGS="-l,-a,-h,--help"
export MAX_COMMAND_LENGTH=1024
export COMMAND_TIMEOUT=60项目结构
stela-mcp/
├── src/
│ ├── stela_mcp/
│ │ ├── __init__.py
│ │ ├── shell.py # Shell command execution
│ │ ├── filesystem.py # File system operations
│ │ └── security.py # Security configuration
│ └── server.py # Main server implementation
├── pyproject.toml # Project configuration
└── README.md用法
启动服务器
使用以下命令运行服务器：
uv run python -m src.stella_mcp.server服务器将启动并通过标准I/O监听连接。
与Claude Desktop一起使用
要将STeLA MCP与Claude Desktop一起使用：
- 选项1：直接使用Python
- 使用以下命令启动服务器：
uv run python -m src.stela_mcp.server- 在克劳德桌面中： - 转到“设置” - 在“工具”下，单击“添加工具” - 选择“MCP服务器” - 输入以下配置： - 名字：STeLA MCP - 路径：Python可执行文件的绝对路径（例如。， /home/username/.venv/bin/python) - 参数: -m src.stela_mcp.server - 工作目录：STeLA MCP项目目录的路径
- 选项2：使用二进制
- 从以下位置复制二进制文件 dist/stela-mcp 到路径中的某个位置 - 在克劳德桌面中： - 转到“设置” - 在“工具”下，单击“添加工具” - 选择“MCP服务器” - 输入以下配置： - 名字：STeLA MCP - 路径：二进制的绝对路径（例如。， /usr/local/bin/stela-mcp) - 参数：（留空） - 工作目录：（留空）
- 配置后，您可以在与Claude的对话中使用STeLA MCP工具。例如：
- “显示主目录的内容” - “创建一个名为'test.txt'的新文件，其中包含一些内容” - “在我当前的目录中运行命令'ls-la'”
- Claude将根据您的请求自动使用适当的工具，并在对话中显示结果。
可用工具
命令工具
execute_命令
在本地系统上执行shell命令。
参数：
command（string，必填）：要执行的shell命令working_dir（string，可选）：应执行命令的目录
退货：
- 成功时：命令输出（stdout）
- 失败时：错误消息和任何命令输出（stderr）
change_directory
更改当前工作目录。
参数：
path（字符串，必填）：要更改的路径
退货：
- 关于成功：新路径的成功信息
- 失败时：错误消息
文件系统工具
read_file
读取文件的内容。
参数：
path（string，必填）：要读取的文件的路径
退货：
- 成功：文件内容
- 失败时：错误消息
读取多个文件
同时读取多个文件。
参数：
paths（array，必填）：要读取的文件路径列表
退货：
- 关于成功：合并所有文件的内容
- 失败时：错误消息和部分结果
write_file
将内容写入文件。
参数：
path（string，必填）：写入文件的路径content（string，必填）：要写入文件的内容
退货：
- 关于成功：成功信息
- 失败时：错误消息
edit_file
对文件进行选择性编辑。
参数：
path（string，必填）：要编辑的文件的路径edits（数组，必填）：编辑操作列表
- 每次编辑都包含 oldText 和 newText
dryRun（布尔值，可选）：预览更改而不应用
退货：
- 关于成功：Git风格的变化差异
- 失败时：错误消息
list_directory
列出目录的内容。
参数：
path（string，必填）：要列出的目录的路径
退货：
- 成功时：文件和目录列表
- 失败时：错误消息
create_directory
创建新目录。
参数：
path（string，必填）：要创建的目录的路径
退货：
- 关于成功：成功信息
- 失败时：错误消息
move_file
移动或重命名文件和目录。
参数：
source（string，必填）：要移动的文件或目录的源路径destination（string，必填）：文件或目录将移动到的目标路径
退货：
- 关于成功：成功信息
- 失败时：错误消息
搜索文件
搜索与模式匹配的文件。
参数：
path（字符串，必填）：搜索的起始路径pattern（字符串，必填）：搜索模式以匹配文件名和目录名excludePatterns（array，可选）：要排除的glob模式列表
退货：
- 成功时：匹配文件列表
- 失败时：错误消息
目录树
生成文件和目录的递归树视图。
参数：
path（string，必填）：生成树的目录路径
退货：
- 成功时：JSON结构表示目录树
- 失败时：错误消息
获取_文件_信息
检索有关文件或目录的详细元数据。
参数：
path（string，必填）：文件或目录的路径
退货：
- 成功时：文件/目录元数据
- 失败时：错误消息
list_allowed_directories
列出允许服务器访问的所有目录。
参数：
- 无
退货：
- 成功时：允许的目录列表
- 失败时：错误消息
show_security_rules
显示当前安全配置。
参数：
- 无
退货：
- 成功后：安全配置详细信息
- 失败时：错误消息
安全考虑
STeLA MCP提供在本地系统上执行命令和文件操作的直接访问。考虑以下安全实践：
- 使用适当的权限运行（避免以root/管理员身份运行）
- 仅在受信任的环境中使用
- 考虑为生产使用实施额外的授权机制
- 请注意允许在哪些目录中执行命令和文件操作
- 实施路径验证以防止未经授权访问系统文件
- 为您的用例使用尽可能严格的配置
- 定期审查和更新允许的命令和目录
- 验证符号链接以防止在允许的目录之外访问
- 确保父目录检查文件创建操作
平台特定安全说明
Linux/macOS
- 使用权限有限的专用用户运行
- 考虑使用chroot环境来限制文件系统访问
- 使用
chmod限制可执行权限 - 考虑使用SELinux/AppArmor来增强安全性
视窗
- 以标准用户而非管理员身份运行
- 考虑使用Windows安全功能来限制访问
- 使用文件夹/文件权限限制对敏感目录的访问
- 考虑使用Windows Defender应用程序控件
发展
添加新工具
要扩展STeLA MCP的附加功能，请遵循以下模式：
- 在中为工具的输入参数定义Pydantic模型
server.py - 向中的相应类添加新方法
shell.py或filesystem.py - 在中注册该工具
server.py使用@server.call_tool()装饰器 - 使用适当的错误处理和返回类型实现工具处理程序
例子：
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:
# Tool implementation
result = await do_something(arguments.param1, arguments.param2)
return {"success": True, "result": result}
except Exception as e:
return {"error": str(e)}许可证
Apache-2.0许可证
致谢
- 使用MCP Python SDK构建
