mcp-dev-server MCP Server

mcp-shell-yeah

一个 Model Context Protocol (MCP) 服务，旨在解决一个常见难题：AI Agent 难以可靠地管理长时间运行的本地开发任务，例如服务器、构建监视器或测试运行器。这些后台 Shell 通常需要在多次对话之间持续运行，而检查其状态或日志往往需要脆弱的自定义脚本或人工干预。mcp-shell-yeah 提供了标准化的 MCP 接口，使 AI Agent 能够可靠地启动、监控、获取日志并停止这些关键的 Shell 进程，从而简化 AI 驱动的开发工作流。

---

快速开始：添加到 Cursor

"mcp-shell-yeah": {
  "command": "npx",
  "args": ["mcp-shell-yeah@latest"]
}

---

🚀 想成为 Cursor 专家吗？🏆

掌握 Cursor 中的高级工作流、技巧和真实 AI 开发策略。
我每周四都会直播授课，通常每周两次。

👉 egghead.io/workshop/cursor

---

核心功能

• 启动和管理长时间运行的 Shell： 启动并管理开发服务器、测试运行器、构建脚本等。
• 在多次对话之间保持 Shell 状态： Shell 会持续运行，并可在未来的聊天中检查或控制。
• 检查实时状态： 即时了解进程正在运行、已崩溃还是已停止。
• 可靠地访问 Shell 输出日志： 获取任何受管理 Shell 的近期日志或完整日志。
• 停止指定 Shell 或所有受管理的 Shell： 根据需要正常或强制终止进程。
• 向交互式 Shell 发送输入： 与提示或命令行工具交互。

---

常见用例

• 启动开发服务器： 运行 npm run dev，之后让 AI 检查其日志或状态——即使是在新的聊天中。
• 监控测试运行器： 运行 npm run test:watch，让 AI 跨会话监视测试失败。
• 跟踪长时间构建： 启动耗时较长的 build 命令，休息一会儿后再检查是否完成。
• 重启卡住的进程： 如果某个开发服务器无响应，可以让 AI 重启它。

---

API 参考

详细的工具和 API 文档（参数、JSON 结构等）请参阅 API.md。

---

开发环境设置

先决条件：

• Node.js（推荐 v20.x 或更高版本）
• pnpm（首选）或 npm

步骤：

1. 克隆代码仓库：

   git clone https://github.com/johnlindquist/mcp-shell-yeah.git # Replace with actual repo URL
   cd mcp-shell-yeah
   

2. 安装依赖：

   pnpm install
   # or
   # npm install
   

3. 构建项目：

   pnpm run build
   # or
   # npm run build
   

4. 在本地运行构建后的服务：

   node build/index.js
   

---

已知限制

• 交互式提示词捕获： 某些交互式提示词（尤其是来自 bash 和 python 脚本的提示词）可能无法捕获到 PTY 日志中，即使使用所有已知的变通方法也不例外。基于 Node.js 的提示词可以可靠捕获。详情请参阅 API 文档。
• Node.js Readline 提示词： 由于 PTY 的限制，Node.js readline 提示词可能不会显示在日志中。这是一个已知的 Node.js/PTY 问题。
• macOS 上的 OSC 133 提示词检测： 在 macOS（bash 3.2）上，可能无法可靠地检测到 OSC 133 提示词序列。系统会使用启发式提示词检测作为回退方案。

---

技术栈

• Node.js / TypeScript
• @modelcontextprotocol/sdk：核心 MCP 服务框架
• node-pty：可靠的伪终端进程管理
• zod：运行时验证
• biomejs：格式化和代码检查
• semantic-release：自动版本管理和发布

---

MCP 合规性

本项目严格遵循官方 Model Context Protocol（MCP）标准中关于工具响应和类型用法的规定。所有结果/内容类型均直接从 @modelcontextprotocol/sdk/types.js 导入（使用 .js 以兼容 ESM）。不允许为工具结果或内容定义自定义类型。所有工具实现和辅助函数均按 MCP 规范要求返回 { content: [...], isError?: boolean } 结构。

