内容
# STeLA MCP
[](https://smithery.ai/server/@Sachin-Bhat/stela-mcp)
> 一个 Model Context Protocol 服务器的 Python 实现，通过标准化的 API 接口提供对本地系统操作的安全访问。
STeLA (Simple Terminal Language Assistant) MCP 是一个轻量级服务器，通过标准化的 API 接口提供对本地机器命令和文件操作的安全访问。它充当应用程序与本地系统之间的桥梁，实现了 Model Context Protocol (MCP) 架构。
## 概述
STeLA MCP 实现了 Model Context Protocol (MCP) 架构，为应用程序提供了一种安全、标准化的方式来在本地机器上执行命令和进行文件操作。它作为一个中介层，通过明确定义的 API 接受请求，在受控环境中执行操作，并返回格式化的结果。
## 特性
* **命令执行**：在本地系统上运行 shell 命令，并进行适当的错误处理
* **文件操作**：读取、写入和管理本地系统上的文件
* **目录可视化**：生成文件系统的递归树视图
* **工作目录支持**：在特定目录中执行命令
* **强大的错误处理**：详细的错误信息和验证
* **全面的输出**：捕获并返回 stdout 和 stderr
* **简单集成**：标准 I/O 接口，便于与各种客户端集成
* **多目录支持**：配置多个允许的目录进行文件操作
* **安全优先设计**：严格的路径验证和命令执行控制
* **文件搜索**：搜索匹配模式的文件
* **文件编辑**：对文件进行选择性编辑
* **类型安全**：使用 Pydantic 模型对所有工具输入进行强类型检查
* **路径验证**：增强的符号链接和父目录验证
## 安装
### 通过 Smithery 安装
要通过 [Smithery](https://smithery.ai/server/@Sachin-Bhat/stela-mcp) 自动安装 STeLA for Claude Desktop：
```bash
npx -y @smithery/cli install @Sachin-Bhat/stela-mcp --client claude
```
### 先决条件
* Python 3.10 - 3.12
* pip 或 uv 包管理器
* Pydantic v2.x
### 安装步骤
1. 克隆仓库：
```bash
git clone <repository-url>
cd stela-mcp
```
2. 创建并激活虚拟环境：
```bash
python -m venv .venv
source .venv/bin/activate # 在 Windows 上: .venv\Scripts\activate
```
3. 安装依赖：
```bash
pip install -e .
```
### 创建二进制分发
要创建一个自包含的二进制文件：
1. 安装 PyInstaller：
```bash
pip install pyinstaller
```
2. 创建二进制文件：
```bash
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`
* 注意：防止命令挂起
### 示例配置
```bash
# 目录访问
export ALLOWED_DIRS="/home/user/project,/home/user/docs"
export ALLOWED_DIR="/home/user/project"
# 命令执行
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 命令执行
│ │ ├── filesystem.py # 文件系统操作
│ │ └── security.py # 安全配置
│ └── server.py # 主服务器实现
├── pyproject.toml # 项目配置
└── README.md
```
## 使用
### 启动服务器
使用以下命令运行服务器：
```bash
uv run python -m src.stella_mcp.server
```
服务器将启动并通过标准 I/O 监听连接。
### 与 Claude Desktop 一起使用
要在 Claude Desktop 中使用 STeLA MCP：
1. 选项 1：直接使用 Python
- 使用以下命令启动服务器：
```bash
uv run python -m src.stela_mcp.server
```
- 在 Claude Desktop 中：
- 转到设置
- 在“工具”下，点击“添加工具”
- 选择“MCP Server”
- 输入以下配置：
- **名称**：STeLA MCP
- **路径**：您的 Python 可执行文件的绝对路径（例如，`/home/username/.venv/bin/python`）
- **参数**：`-m src.stela_mcp.server`
- **工作目录**：您的 STeLA MCP 项目目录的路径
2. 选项 2：使用二进制文件
- 将 `dist/stela-mcp` 中的二进制文件复制到您的 PATH 中的某个位置
- 在 Claude Desktop 中：
- 转到设置
- 在“工具”下，点击“添加工具”
- 选择“MCP Server”
- 输入以下配置：
- **名称**：STeLA MCP
- **路径**：二进制文件的绝对路径（例如，`/usr/local/bin/stela-mcp`）
- **参数**：（留空）
- **工作目录**：（留空）
3. 配置完成后，您可以在与 Claude 的对话中使用 STeLA MCP 工具。例如：
- “显示我的主目录的内容”
- “创建一个名为 'test.txt' 的新文件，并添加一些内容”
- “在我当前目录中运行命令 'ls -la'”
4. Claude 将根据您的请求自动使用适当的工具，并在对话中显示结果。
### 可用工具
#### 命令工具
##### execute_command
在本地系统上执行 shell 命令。
**参数：**
* `command`（字符串，必需）：要执行的 shell 命令
* `working_dir`（字符串，可选）：命令应执行的目录
**返回：**
* 成功时：命令输出（stdout）
* 失败时：错误信息和任何命令输出（stderr）
##### change_directory
更改当前工作目录。
**参数：**
* `path`（字符串，必需）：要更改到的路径
**返回：**
* 成功时：带有新路径的成功消息
* 失败时：错误信息
#### 文件系统工具
##### read_file
读取文件的内容。
**参数：**
* `path`（字符串，必需）：要读取的文件路径
**返回：**
* 成功时：文件内容
* 失败时：错误信息
##### read_multiple_files
同时读取多个文件。
**参数：**
* `paths`（数组，必需）：要读取的文件路径列表
**返回：**
* 成功时：所有文件的合并内容
* 失败时：错误信息和部分结果
##### write_file
将内容写入文件。
**参数：**
* `path`（字符串，必需）：文件将被写入的路径
* `content`（字符串，必需）：要写入文件的内容
**返回：**
* 成功时：成功消息
* 失败时：错误信息
##### edit_file
对文件进行选择性编辑。
**参数：**
* `path`（字符串，必需）：要编辑的文件路径
* `edits`（数组，必需）：编辑操作列表
* 每个编辑包含 `oldText` 和 `newText`
* `dryRun`（布尔值，可选）：预览更改而不应用
**返回：**
* 成功时：更改的 Git 风格 diff
* 失败时：错误信息
##### list_directory
列出目录的内容。
**参数：**
* `path`（字符串，必需）：要列出的目录路径
**返回：**
* 成功时：文件和目录的列表
* 失败时：错误信息
##### create_directory
创建新目录。
**参数：**
* `path`（字符串，必需）：要创建的目录路径
**返回：**
* 成功时：成功消息
* 失败时：错误信息
##### move_file
移动或重命名文件和目录。
**参数：**
* `source`（字符串，必需）：要移动的文件或目录的源路径
* `destination`（字符串，必需）：文件或目录将被移动到的目标路径
**返回：**
* 成功时：成功消息
* 失败时：错误信息
##### search_files
搜索匹配模式的文件。
**参数：**
* `path`（字符串，必需）：搜索的起始路径
* `pattern`（字符串，必需）：用于匹配文件和目录名称的搜索模式
* `excludePatterns`（数组，可选）：要排除的 glob 模式列表
**返回：**
* 成功时：匹配文件的列表
* 失败时：错误信息
##### directory_tree
生成文件和目录的递归树视图。
**参数：**
* `path`（字符串，必需）：生成树的目录路径
**返回：**
* 成功时：表示目录树的 JSON 结构
* 失败时：错误信息
##### get_file_info
检索文件或目录的详细元数据。
**参数：**
* `path`（字符串，必需）：文件或目录的路径
**返回：**
* 成功时：文件/目录元数据
* 失败时：错误信息
##### list_allowed_directories
列出服务器允许访问的所有目录。
**参数：**
* 无
**返回：**
* 成功时：允许的目录列表
* 失败时：错误信息
##### show_security_rules
显示当前安全配置。
**参数：**
* 无
**返回：**
* 成功时：安全配置详情
* 失败时：错误信息
## 安全考虑
STeLA MCP 提供直接访问以执行命令和进行本地系统的文件操作。请考虑以下安全实践：
* 以适当的权限运行（避免以 root/管理员身份运行）
* 仅在受信任的环境中使用
* 考虑为生产使用实施额外的授权机制
* 小心选择允许命令执行和文件操作的目录
* 实施路径验证以防止未经授权访问系统文件
* 对于您的用例，使用尽可能严格的配置
* 定期审查和更新允许的命令和目录
* 验证符号链接以防止访问允许目录之外的内容
* 确保文件创建操作的父目录检查
### 平台特定的安全注意事项
#### Linux/macOS
* 以具有有限权限的专用用户身份运行
* 考虑使用 chroot 环境限制文件系统访问
* 使用 `chmod` 限制可执行权限
* 考虑使用 SELinux/AppArmor 提供额外安全性
#### Windows
* 以标准用户身份运行，而不是管理员
* 考虑使用 Windows 安全功能限制访问
* 使用文件夹/文件权限限制对敏感目录的访问
* 考虑使用 Windows Defender 应用程序控制
## 开发
### 添加新工具
要通过额外功能扩展 STeLA MCP，请遵循以下模式：
1. 在 `server.py` 中为工具的输入参数定义一个 Pydantic 模型
2. 在 `shell.py` 或 `filesystem.py` 中的适当类中添加一个新方法
3. 使用 `@server.call_tool()` 装饰器在 `server.py` 中注册工具
4. 实现工具处理程序，进行适当的错误处理和返回类型
示例：
```python
from pydantic import BaseModel, Field
class MyToolInput(BaseModel):
param1: str = Field(description="param1 的描述")
param2: int = Field(description="param2 的描述")
@server.call_tool()
async def my_tool(request: Request[MyToolInput, str], arguments: MyToolInput) -> Dict[str, Any]:
"""工具的描述。"""
try:
# 工具实现
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 构建
连接信息
猜你喜欢
暂无推荐服务器