一个安全的MCP(模型上下文协议)服务器,允许其他AI代理使用Goose CLI在单个项目文件夹上自动化编码任务。
- 在无头(非交互式)模式下与官方 Goose CLI 协作
- 仅在预先批准的单个项目目录内运行
- 允许您启动任务、检查状态以及为长时间运行的工作流式传输日志
- 由承载令牌(授权头)保护
快速入门(完全无头模式)```bash
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. 克隆此仓库
1. 安装依赖项```bash
npm install
- 安装Goose CLI(如需)```bash
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` (推荐给大多数用户):```bash
export AUTH_TOKEN="your-secret"
export PROJECT_NAME="my-website"
export MAX_CONCURRENCY="1"
export LOG_MAX_BYTES="8000000"
示例与 GOOSE_SCOPE_DIR (针对现有项目):```bash
export AUTH_TOKEN="your-secret"
export GOOSE_SCOPE_DIR="/abs/path/to/your/project"
export MAX_CONCURRENCY="1"
export LOG_MAX_BYTES="8000000"
你也可以从本仓库中提供的示例环境文件开始(记得使用SOURCE命令来加载它,而不是运行它):```bash
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:```bash
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环境变量,请参阅:
## 启动服务器```bash
npm start
服务器将启动并等待MCP客户端连接。启动时,它会自动检查是否已安装Goose,并报告检查结果 goose info 结果。它使用与参考MCP服务器相同的头部风格来验证请求Authorization: Bearer)。
与MCP客户端一起使用
任何兼容MCP的客户端/代理都可以连接并调用所暴露的工具 mcp-goose从高层来看,流程大致如下:
- 启动一个Goose任务,使用
goose_run(例如,运行一个食谱) - 与(某人/某团队)一起了解民意调查进展
goose_status - 使用(工具)流式处理日志
goose_stream_logs - 可选择地获取最终输出结果
goose_get_output - 如有需要,请使用(以下命令/方法)停止正在运行的任务
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端点:```bash
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以及教程。*** 结束补丁
