SupervisordMCP- AI Agent DevServer Management Made Simple

Supervisord MCP

通过 Model Context Protocol（MCP）集成 AI Agent，简化 Supervisord 进程管理。

Supervisord MCP 通过 Model Context Protocol 为编码 Agent 提供对 Supervisord 进程管理的直接访问。它提供标准化的进程控制能力，免去了复杂的 Shell 命令解析，并减少了 AI Agent 在生产和开发环境中的 Token 消耗。

MCP 集成流程

sequenceDiagram
    participant Agent as AI Coding Agent
    participant MCP as Supervisord MCP Server
    participant Supervisord as Supervisord Daemon
    participant Process as Application Process

    Agent->>MCP: Request: start_process("webapp")
    MCP->>Supervisord: Start process via XML-RPC
    Supervisord->>Process: Launch application
    Process-->>Supervisord: Process started (PID: 1234)
    Supervisord-->>MCP: Process status: RUNNING
    MCP-->>Agent: {"status": "ok", "message": "Process started"}

    Agent->>MCP: Request: get_logs("webapp", lines=50)
    MCP->>Supervisord: Fetch stdout/stderr logs
    Supervisord-->>MCP: Log entries
    MCP-->>Agent: {"status": "ok", "logs": ["Application started..."]}

什么是 Supervisord MCP？

Supervisord MCP 让 AI 编码 Agent 更高效地管理生产环境进程，有助于提升部署可靠性和运营效率。

Supervisord MCP 通过 Model Context Protocol 提供直接的进程控制，免去 Shell 命令的开销，并减少 AI Agent 管理生产和开发环境时的 Token 消耗。

核心功能：

• AI 集成：内置 MCP 协议支持，适用于编码 Agent
• 可用于生产环境：基于经过实战检验的 Supervisord 进程管理器
• 实时监控：访问进程状态和日志
• 可靠操作：可靠地管理进程生命周期

快速开始

安装

uv add supervisord-mcp

基本用法

# Start a process (requires it to be configured in supervisord.conf)
uv run supervisord-mcp start webapp

# Check what's running
uv run supervisord-mcp list-processes

# View logs
uv run supervisord-mcp logs webapp

# Get system information
uv run supervisord-mcp info

主要功能

🚀 轻松管理进程

# Start/stop/restart processes
uv run supervisord-mcp start api
uv run supervisord-mcp stop api
uv run supervisord-mcp restart api

# Get detailed status
uv run supervisord-mcp status api

📊 全面监控

# List all processes with status
uv run supervisord-mcp list-processes

# View real-time logs
uv run supervisord-mcp logs api --lines 100
uv run supervisord-mcp logs api --stderr

# System information
uv run supervisord-mcp info

🤖 AI Agent 集成

Supervisord MCP 内置 MCP 协议支持，让 AI Agent 能够管理你的进程：

# Start MCP server for AI integration
uv run supervisord-mcp mcp

在 AI Agent 中使用推荐的 stdio 传输方式进行配置：

{
  "mcpServers": {
    "supervisord-mcp": {
      "command": "uv",
      "args": ["run", "supervisord-mcp", "mcp"],
      "cwd": "/path/to/your/project"
    }
  }
}

适用于不同的项目配置：

{
  "mcpServers": {
    "supervisord-mcp": {
      "command": "uv",
      "args": ["run", "supervisord-mcp", "mcp"],
      "cwd": "/app"
    }
  }
}

注意：本工具面向生产和开发环境，使用 MCP 文档（https://modelcontextprotocol.io/）中所述的 stdio 传输方式。这种方式可在 AI Agent 与进程管理器之间提供安全、直接的通信。

常见用例

生产环境 Web 应用

# Configure in supervisord.conf:
[program:webapp]
command=gunicorn app:application
directory=/app
numprocs=4
autostart=true
autorestart=true

# Then manage via Supervisord MCP:
uv run supervisord-mcp start webapp
uv run supervisord-mcp logs webapp

开发环境

# Configure multiple services in supervisord.conf:
[program:frontend]
command=npm run dev
directory=/app/frontend
autostart=false

