shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

mcp-background-job

MCP后台作业服务器是一个基于Python的异步任务执行系统，支持通过MCP协议管理长时间运行的Shell命令，提供进程生命周期管理、实时输出监控和交互式操作功能。

article

README

🚀 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 工具：

只读工具

| 工具 | 描述 | 参数 | 返回值 | |------|------|------|------| | list | 列出所有后台作业 | 无 | {jobs: [JobSummary]} | | status | 获取作业状态 | job_id: str | {status: JobStatus} | | output | 获取作业的完整输出 | job_id: str | {stdout: str, stderr: str} | | tail | 获取最近的输出行 | job_id: str, lines: int | {stdout: str, stderr: str} |

交互式工具

| 工具 | 描述 | 参数 | 返回值 | |------|------|------|------| | execute | 启动新的后台作业 | command: str | {job_id: str} | | interact | 向作业的标准输入发送输入 | job_id: str, input: str | {stdout: str, stderr: str} | | kill | 终止正在运行的作业 | job_id: str | {status: str} |

作业状态值

  • 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+ 精心打造 ❤️

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client