The Dev Server MCP

🚀 the-dev-server MCP

Let Claude register, start, and inspect every dev server you run with PM2.

Why • Features • Quick Start • Usage • Testing • How It Works • Documentation • Contributing

A Model Context Protocol (MCP) server that owns PM2 process management for your dev environments—Claude can register processes, boot them, inspect logs, and keep configuration in sync.

______________________________________________________________________

🎯 为何存在这个

在多个项目中运行多个开发服务器很快就会变得一团糟：

• ❌ 配置文件散落在随机脚本和终端历史记录中
• ❌ 每个团队成员对PM2的管理方式各不相同（或者根本不管理）
• ❌ 重启工作流程是部落知识（或：内部不成文的规定）
• ❌ 日志文件散落各处，无人问津
• ❌ 克劳德必须猜测你关心的是哪个过程

开发服务器（the-dev-server）MCP解决了这个问题 通过让Claude作为PM2控制平面来实现。您关心的每一个开发服务器都会被注册一次，存储在版本化的JSON文件中，并通过相同的MCP工具进行控制。

✨ 特点/功能

• 🧠 管理进程注册表 – 为每个开发服务（脚本、当前工作目录、参数、环境）声明一次；MCP（可能是指某种配置或管理平台）会持久化存储它 .the-dev-server-state.json.
• ⚙️ PM2 任务编排 – 通过MCP工具完全实现进程的启动、停止、重启、删除和描述功能。
• 配置漂移控制 - 更新注册信息，即时将配置更改应用到PM2，并保持状态同步。
• 统一状态视图 – get-managed-processes 将存储的注册表与实时的PM2状态合并，以便Claude能看到 *应该* 存在的是什么，以及实际在运行的是什么。
• 📝 日志流 – 在不退出对话的情况下，从任何已注册的进程中查看标准输出/错误日志。
• 🩺 故障排除提示 – diagnose-server 向克劳德介绍一种以PM2为优先的调试工作流程。
• 💾 磁盘持久化 – 注册信息在MCP重启后仍然保留，因此一旦定义了一个进程，它将永久可用。
• 🔧 macOS 和 Linux 支持 – 专为支持PM2的Unix环境构建（Windows支持将在稍后推出）。

🚀 快速入门

安装

# Clone or download this repository
cd the-dev-server-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

添加到您的Claude桌面配置中（~/Library/Application Support/Claude/claude_desktop_config.json （在 macOS 上）：

{
  "mcpServers": {
    "the-dev-server": {
      "command": "node",
      "args": ["/absolute/path/to/the-dev-server-mcp/build/index.js"]
    }
  }
}

替换 /absolute/path/to/ 并替换为您的实际安装路径。

重启Claude桌面版

更新配置后，重启 Claude Desktop 以加载 MCP 服务器。

添加项目说明（建议）

为了获得最佳效果，请在您的项目中添加说明：

# For Claude - copy to your project root
cp /path/to/the-dev-server-mcp/CLAUDE.md.example /your/project/CLAUDE.md

# For CLI tools (Cline, Cursor, etc.) - copy to your project root
cp /path/to/the-dev-server-mcp/.clinerules.example /your/project/.clinerules

这确保了Claude和其他人工智能助手在回答服务器相关问题时始终使用MCP。

🔔 注意： MCP（可能是指某种开发或管理平台）内置了指令，Claude能够自动看到这些指令。项目文件在每个仓库的基础上强化了“始终通过PM2管理服务器”的原则。

📖 使用方法

日常流程/日常流动

1. 一次性注册所有开发服务器

克劳德： register-managed-process

{
  "name": "next-app",
  "script": "npm",
  "args": ["run", "dev"],
  "cwd": "/Users/alexnewman/Projects/next-app",
  "env": { "PORT": "3000" }
}

这将在本地存储配置，并（可选地）通过PM2立即启动它。

1. 按需启动/停止/重启

• start-managed-process → 通过PM2启动已注册的脚本
• stop-managed-process 优雅关闭
• restart-managed-process → 非常适合配置重载或代码更改

1. 随时检查状态

• get-managed-processes 同时显示注册表信息和实时的PM2信息。
• describe-managed-process 当你需要低级别的详细信息时，它会提供原始的PM2描述输出。

1. 安全地更新定义

• 使用 update-managed-process 更改脚本参数、环境变量、解释器或监控/自动重启标志。
• 通行证；通过 "applyToPm2": true 自动删除并重新注册PM2进程。

1. 项目结束后进行清理

• delete-managed-process 从注册表和PM2中移除条目（除非您选择保持PM2进程运行）。

1. 直接在聊天中查看日志尾部

• read-managed-process-logs 支持 type: "all" | "out" | "error" 具有可配置的行数。

1. 需要了解全局吗？

• get-pm2-status 始终可用于所有流程（无论是否注册）中的临时PM2检查。

💡（这个符号在中文里通常表示“灵感”或“想法”的意思，但直接翻译为文字时，由于其本身是一个表情符号，所以可以保留原样或根据上下文意译为“灵光一闪”等表达） 提示： 这个（或“该”） diagnose-server 当用户说“服务器坏了”时，提示符会自动协调执行这些步骤

工具参考

资源

server-config – 快速只读访问项目中的内容 package.json 元数据。

提示

diagnose-server – 结构化的PM2优先调试检查清单。

🧪 使用示例进行测试

此存储库包含两个示例应用程序，用以展示MCP（多上下文处理/多条件处理等，具体含义根据上下文确定）的实际应用：

示例应用

