mcp-bruno

🔌 Bruno Python MCP 服务

用于运行 Bruno 集合的 Python MCP 服务。它通过 stdio 提供模型上下文协议服务，其中的工具可通过 bru CLI 运行集合，并返回规范化的 JSON 结果。

注意：本仓库中的所有示例都使用占位名称（project1、/home/user/project/bruno、example.test）。请替换为你自己的路径和集合名称。

✨ 功能

• 运行 Bruno 集合：使用 Bruno CLI 原生运行。
• 发现集合：自动发现集合和同级环境文件。
• 支持环境文件和动态环境变量。
• **安全注入密钥：**通过 inherited_variables 将密钥传递给 Bruno，而不会向大模型暴露其值。密钥值通过临时的、仅所有者可访问的 --env-file 和子进程环境注入，不会出现在 CLI 参数（ps 输出）或日志中。
• **筛选条件检查：**检查文档中记录的查询筛选条件，并运行临时筛选场景，而不会修改源集合。
• **两阶段完整验证：**在一次工具调用中执行基线测试和所有文档中记录的筛选条件。
• **规范化输出：**返回包含 success、summary、failures 和 timings 的结构化执行结果。

📦 要求

• **Python：**3.10 或更高版本
• 包管理器：uv
• Node 包管理器：npm （仅当尚未安装 Bruno CLI 时需要）

安装程序会检查 Bruno CLI 命令 bru 是否可用。如果未安装，服务会明确报错，而不会静默安装软件包。手动安装固定版本：

npm install -g @usebruno/[email protected]

运行时自动安装功能可用，但需选择启用：设置 BRUNO_MCP_AUTO_INSTALL_BRU=1（或在配置文件的 [bruno] 下设置 auto_install = true），服务便会安装 cli_version / BRUNO_MCP_BRU_VERSION 中指定的固定版本。

🚀 安装与运行

1. 安装

使用 uv 安装依赖：

uv sync

（如果你配置的软件包索引未镜像 MCP Python SDK，请在同步时将 uv 指向 PyPI：UV_DEFAULT_INDEX=https://pypi.org/simple uv sync）

2. 运行服务

你可以直接使用 uv 运行服务：

uv run bruno-mcp

或者，在 uv 环境中直接运行模块：uv run python -m bruno_mcp

⚙️ 配置

MCP 配置

此工作区根目录下的 MCP stdio 配置示例：

{
  "mcpServers": {
    "bruno-runner": {
      "command": "uv",
      "args": ["run", "bruno-mcp"]
    }
  }
}

配置文件（bruno-mcp.toml）

可以在当前工作目录的 bruno-mcp.toml 中配置默认根目录和身份验证别名，也可以在全局配置文件 ~/.config/bruno-mcp/config.toml 中配置。

带注释的模板请参阅 bruno-mcp.example.toml：

[workspace]
roots = [
  "/home/user/project/bruno"
]

[bruno]
cli_version = "4.2.0"   # pinned Bruno CLI version
auto_install = false     # never install bru silently at runtime

[limits]
run_timeout_seconds = 300
max_output_bytes = 8388608
max_concurrent_runs = 2

[artifacts]
ttl_hours = 24           # raw reports are auto-deleted after this
max_files = 50

[security]
enforce_root_confinement = true   # reject collection paths outside workspace roots

[auth]
inherited_variables = [
  "BRUNO_AUTH_TOKEN",
  "BRUNO_API_KEY"
]

[defaults]
environment = "dev"

每项设置也可以通过环境变量配置（BRUNO_MCP_BRU_VERSION、BRUNO_MCP_AUTO_INSTALL_BRU、BRUNO_MCP_RUN_TIMEOUT、BRUNO_MCP_MAX_OUTPUT_BYTES、BRUNO_MCP_MAX_CONCURRENT_RUNS、BRUNO_MCP_ARTIFACTS_DIR、BRUNO_MCP_ARTIFACT_TTL_HOURS、BRUNO_MCP_ARTIFACT_MAX_FILES、BRUNO_MCP_ENFORCE_ROOT_CONFINEMENT、BRUNO_MCP_LOG_LEVEL），且环境变量的优先级高于配置文件。

