director-shell-mcp

director-shell-mcp 是一个用于 director 模式代理的小型 MCP 服务器。它使用 MCP stdio 传输，为写入文件、运行 Python 数据探索代码、运行 shell 命令以及监督分离的后台作业提供受控的逃生舱。命令仅在代理显式调用工具时启动；服务器本身不会运行 shell。

安装

需要 Node.js 18 或更高版本。从本目录运行：

npm install

直接运行服务器：

node C:/path/to/director-shell-mcp/index.js

Related MCP server: shell-0

OMP 注册（主要）

主要客户端是 Oh My Pi (OMP) 框架。将以下确切配置添加到用户级 ~/.omp/agent/mcp.json（或项目级 .omp/mcp.json）：

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

对于 stdio 服务器，可以省略 type。编辑配置后，在 OMP 中运行 /mcp reload，然后运行 /mcp test director-shell。

通用 MCP 客户端注册

其他 MCP 客户端通常接受等效的 stdio 注册：

{
  "mcpServers": {
    "director-shell": {
      "command": "node",
      "args": ["C:/path/to/director-shell-mcp/index.js"]
    }
  }
}

工具参考

所有工具都在 MCP 文本内容中返回 JSON 对象。错误以 MCP 工具错误形式返回，并带有句子形式的 error 字段。

shell_run

运行命令直至完成。参数：

• command（字符串，必需）：命令文本。

• cwd（字符串，可选）：工作目录。

• timeout_ms（整数，可选）：默认为 60,000；最大 600,000。

• shell（powershell、cmd 或 bash，可选）：在 Windows 上默认为 PowerShell，在其他系统上默认为 Bash。

结果包含 exit_code、duration_ms 以及 stdout/stderr 对象。每个流最多包含约 50 KiB 的预览文本。如果流超过该上限，其对象还会包含 truncated: true 和 full_output_path，指向包含完整流的临时文件。超时返回 MCP 工具错误，并附带清晰的消息和部分结果。

write_file

将 UTF-8 文本写入绝对文件路径。参数：

• path（字符串，必需）：绝对文件路径。

• content（字符串，必需）：要写入的文本。

• append（布尔值，可选）：追加而不是替换；默认为 false。

• create_dirs（布尔值，可选）：创建缺失的父目录；默认为 true。

结果包含 path、bytes_written、created（文件在调用前是否不存在）和 appended。

edit_file

替换绝对路径下 UTF-8 文件中的文本。参数：

• path（字符串，必需）：绝对文件路径。

• old_text（字符串，必需）：要查找的非空文本。

• new_text（字符串，必需）：替换文本。

• replace_all（布尔值，可选）：替换所有出现；默认为 false。

如果没有 replace_all，old_text 必须恰好出现一次。零匹配或多个匹配返回 MCP 工具错误，并保持文件不变。结果包含 path 和 replacements。

run_python

运行 Python 源代码直至完成，并限制输出和超时。在 Windows 上，服务器先探测 py 启动器，然后探测 python；在其他系统上，先探测 python3，然后探测 python，并缓存第一个可用的可执行文件。参数：

• code（字符串，必需）：Python 源代码。

• cwd（字符串，可选）：Python 进程的工作目录。

• timeout_ms（整数，可选）：默认为 60,000；最大 600,000。

• args（字符串数组，可选）：作为 sys.argv[1:] 传递的值。

结果包含 exit_code、duration_ms、stdout/stderr 对象和 python_executable。输出流被限制并溢出到临时文件，行为与 shell_run 相同。超时返回 MCP 工具错误，并附带清晰的消息和部分结果。

job_start

启动一个分离的命令，该命令在工具调用返回后继续运行。参数：

• command（字符串，必需）

• cwd（字符串，可选）

• shell（powershell、cmd 或 bash，可选）

• name（字符串，可选，人类可读标签）

结果包含 job_id、pid、log_paths（stdout、stderr 和 combined）以及 exit_marker 路径。元数据以 JSON 形式持久化在 %LOCALAPPDATA%/director-shell-mcp/jobs/<jobId>/ 下，因此服务器重启后作业仍然可发现。

job_status

读取作业的持久化状态。参数：

• job_id（字符串，必需）：job_start 返回的 ID。

• tail_lines（整数，可选）：默认为 40；最大 1,000。

