MCP Background Job

🚀 MCP 後臺作業服務器

MCP 後臺作業服務器是一個基於 MCP（模型上下文協議）的服務器，支持編碼代理異步執行長時間運行的 shell 命令，並具備完整的進程管理能力。它為在後臺運行 shell 命令提供了強大的解決方案，允許代理啟動進程、監控其狀態、與它們交互並管理其生命週期。這對於涉及構建過程、測試套件、服務器或任何長時間運行操作的開發工作流程特別有用。

🚀 快速開始

與 Claude Code 配合使用

配置完成後，可讓 Claude 協助處理後臺任務：

你: "在後臺啟動我的開發服務器並監控它"

Claude: 我將使用後臺作業服務器啟動你的開發服務器。

[使用執行工具運行你的開發服務器]
[顯示作業 ID 並監控啟動進度]
[提供狀態更新]

Claude: "你的開發服務器現已在 http://localhost:3000 上運行。
作業 ID 是 abc123 - def456，如果你以後需要控制它。"

手動使用服務器

用於開發或直接使用：

# 使用標準輸入輸出傳輸運行（最常見）
uvx mcp-background-job

# 或者用於開發：
uv run python -m mcp_background_job

✨ 主要特性

• 異步進程執行：以唯一的作業 ID 作為後臺作業執行 shell 命令。
• 進程生命週期管理：啟動、監控、與後臺進程交互並終止它們。
• 即時輸出監控：捕獲和檢索標準輸出/標準錯誤，並具備緩衝和尾隨功能。
• 交互式進程支持：通過標準輸入向正在運行的進程發送輸入。
• 資源管理：可配置作業限制，並自動清理已完成的進程。
• MCP 協議集成：與模型上下文協議完全集成，便於代理交互。

📦 安裝指南

快速安裝（推薦）

使用 uvx 直接從 PyPI 安裝：

# 安裝並運行 MCP 服務器
uvx mcp-background-job

集成到 Claude Code

將服務器添加到你的 Claude Code 配置中：

1. 選項 A：使用 Claude Code 桌面版
   • 打開 Claude Code 設置/偏好設置。
   • 導航到 MCP 服務器部分。
   • 添加新服務器：
     • 名稱：background-job
     • 命令：uvx
     • 參數：["mcp-background-job"]
2. 選項 B：配置文件 在你的 Claude Code 配置文件中添加以下內容：

   {
     "mcpServers": {
       "background-job": {
         "command": "uvx",
         "args": ["mcp-background-job"]
       }
     }
   }
   

3. 重啟 Claude Code 以加載新的 MCP 服務器。

開發環境設置

用於本地開發或貢獻代碼：

前提條件

• Python 3.12 或更高版本
• uv 包管理器

設置步驟

1. 克隆並進入項目目錄：

   git clone https://github.com/dylan-gluck/mcp-background-job.git
   cd mcp-background-job
   

2. 安裝依賴項：

   uv sync
   

3. 以開發模式安裝：

   uv add -e .
   

💻 使用示例

基礎用法

# 1. 執行一個長時間運行的命令
execute_result = await execute_command("npm run dev")
job_id = execute_result.job_id

# 2. 檢查作業狀態
status = await get_job_status(job_id)
print(f"作業狀態: {status.status}")

# 3. 獲取最近的輸出
output = await tail_job_output(job_id, lines=20)
print("最近的輸出:", output.stdout)

# 4. 與進程交互
interaction = await interact_with_job(job_id, "some input\n")
print("進程響應:", interaction.stdout)

# 5. 完成後終止作業
result = await kill_job(job_id)
print(f"終止結果: {result.status}")

開發服務器工作流程示例

# 啟動開發服務器
job_id=$(echo '{"command": "npm run dev"}' | mcp-tool execute)

# 監控啟動過程
mcp-tool tail --job_id "$job_id" --lines 10

# 檢查服務器是否就緒
mcp-tool status --job_id "$job_id"

# 停止服務器
mcp-tool kill --job_id "$job_id"

長時間構建過程示例

# 啟動構建過程
job_id=$(echo '{"command": "docker build -t myapp ."}' | mcp-tool execute)

# 監控構建進度
while true; do
  status=$(mcp-tool status --job_id "$job_id")
  if [[ "$status" != "running" ]]; then break; fi
  mcp-tool tail --job_id "$job_id" --lines 5
  sleep 10
done

# 獲取最終構建輸出
mcp-tool output --job_id "$job_id"

交互式進程示例

# 啟動 Python REPL
job_id=$(echo '{"command": "python -i"}' | mcp-tool execute)

# 發送 Python 代碼
mcp-tool interact --job_id "$job_id" --input "print('Hello, World!')\n"