**注意：**安装程序会创建包含虚拟根目录的 ~/.config/bruno-mcp/config.toml。本地 bruno-mcp.toml 文件会被 Git 忽略，因此真实路径和环境名称永远不会被提交。

💻 本地 VS Code 安装

在项目根目录中，使用 uv 安装依赖：

UV_DEFAULT_INDEX=[https://pypi.org/simple](https://pypi.org/simple) uv sync

确保 Bruno CLI 可用（bru --version）。此仓库包含 .vscode/mcp.json，可让 VS Code 从工作区发现本地 MCP 服务：

{
  "servers": {
    "bruno-runner": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "bruno-mcp"]
    }
  }
}

同步依赖后，重新加载 VS Code 窗口。现在，MCP 服务列表中应该会显示 bruno-runner 服务。

全局安装

将 MCP 服务安装到 VS Code 用户配置文件中，使其在任何工作区中都可用：

uv run python scripts/install_vscode.py

（若要同时全局安装可复用的 Copilot 提示词和 Agent，请在上方命令后追加 --with-copilot-customizations。）

若要在另一个本地 VS Code 工作区中手动安装，请将命令参数更改为包含 --directory：

"args": ["--directory", "/home/user/mcp-bruno", "run", "bruno-mcp"]

🧰 可用工具

🔍 list-collections

列出根目录或已配置根目录下的 Bruno 集合。当用户提供的是不完整的集合名称而非完整路径时，可使用此工具。

• root （可选）：Bruno 根目录（通常包含 collections/ 和 environments/）。
• query （可选）：用于筛选集合名称和路径的大小写不敏感文本。

▶️ run-collection

运行 Bruno 集合并返回规范化的执行结果。

• collection （必填）：Bruno 集合的路径。
• environment （可选）：环境文件的路径。
• variables （可选）：以 KEY=value 字符串表示的环境变量。
• inherited_variables （可选）：要从 MCP 服务进程中读取并注入 Bruno 的环境变量名称，不会向大模型暴露变量值。变量值通过临时的、仅所有者可访问的 --env-file 和子进程环境传递（{{process.env.NAME}} 也适用），绝不会出现在 CLI 参数中。

{
  "collection": "/home/user/project/bruno/collections/project1",
  "environment": "dev",
  "inherited_variables": ["BRUNO_AUTH_TOKEN"]
}

🌍 discover-environments

检查 Bruno 集合周围的文件夹结构，并返回同级环境目录、可用环境名称以及变量名称（不返回机密变量值）。

📖 read-result-artifact

从 run-collection 返回的原始 Bruno JSON 工件路径中，读取范围受限且已脱敏的摘要。

• path （必填）：之前一次运行返回的 artifact.path 值。
• max_items （可选）：每个请求要抽取的响应项数（默认值为 3，最大值为 20）。

🧪 list-request-filters 和 run-filter-scenarios

• list-request-filters：检查 YAML 请求文件，并返回按启用和禁用状态分组的查询参数。
• run-filter-scenarios：运行临时请求变体，启用选定的禁用查询参数，但不会修改源文件。

🛡️ run-full-validation

在一次工具调用中执行两阶段编排：

1. 基线：运行一次集合，并检查每个端点是否都能无错误地响应（无 4xx/5xx）。
2. 筛选器：仅在基线检查通过时运行。自动发现并测试每个端点上所有已禁用的查询筛选器。

Agent 技能与 Copilot 集成

这些工作流使用配置为 bruno-runner 的 MCP 服务；安装技能或提示词不会安装或配置该服务。请先使用上面的 MCP 配置，在客户端中配置该服务。

VS Code GitHub Copilot

此仓库包含一个自定义 Agent 和一个斜杠命令提示词。在此仓库根目录下，将它们复制到目标工作区：

