diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c16cd27d..34aa12bb7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,7 +8,7 @@ Hi there! We're thrilled that you'd like to contribute to this project. Your hel Contributions to this project are [released](https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license) to the public under the [project's open source license](LICENSE). -Please note that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. +Please note that this project is released with a [Contributor Code of Conduct](https://github.com/github/github-mcp-server/blob/main/CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms. ## What we're looking for @@ -39,8 +39,8 @@ These are one time installations required to be able to test your changes locall - Run linter: `script/lint` - Update snapshots and run tests: `UPDATE_TOOLSNAPS=true go test ./...` - Update readme documentation: `script/generate-docs` - - If renaming a tool, add a deprecation alias (see [Tool Renaming Guide](docs/tool-renaming.md)) - - For toolset and icon configuration, see [Toolsets and Icons Guide](docs/toolsets-and-icons.md) + - If renaming a tool, add a deprecation alias (see [Tool Renaming Guide](https://github.com/github/github-mcp-server/blob/main/docs/tool-renaming.md)) + - For toolset and icon configuration, see [Toolsets and Icons Guide](https://github.com/github/github-mcp-server/blob/main/docs/toolsets-and-icons.md) 6. Push to your fork and [submit a pull request][pr] targeting the `main` branch 7. Pat yourself on the back and wait for your pull request to be reviewed and merged. diff --git a/README.md b/README.md index 1a0f6b1c4..d494b4b5b 100644 --- a/README.md +++ b/README.md @@ -80,12 +80,12 @@ Alternatively, to manually configure VS Code, choose the appropriate JSON block ### Install in other MCP hosts -- **[GitHub Copilot in other IDEs](/docs/installation-guides/install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot -- **[Claude Applications](/docs/installation-guides/install-claude.md)** - Installation guide for Claude Desktop and Claude Code CLI -- **[Codex](/docs/installation-guides/install-codex.md)** - Installation guide for Open AI Codex -- **[Cursor](/docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE -- **[Windsurf](/docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE -- **[Rovo Dev CLI](/docs/installation-guides/install-rovo-dev-cli.md)** - Installation guide for Rovo Dev CLI +- **[GitHub Copilot in other IDEs](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot +- **[Claude Applications](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md)** - Installation guide for Claude Desktop and Claude Code CLI +- **[Codex](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-codex.md)** - Installation guide for Open AI Codex +- **[Cursor](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE +- **[Windsurf](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE +- **[Rovo Dev CLI](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-rovo-dev-cli.md)** - Installation guide for Rovo Dev CLI > **Note:** Each MCP host application needs to configure a GitHub App or OAuth App to support remote access via OAuth. Any host application that supports remote MCP servers should support the remote GitHub server with PAT authentication. Configuration details and support levels vary by host. Make sure to refer to the host application's documentation for more info. @@ -93,7 +93,7 @@ Alternatively, to manually configure VS Code, choose the appropriate JSON block #### Toolset configuration -See [Remote Server Documentation](docs/remote-server.md) for full details on remote server configuration, toolsets, headers, and advanced usage. This file provides comprehensive instructions and examples for connecting, customizing, and installing the remote GitHub MCP Server in VS Code and other MCP hosts. +See [Remote Server Documentation](https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md) for full details on remote server configuration, toolsets, headers, and advanced usage. This file provides comprehensive instructions and examples for connecting, customizing, and installing the remote GitHub MCP Server in VS Code and other MCP hosts. When no toolsets are specified, [default toolsets](#default-toolset) are used. @@ -297,13 +297,13 @@ Optionally, you can add a similar example (i.e. without the mcp key) to a file c For other MCP host applications, please refer to our installation guides: -- **[GitHub Copilot in other IDEs](/docs/installation-guides/install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot -- **[Claude Code & Claude Desktop](docs/installation-guides/install-claude.md)** - Installation guide for Claude Code and Claude Desktop -- **[Cursor](docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE -- **[Google Gemini CLI](docs/installation-guides/install-gemini-cli.md)** - Installation guide for Google Gemini CLI -- **[Windsurf](docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE +- **[GitHub Copilot in other IDEs](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot +- **[Claude Code & Claude Desktop](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md)** - Installation guide for Claude Code and Claude Desktop +- **[Cursor](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE +- **[Google Gemini CLI](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-gemini-cli.md)** - Installation guide for Google Gemini CLI +- **[Windsurf](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE -For a complete overview of all installation options, see our **[Installation Guides Index](docs/installation-guides)**. +For a complete overview of all installation options, see our **[Installation Guides Index](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides)**. > **Note:** Any host application that supports local MCP servers should be able to access the local GitHub MCP server. However, the specific configuration process, syntax and stability of the integration will vary by host application. While many may follow a similar format to the examples above, this is not guaranteed. Please refer to your host application's documentation for the correct MCP configuration syntax and setup process. @@ -336,7 +336,7 @@ _Toolsets are not limited to Tools. Relevant MCP Resources and Prompts are also When no toolsets are specified, [default toolsets](#default-toolset) are used. -> **Looking for examples?** See the [Server Configuration Guide](./docs/server-configuration.md) for common recipes like minimal setups, read-only mode, and combining tools with toolsets. +> **Looking for examples?** See the [Server Configuration Guide](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md) for common recipes like minimal setups, read-only mode, and combining tools with toolsets. #### Specifying Toolsets @@ -386,7 +386,7 @@ You can also configure specific tools using the `--tools` flag. Tools can be use - Tools, toolsets, and dynamic toolsets can all be used together - Read-only mode takes priority: write tools are skipped if `--read-only` is set, even if explicitly requested via `--tools` - Tool names must match exactly (e.g., `get_file_contents`, not `getFileContents`). Invalid tool names will cause the server to fail at startup with an error message -- When tools are renamed, old names are preserved as aliases for backward compatibility. See [Deprecated Tool Aliases](docs/deprecated-tool-aliases.md) for details. +- When tools are renamed, old names are preserved as aliases for backward compatibility. See [Deprecated Tool Aliases](https://github.com/github/github-mcp-server/blob/main/docs/deprecated-tool-aliases.md) for details. ### Using Toolsets With Docker @@ -1513,4 +1513,4 @@ The exported Go API of this module should currently be considered unstable, and ## License -This project is licensed under the terms of the MIT open source license. Please refer to [MIT](./LICENSE) for the full terms. +This project is licensed under the terms of the MIT open source license. Please refer to [MIT](https://github.com/github/github-mcp-server/blob/main/LICENSE) for the full terms. diff --git a/docs/installation-guides/README.md b/docs/installation-guides/README.md index be967f81d..f06bbe87d 100644 --- a/docs/installation-guides/README.md +++ b/docs/installation-guides/README.md @@ -3,13 +3,13 @@ This directory contains detailed installation instructions for the GitHub MCP Server across different host applications and IDEs. Choose the guide that matches your development environment. ## Installation Guides by Host Application -- **[GitHub Copilot in other IDEs](install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot -- **[Antigravity](install-antigravity.md)** - Installation for Google Antigravity IDE -- **[Claude Applications](install-claude.md)** - Installation guide for Claude Web, Claude Desktop and Claude Code CLI -- **[Cursor](install-cursor.md)** - Installation guide for Cursor IDE -- **[Google Gemini CLI](install-gemini-cli.md)** - Installation guide for Google Gemini CLI -- **[OpenAI Codex](install-codex.md)** - Installation guide for OpenAI Codex -- **[Windsurf](install-windsurf.md)** - Installation guide for Windsurf IDE +- **[GitHub Copilot in other IDEs](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-other-copilot-ides.md)** - Installation for JetBrains, Visual Studio, Eclipse, and Xcode with GitHub Copilot +- **[Antigravity](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-antigravity.md)** - Installation for Google Antigravity IDE +- **[Claude Applications](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-claude.md)** - Installation guide for Claude Web, Claude Desktop and Claude Code CLI +- **[Cursor](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE +- **[Google Gemini CLI](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-gemini-cli.md)** - Installation guide for Google Gemini CLI +- **[OpenAI Codex](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-codex.md)** - Installation guide for OpenAI Codex +- **[Windsurf](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE ## Support by Host Application @@ -88,7 +88,7 @@ If you encounter issues: 2. Verify your GitHub PAT has the required permissions 3. Ensure Docker is running (for local installations) 4. Review your host application's logs for error messages -5. Consult the main [README.md](README.md) for additional configuration options +5. Consult the main [README.md](https://github.com/github/github-mcp-server/blob/main/README.md) for additional configuration options ## Configuration Options diff --git a/docs/installation-guides/install-antigravity.md b/docs/installation-guides/install-antigravity.md index c24d8e01d..3593479a5 100644 --- a/docs/installation-guides/install-antigravity.md +++ b/docs/installation-guides/install-antigravity.md @@ -128,7 +128,7 @@ Once installed, you'll have access to tools like: - `get_file_contents` - Read file content - And many more... -For a complete list of available tools and features, see the [main README](../../README.md). +For a complete list of available tools and features, see the [main README](https://github.com/github/github-mcp-server/blob/main/README.md). ## Differences from Other IDEs @@ -138,6 +138,6 @@ For a complete list of available tools and features, see the [main README](../.. ## Next Steps -- Explore the [Server Configuration Guide](../server-configuration.md) for advanced options -- Check out [toolsets documentation](../../README.md#available-toolsets) to customize available tools -- See the [Remote Server Documentation](../remote-server.md) for more details +- Explore the [Server Configuration Guide](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md) for advanced options +- Check out [toolsets documentation](https://github.com/github/github-mcp-server/blob/main/README.md#available-toolsets) to customize available tools +- See the [Remote Server Documentation](https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md) for more details diff --git a/docs/installation-guides/install-codex.md b/docs/installation-guides/install-codex.md index 5f92996bc..d16b8828a 100644 --- a/docs/installation-guides/install-codex.md +++ b/docs/installation-guides/install-codex.md @@ -56,7 +56,7 @@ After starting Codex (CLI or IDE): ## Usage -After setup, Codex can interact with GitHub directly. It will use the default tool set automatically but can be [configured](../../README.md#default-toolset). Try these example prompts: +After setup, Codex can interact with GitHub directly. It will use the default tool set automatically but can be [configured](https://github.com/github/github-mcp-server/blob/main/README.md#default-toolset). Try these example prompts: **Repository Operations:** - "List my GitHub repositories" @@ -109,4 +109,4 @@ Use the principle of least privilege: add scopes only when a tool request fails - Remote server URL: `https://api.githubcopilot.com/mcp/` - Release binaries: [GitHub Releases](https://github.com/github/github-mcp-server/releases) - OpenAI Codex MCP docs: https://developers.openai.com/codex/mcp -- Main project README: [Advanced configuration options](../../README.md) +- Main project README: [Advanced configuration options](https://github.com/github/github-mcp-server/blob/main/README.md) diff --git a/docs/installation-guides/install-gemini-cli.md b/docs/installation-guides/install-gemini-cli.md index 20764384c..72b894a93 100644 --- a/docs/installation-guides/install-gemini-cli.md +++ b/docs/installation-guides/install-gemini-cli.md @@ -28,7 +28,7 @@ MCP servers for Gemini CLI are configured in its settings JSON under an `mcpServ After securely storing your PAT, you can add the GitHub MCP server configuration to your settings file using one of the methods below. You may need to restart the Gemini CLI for changes to take effect. -> **Note:** For the most up-to-date configuration options, see the [main README.md](../../README.md). +> **Note:** For the most up-to-date configuration options, see the [main README.md](https://github.com/github/github-mcp-server/blob/main/README.md). ### Method 1: Gemini Extension (Recommended) diff --git a/docs/installation-guides/install-other-copilot-ides.md b/docs/installation-guides/install-other-copilot-ides.md index a3200179c..138755f8e 100644 --- a/docs/installation-guides/install-other-copilot-ides.md +++ b/docs/installation-guides/install-other-copilot-ides.md @@ -1,6 +1,6 @@ # Install GitHub MCP Server in Copilot IDEs -Quick setup guide for the GitHub MCP server in GitHub Copilot across different IDEs. For VS Code instructions, refer to the [VS Code install guide in the README](/README.md#installation-in-vs-code) +Quick setup guide for the GitHub MCP server in GitHub Copilot across different IDEs. For VS Code instructions, refer to the [VS Code install guide in the README](https://github.com/github/github-mcp-server/blob/main/README.md#installation-in-vs-code) ### Requirements: - **GitHub Copilot License**: Any Copilot plan (Free, Pro, Pro+, Business, Enterprise) for Copilot access diff --git a/docs/remote-server.md b/docs/remote-server.md index d7d0f72b1..f4f44df34 100644 --- a/docs/remote-server.md +++ b/docs/remote-server.md @@ -68,7 +68,7 @@ The Remote GitHub MCP server has optional headers equivalent to the Local server - Equivalent to `GITHUB_LOCKDOWN_MODE` env var for Local server. - If this header is empty, "false", "f", "no", "n", "0", or "off" (ignoring whitespace and case), it will be interpreted as false. All other values are interpreted as true. -> **Looking for examples?** See the [Server Configuration Guide](./server-configuration.md) for common recipes like minimal setups, read-only mode, and combining tools with toolsets. +> **Looking for examples?** See the [Server Configuration Guide](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md) for common recipes like minimal setups, read-only mode, and combining tools with toolsets. Example: @@ -88,7 +88,7 @@ Example: The Remote GitHub MCP server supports the following URL path patterns: -- `/` - Default toolset (see ["default" toolset](../README.md#default-toolset)) +- `/` - Default toolset (see ["default" toolset](https://github.com/github/github-mcp-server/blob/main/README.md#default-toolset)) - `/readonly` - Default toolset in read-only mode - `/x/all` - All available toolsets - `/x/all/readonly` - All available toolsets in read-only mode diff --git a/docs/scope-filtering.md b/docs/scope-filtering.md index f29d631ca..e605184b7 100644 --- a/docs/scope-filtering.md +++ b/docs/scope-filtering.md @@ -24,7 +24,7 @@ With OAuth, the remote server can dynamically request additional scopes as neede ## OAuth Scope Challenges (Remote Server) -When using the [remote MCP server](./remote-server.md) with OAuth authentication, the server uses a different approach called **scope challenges**. Instead of hiding tools upfront, all tools are available, and the server requests additional scopes on-demand when you try to use a tool that requires them. +When using the [remote MCP server](https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md) with OAuth authentication, the server uses a different approach called **scope challenges**. Instead of hiding tools upfront, all tools are available, and the server requests additional scopes on-demand when you try to use a tool that requires them. **How it works:** 1. You attempt to use a tool (e.g., creating an issue) @@ -58,7 +58,7 @@ Some scopes implicitly include others: This means if your token has `repo`, tools requiring `security_events` will also be available. -Each tool in the [README](../README.md#tools) lists its required and accepted OAuth scopes. +Each tool in the [README](https://github.com/github/github-mcp-server/blob/main/README.md#tools) lists its required and accepted OAuth scopes. ## Public Repository Access @@ -98,6 +98,6 @@ WARN: failed to fetch token scopes, continuing without scope filtering ## Related Documentation -- [Server Configuration Guide](./server-configuration.md) +- [Server Configuration Guide](https://github.com/github/github-mcp-server/blob/main/docs/server-configuration.md) - [GitHub PAT Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) - [OAuth Scopes Reference](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps) diff --git a/docs/server-configuration.md b/docs/server-configuration.md index 46ec3bc64..ab874e1af 100644 --- a/docs/server-configuration.md +++ b/docs/server-configuration.md @@ -1,6 +1,6 @@ # Server Configuration Guide -This guide helps you choose the right configuration for your use case and shows you how to apply it. For the complete reference of available toolsets and tools, see the [README](../README.md#tool-configuration). +This guide helps you choose the right configuration for your use case and shows you how to apply it. For the complete reference of available toolsets and tools, see the [README](https://github.com/github/github-mcp-server/blob/main/README.md#tool-configuration). ## Quick Reference We currently support the following ways in which the GitHub MCP Server can be configured: @@ -28,7 +28,7 @@ Note: **read-only** mode acts as a strict security filter that takes precedence ## Configuration Examples -The examples below use VS Code configuration format to illustrate the concepts. If you're using a different MCP host (Cursor, Claude Desktop, JetBrains, etc.), your configuration might need to look slightly different. See [installation guides](./installation-guides) for host-specific setup. +The examples below use VS Code configuration format to illustrate the concepts. If you're using a different MCP host (Cursor, Claude Desktop, JetBrains, etc.), your configuration might need to look slightly different. See [installation guides](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides) for host-specific setup. ### Enabling Specific Tools @@ -341,7 +341,7 @@ Lockdown mode ensures the server only surfaces content in public repositories fr This happens transparently—no configuration needed. If scope detection fails for a classic PAT (e.g., network issues), the server logs a warning and continues with all tools available. -See [Scope Filtering](./scope-filtering.md) for details on how filtering works with different token types. +See [Scope Filtering](https://github.com/github/github-mcp-server/blob/main/docs/scope-filtering.md) for details on how filtering works with different token types. --- @@ -349,7 +349,7 @@ See [Scope Filtering](./scope-filtering.md) for details on how filtering works w | Problem | Cause | Solution | |---------|-------|----------| -| Server fails to start | Invalid tool name in `--tools` or `X-MCP-Tools` | Check tool name spelling; use exact names from [Tools list](../README.md#tools) | +| Server fails to start | Invalid tool name in `--tools` or `X-MCP-Tools` | Check tool name spelling; use exact names from [Tools list](https://github.com/github/github-mcp-server/blob/main/README.md#tools) | | Write tools not working | Read-only mode enabled | Remove `--read-only` flag or `X-MCP-Readonly` header | | Tools missing | Toolset not enabled | Add the required toolset or specific tool | | Dynamic tools not available | Using remote server | Dynamic mode is available in the local MCP server only | @@ -358,8 +358,8 @@ See [Scope Filtering](./scope-filtering.md) for details on how filtering works w ## Useful links -- [README: Tool Configuration](../README.md#tool-configuration) -- [README: Available Toolsets](../README.md#available-toolsets) — Complete list of toolsets -- [README: Tools](../README.md#tools) — Complete list of individual tools -- [Remote Server Documentation](./remote-server.md) — Remote-specific options and headers -- [Installation Guides](./installation-guides) — Host-specific setup instructions +- [README: Tool Configuration](https://github.com/github/github-mcp-server/blob/main/README.md#tool-configuration) +- [README: Available Toolsets](https://github.com/github/github-mcp-server/blob/main/README.md#available-toolsets) — Complete list of toolsets +- [README: Tools](https://github.com/github/github-mcp-server/blob/main/README.md#tools) — Complete list of individual tools +- [Remote Server Documentation](https://github.com/github/github-mcp-server/blob/main/docs/remote-server.md) — Remote-specific options and headers +- [Installation Guides](https://github.com/github/github-mcp-server/blob/main/docs/installation-guides) — Host-specific setup instructions diff --git a/docs/testing.md b/docs/testing.md index 226660e9d..5ed32ec59 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -17,7 +17,7 @@ This project uses a combination of unit tests and end-to-end (e2e) tests to ensu ## End-to-End (e2e) Tests -- E2E tests are located in the [`e2e/`](../e2e/) directory. See the [e2e/README.md](../e2e/README.md) for full details on running and debugging these tests. +- E2E tests are located in the [`e2e/`](https://github.com/github/github-mcp-server/blob/main/e2e/) directory. See the [e2e/README.md](https://github.com/github/github-mcp-server/blob/main/e2e/README.md) for full details on running and debugging these tests. ## toolsnaps: Tool Schema Snapshots @@ -31,4 +31,4 @@ committed. ## Notes - Some tools that mutate global state (e.g., marking all notifications as read) are tested primarily with unit tests, not e2e, to avoid side effects. -- For more on the limitations and philosophy of the e2e suite, see the [e2e/README.md](../e2e/README.md). +- For more on the limitations and philosophy of the e2e suite, see the [e2e/README.md](https://github.com/github/github-mcp-server/blob/main/e2e/README.md). diff --git a/docs/tool-renaming.md b/docs/tool-renaming.md index cf342f6dc..84024da13 100644 --- a/docs/tool-renaming.md +++ b/docs/tool-renaming.md @@ -12,7 +12,7 @@ This allows us to rename tools safely, without introducing breaking changes for ## Quick Steps 1. **Rename the tool** in your code (as usual, this will imply a range of changes like updating the tool registration, the tests and the toolsnaps). -2. **Add a deprecation alias** in [pkg/github/deprecated_tool_aliases.go](../pkg/github/deprecated_tool_aliases.go): +2. **Add a deprecation alias** in [pkg/github/deprecated_tool_aliases.go](https://github.com/github/github-mcp-server/blob/main/pkg/github/deprecated_tool_aliases.go): ```go var DeprecatedToolAliases = map[string]string{ "old_tool_name": "new_tool_name",