Simple Commands MCP

🚀 簡單命令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服務器的目錄中執行。若要在特定目錄中運行命令，可採用以下兩種方法：

1. 從該目錄啟動服務器：

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

2. 或者在命令中使用絕對路徑：

   {
     "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 頁面。