Terminal Command Runner MCP Server

终端命令运行器 MCP 服务

一个功能强大的模型控制协议（MCP）服务，通过 RESTful API 接口为 AI 助手提供终端命令执行和文件系统管理功能。

🌟 功能

终端管理

• 执行命令并配置超时时间
• 在后台管理长时间运行的进程
• 获取活动命令会话的输出
• 列出所有活动会话和系统进程
• 终止或杀死进程
• 通过命令黑名单增强安全性

文件系统操作

• 读取和写入文件
• 创建目录
• 列出目录内容
• 移动/重命名文件
• 使用 glob 模式搜索文件
• 获取详细的文件信息

高级功能

• 使用搜索和替换精确编辑文本
• 获取系统信息
• 计算数学表达式

🚀 快速开始

先决条件

• Python 3.13+
• uv 包管理器（推荐）

安装

1. 克隆仓库：

git clone https://github.com/neoforge-dev/neoforge-mcp-server.git
cd python-server-mcp

2. 创建虚拟环境并安装依赖：

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

3. 启动 MCP 服务：

python server.py

服务将在 http://0.0.0.0:8000 上启动。

🧪 测试

项目包含全面的测试套件，用于验证功能：

# Install test dependencies
uv pip install -r requirements.txt

# Run all tests
./run_tests.py

# Run tests with coverage report
./run_tests.py --coverage

# Run tests with verbose output
./run_tests.py --verbose

# Run specific test file
./run_tests.py --test tests/test_command_execution.py

测试套件涵盖：

• 命令执行和进程管理
• 文件系统操作
• 系统工具
• 安全功能

🔧 配置

在 ~/.cursor/mcp.json 文件中添加此 MCP 服务，以配置 Cursor 使用它：

{
  "mcpServers": {
    "NeoMCP": {
      "command": "/path/to/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/path/to/python-server-mcp/server.py"
      ]
    }
  }
}

📖 API 参考

终端工具

• execute_command：运行命令并配置超时时间
• read_output：获取运行中进程的输出
• force_terminate：停止运行中的命令
• list_sessions：显示所有活动命令会话
• list_processes：查看所有系统进程
• kill_process：通过 PID 杀死进程
• block_command：将命令加入黑名单
• unblock_command：将命令从黑名单中移除

文件系统工具

• read_file：读取文件内容
• write_file：向文件写入数据
• create_directory：创建新目录
• list_directory：列出目录内容
• move_file：移动或重命名文件和目录
• search_files：查找符合模式的文件
• get_file_info：获取详细的文件信息

编辑工具

• edit_block：使用类似 diff 的语法精确替换文本

系统工具

• system_info（资源）：获取详细的系统信息
• calculate：计算数学表达式

🔒 安全注意事项

• 服务通过命令黑名单来阻止危险命令
• 限制读取操作的文件大小
• 提供表达式计算防护措施
• 默认执行命令安全检查

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。