Neoforge MCP Server

🚀 终端命令运行器 MCP 服务器

这是一个功能强大的模型控制协议（MCP）服务器，借助 RESTful API 接口，为 AI 助手赋予了终端命令执行和文件系统管理的能力，能极大提升操作效率与便捷性。

🚀 快速开始

先决条件

• 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  # Windows 环境下：.venv\Scripts\activate
uv pip install -e .

3. 启动 MCP 服务器：

python server.py

服务器将在 http://0.0.0.0:8000 上运行。

✨ 主要特性

终端管理

• 执行带有可配置超时的命令
• 管理后台长-running 进程
• 从活动命令会话获取输出
• 列出所有活动会话和系统进程
• 终止或杀死进程
• 命令黑名单功能（安全）

文件系统操作

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

高级功能

• 精确文本编辑（包括搜索和替换）
• 系统信息检索
• 数学表达式计算

🧪 测试

该项目包含全面的测试套件以验证功能：

# 安装测试依赖项
uv pip install -r requirements.txt

# 运行所有测试
./run_tests.py

# 生成覆盖率报告运行测试
./run_tests.py --coverage

# 详细输出运行测试
./run_tests.py --verbose

# 运行特定测试文件
./run_tests.py --test tests/test_command_execution.py

测试套件覆盖以下内容：

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

🔧 配置

通过将 MCP 服务添加到 ~/.cursor/mcp.json 文件来配置 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：移动或重命名文件
• 获取详细文件信息

高级工具

• 精确文本编辑（包括搜索和替换）
• 系统信息检索
• 数学表达式计算

🤝 贡献指南

欢迎贡献！请参考 CONTRIBUTING.md 了解如何参与。

📄 许可证

本项目受 LICENSE 保护。