使用说明

⚡ GodMode MCP服务器

LLM系统控制的全能接口

让你的AI代理直接、异步和持久地控制操作系统。 Shell执行•文件系统掌握•网络反思•后台作业管理

🛑 安全警告

⚠️ 关键： 此服务器提供 远程代码执行（RCE） 连接客户端的能力。它允许LLM执行shell命令、修改文件和控制系统进程。

不要将此服务器暴露到公共互联网。

不要在关键生产环境中运行此程序，而无需沙盒。

总是部署前检查代码。

📖 概述

上帝模式 是一个高性能的实现 **模型上下文协议（MCP）**与标准沙盒工具不同，GodMode弥合了LLM和主机操作系统内核之间的差距。

它具有自定义功能 异步作业管理器 对于长时间运行的流程，a 断路器 容错模式，以及 持久状态 管理以确保服务器重启后的生存。它将标准LLM转换为功能齐全的系统管理员。

🚀 核心能力

1.🐚 先进的外壳和过程控制

异步执行： 通过非阻塞命令执行 shell_exec.
智能执行： 自动将长时间运行的命令提升到后台作业(smart_exec).
工作坚持性： 分离的后台作业在服务器重新启动后仍然有效。随时监控日志、停止或查询状态。
断路器： 自动故障隔离——如果工具反复发生故障，它将进入冷却状态，以防止系统不稳定。

2.💻 互动环节

虚拟终端： 维护有状态的PowerShell/Bash会话。
情境感知： 设置环境变量或导航目录，会话就会记住。

3.📂 文件系统权限

深度搜索： Grep式递归模式搜索(fs_search).
智能阅读： 分页和“尾部”模式，用于读取大量日志文件而不会发生内存溢出。
积垢： 完整的创建、读取、更新、删除功能。

4.🌐 网络与系统上帝模式

反思： 查看打开的套接字、路由表和接口统计信息(net_inspect).
诊断： DNS解析和TCP端口测试。
资源监控： 实时CPU、RAM和磁盘负载分析。

🏗 系统架构

GodMode是建立在 FastMCP （Starlette/Uvicorn），具有用于流程管理的自定义线程模型。

graph TD
    A[LLM / Claude Desktop] -->|MCP Protocol / SSE| B(GodMode Server)
    B --> C{Decision Engine}
    
    C -->|Short Task| D[Direct Shell Exec]
    C -->|Long Task| E[Async Job Manager]
    C -->|Interactive| F[Session Manager]
    
    E --> G[(jobs.json / Logs)]
    F --> H[Persistent Pwsh Process]
    
    D --> I[OS Kernel]
    E --> I
    
    subgraph "Stability Layer"
    J[Circuit Breaker] -.-> D
    J -.-> E
    end

🛠 部署

先决条件

Python 3.10+
PowerShell（推荐用于Windows）或Bash（Linux）

1.克隆和安装

git clone https://github.com/Praveens1234/pwsh.mcp.git
cd pwsh.mcp

# Create virtual environment (recommend but not required)
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

# Install dependencies
pip install mcp[cli] uvicorn starlette psutil FastMCP

2.配置

确保脚本已命名 server.py （不是 mcp.py 以避免导入冲突）。

3.运行服务器

# Run on default port 8000
python server.py

🔌 连接到客户

Claude桌面应用程序

将以下内容添加到您的 %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json （Mac）。

{
  "mcpServers": {
    "godmode": {
      "command": "path/to/venv/Scripts/python",
      "args": ["path/to/godmode/server.py"]
    }
  }
}

🧰 工具参考

⌨️ Shell & Jobs (Click to Expand)

工具名称	描述
`shell_exec`	执行单个命令。返回stdout/stderr。
`smart_exec`	运行命令。如果需要>3s，则转换为后台作业。
`job_start`	显式启动一个分离的后台进程。
`job_list`	显示所有正在运行/已完成/失败的作业。
`job_stop`	很难杀死一个后台工作。
`job_logs`	从后台作业读取输出（支持尾随）。

🖥️ Interactive Sessions (Click to Expand)

工具名称	描述
`session_create`	生成一个新的持久shell会话。
`session_send`	向会话发送命令（维护变量/路径）。
`session_read`	读取会话的缓冲输出。
`session_kill`	终止会话。

📂 File System (Click to Expand)

工具名称	描述
`fs_read`	使用分页或尾部支持读取文件内容。
`fs_write`	向文件写入或附加内容。
`fs_search`	递归grep搜索文本模式。
`fs_list`	列出目录内容。
`fs_delete`	删除文件或目录。

🌐 Network & Admin (Click to Expand)

工具名称	描述
`net_inspect`	查看接口、路由或活动套接字。
`net_connect`	测试与远程主机的TCP连接。
`sys_info`	获取硬件资源使用情况（CPU/RAM/磁盘）。
`service_manage`	启动、停止或重新启动系统服务。
`registry_read`	读取Windows注册表项（仅限Windows）。

🛡️ 可靠性特性

碰撞恢复： 这 StateManager 将作业状态保存到 jobs.json如果服务器崩溃，它会在重新启动时尝试协调进程状态。
全球盾牌： 装饰器封装每个工具执行。

捕获未处理的异常。
将错误记录到 error.log.
断路器： 如果一个工具快速发生5次故障，它将被禁用60秒，以防止级联系统故障。

日志轮换： 内建 RotatingFileHandler 确保 server.log 永远不会消耗太多的磁盘空间。

📜 许可证

MIT许可证。负责任地使用。