MCP 服务器

STeLA MCP

用于本地系统操作的 MCP 服务器

Sachin-Bhat

开发者工具

访问服务器

README

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 接口，易于与各种客户端集成

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 STeLA：

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

前提条件

Python 3.10 - 3.12
pip 或 uv 包管理器

安装步骤

克隆存储库：

git clone <repository-url>
cd stela-mcp

创建并激活虚拟环境：

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

安装依赖项：

pip install -e .

创建二进制分发

要创建自包含的二进制文件：

安装 PyInstaller：

pip install pyinstaller

创建二进制文件：

pyinstaller --onefile src/stella_mcp//server.py --name stela-mcp

二进制文件将在 dist 目录中创建。

项目结构

stela-mcp/
├── src/
│   ├── stela_mcp/
│   │   ├── __init__.py
│   │   ├── shell.py        # Shell 命令执行
│   │   └── filesystem.py   # 文件系统操作
│   └── server.py           # 主服务器实现
├── pyproject.toml          # 项目配置
└── 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.stella_mcp.server
```
- 在 Claude Desktop 中：
  - 转到设置
  - 在“工具”下，单击“添加工具”
  - 选择“MCP 服务器”
  - 输入以下配置：
    - 名称: STeLA MCP
    - 路径: Python 可执行文件的绝对路径（例如，/home/username/.venv/bin/python）
    - 参数: -m src.stela_mcp.server
    - 工作目录: STeLA MCP 项目目录的路径
选项 2：使用二进制文件
- 将二进制文件从 dist/stela-mcp 复制到 PATH 中的某个位置
- 在 Claude Desktop 中：
  - 转到设置
  - 在“工具”下，单击“添加工具”
  - 选择“MCP 服务器”
  - 输入以下配置：
    - 名称: STeLA MCP
    - 路径: 二进制文件的绝对路径（例如，/usr/local/bin/stela-mcp）
    - 参数: （留空）
    - 工作目录: （留空）
配置完成后，您可以在与 Claude 的对话中使用 STeLA MCP 工具。例如：
- "显示我的主目录的内容"
- "创建一个名为 'test.txt' 的新文件，其中包含一些内容"
- "在我的当前目录中运行命令 'ls -la'"
Claude 将根据您的请求自动使用适当的工具，并在对话中显示结果。

可用工具

命令工具

execute_command

在本地系统上执行 shell 命令。

参数：

command (字符串，必需): 要执行的 shell 命令
working_dir (字符串，可选): 应该执行命令的目录

返回值：

成功时：命令输出 (stdout)
失败时：错误消息和任何命令输出 (stderr)

change_directory

更改当前工作目录。

参数：

path (字符串，必需): 要更改到的路径

返回值：

成功时：带有新路径的成功消息
失败时：错误消息

文件系统工具

read_file

读取文件的内容。

参数：

path (字符串，必需): 要读取的文件的路径

返回值：

成功时：文件内容
失败时：错误消息

write_file

将内容写入文件。

参数：

path (字符串，必需): 将写入文件的路径
content (字符串，必需): 要写入文件的内容

返回值：

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

list_directory

列出目录的内容。

参数：

path (字符串，必需): 要列出的目录的路径

返回值：

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

create_directory

创建一个新目录。

参数：

path (字符串，必需): 要创建的目录的路径

返回值：

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

move_file

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

参数：

source (字符串，必需): 要移动的文件或目录的源路径
destination (字符串，必需): 文件或目录将移动到的目标路径

返回值：

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

search_files

搜索与模式匹配的文件。

参数：

path (字符串，必需): 搜索的起始路径
pattern (字符串，必需): 用于匹配文件和目录名称的搜索模式

返回值：

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

directory_tree

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

参数：

path (字符串，必需): 用于生成树的目录的路径

返回值：

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

安全注意事项

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

以适当的权限运行（避免以 root/管理员身份运行）
仅在受信任的环境中使用
考虑为生产用途实施额外的授权机制
谨慎选择允许命令执行和文件操作的目录
实施路径验证以防止未经授权访问系统文件

平台特定的安全说明

Linux/macOS

以具有有限权限的专用用户身份运行
考虑使用 chroot 环境来限制文件系统访问
使用 chmod 限制可执行权限

Windows

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

开发

添加新工具

要使用其他功能扩展 STeLA MCP，请遵循以下模式：

在 shell.py 或 filesystem.py 中的相应类中添加一个新方法
使用 @server.call_tool() 装饰器在 server.py 中注册该工具
使用适当的错误处理和返回类型来实现工具处理程序

示例：

@server.call_tool()
async def my_tool(request: Request[RequestParams, str], arguments: Dict[str, Any]) -> Dict[str, Any]:
    """工具的描述。"""
    try:
        # 工具实现
        result = await do_something(arguments)
        return {"success": True, "result": result}
    except Exception as e:
        return {"error": str(e)}