JinDaGe - simple-commands-mcp MCP Details

article

README

🚀 简单命令MCP服务器

这是一个由配置驱动的模型上下文协议（MCP）服务器，它提供了执行开发者命令和管理长时间运行进程的工具。该服务器允许AI助手通过简单的JSON配置文件运行预定义的命令。

🚀 快速开始

你可以根据不同的需求，选择合适的安装方式来启动这个MCP服务器。具体的安装步骤如下文所示。

✨ 主要特性

配置驱动：只需更新JSON配置文件即可添加新工具。
守护进程管理：使用自动启动/停止/状态/日志命令处理长时间运行的进程。
自动生成控制命令：每个守护进程自动获得 _start、_status、_stop 和 _logs 命令。
进程监控：跟踪所有守护进程的PID、正常运行时间、状态并捕获输出。
自动清理：当MCP客户端断开连接时，所有进程都会终止。
跨平台：可在macOS、Linux和Windows上运行。

📦 安装指南

使用npx（推荐）

无需安装！直接运行：

npx simple-commands-mcp @config.json

全局安装

npm install -g simple-commands-mcp
simple-commands-mcp @config.json

本地开发

git clone https://github.com/yourusername/simple-commands-mcp.git
cd simple-commands-mcp
npm install
npm run build
npm link
simple-commands-mcp @config.json

💻 使用示例

基础用法

创建一个包含工具定义的 config.json 文件：

{
  "tools": [
    {
      "name": "list_files",
      "description": "列出当前目录中的文件",
      "command": "ls -la",
      "daemon": false
    },
    {
      "name": "dev_server",
      "description": "启动开发服务器",
      "command": "npm run dev",
      "daemon": true
    }
  ]
}

然后运行MCP服务器：

npx simple-commands-mcp @config.json

配置选项

配置中的每个工具都有以下属性：

name（字符串，必需）：工具的唯一标识符。
description（字符串，必需）：工具功能的人类可读描述。
command（字符串，必需）：要执行的shell命令。
daemon（布尔值，必需）：对于长时间运行的进程设置为 true，对于一次性命令设置为 false。

守护进程工具

当你为某个工具设置 daemon: true 时，服务器会自动创建四个命令：

{name}_start：启动守护进程。
{name}_status：获取当前状态、PID、正常运行时间和最近的输出。
{name}_stop：停止守护进程。
{name}_logs：获取最后N行输出（默认：50）。

示例：一个名为 dev_server 且 daemon: true 的工具将创建：

dev_server_start
dev_server_status
dev_server_stop
dev_server_logs

简单命令配置示例

{
  "tools": [
    {
      "name": "git_status",
      "description": "显示git仓库状态",
      "command": "git status",
      "daemon": false
    },
    {
      "name": "run_tests",
      "description": "运行测试套件",
      "command": "npm test",
      "daemon": false
    },
    {
      "name": "build_project",
      "description": "构建项目",
      "command": "npm run build",
      "daemon": false
    }
  ]
}

开发环境配置示例

{
  "tools": [
    {
      "name": "frontend",
      "description": "带有热重载的前端开发服务器",
      "command": "npm run dev:frontend",
      "daemon": true
    },
    {
      "name": "backend",
      "description": "后端API服务器",
      "command": "npm run dev:backend",
      "daemon": true
    },
    {
      "name": "database",
      "description": "本地数据库服务器",
      "command": "docker-compose up db",
      "daemon": true
    },
    {
      "name": "migrate",
      "description": "运行数据库迁移",
      "command": "npm run db:migrate",
      "daemon": false
    }
  ]
}

MCP客户端配置示例

要将此服务器与MCP客户端（如Claude Desktop）一起使用，请将其添加到你的MCP设置中：

{
  "mcpServers": {
    "simple-commands": {
      "command": "npx",
      "args": ["simple-commands-mcp", "@/path/to/your/config.json"]
    }
  }
}

📚 详细文档

工作目录

命令在你运行MCP服务器的目录中执行。若要在特定目录中运行命令，可采用以下两种方法：

从该目录启动服务器：

cd /path/to/project
npx simple-commands-mcp @config.json

或者在命令中使用绝对路径：

{
  "name": "project_build",
  "description": "构建项目",
  "command": "cd /path/to/project && npm run build",
  "daemon": false
}

故障排除

服务器无法启动

确保安装了Node.js 18+：node --version
检查你的配置文件是否为有效的JSON
确保配置文件路径正确并以 @ 为前缀

命令执行失败

验证命令在同一目录下手动运行时是否正常工作
检查所需的依赖项是否在PATH中
查看服务器日志以获取错误消息

守护进程无法停止

当以下情况发生时，服务器会自动跟踪并终止所有守护进程：
- MCP客户端断开连接
- 服务器收到SIGINT/SIGTERM信号
- 你使用 {name}_stop 命令
使用Ctrl+C优雅地关闭服务器和所有守护进程

开发

从源代码构建

npm install
npm run build

在开发模式下运行

npm run dev

项目结构

simple-commands-mcp/
├── src/
│   ├── cli.ts           # npx的CLI入口点
│   ├── server.ts        # 主MCP服务器
│   ├── types.ts         # TypeScript类型定义
│   ├── logger.ts        # 日志记录工具
│   ├── processManager.ts # 守护进程管理
│   └── toolExecutor.ts  # 命令执行逻辑
├── dist/                # 编译后的JavaScript（自动生成）
├── config.json          # 示例配置
├── package.json         # 包元数据和脚本
└── tsconfig.json        # TypeScript配置

📄 许可证

本项目采用MIT许可证。

贡献

欢迎贡献代码！请随时提交拉取请求。

支持

如有问题和功能请求，请使用 GitHub Issues 页面。

simple-commands-mcp