1. Next.js 应用 (examples/example-nextjs- Next.js 15 + React 19 + TypeScript + Tailwind（中文翻译）：Next.js 15 版本 + React 19 版本 + TypeScript + Tailwind（一种实用的 CSS 框架）
2. Vite React 应用 (examples/example-vite-react- Vite + React 19 + TypeScript + Tailwind（中文翻译为：Vite + React 19 + TypeScript + Tailwind，保持原技术栈名称不变）

这两个应用都包括：

• 一个主页
• 格式美观的文档页面
• 针对MCP的严格CLAUDE.md指令
• 即开即用的配置

如何测试

1. 在示例中安装依赖项：

   cd examples/example-nextjs
   npm install

1. 将您的MCP兼容AI助手的项目根目录设置为示例文件夹 （例如。， examples/example-nextjs)

1. 使用这个确切的提示：

   Make the site 'pretty in pink' and make sure it builds and runs

1. 应该发生的情况是：

- AI阅读了CLAUDE.md文件，并看到了严格的MCP指令 - 它检查服务器状态与 get-managed-processes() - 如果服务器未注册，则进行注册 - 它将风格修改为“粉嫩可爱” - 它使用MCP来构建和运行服务器（不是直接使用npm命令） - 它确认了一切都运行正常

这表明了什么

• ✅ 人工智能助手 记得 使用MCP进行所有开发服务器操作
• ✅ 严格的CLAUDE.md指令是 处于最前沿和中心位置
• ✅ 无直接（联系/关系/影响等，具体含义需根据上下文确定） npm run dev 或者 npm run build 命令被使用
• ✅ MCP（管理控制平面/微控制器抽象层等，具体含义根据上下文确定）管理整个生命周期：注册 → 启动 → 构建 → 日志

测试两个示例

在两个应用程序中尝试相同的提示，看看MCP如何处理不同的框架：

• 使用App Router的Next.js
• 使用 React Router 进行快速开发

两者应通过MCP接口表现出一致的行为。

🏗️ 工作原理

MCP 在您的仓库根目录中持久化存储一个注册表文件： .the-dev-server-state.json。

interface ManagedProcessConfig {
  name: string;
  script: string;
  cwd?: string;
  args?: string[];
  env?: Record;
  interpreter?: string;
  instances?: number;
  watch?: boolean;
  autorestart?: boolean;
}

interface DevServerState {
  managedProcesses: Record;
  lastSynced?: Date;
}

启动时，MCP（管理控制面板/主控制程序）会加载此文件，初始化注册表，并且每次修改（注册/更新/删除）都会以新的时间戳写回磁盘。PM2（进程管理器2）命令是使用存储的配置来执行的，因此MCP始终知道如何重新创建进程。

🔧 开发

手表模式

npm run watch

构建

npm run build

本地测试

# Run the built server directly
node build/index.js

服务器通过标准输入输出（stdio）进行通信，因此它被设计为通过Claude Desktop或其他MCP客户端来使用。

📋 要求

• Node.js 18+（支持ES2022）
• macOS 或 Linux（使用如 Unix 命令 lsof 并且 ps)
• TypeScript 5.7+（或更高版本）

注由于包含Unix特定命令，Windows目前不受支持。

🎓 最佳实践

1. 先注册再运行 – 确保每个开发服务都在注册表中有一个条目，以便Claude能够管理它们。
2. 让MCP开始/停止 – 抵抗 pm2 CLI肌肉记忆；通过MCP工具触发生命周期操作以保持状态一致。
3. 通过MCP更新配置 – 使用 update-managed-process 而不是编辑 .the-dev-server-state.json 手工（完成）。
4. 依赖诊断提示 – 当服务器行为异常时，提示符会自动协调状态检查、重启和日志审查。
5. 保持PM2清洁 – 使用 delete-managed-process 在清理房屋（此处比喻为清理系统或进程）时，要避免留下孤立的进程。

📚 文档

🛣️ 路线图

• \[ \] Windows支持（PowerShell与PM2功能一致）
• \[ \] 多服务器编排（组与依赖关系图）
• 除了PM2之外，还支持Docker/Compose目标
• \[ \] 健康监测和自动重启策略
• \[ \] 远程环境支持（SSH隧道/容器）
• \[ \] 丰富的重启历史和日志书签功能

🤝 贡献（或：参与贡献）

欢迎贡献！这是一个实用的MCP（多角色通信协议/模块），旨在解决Claude开发工作流程中的一个实际痛点。

投稿建议：

• Windows支持实现
• 一流的Docker/Compose运行器
• 进程分组和聚合命令
• 用于PM2指标的监控模式仪表板
• 文档与入职流程改进

📄 许可证

麻省理工学院（MIT）

______________________________________________________________________

🙏 致谢

构建于：

• @modelcontextprotocol/sdk（可翻译为）：@模型上下文协议/SDK（或根据具体语境，可译为“@模型上下文协议开发工具包”） – 官方 TypeScript MCP SDK
• zod（注：这是一个专有名词或特定术语，在中文中没有直接对应的翻译，通常保持原样使用） – 模式验证

💡 相关项目

• MCP服务器 - 官方MCP服务器实现
• Claude Desktop（可译为“Claude桌面版”） - 支持MCP的桌面应用程序

📮 支持

如果你觉得这很有用并且节省了你的时间，不妨考虑一下：

• ⭐ 收藏此仓库
• 🐛 通过 GitHub Issues 报告错误
• 💡 提出功能建议
• 🔀 贡献代码

______________________________________________________________________

Never lose track of your dev server again. 🚀