MCP Goose

mcp-goose 翻译为中文是“MCP-鹅（或MCP-鹅形物/鹅状物）”，但具体翻译可能需要根据上下文来确定，因为“mcp”可能是一个特定的缩写或代码，而“goose”在这里直接翻译为“鹅”。如果“mcp”有特定的含义或背景，那么翻译时可能需要考虑这一点。在没有具体上下文的情况下，上述翻译是一个较为通用的译法

一个安全的MCP（模型上下文协议）服务器，允许其他AI代理使用Goose CLI在单个项目文件夹上自动化编码任务。

• 在无头（非交互式）模式下与官方 Goose CLI 协作
• 仅在预先批准的单个项目目录内运行
• 允许您启动任务、检查状态以及为长时间运行的工作流式传输日志
• 由承载令牌（授权头）保护

快速入门（完全无头模式）

# 1) Install dependencies
npm install

# 2) Configure environment (edit values for your setup)
export AUTH_TOKEN="your-secret"
export GOOSE_SCOPE_DIR="/abs/path/to/your/project"
# optional: export GOOSE_BINARY="/usr/local/bin/goose"

# Provider and model (example: OpenAI)
export GOOSE_PROVIDER__TYPE="openai"
export GOOSE_PROVIDER__HOST="https://api.openai.com/v1"
export GOOSE_PROVIDER__API_KEY="your-openai-api-key"
export GOOSE_MODE="auto"
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-4.1"
export GOOSE_MAX_TURNS="100"

# Tip: If you keep your exports in a shell file (e.g. ./.goose-env.sh), be sure to SOURCE it so the variables apply to your current shell:
#   source ./.goose-env.sh
# (Running `sh ./.goose-env.sh` will not persist the variables.)

# 3) Start the server (auto-preflight + auto-install if needed)
npm start

发生的事情 npm start:

• 验证 Goose 是否已安装。如果未安装，它将自动从稳定渠道（非交互式）安装 Goose 并重试。
• 跑步 goose info 确认配置（例如，提供商API密钥）。如果出现问题，启动将失败并给出明确的指导。

注：自动安装需要 curl 在系统中可用。

绝对路径要求：

• GOOSE_SCOPE_DIR 必须是绝对路径（例如。， /Users/you/code/my-project）。

这是什么？

mcp-goose 它就像是人工智能代理（AI agents）与您本地Goose设置之间的桥梁。它通过MCP协议，从Goose命令行界面（CLI）中暴露了一小部分安全且专注的命令，因此任何兼容MCP的人工智能代理都可以：

• 启动一个Goose任务（例如，运行一个配方）
• 查看那个任务的进展情况
• 随着任务运行，阅读输出日志
• 如有需要，停止任务

所有这些操作都发生在你事先配置好的一个项目目录内。

我为什么要用它？

• 你希望一个AI代理（或多个代理）在你控制的代码库上运行Goose任务
• 您需要设置严格的安全边界：只有Goose可以运行，且仅限于一个文件夹内
• 你需要可靠的方法来监控和管理长时间运行的任务

其工作原理（概述）

• 你指出 mcp-goose 在您希望Goose操作的项目文件夹中（即“作用域目录”）。
• 您提供一个承载令牌，客户端必须使用该令牌进行身份验证。
• 一个AI代理通过MCP（管理控制协议）连接，并使用一组小型工具来执行Goose命令。
• 服务器在Goose运行时捕获日志并提供状态更新。

安全边界

• 仅执行Goose二进制文件；无shell访问权限，无任意命令执行权限
• 所有命令都在您配置的项目目录内运行
• 支持一小部分经过白名单许可的Goose命令和标志
• 需要通过以下方式进行身份验证 Authorization: Bearer
• 默认情况下，并发性限制为一次仅一个作业

这些界限是为了确保在生产环境中的安全使用而设计的。

你将需要

• Node.js 18及以上版本
• 已安装 Goose CLI（推荐使用最新版本）
• 一个已为Goose配置好的项目目录（此服务器为零配置）

有用的鹅（Helpful Goose）文档：

• 快速入门：https://block.github.io/goose/docs/quickstart
• CLI 命令：https://block.github.io/goose/docs/guides/goose-cli-commands
• 无头模式：https://block.github.io/goose/docs/tutorials/headless-goose

安装

1. 克隆此仓库
2. 安装依赖项

npm install

1. 安装Goose CLI（如需）

# optional: installs Goose from the stable channel without interactive configure
chmod +x scripts/install-goose.sh
./scripts/install-goose.sh

配置

在启动服务器之前，请设置以下环境变量：