mkdir -p /path/to/workspace/.github/agents /path/to/workspace/.github/prompts
cp copilot/agents/bruno-runner.agent.md /path/to/workspace/.github/agents/
cp copilot/prompts/run-bruno-collection.prompt.md /path/to/workspace/.github/prompts/

在 Copilot Chat 的 Agent 选择器中选择 bruno-runner 自定义 Agent（支持时使用 @bruno-runner），或在 Chat 中运行 /run-bruno-collection <collection or path> [environment]。无需选择自定义 Agent，也可以独立使用斜杠命令。

或者，使用以下命令全局安装两者：

uv run python scripts/install_vscode.py --with-copilot-customizations

Claude Code / Cursor / Windsurf

通用的 Bruno Runner 技能整合了集合发现、环境选择、标准运行、定向筛选器场景、完整的两阶段验证、密钥安全和报告规则。

对于 Claude Code，请将其复制到目标项目的技能目录：

mkdir -p /path/to/workspace/.claude/skills/bruno-runner
cp skills/bruno-runner/SKILL.md /path/to/workspace/.claude/skills/bruno-runner/SKILL.md

或者，使用绝对源路径创建技能目录的符号链接：

mkdir -p /path/to/workspace/.claude/skills
ln -s /absolute/path/to/mcp-bruno/skills/bruno-runner /path/to/workspace/.claude/skills/bruno-runner

对于 Cursor，请将同一目录复制或符号链接到 .cursor/skills/bruno-runner/；对于 Windsurf，请在目标工作区中使用 .windsurf/skills/bruno-runner/。技能发现取决于客户端版本和配置。对于使用规则的客户端，请将技能正文改写为其原生规则格式（例如，使用 Cursor 规则 frontmatter 的 .cursor/rules/bruno-runner.mdc 文件）；仅将 SKILL.md 复制到规则目录并不能保证技能会被激活。

可以要求运行集合、验证特定筛选器，或测试所有端点和筛选器。工作流通过 inherited_variables 在本地解析密钥；切勿将凭据粘贴到聊天中。服务的本地令牌回退路径为 ~/.config/bruno-mcp/.bearer_token（原始令牌），而不是 ~/.config/mcp-bruno/.bearer_token。更新后，请重启 MCP 服务。

仓库资源

技能和 Copilot 模板仍分别整理在仓库根目录下的 skills/ 和 copilot/ 中，与 pyproject.toml 中 src/ 下发现的 Python 包分开。它们是仓库资源，不是已安装 wheel 中的资源；请使用仓库检出版本运行上述复制、符号链接和安装命令。仅安装 Python 包不会向客户端注册 Agent 工作流。

执行结果保留服务规范化的输出契约：

{
  "success": true,
  "summary": {
    "total": 5,
    "failed": 0,
    "passed": 5
  },
  "failures": [],
  "auth_failure": false,
  "auth_message": null,
  "timings": {
    "started": "2024-03-14T10:00:00.000000Z",
    "completed": "2024-03-14T10:00:01.000000Z",
    "duration": 1000
  }
}

🐳 Docker

Docker 镜像会同时安装此 Python 服务和 Bruno CLI：

docker build -t bruno-mcp-python .
docker run --rm -i bruno-mcp-python

🛠️ 开发与项目结构

命令：

• 编译检查源代码：uv run python -m compileall src
• 运行测试套件：uv run python -m unittest discover -s tests -v

结构：

.
├── src/bruno_mcp/         # MCP server, runner, config, and types
├── scripts/               # VS Code installer script
├── copilot/               # Reusable Copilot prompt and agent templates
├── skills/bruno-runner/    # Universal Agent Skill (SKILL.md)
├── tests/                 # Unit tests
├── .vscode/mcp.json       # Workspace MCP server entry
└── bruno-mcp.example.toml # Commented configuration template

mcp-name: io.github.kta41/mcp-bruno

📄 许可证

基于 MIT License 发布。