STeLA MCP

STeLA MCP

一个 Python 实现的 Model Context Protocol 服务，通过标准化 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 自动为 Claude Desktop 安装 STeLA：

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

前置条件

• Python 3.10 - 3.12
• pip 或 uv 包管理器
• Pydantic v2.x

安装步骤

1. 克隆仓库：

git clone <repository-url>
cd stela-mcp

2. 创建并激活虚拟环境：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. 安装依赖：

pip install -e .

创建二进制发行版

创建独立运行的二进制文件：

1. 安装 PyInstaller：

pip install pyinstaller

2. 创建二进制文件：

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

服务将启动，并通过标准输入/输出监听连接。

与 Claude Desktop 配合使用

要将 STeLA MCP 与 Claude Desktop 配合使用：

1. 选项 1：直接使用 Python

   • 运行以下命令启动服务：

     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 风格差异
• 失败时：错误消息

list_directory

列出目录内容。

参数：

• path（字符串，必填）：要列出内容的目录路径

返回：

• 成功时：文件和目录列表
• 失败时：错误消息

create_directory

创建新目录。

参数：

• path（字符串，必填）：要创建的目录路径

返回：

• 成功时：成功消息
• 失败时：错误消息

move_file

移动或重命名文件和目录。

参数：

• source（string，必填）：要移动的文件或目录的源路径
• destination（string，必填）：文件或目录将被移动到的目标路径

返回：

• 成功时：成功消息
• 失败时：错误消息

search_files

搜索符合指定模式的文件。

参数：

• path（string，必填）：搜索的起始路径
• pattern（string，必填）：用于匹配文件和目录名称的搜索模式
• excludePatterns（array，可选）：要排除的 glob 模式列表

返回：

• 成功时：匹配文件列表
• 失败时：错误消息

directory_tree

递归生成文件和目录的树形视图。

参数：

• path（string，必填）：用于生成目录树的目录路径

返回：

• 成功时：表示目录树的 JSON 结构
• 失败时：错误消息

get_file_info

获取文件或目录的详细元数据。

参数：

• path（string，必填）：文件或目录的路径

返回：

• 成功时：文件/目录元数据
• 失败时：错误消息

list_allowed_directories

列出服务允许访问的所有目录。

参数：

• 无

返回：

• 成功时：允许访问的目录列表
• 失败时：错误消息

show_security_rules

显示当前安全配置。

参数：

• 无

返回：

• 成功时：安全配置详情
• 失败时：错误消息

安全注意事项

STeLA MCP 提供直接访问本地系统并执行命令和文件操作的能力。请考虑以下安全实践：

• 使用适当的权限运行（避免以 root/管理员身份运行）
• 仅在可信环境中使用
• 考虑在生产环境中实施额外的授权机制
• 谨慎设置允许执行命令和进行文件操作的目录
• 实施路径验证，防止未经授权访问系统文件
• 针对你的使用场景采用限制最严格的配置
• 定期检查并更新允许的命令和目录
• 验证符号链接，防止访问允许目录之外的位置
• 确保在创建文件时检查父目录

特定平台的安全说明

Linux/macOS

• 使用权限受限的专用用户运行
• 考虑使用 chroot 环境限制文件系统访问
• 使用 chmod 限制可执行权限
• 考虑使用 SELinux/AppArmor 增强安全性

Windows

• 使用标准用户身份运行，而非管理员身份
• 考虑使用 Windows 安全功能限制访问
• 使用文件夹/文件权限限制对敏感目录的访问
• 考虑使用 Windows Defender Application Control

开发

添加新工具

要为 STeLA MCP 扩展更多功能，请遵循以下模式：

1. 在 server.py 中为工具的输入参数定义 Pydantic 模型
2. 在 shell.py 或 filesystem.py 中相应的类里添加新方法
3. 在 server.py 中使用 @server.call_tool() 装饰器注册工具
4. 实现工具处理程序，并妥善处理错误和返回类型

示例：

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 构建