Build Output Tools MCP

🛠️ 构建输出工具MCP

MCP服务器，执行构建/测试命令，并将输出路由到较小的LLM，以分析输出并提供简洁、可操作的摘要，同时存储完整的输出，以便在需要时进行详细检查。

./builder-tools-mcp-diagram.png

博客文章：https://gordles.io/blog/llm-friendly-test-suite-outputs-pytest-llm

为什么选择此服务器？

此工具的主要目标是通过减少执行构建或测试时处理的令牌量来保存主编码代理线程中的上下文。

这个服务器没有用数千行构建输出淹没Claude的上下文，而是：

• 执行任何构建/测试命令 - npm test, pytest, docker build, cargo test等等。
• 提供智能摘要 -LLM分析输出，并给出主线需要做什么的实际内容
• 存储完整输出 -需要详细分析时访问完整日志
• 维护历史记录 -使用唯一ID跟踪随时间推移的构建

快速导航

• 入门指南 -5分钟后设置
• 可用工具 -所有MCP工具概述
• 使用示例 -现实世界场景
• 配置 -API密钥和设置

特性

基于安全提供者的执行

# Safe, provider-based commands only
run_build("/my-app", "npm", ["run", "test"])
run_build("/my-api", "pytest", ["--cov=src", "tests/"])
run_build("/my-container", "docker", ["build", "-t", "myapp", "."])
run_build("/my-python", "unittest", ["discover", "-s", "tests"])

支持的测试/构建框架

智能分析

• 智能摘要 来自OpenRouter LLM（西北风、双子座等）
• 突出显示错误 -关注可操作的故障
• 成功量度 -提取测试计数、覆盖率、性能数据
• 可配置模型 -根据您的分析需求选择合适的法学硕士

输出存储和检索

• 自动存储 -每个构建都有一个唯一的ID
• 全文访问 -需要时检索完整的stdout/stderr
• 构建历史记录 -随着时间的推移，轨迹会逐渐建立
• 自动清理 -自动管理磁盘空间

工作流集成

非常适合开发工作流程：

1. 运行构建 -获取即时智能摘要
2. 调试失败 -访问完整日志以进行详细分析
3. 追踪进度 -监视器随时间构建
4. 分享结果 -构建ID使协作变得容易

入门指南

先决条件

• Python 3.9+
• OpenRouter 的 API密钥
• Claude Code CLI（推荐）或其他MCP兼容的代理CLI

1.快速设置

# Clone and setup
git clone https://github.com/your-username/build-output-tools-mcp.git
cd build-output-tools-mcp

# One-command setup
./run_server.sh

安装脚本将：

• 创建Python虚拟环境
• 安装依赖项
• 设置 .env 文件
• 可选择添加到克劳德代码

2.添加API密钥

编辑 .env 使用OpenRouter API密钥的文件：

OPENROUTER_API_KEY=your_openrouter_api_key_here
DEFAULT_MODEL=mistralai/mistral-small-3.2-24b-instruct-2506:free

3.开始使用！

在克劳德代码中：

# List available providers
list_providers()

# Run tests with specific provider
run_build(
  project_path="/path/to/my-app",
  provider="npm",
  flags=["run", "test"]
)

可用工具

run_build -执行和分析命令

使用支持的提供程序执行构建/测试命令，并获得智能分析。

参数：

• project_path （string）-运行命令的目录
• provider （string）-构建提供程序：“pytest”、“unittest”、”npm”或“docker”
• flags （可选列表）-要传递给提供程序的标志/参数列表
• timeout （可选int）-命令超时时间（秒）（默认值：600）
• model （可选字符串）-LLM分析模型

退货：

• 较小LLM的构建或测试结果摘要
• 用于检索完整输出的生成ID
• 退出代码和基本指标

例子：

run_build(
  project_path="/my-react-app",
  provider="npm",
  flags=["run", "test", "--", "--coverage"],
  timeout=300,
  model="openai/gpt-4o-mini"
)

get_build_output -检索完整输出

从任何以前的版本中获取完整的stdout/stderr。

参数：

• build_id （string）-根据run_Build结果生成ID

退货：

• 完成stdout和stderr文本
• 命令详细信息和元数据
• 执行时间戳

例子：

# First run a build
result = run_build("/my-app", "npm", ["test"])
build_id = json.loads(result)["build_id"]

# Later, get full output for detailed analysis
full_output = get_build_output(build_id)

list_build_history -浏览过去的建筑

列出最近的版本及其ID和摘要。

参数：

• limit （可选int）-要返回的最大内部版本数（默认值：10）

退货：

• 包含元数据的最新版本列表
• 用于检索完整输出的构建ID

list_providers -支持的提供商

显示支持的构建/测试提供程序和示例用法。

退货：

• 支持的提供商列表
• 每个提供程序的示例标志
• 使用指南

list_models -可用的AI模型

显示可用的LLM模型以供分析。

退货：

• 常见OpenRouter型号列表
• 默认模型配置

cleanup_old_builds -管理存储

清理旧的构建输出以节省磁盘空间。

参数：

• max_age_days （可选int）-最大年龄（以天为单位）（默认值：7）

使用示例

基本构建分析

# Run tests and get summary
result = run_build("/my-app", "npm", ["run", "test"])

