From f6e43e7aea98757b377b8f9895772a9c62c00076 Mon Sep 17 00:00:00 2001 From: "w. ian douglas" Date: Wed, 14 May 2025 14:43:58 -0600 Subject: [PATCH] docs: adding remote sse deeplinks (#2535) --- .../docs/getting-started/using-extensions.md | 58 +++++++++++++++++-- 1 file changed, 54 insertions(+), 4 deletions(-) diff --git a/documentation/docs/getting-started/using-extensions.md b/documentation/docs/getting-started/using-extensions.md index 299b5906b1..8444390d50 100644 --- a/documentation/docs/getting-started/using-extensions.md +++ b/documentation/docs/getting-started/using-extensions.md @@ -140,7 +140,7 @@ See available servers in the **[MCP Server Directory](https://www.pulsemcp.com/s 2. Select `Add Extension` from the menu. - 3. Choose the type of extension you’d like to add: + 3. Choose the type of extension you'd like to add: - `Built-In Extension`: Use an extension that comes pre-installed with Goose. - `Command-Line Extension`: Add a local command or script to run as an extension. - `Remote Extension`: Connect to a remote system via SSE (Server-Sent Events). @@ -246,6 +246,58 @@ Note: Java and Kotlin extensions are only support on Linux and macOS + +### Deeplinks + +Extensions can be installed using Goose's deep link protocol. The URL format varies based on the extension type: + + +``` +goose://extension?cmd=&arg=&id=&name=&description= +``` + +Required parameters: +- `cmd`: The base command to run (e.g., `npx`, `uvx`) +- `arg`: (cmd only) Command arguments (can be repeated for multiple arguments: `&arg=...&arg=...`) +- `timeout`: Maximum time (in seconds) to wait for extension responses +- `id`: Unique identifier for the extension +- `name`: Display name for the extension +- `description`: Brief description of the extension's functionality + +A command like `npx -y @modelcontextprotocol/server-github` would be represented as: + +``` +goose://extension?cmd=npx&arg=-y&arg=%40modelcontextprotocol/server-github&timeout=&id=&name=&description= +``` + +Note that each parameter to the `npx` command is passed as a separate `arg` parameter in the deeplink. + + +``` +goose://extension?url=&id=&name=&description= +``` + +Parameters: +- `url`: The URL of the remote SSE server +- `timeout`: Maximum time (in seconds) to wait for extension responses +- `id`: Unique identifier for the extension +- `name`: Display name for the extension +- `description`: Brief description of the extension's functionality + +For example, a deeplink for a URL like `http://localhost:8080/sse` would look like this when URL-encoded: + +``` +goose://extension?url=http%3A%2F%2Flocalhost%3A8080%2Fsse&timeout=&id=&name=&description=> +``` + + + + +:::note +All parameters in the deeplink must be URL-encoded. For example, spaces should be replaced with `%20`, and `@` should be replaced with `%40`. +::: + + ### Config Entry For advanced users, you can also directly edit the config file (`~/.config/goose/config.yaml`) to add, remove, or update an extension: @@ -465,9 +517,6 @@ You can remove installed extensions. - - - ## Starting Session with Extensions You can start a tailored Goose session with specific extensions directly from the CLI. @@ -531,6 +580,7 @@ goose session --with-extension "GITHUB_PERSONAL_ACCESS_TOKEN= npx -y Note that you'll need [Node.js](https://nodejs.org/) installed on your system to run this command, as it uses `npx`. ::: + ### Remote Extensions over SSE To enable a remote extension over SSE while starting a session, run the following command: