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 构建。