# Output:
{
  "status": "failed",
  "summary": "Tests failed: 2 of 15 tests failed in UserAuth module. TypeError in login validation - expected string but received undefined.",
  "build_id": "1704123456_1234",
  "exit_code": 1
}

详细错误调查

# Get full output for debugging
full_output = get_build_output("1704123456_1234")

# Access complete logs
stdout = json.loads(full_output)["stdout"]
stderr = json.loads(full_output)["stderr"]

Docker构建分析

# Analyze Docker builds
run_build(
  project_path="/my-container-app",
  provider="docker",
  flags=["build", "-t", "myapp:latest", "."]
)

# Output might be:
{
  "status": "success", 
  "summary": "Docker build completed successfully. Image size: 1.2GB. Build time: 3m 45s. All layers cached except final application layer.",
  "build_id": "1704123789_5678"
}

Python覆盖测试

# Run Python tests with coverage
run_build(
  project_path="/my-python-api",
  provider="pytest",
  flags=["--cov=src", "--cov-report=term-missing", "tests/"],
  model="anthropic/claude-3-haiku"
)

# Run unittest discovery
run_build(
  project_path="/my-python-api",
  provider="unittest",
  flags=["discover", "-s", "tests", "-p", "test_*.py"]
)

构建历史跟踪

# Check recent builds
history = list_build_history(5)

配置

环境变量

在中配置 .env 文件：

# OpenRouter API Configuration (Required)
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

# Default model for analysis
DEFAULT_MODEL=mistralai/mistral-small-3.2-24b-instruct-2506:free

# Command timeout (seconds)
DEFAULT_TIMEOUT=600

模型选择

用于构建分析的流行OpenRouter模型：

快速免费：

• mistralai/mistral-small-3.2-24b-instruct-2506:free
• google/gemini-flash-1.5-8b:free
• deepseek/deepseek-r1-0528:free
• qwen/qwen3-32b:free
• google/gemini-2.0-flash-exp:free
• mistralai/mistral-nemo:free

平衡的：

• anthropic/claude-3-haiku
• openai/gpt-4o-mini

高品质：

• anthropic/claude-3-sonnet
• openai/gpt-4o

存储配置

构建输出存储在 build_outputs/ 目录：

• 具有完整命令输出的JSON文件
• 用于快速查找的索引文件
• 7天后自动清理（可配置）

Claude代码集成

自动设置

这 run_server.sh 脚本可以自动将服务器添加到Claude Code中：

./run_server.sh
# Choose 'Y' when prompted to add to Claude Code

手动设置

claude mcp add build-output-tools -s user -- /path/to/.venv/bin/python /path/to/src/build_output_tools_mcp/server.py

服务器管理

# Stop the MCP server connection
./scripts/stop_server.sh

# Completely remove from Claude Code
./scripts/uninstall_server.sh

# Reinstall after removal
./run_server.sh

Claude桌面设置

增添 claude_desktop_config.json:

{
  "mcpServers": {
    "build-output-tools": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/src/build_output_tools_mcp/server.py"]
    }
  }
}

故障排除

常见问题

MCP服务器连接问题：

# Stop and restart the server
./scripts/stop_server.sh
./scripts/uninstall_server.sh
./run_server.sh

API密钥无效：

# Check your .env file
cat .env | grep OPENROUTER_API_KEY

# Verify API key at https://openrouter.ai/

命令超时：

# Increase timeout for long builds
run_build("/my-app", "npm", ["run", "build"], timeout=1200)

存储空间已满：

# Clean up old builds
cleanup_old_builds(max_age_days=3)

测试服务器

# Run test suite
python -m pytest tests/ -v

# Test with sample providers
run_build("/tmp", "npm", ["--version"])
run_build("/tmp", "pytest", ["--help"])

高级用法

提供商发现和验证

# Discover available providers
providers = list_providers()
print(json.loads(providers)["supported_providers"])  # ["pytest", "unittest", "npm", "docker"]

# Invalid provider handling
result = run_build("/my-app", "invalid_provider", ["test"])
# Returns: {"status": "error", "error": "Unsupported provider: invalid_provider..."}

定制型号

# Use specific models for different analysis needs
run_build("/my-app", "npm", ["test"], model="anthropic/claude-3-sonnet")  # Deep analysis
run_build("/my-app", "npm", ["run", "lint"], model="google/gemini-flash-1.5")  # Quick checks

错误模式检测

# Get history and analyze patterns
history = list_build_history(50)

# Use build IDs to analyze common failure patterns
failing_builds = [b for b in history if not b["success"]]

贡献

我们欢迎捐款！一些潜在的改进领域：

• API与供应商的直接集成 -删除对OpenRouter的硬依赖，并为Anthropic或OpenAI等其他模型提供商添加API访问权限
• 运行测试命令的安全检查 -当前的使用方法 subprocess 有保证的启动命令，如 pytest 或 docker 这是一个良好的开端，但恶意活动的解决方法仍有可能存在。
• 特定于框架的解析器 -寻找贡献者来添加对更多测试框架的支持！
• 构建比较 -构建之间的差异分析

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

• 问题:
• 文档：此自述文件
• api参考：请参阅上面的工具说明