Quiet Shell MCP

🚀 quiet-shell

quiet-shell 是一個 MCP 服務器，它能夠執行 shell 命令，並通過智能的輸出過濾功能，減少 AI 代理上下文的消耗。

🚀 快速開始

當 AI 編碼助手執行 shell 命令（尤其是測試和構建命令）時，會收到數千行的冗長輸出，這些輸出會帶來以下問題：

• 消耗寶貴的上下文窗口令牌。
• 將重要信息（錯誤、失敗）淹沒在噪音中。
• 難以聚焦於可操作的反饋。

例如，運行包含 50 個通過和 2 個失敗測試的測試用例時，會生成 2000 多行的輸出，但代理只需要約 20 行顯示失敗和總結的內容。

quiet-shell 通過可配置的模板來執行命令並智能過濾輸出：

• 正則過濾：只保留與錯誤模式匹配的行。
• 尾部段落：始終包含總結部分。
• 結果解釋：快速顯示成功/失敗狀態。
• 內置模板：為常見工具（tsc、vitest、maven）預先配置。
• 自定義模板：可以為每個倉庫定義自己的過濾器。

✨ 主要特性

• 智能過濾 shell 命令輸出，減少 AI 代理上下文消耗。
• 支持正則過濾、尾部段落保留和結果解釋。
• 提供內置模板，也可自定義模板。
• 與 MCP 客戶端兼容，可通過 stdio 通信。

📦 安裝指南

可以使用 npm 或 pnpm 進行全局安裝：

npm install -g @codemcp/quiet-shell-mcp

或者使用 pnpm：

pnpm add -g @codemcp/quiet-shell-mcp

📚 詳細文檔

MCP 客戶端配置

Claude Desktop

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加以下內容：

{
  "mcpServers": {
    "quiet-shell": {
      "command": "quiet-shell-mcp"
    }
  }
}

其他 MCP 客戶端

使用命令：quiet-shell-mcp 服務器通過 stdio 遵循 Model Context Protocol 規範進行通信。

可用工具

execute_command

執行 shell 命令並可選擇進行輸出過濾。 參數：

• command（必需）：要執行的 shell 命令。
• template（可選）：過濾模板名稱（使用 list_templates 查看可用模板）。
• suppress_output_on_success（可選，默認：true）：命令成功執行（退出碼為 0）時抑制輸出。設置為 false 可始終顯示輸出，即使命令成功。

響應：

{
  "result": "success",
  "exit_code": 0,
  "output": "filtered output here",
  "template_used": "vitest"
}

示例：

// 運行測試並過濾輸出
execute_command("npm test", "vitest");
// 返回：僅失敗的測試和總結（約 20 行而不是 2000 多行）
// 如果測試通過：輸出被抑制（默認行為）

// TypeScript 編譯
execute_command("tsc --noEmit", "tsc");
// 返回：僅類型錯誤和總結
// 如果編譯成功：輸出被抑制（默認行為）

// 即使成功也始終顯示輸出
execute_command("npm test", null, false); // suppress_output_on_success = false
// 返回：無論退出碼如何，都返回完整輸出

// 使用默認抑制的原始輸出
execute_command("echo hello");
// 如果成功："Command completed successfully (output suppressed - exit code 0)"

list_templates

列出所有可用的過濾模板及其描述。 響應：

{
  "templates": [
    {
      "name": "vitest",
      "description": "Use when running tests with Vitest - returns failed tests and test summary",
      "include_regex": "(FAIL|ERROR|✖|❯.*failed)",
      "tail_paragraphs": 2
    },
    ...
  ],
  "count": 4
}

內置模板

• tsc：TypeScript 編譯器 - 返回類型錯誤和總結。
• vitest：Vitest 測試 - 返回測試失敗和總結。
• maven-build：Maven 構建 - 返回構建錯誤和總結。
• maven-test：Maven 測試 - 返回測試失敗和總結。

自定義模板

在倉庫中創建 .quiet-shell/config.yaml 文件：

templates:
  jest:
    description: "Use when running tests with Jest - returns failed tests and test summary"
    include_regex: "(FAIL|●|✕)"
    tail_paragraphs: 2

  eslint:
    description: "Use when running ESLint - returns linting errors and summary"
    include_regex: "(error|warning|✖)"
    tail_paragraphs: 1

  # 始終顯示成功輸出的模板
  build-with-stats:
    description: "Build command that shows statistics even on success"
    include_regex: "(error|warning|built|compiled)"
    tail_paragraphs: 2
    suppress_output_on_success: false # 覆蓋默認抑制

特性：

• 自定義模板可以擴展內置模板。
• 自定義模板可以覆蓋同名的內置模板。
• 配置可以進行版本控制並與團隊共享。
• 服務器通過從當前目錄向上搜索來發現配置。

工作原理

模板結構

每個模板定義：

• include_regex：用於匹配重要行（錯誤、失敗）的模式。
• tail_paragraphs：從末尾包含的段落數（總結）。
• description：何時使用此模板（供代理發現）。

過濾算法

1. 解析：將輸出解析為段落（由空行分隔的行組）。
2. 過濾：過濾與 include_regex 匹配的行。
3. 提取：提取最後 N 個段落（總結）。
4. 合併：合併並去重（保留順序）。
5. 返回：返回過濾後的輸出。

示例

輸入（2000 行）：

✓ test 1 passed
✓ test 2 passed
... (48 more passing tests)
✖ test 51 failed
  Expected: true
  Received: false
✖ test 52 failed
  Error: timeout

Tests: 50 passed, 2 failed, 52 total
Time: 5.2s

使用 vitest 模板的輸出（約 10 行）：

✖ test 51 failed
  Expected: true
  Received: false
✖ test 52 failed
  Error: timeout
Tests: 50 passed, 2 failed, 52 total
Time: 5.2s

開發

單倉庫結構

packages/
  core/          # @codemcp/quiet-shell-core
                 # 可重用的過濾邏輯

  mcp-server/    # @codemcp/quiet-shell-mcp
                 # MCP 協議實現

構建

pnpm install
pnpm build

測試

pnpm test

使用 MCP Inspector 測試

npx @modelcontextprotocol/inspector quiet-shell-mcp

架構

• 日誌記錄器：依賴注入的日誌記錄器（僅輸出到 stderr，從不輸出到 stdout）。
• 模板管理器：配置加載，緩存 TTL 為 60 秒。
• 命令執行器：生成命令，捕獲 stdout/stderr。
• 輸出過濾器：基於段落的正則過濾。
• MCP 服務器：stdio 傳輸，結構化 JSON 響應。

要求

• Node.js >= 18
• pnpm >= 9（用於開發）

📄 許可證

本項目採用 MIT 許可證。

貢獻

歡迎貢獻代碼！本項目使用：

• TypeScript 並開啟嚴格模式。
• Vitest 進行測試。
• ESLint + Prettier 保證代碼質量。
• Turbo 進行單倉庫構建。

致謝

本項目基於 Model Context Protocol SDK 構建。