Bg Server MCP Shell

文件： 主 | 测试

Cover Image

bg-mcp shell服务器

用于在PTY中运行长时间运行的进程的MCP服务器，具有实时输出流

✨ 特性

• ✅ 实时输出流 -实时终端输出
• ✅ 交互式过程 -向正在运行的进程发送输入
• ✅ 多个会话 -同时控制多个进程
• ✅ 缓冲输出 -保留完整的输出历史记录
• ✅ PTY仿真 -真正的终端体验

👥 非常适合

• 🚀 开发服务器 （Vite、webpack、Next.js）
• 🔄 观看模式 （nodemon，是 --watch）
• 🐳 Docker/Docker编写
• 🧪 长时间运行测试
• 💬 交互式CLI工具

🤖 用例提示

\[你\] 运行web开发服务器，检查错误并修复

\[你\] “运行剧作家测试并监控错误。”

\[你\] “构建并部署到Cloudflare。”

\[你\] “启动docker compose，告诉我postgres什么时候准备好了。”

\[你\] “告诉我正在运行哪些进程。”

\[你\] “重新启动进程。”

📊 比较

|创建者|长时间运行的流程|响应输出|交互|最适合| |-|-|-|-|-| | 背景 | ✅ 是|✅ 缓冲器+端子|✅ writeInput |开发服务器、监视模式| | tumf | ❌ 悬挂|✅ 是|✅ 是|ls、cat、grep、git状态| | hdresearch | ❌ 悬挂|✅ 是|✅ 是|基本命令| | 运行命令 | ⚠️ 阻塞/异步|⚠️ 部分|❌ 否|具有用户批准的标准命令|

🚀 快速开始

安装

npm install -g bg-server-mcp-shell

配置

添加到您的MCP客户端配置中（例如，Claude Desktop、Cline）：

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["-y", "bg-server-mcp-shell@latest"],
      "env": {
        "COLOR": "false"
      }
    }
  }
}

🛠️ 函数

快速命令（等待完成）： startProcessAndWait 运行命令并等待完成

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"startProcessAndWait","arguments":{"cmd":"echo","args":["Hello"],"timeoutMs":5000}}}' | npx bg-server-mcp-shell

启动后台进程： startProcessBackground 在后台启动长时间运行的进程

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"startProcessBackground","arguments":{"cmd":"npm","args":["run","dev"]}}}' | npx bg-server-mcp-shell

列出会话： listSessions 列出所有活动会话

echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"listSessions","arguments":{}}}' | npx bg-server-mcp-shell

获取输出： getSessionOutput 从会话中读取缓冲输出

echo '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"getSessionOutput","arguments":{"sessionId":""}}}' | npx bg-server-mcp-shell

发送输入： writeInput 向正在运行的进程发送输入

echo '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"writeInput","arguments":{"sessionId":"","data":"rs\n"}}}' | npx bg-server-mcp-shell

停止进程： stopProcess 停止正在运行的会话

echo '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"stopProcess","arguments":{"sessionId":""}}}' | npx bg-server-mcp-shell

清理已完成的会话： cleanupSessions 从内存中删除已完成的会话

# Cleanup specific session
echo '{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"cleanupSessions","arguments":{"sessionId":""}}}' | npx bg-server-mcp-shell

# Or cleanup all finished sessions
echo '{"jsonrpc":"2.0","id":8,"method":"tools/call","params":{"name":"cleanupSessions","arguments":{}}}' | npx bg-server-mcp-shell

🧪 发展

完整文档： 看 测试文件 以获取完整的测试指南、覆盖范围和API参考。

📦 技术细节

• 框架： MCP（模型上下文协议） MCP协议规范
• 测试跑者： Node.js原生测试运行器（Node:test）
• PTY： 终端仿真节点pty
• 节点： 18+必填
• 平台： macOS、Linux、Windows

🤝 贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 为新功能添加测试
4. 确保所有测试通过： npm test
5. 提交拉取请求

🐛 问题和Bug报告

发现错误或有功能请求？请在GitHub上报告：

报告问题

📄 许可证

MIT© 布鲁诺·加勒特