结果包含 running、exit_code（可用时）、runtime_ms、started_at 和来自组合日志的 output_tail。分离的包装器在命令退出时写入 exit_code.txt，从而在服务器重启后保留退出代码。

job_kill

终止由此服务器启动的作业。它接受 job_id。在 Windows 上，它使用 taskkill /T /F 终止包装器的进程树。已完成的作业保持不变。

job_list

列出所有有效的持久化作业及其 job_id、可选的 name、pid、running 状态、退出代码和开始时间。

grep_files

使用 JavaScript 正则表达式递归搜索绝对文件或目录，无需 ripgrep。搜索跳过 node_modules、.git、bin、obj、dist 和 target，忽略大于 5 MiB 的文件和二进制文件，并在达到结果限制时停止。参数：

• pattern（字符串，必需）：JavaScript 正则表达式源。

• path（字符串，必需）：绝对文件或目录路径。

• glob（字符串，可选）：使用 * 和 ? 的简单文件名过滤器。

• case_sensitive（布尔值，可选）：默认为 false。

• max_results（整数，可选）：默认为 200；最大 1,000。

• context_lines（整数，可选）：每个匹配前后的行数；默认为 0；最大 5。

结果包含 matches，其中包含 file、line_number、line、before 和 after，以及 files_scanned 和 truncated。无效的正则表达式返回 MCP 工具错误。

job_wait

等待现有的分离作业退出，每 500 毫秒轮询其持久化的退出标记。参数：

• job_id（字符串，必需）：job_start 返回的 ID。

• timeout_ms（整数，可选）：默认为 60,000；最大 600,000。

• tail_lines（整数，可选）：默认为 40；最大 1,000。

结果与 job_status 具有相同的字段，并添加了 timed_out。作业仍在运行时达到截止时间是一个正常结果，带有 timed_out: true，而不是 MCP 错误。

lock_acquire 和 lock_release

提供跨代理的命名互斥锁，持久化在 %LOCALAPPDATA%/director-shell-mcp/locks/ 下。名称仅包含字母、数字、_、. 和 -，且最多 64 个字符。lock_acquire 接受 name（必需）、wait_ms（可选，默认为 0，最大 600,000）和可选的 note；它返回 name、UUID token 和 acquired_at。获取使用原子目录创建，并恢复其记录的所有者进程不再存活的锁。持锁错误会标识其 pid、note（如果存在）和持续时间。lock_release 接受 name 和所有者 token；错误的 token 和空闲锁是错误，不会改变锁。

screenshot

在 Windows 上使用 System.Drawing 和 Windows API 将整个虚拟屏幕或可见的顶级窗口捕获为 PNG。参数：

• target（screen 或 window，可选）：默认为 screen。

• window_title（字符串，window 必需）：不区分大小写的可见窗口标题子字符串。

• output_path（绝对 .png，可选）：默认为临时输出目录中带时间戳的文件。

结果包含 path、width、height、target 以及窗口捕获的匹配 window_title。在非 Windows 系统上返回清晰的“不支持”错误，在找不到请求的窗口时返回清晰的“无匹配”错误。

process_list

在 Windows 上返回只读进程列表。参数：

• name_filter（字符串，可选）：进程名称或可执行路径的不区分大小写的子字符串。

• max_results（整数，可选）：默认为 100；最大 1,000。

每个进程包含 pid 和 name，并在可用时包含 path、started_at 和 working_set_bytes。结果还包含 truncated。

file_lockers

通过 Restart Manager API 报告在 Windows 上持有现有文件打开的进程。它接受 path（必需），必须是现有文件的绝对路径，并返回 { path, lockers }。每个 locker 包含 pid、app_name 和 app_type；未锁定的文件是成功结果，lockers 数组为空。非 Windows 系统返回清晰的“不支持”错误。

验证

运行轻量级端到端冒烟测试（仅使用 echo 和 PowerShell sleep）：

npm run smoke

冒烟测试通过 stdio 启动一个新的 MCP 服务器，执行初始化，列出所有十五个工具，练习文件写入、精确文本编辑、Python 执行和参数传递、命令完成和输出捕获，验证分离作业在运行期间和退出后的状态，练习 grep、wait、锁、截图、进程列表和 Restart Manager 文件锁检测，通过 job_list 检查持久性，并验证命令超时处理。

许可证

MIT