quiet-shell

执行shell命令并使用智能输出过滤来减少AI代理上下文消耗的MCP服务器。

问题

当AI编码助手执行shell命令（尤其是测试和构建）时，它们会收到数千行冗长的输出，这会导致：

• 消耗宝贵的上下文窗口令牌
• 将重要信息（错误、失败）淹没在噪音中
• 难以专注于可操作的反馈

示例：运行包含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

该服务器通过stdio通信，遵循模型上下文协议规范。

使用方法

可用工具

execute_command

执行shell命令，可选地进行输出过滤。

参数：

• command（必需）：要执行的shell命令
• template（可选）：过滤模板名称（使用list_templates查看可用模板）
• suppress_output_on_success（可选，默认值：true）：命令成功时（退出码0）抑制输出。设置为false以在成功时也显示输出

响应：

{
  "result": "success",
  "exit_code": 0,
  "output": "过滤后的输出在这里",
  "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");
// 如果成功："命令完成成功（输出被抑制 - 退出码0）"

list_templates

列出所有可用的过滤模板及其描述。

响应：

{
  "templates": [
    {
      "name": "vitest",
      "description": "运行Vitest测试时使用 - 返回失败测试和测试总结",
      "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: "运行Jest测试时使用 - 返回失败测试和测试总结"
    include_regex: "(FAIL|●|✕)"
    tail_paragraphs: 2

  eslint:
    description: "运行ESLint时使用 - 返回linting错误和总结"
    include_regex: "(error|warning|✖)"
    tail_paragraphs: 1

  # 始终显示成功输出的模板
  build-with-stats:
    description: "即使成功也显示统计信息的构建命令"
    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行）：

✓ 测试1通过
✓ 测试2通过
... （还有48个通过的测试）
✖ 测试51失败
  预期：true
  接收：false
✖ 测试52失败
  错误：超时

测试：50个通过，2个失败，总共52个
时间：5.2秒

使用vitest模板的输出（约10行）：

✖ 测试51失败
  预期：true
  接收：false
✖ 测试52失败
  错误：超时
测试：50个通过，2个失败，总共52个
时间：5.2秒

开发

单一仓库结构

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进行单一仓库构建

致谢

使用模型上下文协议SDK构建。