---

贡献者指南、内部说明和高级集成详情，请参阅 CONTRIBUTING.md 和 API.md。

功能

• 启动进程： 使用 Shell 命令在指定工作目录中启动新的后台进程。
• 监控状态： 检查进程是否处于启动中、运行中、验证中、已停止、重启中、已崩溃或错误状态。
• 查看日志： 获取托管进程的近期输出（stdout/stderr）。
• 停止进程： 正常终止（SIGTERM）或强制杀死（SIGKILL）指定进程。
• 停止全部进程： 终止服务实例管理的所有进程。
• 重启进程： 便捷地停止并重新启动指定进程。
• 等待状态： 暂停执行，直到进程达到所需状态（例如，'running'）。
• 可选标签： 为进程设置自定义标签，或让服务根据命令和工作目录生成标签。
• 自动清理： 提供基本的僵尸进程检测，并尝试在关闭时终止托管进程。
• 更完善的 Cursor-tail 指引： 为 Cursor IDE 用户启动后台进程时提供更完善的指引。
• 自动清除： 自动从进程列表中清除已停止的进程；查询已清除的进程时，会返回已停止状态和空日志。

可用工具

此服务向 MCP 客户端提供以下工具：

• start_shell：启动一个新的后台进程。（标签可选）如果日志中发现任何 URL，AI 应提取这些 URL 并以 Markdown 链接形式返回。

• start_shell_with_verification：启动一个新的后台进程，并提供验证、超时和重试选项。（标签可选）

• check_shell：检查指定进程的状态和日志。（需要标签）如果日志中发现任何 URL，AI 应提取这些 URL 并以 Markdown 链接形式返回。

• stop_shell：停止指定进程。（需要标签）

• list_shells：列出所有当前管理的进程及其基本状态。

• stop_all_shells：尝试停止所有受管理的进程。

• restart_shell：重启指定进程。（需要标签）

• wait_for_shell：等待指定进程达到目标状态。（需要标签）

• get_all_loglines：获取指定受管理进程存储的完整日志记录。（需要标签）

• send_input：向运行中进程的 stdin 发送文本输入。（需要标签）

  **新行为：**发送输入后，此工具会等待 1 秒，然后返回 check_shell 调用的结果，其中包含更新后的日志和进程状态。这样你就能看到输入对进程产生的即时影响。

  示例：

  // 集成测试代码片段
  const sendInputRequest = {
    jsonrpc: "2.0",
    method: "tools/call",
    params: {
      name: "send_input",
      arguments: { label, input: 'echo "hello from send_input"' },
    },
    id: `req-sendinput-${label}`,
  };
  const sendInputResponse = (await sendRequest(serverProcess, sendInputRequest));
  const sendInputResult = JSON.parse(sendInputResponse.result.content[0].text);
  // sendInputResult.logs 将包含 "hello from send_input"
  // sendInputResult.status 将反映更新后的进程状态
  

• health_check：提供进程管理器自身的状态摘要。

快速入门：运行服务

运行 MCP Process Manager 最简单的方式是使用 npx，无需手动安装即可确保使用最新发布版本。

1. 打开终端。
2. 运行服务：

   npx mcp-shell-yeah
   

3. **服务正在运行：**该命令会下载（如有需要）并执行 mcp-shell-yeah 服务。它会将初始化日志输出到 stderr，然后等待通过标准输入（stdin）接收 MCP 消息，并将响应发送到标准输出（stdout）。

现在，你可以将 MCP 客户端或编排器配置为通过该进程的 stdio 流进行通信。

开发环境设置

如果你想修改此服务或参与开发：

先决条件：

• Node.js（建议使用 v20.x 或更高版本）
• npm（通常随 Node.js 一起安装）或 pnpm

步骤：

1. 克隆仓库：

   git clone https://github.com/johnlindquist/mcp-shell-yeah.git # Replace with actual repo URL
   cd mcp-shell-yeah
   

2. 安装依赖：

   npm install
   # or if using pnpm:
   # pnpm install
   

3. 构建项目： 这会将 TypeScript 代码编译为 JavaScript，并输出到 build/ 目录。

   npm run build
   

4. 在本地运行构建后的服务： 使用 Node 直接执行编译后的代码。

   node build/index.js
   

   服务将启动并监听 stdio，与 npx 版本一样。

5. （可选）监视更改： 在积极开发时，可以运行监视脚本。每当你保存源文件（src/**/*.ts）的更改时，脚本都会自动重新构建项目。

   npm run watch
   

   每次重新构建后，你都需要手动重启 node build/index.js 进程，才能运行更新后的代码。

开发说明：

• 代码库已模块化，以提高代码清晰度和可维护性。
• 类型和常量现已集中管理。
• 集成测试和单元测试已拆分，以提高清晰度和运行速度。
• 所有测试和辅助工具都要求使用 MCP 结果格式（result.content[]）。
• 整个代码库都严格执行类型安全和 MCP 合规性要求。

技术栈

• Node.js / TypeScript
• @modelcontextprotocol/sdk：核心 MCP 服务框架。
• node-pty：用于可靠地管理伪终端进程。
• zod：用于在运行时验证工具参数。
• biomejs：用于格式化和代码检查。
• semantic-release：用于自动化版本管理和发布。

MCP 合规性

本项目严格遵循官方 Model Context Protocol（MCP）标准，规范工具响应和类型的使用：

• 所有工具结果／内容类型都直接从 @modelcontextprotocol/sdk/types.js 导入（使用 .js 以兼容 ESM）。
• 不允许为工具结果或内容自定义类型定义。
• 所有工具实现和辅助工具都必须按 MCP 规范要求，返回 { content: [...], isError?: boolean } 结构。
• 测试和辅助工具必须使用新格式（例如，使用 result.content[0].text，而不是任何旧格式）。
• 测试辅助工具和类型断言必须符合新格式。

示例请参阅 [src/mcpUtils.ts]、[src/toolImplementations.ts] 和 [tests/integration/test-helpers.ts]。

核心概念（2024）

• **命令式 AI 指令：**响应中的 ai_instructions 字段现已成为 AI 下一步必须执行操作的唯一依据。该字段始终存在，并使用明确、强制的措辞（例如：“MANDATORY: Immediately run the tail_command using your run_terminal_cmd tool in a BACKGROUND terminal to monitor this shell's output (the command may be blocking). You MUST also display every detected_urls entry as a clickable markdown link to the user. Do not skip these steps.”）。
• **必须使用后台终端：**AI 必须始终在后台终端中运行 tail_command，因为该命令可能会阻塞。切勿在前台运行。
• **提取 URL：**日志中找到的任何 URL 都会返回到 detected_urls 数组中。AI 必须始终将这些 URL 以可点击的 Markdown 链接形式展示给用户。

工具目录

本节介绍 mcp-shell-yeah 提供的工具。

start_shell

启动并管理后台进程（例如开发服务器或脚本）。

参数：

• command（字符串，必填）：要执行的命令。
• workingDirectory（字符串，必填）：运行命令的绝对工作目录。此设置为必填项。请勿使用 . 或 ../ 等相对路径。请提供完整路径（例如，/Users/me/myproject）。
• label（字符串，可选）：可选的易读标识符（例如，'dev-server'）。留空时，服务将根据 CWD 和命令生成标识符。
• args（字符串数组，可选，默认值：[]）：命令的可选参数。
• host（字符串，可选，枚举值："cursor"、"claude"、"chatgpt"、"vscode"、"windsurf"、"unknown"，默认值："unknown"）：发起进程的客户端标识符。用于提供针对性的回复或说明。

返回值：（JSON）

成功调用 start_shell 后返回的响应负载。包含 label、status、pid、command、args、cwd、exitCode、signal、log_file_path、tail_command、message、logs、monitoring_hint、info_message 和 detected_urls 等字段（如果日志中发现任何 URL，AI 应将其提取并以 Markdown 链接的形式返回）。

