Quiet Shell MCP

🚀 quiet - shell

quiet - shellは、シェルコマンドを実行し、AIエージェントのコンテキスト消費を削減するために出力をインテリジェントにフィルタリングするMCPサーバーです。

🚩 問題

AIコーディングアシスタントがシェルコマンド（特にテストやビルド）を実行する際、数千行に及ぶ冗長な出力を受け取ります。これにより以下の問題が発生します。

• 貴重なコンテキストウィンドウのトークンを消費する
• 重要な情報（エラー、失敗）がノイズの中に埋もれる
• 実行可能なフィードバックに集中することが困難になる

例：50件のテストが成功し、2件が失敗したテストを実行すると、2000行以上の出力が生成されますが、エージェントが必要とするのは失敗と要約を示す約20行だけです。

💡 解決策

quiet - shellはコマンドを実行し、設定可能なテンプレートを使用して出力をインテリジェントにフィルタリングします。

• 正規表現フィルタリング：エラーパターンに一致する行のみを残す
• 末尾の段落：常に要約セクションを含める
• 結果解釈：迅速な成功/失敗ステータス
• 組み込みテンプレート：一般的なツール（tsc、vitest、maven）用に事前に設定されている
• カスタムテンプレート：リポジトリごとに独自のフィルターを定義する

📦 インストール

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を使用します。

サーバーはModel Context Protocol仕様に従ってstdioを介して通信します。

💻 使用例

利用可能なツール

execute_command

オプションの出力フィルタリングを伴うシェルコマンドを実行します。

パラメーター：

• command（必須）：実行するシェルコマンド
• 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");
// 返り値: 失敗したテスト + 要約（2000行以上ではなく約20行）
// テストが合格した場合: 出力が抑制される（デフォルトの動作）

// 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インスペクターでのテスト

npx @modelcontextprotocol/inspector quiet-shell-mcp

🏗️ アーキテクチャ

• ロガー：依存性注入されたロガー（stderrのみ、stdoutには出力しない）
• テンプレートマネージャー：60秒のキャッシュTTLを持つ設定ロード
• コマンド実行器：コマンドを起動し、stdout/stderrをキャプチャする
• 出力フィルター：段落ベースの正規表現フィルタリング
• MCPサーバー：stdioトランスポート、構造化JSONレスポンス

📋 要件

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

📄 ライセンス

MIT

🤝 コントリビューション

コントリビューションを歓迎します！このプロジェクトは以下を使用しています。

• 厳格モードのTypeScript
• テスト用のVitest
• コード品質用のESLint + Prettier
• モノレポビルド用のTurbo

🙌 クレジット

Model Context Protocol SDKを使用して構築されています。