# 發送更多命令
mcp-tool interact --job_id "$job_id" --input "import sys; print(sys.version)\n"

# 退出 REPL
mcp-tool interact --job_id "$job_id" --input "exit()\n"

📚 詳細文檔

MCP 工具參考

服務器公開了 7 個用於進程管理的 MCP 工具：

只讀工具

交互式工具

作業狀態值

• running - 進程當前正在執行。
• completed - 進程已成功完成。
• failed - 進程因錯誤而終止。
• killed - 進程被用戶終止。

配置

環境變量

使用以下環境變量配置服務器行為：

# 最大併發作業數（默認：10）
export MCP_BG_MAX_JOBS=20

# 每個作業的最大輸出緩衝區（默認：10MB）
export MCP_BG_MAX_OUTPUT_SIZE=20MB
# 或使用字節表示：
export MCP_BG_MAX_OUTPUT_SIZE=20971520

# 默認作業超時時間（秒）（默認：無超時）
export MCP_BG_JOB_TIMEOUT=3600

# 清理已完成作業的間隔時間（秒）（默認：300）
export MCP_BG_CLEANUP_INTERVAL=600

# 作業的工作目錄（默認：當前目錄）
export MCP_BG_WORKING_DIR=/path/to/project

# 允許的命令模式（可選的安全限制）
export MCP_BG_ALLOWED_COMMANDS="^npm ,^python ,^echo ,^ls"

使用環境變量進行 Claude Code 配置

{
  "mcpServers": {
    "background-job": {
      "command": "uvx",
      "args": ["mcp-background-job"],
      "env": {
        "MCP_BG_MAX_JOBS": "20",
        "MCP_BG_MAX_OUTPUT_SIZE": "20MB"
      }
    }
  }
}

編程式配置

from mcp_background_job.config import BackgroundJobConfig

config = BackgroundJobConfig(
    max_concurrent_jobs=20,
    max_output_size_bytes=20 * 1024 * 1024,  # 20MB
    default_job_timeout=7200,  # 2 小時
    cleanup_interval_seconds=600  # 10 分鐘
)

架構

服務器採用模塊化架構構建：

• JobManager：用於作業生命週期管理的核心服務。
• ProcessWrapper：具有 I/O 緩衝功能的子進程處理抽象層。
• FastMCP 服務器：帶有工具定義的 MCP 協議實現。
• Pydantic 模型：類型安全的數據驗證和序列化。

關鍵組件

src/mcp_background_job/
├── server.py          # FastMCP 服務器和工具定義
├── service.py         # JobManager 服務實現
├── process.py         # 用於子進程管理的 ProcessWrapper
├── models.py          # Pydantic 數據模型
├── config.py          # 配置管理
└── logging_config.py  # 日誌設置

開發

運行測試

# 運行所有測試
uv run pytest tests/

# 僅運行單元測試
uv run pytest tests/unit/ -v

# 僅運行集成測試
uv run pytest tests/integration/ -v

代碼格式化

# 使用 ruff 格式化代碼
uv run ruff format

# 運行類型檢查
uv run mypy src/

開發工作流程

1. 進行更改。
2. 運行測試：uv run pytest tests/。
3. 格式化代碼：uv run ruff format。
4. 提交更改。

🔧 技術細節

傳輸支持

服務器支持多種 MCP 傳輸方式：

• stdio：用於本地開發和代理集成的默認傳輸方式。
• HTTP：用於遠程訪問（需要額外設置）。

對於 stdio 傳輸，請確保日誌僅輸出到標準錯誤，以避免協議衝突。

故障排除

常見問題

• 導入錯誤：確保以開發模式安裝了該包：

uv add -e .

• 測試無法運行：先安裝該包，然後運行測試：

uv sync
uv add -e .
uv run pytest tests/

• 權限錯誤：確保你對要執行的命令具有適當的權限。
• 內存問題：如果處理產生大量輸出的進程，請調整 MCP_BG_MAX_OUTPUT_SIZE。

📄 許可證

本項目採用 MIT 許可證 - 有關詳細信息，請參閱 LICENSE 文件。

變更日誌

v0.1.1

• 發佈到 PyPI，可通過 uvx 輕鬆安裝。
• 添加了控制檯腳本入口點 (mcp-background-job)。
• 更新了安裝和使用說明的文檔。
• 修復了 linting 問題並提高了代碼質量。

v0.1.0

• 初始實現，支持完整的 MCP 工具。
• 進程生命週期管理。
• 可配置的資源限制。
• 全面的測試套件。

使用 FastMCP 和 Python 3.12+ 精心打造 ❤️