From cda36e83ad0f2e47d3fdb0fd8700f93074321b2b Mon Sep 17 00:00:00 2001 From: Javier Uruen Val Date: Wed, 26 Mar 2025 16:33:04 +0100 Subject: [PATCH 1/2] update install instructions --- README.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 76 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 10e500373..eb9f396c8 100644 --- a/README.md +++ b/README.md @@ -351,40 +351,103 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description ## Testing on VS Code Insiders -First of all, install `github-mcp-server` with: +### Requirements + +You can either use a Docker image or build the binary from the repo. + +#### Docker image + +As of now, this repo is private and hence the docker image is not available publicly. To pull it, +you need to make sure you can access the GitHub docker registry. See [this](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic) +for more details. + +To make sure you can access the GitHub docker registry, run the following command: + +```bash +docker pull ghcr.io/github/github-mcp-server:main +``` + +If the above command works, you are good to go. + +#### Build from repo +First of all, install `github-mcp-server` by cloning the repo and running the following command: ```bash go install ./cmd/github-mcp-server ``` +If you don't want to clone the repo, you can run: + +```bash +GOPRIVATE=github.com/github go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest +``` + +This will install the `github-mcp-server` binary in your `$GOPATH/bin` directory. + +Find where the binary is installed by running: + +```bash +which github-mcp-server +``` + +### Start VS Code Insiders + +Start VS Code Insiders and make sure you pass the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable to the process. + +One way to do this is to make sure that [you can run VS code from your terminal](https://code.visualstudio.com/docs/setup/mac#_launch-vs-code-from-the-command-line) and +start it with the following command: + +```bash +export GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here +code-insiders +``` + Run **Preferences: Open User Settings (JSON)**, and create or append to the `mcp` setting: +If you are using the docker image, use this configuration: + ```json { "mcp": { - "inputs": [ - { - "type": "promptString", - "id": "githubpat", - "description": "GitHub Personal Access Token", - "password": true + "inputs": [], + "servers": { + "github-mcp-server": { + "type": "stdio", + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITHUB_PERSONAL_ACCESS_TOKEN", + "ghcr.io/github/github-mcp-server:main" + ], + "env": {} } - ], + } + } +} +``` + +If you built the binary from the repo use this configuration: + +```json +{ + "mcp": { + "inputs": [ ], "servers": { "mcp-github-server": { "command": "path-to-your/github-mcp-server", "args": ["stdio"], - "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:githubpat}" - }, + "env": { } } } } } ``` -In `Copilot Edits`, you should now see an option to reload the available `tools`. -Reload, and you should be good to go. +Right on top of `servers`, you should see a `start` link to start the server. + Try something like the following prompt to verify that it works: From 6dbe595de4c7359fe456aa7f38ccfc8579f4844a Mon Sep 17 00:00:00 2001 From: Javier Uruen Val Date: Thu, 27 Mar 2025 09:52:22 +0100 Subject: [PATCH 2/2] move setup instructions to the top --- README.md | 228 +++++++++++++++++++++++++++--------------------------- 1 file changed, 114 insertions(+), 114 deletions(-) diff --git a/README.md b/README.md index eb9f396c8..0c0652adc 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,120 @@ GitHub MCP Server implemented in Go. Create a GitHub Personal Access Token with the appropriate permissions and set it as the GITHUB_PERSONAL_ACCESS_TOKEN environment variable. +## Testing on VS Code Insiders + +### Requirements + +You can either use a Docker image or build the binary from the repo. + +#### Docker image + +As of now, this repo is private, and hence the docker image is not available publicly. To pull it, +you need to make sure you can access the GitHub docker registry. See [this](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic) +for more details. + +To make sure you can access the GitHub docker registry, run the following command: + +```bash +docker pull ghcr.io/github/github-mcp-server:main +``` + +If the above command works, you are good to go. + +#### Build from repo +First, install `github-mcp-server` by cloning the repo and running the following command: + +```bash +go install ./cmd/github-mcp-server +``` + +If you don't want to clone the repo, you can run: + +```bash +GOPRIVATE=github.com/github go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest +``` + +This will install the `github-mcp-server` binary in your `$GOPATH/bin` directory. + +Find where the binary is installed by running: + +```bash +# note this assumes $GOPATH/bin is in your $PATH +which github-mcp-server +``` + +### Start VS Code Insiders + +Start VS Code Insiders and make sure you pass the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable to the process. + +One way to do this is to make sure that [you can run VS code from your terminal](https://code.visualstudio.com/docs/setup/mac#_launch-vs-code-from-the-command-line) and +start it with the following command: + +```bash +export GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here +code-insiders +``` + +Another way is to set the environment variable in your shell configuration file (e.g., `.bashrc`, `.zshrc`, etc.). + +Run **Preferences: Open User Settings (JSON)**, and create or append to the `mcp` setting: + +If you are using the docker image, use this configuration: + +```json +{ + "mcp": { + "inputs": [], + "servers": { + "github-mcp-server": { + "type": "stdio", + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITHUB_PERSONAL_ACCESS_TOKEN", + "ghcr.io/github/github-mcp-server:main" + ], + "env": {} + } + } + } +} +``` + +If you built the binary from the repo use this configuration: + +```json +{ + "mcp": { + "inputs": [ ], + "servers": { + "mcp-github-server": { + "command": "path-to-your/github-mcp-server", + "args": ["stdio"], + "env": { } + } + } + } +} +``` + +Right on top of `servers`, you should see a `Start` link to start the server. + + +Try something like the following prompt to verify that it works: + +``` +I'd like to know more about my GitHub profile. +``` + +## GitHub Enterprise Server + +The flag `--gh-host` and the environment variable `GH_HOST` can be used to set the GitHub Enterprise Server hostname. + + ## Tools ### Users @@ -349,123 +463,9 @@ For example, to override the `TOOL_ADD_ISSUE_COMMENT_DESCRIPTION` tool, you can export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description" ``` -## Testing on VS Code Insiders - -### Requirements - -You can either use a Docker image or build the binary from the repo. - -#### Docker image - -As of now, this repo is private and hence the docker image is not available publicly. To pull it, -you need to make sure you can access the GitHub docker registry. See [this](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic) -for more details. - -To make sure you can access the GitHub docker registry, run the following command: - -```bash -docker pull ghcr.io/github/github-mcp-server:main -``` - -If the above command works, you are good to go. - -#### Build from repo -First of all, install `github-mcp-server` by cloning the repo and running the following command: - -```bash -go install ./cmd/github-mcp-server -``` - -If you don't want to clone the repo, you can run: - -```bash -GOPRIVATE=github.com/github go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest -``` - -This will install the `github-mcp-server` binary in your `$GOPATH/bin` directory. - -Find where the binary is installed by running: - -```bash -which github-mcp-server -``` - -### Start VS Code Insiders - -Start VS Code Insiders and make sure you pass the `GITHUB_PERSONAL_ACCESS_TOKEN` environment variable to the process. - -One way to do this is to make sure that [you can run VS code from your terminal](https://code.visualstudio.com/docs/setup/mac#_launch-vs-code-from-the-command-line) and -start it with the following command: - -```bash -export GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here -code-insiders -``` - -Run **Preferences: Open User Settings (JSON)**, and create or append to the `mcp` setting: - -If you are using the docker image, use this configuration: - -```json -{ - "mcp": { - "inputs": [], - "servers": { - "github-mcp-server": { - "type": "stdio", - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", - "ghcr.io/github/github-mcp-server:main" - ], - "env": {} - } - } - } -} -``` - -If you built the binary from the repo use this configuration: - -```json -{ - "mcp": { - "inputs": [ ], - "servers": { - "mcp-github-server": { - "command": "path-to-your/github-mcp-server", - "args": ["stdio"], - "env": { } - } - } - } -} -``` - -Right on top of `servers`, you should see a `start` link to start the server. - - -Try something like the following prompt to verify that it works: - -``` -I'd like to know more about my GitHub profile. -``` - -## GitHub Enterprise Server - -The flag `--gh-host` and the environment variable `GH_HOST` can be used to set the GitHub Enterprise Server hostname. - ## TODO Testing - Integration tests - Blackbox testing: ideally comparing output to Anthropic's server to make sure that this is a fully compatible drop-in replacement. - -And some other stuff: - -- ...