• ai_instructions（字符串，必填）：AI 必须始终遵循此字段中的说明。此字段始终会要求 AI 在后台终端中运行 tail_command（切勿在前台运行，因为这可能会阻塞），并将所有 detected_urls 显示为可点击的 Markdown 链接。AI 绝不能跳过或延迟这些步骤。
• user_hint（字符串，可选）：面向用户的后续操作提示。

失败时，返回一个错误对象，可能包含 error、status、cwd、error_type。

用法示例：

{
  "command": "npm",
  "args": ["run", "dev"],
  "workingDirectory": "/path/to/my-web-app",
  "label": "webapp-dev-server",
  "host": "cursor"
}

start_shell_with_verification

启动后台进程并进行验证（模式、超时、重试）。

参数：

• command（字符串，必填）：要执行的命令。
• workingDirectory（字符串，必填）：运行命令的绝对工作目录。此设置为必填项。请勿使用 . 或 ../ 等相对路径。请提供完整路径（例如，/Users/me/myproject）。
• label（字符串，可选）：可选的易读标识符（例如，'dev-server'）。留空时，服务将根据 CWD 和命令生成标识符。
• args（字符串数组，可选，默认值：[]）：命令的可选参数。
• host（字符串，可选，枚举值："cursor"、"claude"、"chatgpt"、"vscode"、"windsurf"、"unknown"，默认值："unknown"）：发起进程的客户端标识符。用于提供针对性的回复或说明。
• verification_pattern（字符串，可选）：用于匹配 stdout/stderr 以验证是否成功启动的可选正则表达式模式。例如，'running on port 3000' 或 'localhost'。
• verification_timeout_ms（整数，可选，默认值：-1）：等待匹配验证模式的毫秒数。-1 表示禁用计时器（默认值）。
• retry_delay_ms（整数，可选）：进程崩溃后重启前的可选延迟时间，单位为毫秒（默认值：1000ms）。
• max_retries（整数，可选）：进程崩溃后的最大重启尝试次数（默认值：3）。0 表示禁用重启。

返回值：（JSON）

成功调用 start_shell_with_verification 后返回的响应负载。包含 label、status、pid、command、args、cwd、exitCode、signal、log_file_path、tail_command、message、logs、monitoring_hint、info_message 等字段。

• instructions（字符串，可选）：如果将 host 指定为 "cursor" 且启用了文件日志记录，此字段将包含给 Cursor IDE 的建议说明，例如启动后台终端来运行 tail_command。 失败时，返回一个错误对象，可能包含 error、status、cwd、error_type。

用法示例：

{
  "command": "npm",
  "args": ["run", "dev"],
  "workingDirectory": "/path/to/my-web-app",
  "label": "webapp-dev-server",
  "host": "cursor",
  "verification_pattern": "ready - started server on",
  "verification_timeout_ms": 30000,
  "retry_delay_ms": 1000,
  "max_retries": 3
}

check_shell

检查受管理进程的当前状态，包括近期日志。

参数：

• label（字符串，必填）：要检查的进程标签。
• log_lines（整数，可选，默认值：20）：请求的近期日志行数。默认值：20。最多存储：1000 行。使用 'getAllLoglines' 获取完整的已存储历史记录（最多 1000 行）。

返回：（JSON）

check_shell 的响应载荷。包含 label、status、pid、command、args、cwd、exitCode、signal、log_file_path、tail_command、logs、hint 和 detected_urls 等字段（如果日志中发现任何 URL，AI 应提取这些 URL，并以 Markdown 链接的形式返回）。

• ai_instructions（字符串，必填）：AI 必须始终遵循此字段中的指令，包括在后台终端中运行 tail_command，并将所有 detected_urls 显示为 Markdown 链接。

使用示例：

{
  "label": "webapp-dev-server",
  "log_lines": 50
}

list_shells

