构建输出工具mcp

Name: 构建输出工具mcp
Author: jgordley

作者：jgordley6 星标更新：2025-07-01

安装使用来源：spider==github.com

项目介绍

🛠️ 构建输出工具 MCP

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

./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跟踪随时间变化的构建。

快速导航

开始使用 - 五分钟设置
可用工具 - 所有MCP工具概述
使用示例 - 实际场景
配置 - API密钥和设置

功能

基于提供商的安全执行

# 安全的基于提供商的命令
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"])

支持的测试/构建框架

提供商	描述	常见标志	示例用法
pytest	Python 测试框架	`--cov=src`, `--verbose`, `-x`, `--tb=short`	`run_build("/app", "pytest", ["--cov=src", "tests/"])`
unittest	Python 内置测试	`discover`, `-s`, `-p`, `-v`	`run_build("/app", "unittest", ["discover", "-s", "tests"])`
npm	Node.js 包管理器	`run`, `test`, `install`, `--coverage`	`run_build("/app", "npm", ["run", "test", "--", "--coverage"])`
docker	容器平台	`build`, `run`, `-t`, `--no-cache`	`run_build("/app", "docker", ["build", "-t", "myapp", "."])`

智能分析

智能摘要 - 来自OpenRouter LLMs（Mistral, Gemini等）
错误高亮 - 关注可操作的失败
成功指标 - 提取测试计数、覆盖率、性能数据
可配置模型 - 根据分析需求选择合适的LLM

输出存储与检索

自动存储 - 每个构建都会获得一个唯一的ID
全文访问 - 需要时检索完整的stdout/stderr
构建历史 - 跟踪随时间变化的构建
自动清理 - 自动管理磁盘空间

工作流集成

适用于开发工作流：

运行构建 - 获取即时智能摘要
调试失败 - 访问完整日志进行详细分析
跟踪进度 - 监控随时间变化的构建
共享结果 - 构建ID使协作变得容易

开始使用

先决条件

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

1. 快速设置

# 克隆并设置
git clone https://github.com/your-username/build-output-tools-mcp.git
cd build-output-tools-mcp

# 单命令设置
./run_server.sh

设置脚本会：

创建Python虚拟环境
安装依赖项
设置.env文件
可选地添加到Claude Code

2. 添加API密钥

编辑.env文件，添加您的OpenRouter API密钥：

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

3. 开始使用！

在Claude Code中：

# 列出可用提供商
list_providers()

# 使用特定提供商运行测试
run_build(
  project_path="/path/to/my-app",
  provider="npm",
  flags=["run", "test"]
)

可用工具

`run_build` - 执行并分析命令

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

参数：

project_path (字符串) - 运行命令的目录
provider (字符串) - 构建提供商："pytest", "unittest", "npm" 或 "docker"
flags (可选列表) - 传递给提供商的标志/参数列表
timeout (可选整数) - 命令超时秒数（默认：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 (字符串) - run_build 结果中的构建ID

返回值：

完整的stdout和stderr文本
命令详情和元数据
执行时间戳

示例：

# 首先运行一个构建
result = run_build("/my-app", "npm", ["test"])
build_id = json.loads(result)["build_id"]

# 后期，获取完整输出进行详细分析
full_output = get_build_output(build_id)

`list_build_history` - 浏览过去构建

列出最近的构建及其ID和摘要。

参数：

limit (可选整数) - 返回的最大构建数（默认：11）

返回值：

最近构建的列表及其元数据
构建ID用于检索完整输出

`list_providers` - 支持的提供商

显示支持的构建/测试提供商及其示例用法。

返回值：

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

`list_models` - 可用AI模型

显示可用于分析的LLM模型。

返回值：

常见的OpenRouter模型列表
默认模型配置

`cleanup_old_builds` - 管理存储

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

参数：

max_age_days (可选整数) - 最大天数（默认：7）

使用示例

基本构建分析

# 运行测试并获取摘要
result = run_build("/my-app", "npm", ["run", "test"])

# 输出：
{
  "status": "failed",
  "summary": "测试失败：UserAuth模块中有15个测试中有2个失败。登录验证中的TypeError - 期望字符串但收到undefined。",
  "build_id": "1704123456_1234",
  "exit_code": 1
}

详细的错误调查

# 获取完整输出进行调试
full_output = get_build_output("1704123456_1234")

# 访问完整的日志
stdout = json.loads(full_output)["stdout"]
stderr = json.loads(full_output)["stderr"]

Docker构建分析

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