[program:backend]
command=python manage.py runserver
directory=/app/backend
autostart=false

# Manage the stack:
uv run supervisord-mcp start frontend
uv run supervisord-mcp start backend
uv run supervisord-mcp list-processes

微服务

# Multiple services configured in supervisord.conf
uv run supervisord-mcp start auth-service
uv run supervisord-mcp start user-service
uv run supervisord-mcp start notification-service

为什么选择 Supervisord MCP？

与 Circus MCP 相比

• 面向生产环境：Supervisord 专为生产环境设计
• 稳定性：经过多年生产环境使用检验的进程监控器
• 配置：使用标准的 supervisord.conf 定义进程

注意：AI Agent 集成限制

Supervisord 的 XML-RPC API 在动态管理 AI Agent 进程方面存在限制：

• API 不支持 add_process（需要手动编辑配置文件并执行 reload）
• stdout/stderr 日志需要通过单独的 API 调用获取
• API 无法提供 CPU/内存资源指标
• 启动已运行的进程会抛出 ALREADY_STARTED 错误（非幂等操作）

对于 AI Agent 需要动态添加和监控进程的用例，Circus MCP 提供了更完整的 API。Supervisord MCP 最适合用于集成现有的 Supervisord 环境。

与 systemd 相比

• 跨平台：可在任何安装了 Python 的系统上运行
• 易于使用：命令简单，并支持 AI 集成
• 灵活：易于配置和管理进程

与 PM2 相比

• 原生支持 Python：非常适合 Python 应用
• AI 集成：开箱即用地支持 MCP 协议
• 经过生产环境验证：基于广泛使用的 Supervisord

高级功能

进程控制

# Standard operations
uv run supervisord-mcp start webapp
uv run supervisord-mcp stop webapp
uv run supervisord-mcp restart webapp

# Get detailed status
uv run supervisord-mcp status webapp

日志管理

# View logs with options
uv run supervisord-mcp logs webapp --lines 100
uv run supervisord-mcp logs webapp --stderr

# Real-time log monitoring (use supervisorctl tail in another terminal)

配置管理

# Reload configuration after changes
uv run supervisord-mcp reload

安装与设置

系统要求

• Python 3.10 或更高版本
• 已安装并运行 Supervisord
• 任意操作系统（Linux、macOS、Windows）

安装选项

# From PyPI (recommended)
uv add supervisord-mcp

# With pip (alternative)
pip install supervisord-mcp

# From source
git clone https://github.com/aether-platform/supervisord-mcp.git
cd supervisord-mcp
uv sync

Supervisord 设置

1. 安装 Supervisord：

pip install supervisor

2. 创建配置目录：

mkdir -p /etc/supervisor/conf.d

3. 创建主配置文件 /etc/supervisor/supervisord.conf：

[unix_http_server]
file=/tmp/supervisor.sock

[supervisord]
logfile=/tmp/supervisord.log
logfile_maxbytes=50MB
logfile_backups=10
loglevel=info
pidfile=/tmp/supervisord.pid
nodaemon=false
minfds=1024
minprocs=200

[rpcinterface:supervisor]
supervisor.rpcinterface_factory = supervisor.rpcinterface:make_main_rpcinterface

[supervisorctl]
serverurl=unix:///tmp/supervisor.sock

[inet_http_server]
port=127.0.0.1:9001