列出所有当前受管理进程及其状态。

参数：

• log_lines（整数，可选，默认值：0）：要为每个进程包含的近期日志行数（默认值：0，即不包含）。

返回：（JSON）

list_shells 的响应载荷，包含进程详细信息数组。每个详细信息对象都包含 label、status、pid、command、args、cwd、exitCode、signal、log_file_path、tail_command、logs、log_hint 等字段。

使用示例：

{
  "log_lines": 10
}

stop_shell

停止指定的受管理进程。

参数：

• label（字符串，必填）：要停止的进程标签。
• force（布尔值，可选，默认值：false）：使用 SIGKILL 强制终止进程，而不是使用 SIGTERM 优雅地终止。默认值为 false。

返回：（JSON）

stop_shell 的响应载荷。包含 label、status、message、pid 等字段。

使用示例：

{
  "label": "webapp-dev-server",
  "force": true
}

stop_all_shells

尝试优雅地停止所有受管理进程。

参数： 无

返回：（JSON）

stop_all_shells 的响应载荷。包含 summary 字符串和 details 数组。每个详细信息对象都包含 label、result（例如 SignalSent、Skipped、Failed）、status、pid。

使用示例：

{}

restart_shell

重启指定的受管理进程（如果进程正在运行，则先停止，然后使用原始配置重新启动）。

参数：

• label（字符串，必填）：要重启的进程标签。

返回：（JSON）

restart_shell 调用成功时的响应载荷（结构与 start_shell 成功时的响应一致）。失败时，返回一个错误对象，其中包含 `

已知限制：交互式提示捕获

某些交互式提示（尤其是来自 bash 和 python 脚本的提示）可能无法捕获到 PTY 日志中，即使使用了所有已知的变通方法（例如 stdbuf、script、无缓冲环境变量）。这是由于操作系统和语言层面的输出缓冲，在某些情况下无法从外部绕过。

• 基于 Node.js 的提示可以可靠捕获。
• 所有语言的回显／输出都可以可靠捕获。
• 如果需要确保进程管理器能够看到提示，请优先使用基于 Node.js 的 CLI，或者确保工具显式刷新输出。
• 这是 PTY 和缓冲行为的根本限制，并非进程管理器中的错误。

已知限制：Node.js Readline 提示词与 PTY 捕获

Node.js readline 提示词可能不会出现在日志中，也可能无法被检测为等待输入的提示词。

• Node.js readline 库有时会将提示词直接写入终端设备，而不是通过进程的 stdout 流输出。
• 在基于 PTY 的进程管理器中，这意味着日志中可能看不到提示词，也可能无法触发提示词检测启发式规则。
• 这是 Node.js readline 与 PTY 交互中一个有充分记录的限制（参见 Node.js issue #29589）。
• 其他所有提示词类型（bash、python、node 自定义 CLI 等）均可正确捕获和检测。
• 如果日志中没有提示词，几乎总是因为程序实际上并未输出提示词（或者使用了你的解析器会忽略的转义序列）。

测试覆盖：

• 已包含用于检测 Node.js readline 提示词的集成测试，但该测试已跳过，以记录此限制并捕捉 PTY 或 Node.js 行为未来可能的改进。

已知限制：macOS 上的 OSC 133 提示词检测

• 在 macOS（bash 3.2）上，从 shell 发出原始 OSC 133 提示词序列（例如，\x1b]133;B\x07）并不可靠。
• 即使使用直接的 printf 或 shell 提示词配置，预期的转义序列也不会出现在 PTY 缓冲区中。
• 这是 shell／环境的限制，而非检测逻辑的问题。
• 因此，基于 OSC 133 的提示词检测测试已跳过，测试文件中附有详细注释。
• 启发式提示词检测（例如，以 :、? 等结尾的行）会作为备用方案使用，足以满足大多数交互式 CLI 使用场景。
• 如果需要可靠地检测 OSC 133，可以考虑在使用较新 bash 或 zsh shell 的 Linux 环境中运行测试。