From a2bd5099be35be72c43aca2878bd9dd2bb05423e Mon Sep 17 00:00:00 2001 From: Angie Jones Date: Fri, 31 Jan 2025 13:22:57 -0600 Subject: [PATCH] docs: github tutorial (#993) Co-authored-by: Adewale Abati --- .../docs/configuration/_category_.json | 8 - .../docs/getting-started/_category_.json | 2 +- documentation/docs/guides/_category_.json | 2 +- documentation/docs/quickstart.md | 2 +- documentation/docs/tutorials/_category_.json | 8 + .../custom-extensions.md | 3 +- documentation/docs/tutorials/github-mcp.md | 207 ++++++++++++++++++ documentation/docusaurus.config.ts | 6 +- 8 files changed, 225 insertions(+), 13 deletions(-) delete mode 100644 documentation/docs/configuration/_category_.json create mode 100644 documentation/docs/tutorials/_category_.json rename documentation/docs/{guides => tutorials}/custom-extensions.md (98%) create mode 100644 documentation/docs/tutorials/github-mcp.md diff --git a/documentation/docs/configuration/_category_.json b/documentation/docs/configuration/_category_.json deleted file mode 100644 index 2f34ccf9..00000000 --- a/documentation/docs/configuration/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Configuration", - "position": 5, - "link": { - "type": "generated-index", - "description": "Extend goose functionalities with extensions and custom configurations" - } -} diff --git a/documentation/docs/getting-started/_category_.json b/documentation/docs/getting-started/_category_.json index dfab504a..9c9d23a8 100644 --- a/documentation/docs/getting-started/_category_.json +++ b/documentation/docs/getting-started/_category_.json @@ -1,6 +1,6 @@ { "label": "Getting Started", - "position": 3, + "position": 2, "link": { "type": "generated-index", "description": "Get up to speed quickly with Goose" diff --git a/documentation/docs/guides/_category_.json b/documentation/docs/guides/_category_.json index 61e33681..3a2eb6f5 100644 --- a/documentation/docs/guides/_category_.json +++ b/documentation/docs/guides/_category_.json @@ -1,6 +1,6 @@ { "label": "Guides", - "position": 4, + "position": 3, "link": { "type": "generated-index", "description": "Learn essential tips and recommendations for using Goose" diff --git a/documentation/docs/quickstart.md b/documentation/docs/quickstart.md index b6ccf727..b77ee4f7 100644 --- a/documentation/docs/quickstart.md +++ b/documentation/docs/quickstart.md @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 1 title: Quickstart --- import Tabs from '@theme/Tabs'; diff --git a/documentation/docs/tutorials/_category_.json b/documentation/docs/tutorials/_category_.json new file mode 100644 index 00000000..c3d98c8b --- /dev/null +++ b/documentation/docs/tutorials/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Tutorials", + "position": 4, + "link": { + "type": "generated-index", + "description": "How to integrate and use MCP servers as Goose extensions" + } +} \ No newline at end of file diff --git a/documentation/docs/guides/custom-extensions.md b/documentation/docs/tutorials/custom-extensions.md similarity index 98% rename from documentation/docs/guides/custom-extensions.md rename to documentation/docs/tutorials/custom-extensions.md index 13212a8c..41f1a4e6 100644 --- a/documentation/docs/guides/custom-extensions.md +++ b/documentation/docs/tutorials/custom-extensions.md @@ -1,6 +1,7 @@ --- title: Building Custom Extensions -sidebar_position: 6 +sidebar_position: 1 +description: Create your own custom MCP Server to use as a Goose extension --- # Building Custom Extensions with Goose diff --git a/documentation/docs/tutorials/github-mcp.md b/documentation/docs/tutorials/github-mcp.md new file mode 100644 index 00000000..090623ba --- /dev/null +++ b/documentation/docs/tutorials/github-mcp.md @@ -0,0 +1,207 @@ +--- +title: GitHub Extension +description: Add GitHub MCP Server as a Goose Extension +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +This tutorial covers how to add the [GitHub MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/github) as a Goose extension to enable file operations, repository management, search functionality, and more. + + +:::tip TLDR + +**Command** +```sh +npx -y @modelcontextprotocol/server-github +``` + +**Environment Variable** +``` +"GITHUB_PERSONAL_ACCESS_TOKEN": "" +``` +::: + +## Configuration + + + + 1. Run the `configure` command: + ```sh + goose configure + ``` + + 2. Choose to add a `Command-line Extension` + ```sh + ┌ goose-configure + │ + ◇ What would you like to configure? + │ Add Extension + │ + ◆ What type of extension would you like to add? + │ ○ Built-in Extension + // highlight-start + │ ● Command-line Extension (Run a local command or script) + // highlight-end + │ ○ Remote Extension + └ + ``` + + 3. Give your extension a name + ```sh + ┌ goose-configure + │ + ◇ What would you like to configure? + │ Add Extension + │ + ◇ What type of extension would you like to add? + │ Command-line Extension + │ + // highlight-start + ◆ What would you like to call this extension? + │ github + // highlight-end + └ + ``` + + 4. Enter the command + ```sh + ┌ goose-configure + │ + ◇ What would you like to configure? + │ Add Extension + │ + ◇ What type of extension would you like to add? + │ Command-line Extension + │ + ◇ What would you like to call this extension? + │ github + │ + // highlight-start + ◆ What command should be run? + │ npx -y @modelcontextprotocol/server-github + // highlight-end + └ + ``` + + 5. Obtain a [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens) and paste it in. + :::info + When creating your access token, you can specify the repositories and granular permissions you'd like Goose to have access to. + ::: + + ```sh + ┌ goose-configure + │ + ◇ What would you like to configure? + │ Add Extension + │ + ◇ What type of extension would you like to add? + │ Command-line Extension + │ + ◇ What would you like to call this extension? + │ github + │ + ◇ What command should be run? + │ npx -y @modelcontextprotocol/server-github + // highlight-start + ◆ Would you like to add environment variables? + │ Yes + │ + ◇ Environment variable name: + │ GITHUB_PERSONAL_ACCESS_TOKEN + │ + ◇ Environment variable value: + │ ▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪▪ + │ + ◇ Add another environment variable? + │ No + // highlight-end + └ Added github extension + ``` + + + + 1. Click `...` in the upper right corner + 2. Click `Settings` + 3. On `Extensions` section, click the `Add` link + 4. On the `Add Extension Manually` modal, enter the following: + * **Type**: `Standard IO` + * **ID**: `gh-mcp` (_set this to whatever you want_) + * **Name**: `github` (_set this to whatever you want_) + * **Description**: `GitHub MCP Server` (_set this to whatever you want_) + * **Command**: `npx -y @modelcontextprotocol/server-github` + * **Environment Variables** + * **Name**: `GITHUB_PERSONAL_ACCESS_TOKEN` + * **Value**: (_Obtain a [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens) and paste it in._) + :::info + When creating your access token, you can specify the repositories and granular permissions you'd like Goose to have access to. + ::: + * Click `Add` button + 5. Click `Add Extension` button + + + +## Example Usage + +When creating my [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens), I gave it the following access: +* Repository: [goose-demo](https://github.com/angiejones/goose-demo) +* Read access to metadata +* Read and Write access to code, commit status, issues, and pull requests + +**Goose Prompt** +``` +create a new branch called hello-world in my angiejones/goose-demo repository. Update the README.md file to say "this was written by goose" and commit it. Open a pull request with your changes. +``` + +**Output** + +``` +I'll help you create a new branch, update the README, and open a pull request. Let me break this down into steps: + +1. First, let's create the new branch called "hello-world" in your repository +2. Then update the README.md file +3. Finally, create a pull request + +Let me execute these steps: + +1. Creating the new branch: + +─── create_branch | github ────────────────────────── +branch: hello-world +owner: angiejones +repo: goose-demo + +2. Now, updating the README.md file in the new branch: + +─── create_or_update_file | github ────────────────────────── +branch: hello-world +content: this was written by goose +message: Update README.md with Goose message +owner: angiejones +path: README.md +repo: goose-demo + + + +3. Finally, creating the pull request: + +─── create_pull_request | github ────────────────────────── +base: main +body: ... +head: hello-world +owner: angiejones +repo: goose-demo +title: Update README.md + + + +Great! I've completed all the requested tasks: +1. Created a new branch called "hello-world" +2. Updated the README.md file with the text "this was written by goose" +3. Created a pull request to merge these changes into the main branch + +You can view the pull request at: https://github.com/angiejones/goose-demo/pull/1 + +The pull request is now ready for your review. Would you like me to do anything else with it? +``` \ No newline at end of file diff --git a/documentation/docusaurus.config.ts b/documentation/docusaurus.config.ts index afff69e9..f07fcf8a 100644 --- a/documentation/docusaurus.config.ts +++ b/documentation/docusaurus.config.ts @@ -86,7 +86,11 @@ const config: Config = { { to: '/', from: '/v1/', - }, + }, + { + to: '/docs/tutorials/custom-extensions', + from: '/docs/guides/custom-extensions' + } ], }, ],