[include]
files = /etc/supervisor/conf.d/*.conf

重要：Supervisord MCP 需要启用 [inet_http_server] 配置块并允许 HTTP 访问。该工具通过 HTTP XML-RPC 协议连接 Supervisord，不支持 Unix 域套接字连接。

4. 启动 Supervisord：

supervisord -c /etc/supervisor/supervisord.conf

验证安装

uv run supervisord-mcp --help
uv run supervisord-mcp info

配置

Supervisord MCP 可与标准 Supervisord 配置配合使用。将程序添加到 /etc/supervisor/conf.d/：

程序配置示例

[program:webapp]
command=gunicorn app:application --bind 0.0.0.0:8000
directory=/app
numprocs=1
autostart=true
autorestart=true
startsecs=10
startretries=3
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/webapp.log

自定义服务 URL

# Use custom Supervisord server
uv run supervisord-mcp --server-url http://localhost:9001/RPC2 list-processes

可用的 MCP 工具

以下工具可供 AI Agent 使用：

• add_process：添加新进程（需要重新加载配置）
• start_process：启动进程
• stop_process：停止进程
• restart_process：重启进程
• list_processes：列出所有进程
• get_process_status：获取详细的进程状态
• get_logs：获取进程日志（stdout/stderr）
• get_system_info：获取 Supervisord 系统信息
• reload_config：重新加载 Supervisord 配置

获取帮助

文档

• Supervisord 文档 - Supervisord 官方文档
• MCP 文档 - Model Context Protocol 规范

支持

• GitHub Issues：报告错误或请求功能
• 讨论区：加入社区

快速命令参考

# Process Management
uv run supervisord-mcp start <name>
uv run supervisord-mcp stop <name>
uv run supervisord-mcp restart <name>
uv run supervisord-mcp status <name>

# Monitoring
uv run supervisord-mcp list-processes
uv run supervisord-mcp logs <name> [--lines N] [--stderr]
uv run supervisord-mcp info

# Configuration
uv run supervisord-mcp reload

# AI Integration
uv run supervisord-mcp mcp

AI Agent 的 Token 成本分析

**减少 token 消耗，让 Agent 更快地工作。**AI Agent 用于进程监控的每个 token，都是未用于解决实际问题的 token。研究显示，在 Agent 工作流中，迭代调试阶段消耗的 token 最多可占总量的 59.4%（Tokenomics，2026）。通过 MCP 提供结构化、简洁的响应，我们降低了 AI 辅助调试中最大的成本驱动因素：不必要的往返请求和非结构化输出解析。

工具架构开销（上下文驻留成本）

注册 MCP 工具后，其架构定义会在整个会话期间保留在对话上下文中。

项目	预估 Token 数
9 个工具架构	约 1,100 个 token

每次调用的 Token 成本

操作	请求	响应	总计
list_processes（5 个进程）	约 30	约 120-200	约 150-230
get_process_status	约 40	约 100-150	约 140-190
get_logs（10 行）	约 50	约 150-450	约 200-500
get_logs（50 行）	约 50	约 750-2,450	约 800-2,500
get_logs（100 行，默认值）	约 50	约 1,450-4,950	约 1,500-5,000
get_system_info	约 30	约 50-90	约 80-120
start/stop/restart_process	约 40	约 30-60	约 70-100
reload_config	约 30	约 40-70	约 70-100

MCP 与原始 Linux 命令对比——“快速退出”问题排查

排查某个进程在启动后立即退出时的成本对比。

原始命令（不使用 MCP）：12 个步骤

supervisorctl status                              # Step 1:  Check all processes
supervisorctl status webapp                       # Step 2:  Check target → FATAL
supervisorctl tail webapp stderr                  # Step 3:  stderr logs (unbounded output risk)
cat /var/log/supervisor/webapp-stderr.log | tail -50  # Step 4:  Read log file directly
supervisorctl start webapp                        # Step 5:  Attempt restart
sleep 2 && supervisorctl status webapp            # Step 6:  Check after restart
supervisorctl tail webapp stderr | tail -20       # Step 7:  Check logs again
ps aux | grep webapp                              # Step 8:  Verify process existence
journalctl -u supervisor --no-pager -n 30         # Step 9:  systemd logs
cat /etc/supervisor/conf.d/webapp.conf            # Step 10: Check configuration
lsof -i :8080                                     # Step 11: Check port conflicts
free -m                                           # Step 12: Check resource exhaustion

• 每次 Bash 调用都有 约 60-90 个 token 的固定开销
• supervisorctl tail 没有行数限制——存在 token 激增风险
• 非结构化文本输出会导致 LLM 解析错误
• 每个步骤之间都会消耗 推理 token（约 150-250 个 token/步）
• “快速退出”场景通常需要对该流程 循环 2-3 次

MCP（结构化工具）：5 个步骤

list_processes                                    # Spot FATAL immediately
get_process_status("webapp")                      # Detailed status
get_logs("webapp", lines=20, stderr=true)         # Error logs (bounded to 20 lines)
restart_process("webapp")                         # Restart
get_process_status("webapp")                      # Verify after restart

对比

指标	原始命令	MCP	降幅
工具调用次数	8-12	3-5	60-70%
输出 token 数	2,000-8,500	560-1,160	70-85%
推理 token 数（步骤间）	~1,500-3,000	~500-1,000	60-70%
总 token 数（不含 schema）	2,900-9,400	935-1,535	60-85%
总 token 数（含 schema）	2,900-9,400	2,035-2,635	30-70%
往返次数	8-12	3-5	60%
实际耗时	12-36s	~5s	60-85%
解析可靠性	低（非结构化）	高（结构化）	—

重试时的扩展情况

需要重复调查时的累计成本（“快速退出”问题中很常见）：

重试次数	原始命令	MCP	节省
1（成功）	~2,900-9,400	~935-1,535	60-85%
2 轮	~5,000-15,000	~1,500-2,500	70-83%
3 轮	~7,000-20,000	~2,000-3,500	71-82%

原始命令的成本会随重试次数呈指数增长（探索性命令不断累积），而 MCP 的成本则线性增长。

盈亏平衡点：将 schema 常驻成本（~1,100 个 token）计算在内后，MCP 在 3-4 次工具调用时成本相当，超过此次数后成本更低。

优化建议

建议	效果
将 get_logs 限制为 lines=10~20	日志检索成本降低 70-80%
使用一次 list_processes 调用获取概览	无需逐个调用状态查询
使用 stderr=true 仅获取 stderr	避免在 stdout 上浪费 token
仅检查状态时跳过 get_system_info	节省 ~80-120 个 token

参考资料

本次 token 成本分析所依据的研究：

• Tokenomics: Quantifying Where Tokens Are Used in Agentic SE — 首个对 Agent 工作流中 token 消耗情况进行的实证分析。迭代阶段消耗了 59.4% 的 token
• Help or Hurdle? Rethinking MCP-Augmented LLMs — MCPGAUGE：首个包含开销在内、涵盖 4 个维度的 MCP 评估框架
• MCP Tool Descriptions Are Smelly! — 对 856 个工具 / 103 个 MCP 服务的大规模研究。工具描述质量会直接影响 Agent 效率
• MCPAgentBench — 包含 841 项任务、20,000 多个 MCP 工具的基准测试。将 Token 效率（TEFS）定义为评估指标
• AgentDiet: Trajectory Reduction — 输入 token 减少 39.9-59.7%
• Token-Budget-Aware LLM Reasoning — 输出 token 减少 67%，成本降低 59%
• Token Efficiency with Structured Output — 函数调用是 token 效率最高的输出格式（Microsoft）

许可证

MIT License — 详见 LICENSE。

关于作者

AetherPlatform — 构建云原生开发工具的未来

• GitHub： @aether-platform
• 项目网站：AetherPlatform
• 联系邮箱：[email protected]

我们的使命

我们通过 AI 集成和现代云原生技术开发工具，提升开发者的工作效率。Supervisord MCP 是我们更广泛的开发工具生态系统的一部分，旨在简化软件开发生命周期。

其他项目

• AetherSaaS：SaaS 平台管理控制台
• AetherCoding：AI 增强型开发环境
• AetherOperation：运维和终端管理工具
• Circus MCP：使用 Circus 实现的替代进程管理方案

致谢

我们衷心感谢 Supervisord 开发团队打造了如此稳健可靠的进程管理基础。正是他们的出色工作让本项目成为可能。Supervisord MCP 基于其坚实的架构构建，为进程管理带来现代 AI Agent 集成能力。

相关项目

• Supervisord - 底层进程管理器
• Model Context Protocol - AI Agent 通信标准
• AetherPlatform - 云原生开发工具
• Circus MCP - 另一种进程管理解决方案

---

由 AetherPlatform 倾情打造 ❤️

Supervisord MCP：面向生产环境的进程管理，AI 驱动的自动化。