• AUTH_TOKEN （必填）

持有者令牌客户端必须在（请求中）发送 Authorization 头球

• 项目目录（选择一个）：

- PROJECT_NAME （推荐）：简单的项目名称（例如。， my-website）。 服务器将在（指定位置）创建并管理一个目录 / / 并自动将其初始化为一个Git仓库。 - GOOSE_SCOPE_DIR指向现有项目目录的绝对路径。当您需要完全控制或想指向管理项目目录之外的现有项目时，请使用此路径。

• GOOSE_PROJECTS_DIR （可选）

使用时创建项目的基准目录 PROJECT_NAME默认为 /projects对于希望在Docker部署中将项目置于（特定位置/环境）的情况非常有用 /projects 或者另一个绝对路径。

• GOOSE_BINARY （可选）

到……的绝对路径 goose 可执行文件。默认为 goose 在你的PATH（环境变量路径）中。

• MAX_CONCURRENCY （可选）

默认为 1保持运营的可预测性和安全性。

• LOG_MAX_BYTES （可选）

每个作业保留的最大日志数据字节数（默认值：8,000,000 ~ 8 MB）。

示例与 PROJECT_NAME （推荐给大多数用户）：

export AUTH_TOKEN="your-secret"
export PROJECT_NAME="my-website"
export MAX_CONCURRENCY="1"
export LOG_MAX_BYTES="8000000"

示例与 GOOSE_SCOPE_DIR （针对现有项目）：

export AUTH_TOKEN="your-secret"
export GOOSE_SCOPE_DIR="/abs/path/to/your/project"
export MAX_CONCURRENCY="1"
export LOG_MAX_BYTES="8000000"

你也可以从本仓库中提供的示例环境文件开始（记得使用SOURCE命令来加载它，而不是运行它）：

cp examples/goose-env.example.sh .goose-env.sh
# edit .goose-env.sh to set your token, ABSOLUTE scope directory, and provider API key
source .goose-env.sh

提供商配置示例（OpenAI）——请在之前设置这些 npm start：

export GOOSE_PROVIDER__TYPE="openai"
export GOOSE_PROVIDER__HOST="https://api.openai.com/v1"
export GOOSE_PROVIDER__API_KEY="your-openai-api-key"

# Optional general headless tuning
export GOOSE_MODE="auto"
export GOOSE_PROVIDER="openai"
export GOOSE_MODEL="gpt-4.1"
export GOOSE_MAX_TURNS="100"
export GOOSE_CONTEXT_STRATEGY="summarize"
export GOOSE_CLI_MIN_PRIORITY="0.2"

要了解更多的Goose环境变量，请参阅： https://block.github.io/goose/docs/guides/environment-variables 翻译为中文是：https://block.github.io/goose/docs/guides/环境变量指南

启动服务器

npm start

服务器将启动并等待MCP客户端连接。启动时，它会自动检查是否已安装Goose，并报告检查结果 goose info 结果。它使用与参考MCP服务器相同的头部风格来验证请求Authorization: Bearer ）。

与MCP客户端一起使用

任何兼容MCP的客户端/代理都可以连接并调用所暴露的工具 mcp-goose从高层来看，流程大致如下：

1. 启动一个Goose任务，使用 goose_run （例如，运行一个食谱）
2. 与（某人/某团队）一起了解民意调查进展 goose_status
3. 使用（工具）流式处理日志 goose_stream_logs
4. 可选择地获取最终输出结果 goose_get_output
5. 如有需要，请使用（以下命令/方法）停止正在运行的任务 goose_stop

支持的工具（简要概述）

• goose_run

- 以无头模式启动一个新的Goose作业，仅使用文本提示。此工具总是执行 goose run --no-session -t ""。

• goose_status

- 检查作业是已排队、运行中、已完成、已失败还是已取消。

• goose_stream_logs

- 以块为单位读取作业的实时或最近日志，以便您能够跟踪进度。

• goose_get_output

- 作业完成后，检索最终的标准输出（stdout）/标准错误（stderr）。

• goose_stop

- 停止正在运行的任务。

• goose_recipe_validate

- 验证一个配方文件（封装 goose recipe validate ）。

• goose_recipe_deeplink

- 为食谱文件生成一个可共享的链接（包裹 goose recipe deeplink ）。

• goose_session_list

- 列出已保存的会话（包含 goose session list 可选（的功能/选项等） --verbose， --format， --ascending）。

• goose_session_export

- 将会话导出为Markdown或标准输出（包裹 goose session export （与……一起）用；带有；具有 --id/--name/--path/--output）。

• goose_list_commands