# 输出可能是：
{
  "status": "success", 
  "summary": "Docker构建成功完成。镜像大小：1.2GB。构建时间：3分45秒。除了最终的应用层外，所有层都已缓存。",
  "build_id": "1704123789_5678"
}

Python测试带覆盖率

# 运行Python测试带覆盖率
run_build(
  project_path="/my-python-api",
  provider="pytest",
  flags=["--cov=src", "--cov-report=term-missing", "tests/"],
  model="anthropic/claude-3-haiku"
)

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

构建历史跟踪

# 检查最近的构建
history = list_build_history(5)

配置

环境变量

在.env文件中配置：

# OpenRouter API配置（必需）
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1

# 分析的默认模型
DEFAULT_MODEL=mistralai/mistral-small-3.2-22b-instruct-2506:free

# 命令超时（秒）
DEFAULT_TIMEOUT=600

模型选择

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

快速且免费：

mistralai/mistral-small-3.2-22b-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 Code集成

自动设置

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

./run_server.sh
# 当提示添加到Claude Code时选择'Y'

手动设置

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

服务器管理

# 停止MCP服务器连接
./scripts/stop_server.sh

# 完全从Claude Code移除
./scripts/uninstall_server.sh

# 移除后重新安装
./run_server.sh

Claude Desktop设置

添加到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服务器连接问题：

# 停止并重启服务器
./scripts/stop_server.sh
./scripts/uninstall_server.sh
./run_server.sh

API密钥不起作用：

# 检查您的.env文件
cat .env | grep OPENROUTER_API_KEY

# 在https://openrouter.ai/验证API密钥

命令超时：

# 对于长时间构建增加超时
run_build("/my-app", "npm", ["run", "build"], timeout=1200)

存储满：

# 清理旧构建
cleanup_old_builds(max_age_days=3)

测试服务器

# 运行测试套件
python -m pytest tests/ -v

# 使用示例提供商测试
run_build("/tmp", "npm", ["--version"])
run_build("/tmp", "pytest", ["--help"])

高级用法

提供商发现与验证

# 发现可用提供商
providers = list_providers()
print(json.loads(providers)["supported_providers"])  # ["pytest", "unittest", "npm", "docker"]

# 处理无效提供商
result = run_build("/my-app", "invalid_provider", ["test"])
# 返回：{"status": "error", "error": "不支持的提供商：invalid_provider..."}

自定义模型

# 使用特定模型满足不同的分析需求
run_build("/my-app", "npm", ["test"], model="anthropic/claude-3-sonnet")  # 深度分析
run_build("/my-app", "npm", ["run", "lint"], model="google/gemini-flash-1.5")  # 快速检查

错误模式检测

# 获取历史并分析模式
history = list_build_history(50)

# 使用构建ID分析常见的失败模式
failing_builds = [b for b in history if not b["success"]]

贡献

我们欢迎贡献！一些潜在的改进领域：

直接API集成与提供商 - 移除对OpenRouter的硬依赖，并添加其他模型提供商如Anthropic或OpenAI的API访问。
运行测试命令的安全检查 - 当前使用subprocess的方法是一个好的开始，但仍然可能存在恶意活动的变通方法。
框架特定解析器 - 寻找贡献者以添加对更多测试框架的支持！
构建比较 - 构建之间的差异分析

许可证

MIT许可证 - 详见LICENSE文件。

支持

问题：GitHub Issues
文档：此README
API参考：参见上面的工具描述

构建输出工具mcp

项目介绍

🛠️ 构建输出工具 MCP

为什么需要这个服务器？

快速导航

功能

基于提供商的安全执行

支持的测试/构建框架

智能分析

输出存储与检索

工作流集成

开始使用

先决条件

1. 快速设置

2. 添加API密钥

3. 开始使用！

可用工具

run_build - 执行并分析命令

get_build_output - 检索完整输出

list_build_history - 浏览过去构建

list_providers - 支持的提供商

list_models - 可用AI模型

cleanup_old_builds - 管理存储

使用示例

基本构建分析

详细的错误调查

Docker构建分析

Python测试带覆盖率

构建历史跟踪

配置

环境变量

模型选择

存储配置

Claude Code集成

自动设置

手动设置

服务器管理

Claude Desktop设置

故障排除

常见问题

测试服务器

高级用法

提供商发现与验证

自定义模型

错误模式检测

贡献

许可证

支持

`run_build` - 执行并分析命令

`get_build_output` - 检索完整输出

`list_build_history` - 浏览过去构建

`list_providers` - 支持的提供商

`list_models` - 可用AI模型

`cleanup_old_builds` - 管理存储