MCP Background Job

🚀 MCPバックグラウンドジョブサーバ

MCP（モデルコンテキストプロトコル）サーバで、コーディングエージェントが長時間実行されるシェルコマンドを非同期で実行し、完全なプロセス管理機能を提供します。

🚀 クイックスタート

MCPバックグラウンドジョブサーバは、シェルコマンドをバックグラウンドで実行するための強力なソリューションを提供します。エージェントはプロセスを起動、状態を監視、インタラクション、ライフサイクルを管理できます。これは、ビルドプロセス、テストスイート、サーバーなどの長時間実行される操作を含む開発ワークフローに特に有用です。

Claude Codeを使用する場合

設定が完了したら、Claudeにバックグラウンドタスクの支援を依頼できます。

You: "デベロッパーサーバーをバックグラウンドで起動し、監視してください"

Claude: バックグラウンドジョブサーバーを使用してデベロッパーサーバーを起動します。

[実行ツールを使用して開発サーバーを実行]
[ジョブIDを表示し、起動プログレスを監視]
[ステータスの更新を提供]

Claude: "デベロッパーサーバーが http://localhost:3000 で起動しました。
後でコントロールする必要がある場合は、ジョブIDは abc123-def456 です。"

手動でサーバーを使用する場合

開発や直接使用のためには、次のコマンドを実行します。

# 標準入出力トランスポートで実行（最も一般的）
uvx mcp-background-job

# または開発用
uv run python -m mcp_background_job

✨ 主な機能

• 非同期プロセス実行：一意のジョブIDでシェルコマンドをバックグラウンドジョブとして実行
• プロセスライフサイクル管理：バックグラウンドプロセスの起動、監視、インタラクション、終了
• リアルタイム出力監視：バッファリングと末尾追跡機能でstdout/stderrをキャプチャして取得
• 対話型プロセスサポート：stdinを介して実行中のプロセスに入力を送信
• リソース管理：設定可能なジョブ制限と完了したプロセスの自動クリーンアップ
• 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. 新しいMCPサーバーを読み込むために、Claude Codeを再起動します。

開発環境のセットアップ

ローカル開発やコントリビューションのためのセットアップ手順です。

前提条件

• 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"Job status: {status.status}")

# 3. 最近の出力を取得
output = await tail_job_output(job_id, lines=20)
print("Recent output:", output.stdout)

# 4. プロセスとインタラクション
interaction = await interact_with_job(job_id, "some input\n")
print("Process response:", interaction.stdout)

# 5. 完了したらジョブを終了
result = await kill_job(job_id)
print(f"Kill result: {result.status}")

📚 ドキュメント

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 Server: ツール定義を含むMCPプロトコルの実装
• Pydantic Models: 型安全なデータ検証とシリアライゼーション

主要コンポーネント

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. 変更をコミットします。

開発サーバーのワークフロー

# 開発サーバーを起動
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"

セキュリティに関する考慮事項

• プロセス分離: 各ジョブは別のサブプロセスとして実行されます。
• リソース制限: 同時実行ジョブ数とメモリ使用量の設定可能な制限。
• 入力検証: すべてのパラメータはPydanticモデルを使用して検証されます。
• コマンド制限: 本番環境ではコマンドの許可リストを実装することを検討してください。
• 出力サニタイズ: プロセスの出力には機密情報が含まれる可能性があることに注意してください。

トランスポートサポート

サーバーは複数のMCPトランスポートをサポートしています。

• stdio: ローカル開発とエージェント統合のためのデフォルトのトランスポート
• HTTP: リモートアクセス用（追加の設定が必要）

stdioトランスポートを使用する場合は、プロトコルの競合を避けるために、ログをstderrのみに出力するようにしてください。

トラブルシューティング

一般的な問題

インポートエラー: パッケージが開発モードでインストールされていることを確認してください。

uv add -e .

テストが実行されない: まずパッケージをインストールしてから、テストを実行してください。

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

権限エラー: 実行しようとしているコマンドに適切な権限があることを確認してください。

メモリ問題: 大量の出力を生成するプロセスを扱う場合は、MCP_BG_MAX_OUTPUT_SIZEを調整してください。

コントリビューション

1. リポジトリをフォークします。
2. 機能ブラン，を作成します。
3. テストを含めて変更を加えます。
4. テストスイートとコードフォーマットを実行します。
5. プルリクエストを送信します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

変更履歴

v0.1.1

• uvxを通じて簡単にインストールできるようにPyPIに公開
• コンソールスクリプトのエントリポイント（mcp-background-job）を追加
• インストールと使用方法の説明を含むドキュメントを更新
• リンティングの問題を修正し、コード品質を向上

v0.1.0

• 完全なMCPツールサポートを備えた初期実装
• プロセスのライフサイクル管理
• 設定可能なリソース制限
• 包括的なテストスイート

❤️ FastMCP とPython 3.12+ を使用して構築されました。