- 查看此服务器允许哪些Goose命令和旗帜。

• goose_help

- 获取 goose --help 输出（可以是通用的，也可以是针对特定子命令的）。

• goose_version

- 返回已安装的Goose版本。

• get_config

- 返回非敏感服务器设置（如作用域目录）。

• health_check

- 简单的存活/就绪检查。

常见示例

• 无头运行文本提示并进行监控

- 打电话 goose_run 输入为： { "text": "create a simple website that is a love letter to gooses" }。 - 带有（或“与……一起进行的”）民意调查 goose_status 在它运行时。 - 使用 goose_stream_logs 观察进展。

• 验证一个食谱

- 呼叫 goose_recipe_validate 与……一起；带有；用……（的方式） file: "my-recipe.yaml"。

• 检查Goose版本

- 呼叫 goose_version。

MCP 检测器

您可以使用检查器快速测试MCP端点：

# server should be running (npm start) and AUTH_TOKEN exported
npm run mcp:inspect

这将MCP流量发送到 POST http://localhost:3003/mcp 与……一起；带有 Authorization: Bearer $AUTH_TOKEN 头球

可靠无头浏览器运行的小贴士

• 更喜欢可重复自动化操作的配方。在无头模式下，配方应包含一个 prompt 字段。
• 在启动服务器之前，请在您的shell/profile中设置Goose环境变量，以符合您的偏好（提供商、模型、最大回合数）。
• 避免使用交互式标志；此服务器旨在用于非交互式、自动化的任务。

控制台输出：

• 默认情况下，作业的标准输出（stdout）/标准错误（stderr）会以类似“\[prefix\]”的前缀形式回显到服务器控制台 [goose::stdout] ...。
• 要禁用控制台回显，请设置 ECHO_JOB_LOGS=false 在……之前 npm start。

分支预览（本地静态托管）

这台服务器可以从您的（位置/资源中）发布静态内容 GOOSE_SCOPE_DIR 并在本地运行它：

• 根站点（主分支）： http://localhost:3003/
• 预览站点（功能分支）： `http://localhost:3003/.preview/

/`

行为：

• 启动时，服务器会发布当前检出的分支。如果它是 main如果（条件满足），根站点会更新；否则，只有匹配的预览路径会更新。
• 每次提交（或切换分支）时，当前分支都会被重新发布。
• 根（/) 始终提供最后发布的最新内容 main预览位于下方 /.preview/。

注：

• 只有已提交的更改会被发布。未提交的工作目录更改根据设计不会被发布。
• 分支名称被转换为文件系统安全的短语（例如。， feature/some-thing → feature_some-thing）。

故障排除预览更新：

• 如果在（某个地方）提交了一个更改 main 没有触发发布，您的仓库可能使用的是Git打包引用。早期版本仅监控 HEAD 和 `refs/heads/

; 提交该更新 .git/packed-refs 不会触发文件监视器事件。这一点已得到加强，现在也会监视 packed-refs 并且进行民意调查 git rev-parse HEAD` 每2秒一次。更新后，重启服务器。

• 一些平台/文件系统可能会丢弃或合并监视事件。轮询回退机制仍应能够检测到新的提交（它会比较 HEAD 哈希)。
• 确保 GOOSE_SCOPE_DIR 指向仓库根目录。如果你在子模块或不同的文件夹中进行提交，监视器将不会看到这些提交。
• 在首次运行时，若处于非（特定状态或环境）下main 分支，在您发布之前，根节点可能为空 main 至少一次。

故障排除

• 认证错误：请确保您的客户端发送 Authorization: Bearer 。
• “命令不允许”：服务器阻止了其内部允许列表中未包含的命令/标志。
• “未找到鹅”：集合 GOOSE_BINARY 如果 Goose CLI 不在系统路径 (PATH) 中，请使用其绝对路径。
• 日志已截断：增加 LOG_MAX_BYTES 如果你需要每项工作都有更长的历史记录。

路线图

• 作业完成时的可选Webhook通知（带签名）
• 持久的工作历史记录（以便在重启后查看之前的运行情况）
• 指标和追踪（了解运行时间和成功率）
• 每令牌策略和速率限制

许可证

这个项目重新使用了来自……的模式 mcp-reference 服务器，并遵循类似的许可使用政策。参见 LICENSE 详情见下。

本地鹅文档（可选）

为了便于离线查阅，我们已在以下位置稀疏地整理了 Goose 的文档：

• ref-docs/documentation/docs/

这包括诸如……之类的指南 guides/goose-cli-commands.md， quickstart.md以及教程。\*\*\* 结束补丁