Adding separate installation guides, policies doc, and punching up the README intro

Author: D1M1TR10S

README.md

@@ -1,14 +1,16 @@
 # GitHub MCP Server
 
-The GitHub MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction)
-server that provides seamless integration with GitHub APIs, enabling advanced
-automation and interaction capabilities for developers and tools.
+The GitHub MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that connects AI tools directly to GitHub's platform. This gives AI agents, assistants, and chatbots the ability to read repositories and code files, manage issues and PRs, analyze code, and automate workflows—all through natural language interactions.
 
 ### Use Cases
 
-- Automating GitHub workflows and processes.
-- Extracting and analyzing data from GitHub repositories.
-- Building AI powered tools and applications that interact with GitHub's ecosystem.
+- Repository Management: Browse code, search files, analyze commits, and understand project structure across any repository you have access to.
+- Issue & PR Automation: Create, update, and manage issues and pull requests. Let AI help triage bugs, review code changes, and maintain project boards.
+- CI/CD & Workflow Intelligence: Monitor GitHub Actions workflow runs, analyze build failures, manage releases, and get insights into your development pipeline.
+- Code Analysis: Examine security findings, review Dependabot alerts, understand code patterns, and get comprehensive insights into your codebase.
+- Team Collaboration: Access discussions, manage notifications, analyze team activity, and streamline processes for your team.
+
+Built for developers who want to connect their AI tools to GitHub context and capabilities, from simple natural language queries to complex multi-step agent workflows.
 
 ---
 
@@ -120,6 +122,8 @@ For MCP Hosts that are [Remote MCP-compatible](docs/host-integration.md), choose
 
 See [Remote Server Documentation](docs/remote-server.md) on how to pass additional configuration settings to the remote GitHub MCP Server.
 
+> **For other host applications:** See our **[Installation Guides Index](installation-guides.md)** for detailed setup instructions for other MCP host apps like Claude Desktop, Cursor and Windsurf.
+
 ---
 
 ## Local GitHub MCP Server
@@ -133,15 +137,36 @@ See [Remote Server Documentation](docs/remote-server.md) on how to pass addition
 3. Lastly you will need to [Create a GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new).
 The MCP server can use many of the GitHub APIs, so enable the permissions that you feel comfortable granting your AI tools (to learn more about access tokens, please check out the [documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)).
 
+<details><summary><b>Securely Storing Your GitHub PATs</b></summary>
+
+To keep your GitHub PAT secure and reusable across different MCP hosts:
+
+1. Save your GitHub PAT in a `.env` file
+```env
+GITHUB_PAT=your_token_here
+```
+2. Ensure `.env` is in your `.gitignore` file to prevent accidental commits.
+3. Source the environment variable
+```bash
+source .env
+```
+4. You can now reference the token using `$GITHUB_PAT` (or any variable name you choose) in CLI commands or config files.
+
+ > Note: the syntax and support for environment variables varies by host app and IDE. Make sure to refer to their documentation for guidance on the proper method for secure token storage and environment variables.
+
+</details>
+
 ## Installation
 
-### Usage with VS Code
+### Install in GitHub Copilot on VS Code
 
 For quick installation, use one of the one-click install buttons. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start.
 
-### Usage in other MCP Hosts
+More about using MCP server tools in VS Code's [agent mode documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
 
-Add the following JSON block to your IDE MCP settings.
+<details><summary><b>Install in GitHub Copilot on other IDEs (JetBrains, Visual Studio, Eclipse, etc.)</b></summary>
+
+Add the following JSON block to your IDE's MCP settings.
 
 ```json
 {
@@ -174,8 +199,11 @@ Add the following JSON block to your IDE MCP settings.
 }
 ```
 
-Optionally, you can add a similar example (i.e. without the mcp key) to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with others.
+Optionally, you can add a similar example (i.e. without the mcp key) to a file called `.vscode/mcp.json` in your workspace. This will allow you to share the configuration with other host applications that accept the same format.
 
+<details>
+<summary><b>Example JSON block without the MCP key included<b></summary>
+<br>
 
 ```json
 {
@@ -204,33 +232,23 @@ Optionally, you can add a similar example (i.e. without the mcp key) to a file c
     }
   }
 }
-
 ```
 
-More about using MCP server tools in VS Code's [agent mode documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
+</details>
 
-### Usage with Claude Desktop
+</details>
 
-```json
-{
-  "mcpServers": {
-    "github": {
-      "command": "docker",
-      "args": [
-        "run",
-        "-i",
-        "--rm",
-        "-e",
-        "GITHUB_PERSONAL_ACCESS_TOKEN",
-        "ghcr.io/github/github-mcp-server"
-      ],
-      "env": {
-        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
-      }
-    }
-  }
-}
-```
+### Install in Other Host Applications
+
+For other MCP host applications, please refer to our installation guides:
+
+- **[Claude Code](install-claude.md)** - Installation guide for Claude Code and Claude Desktop
+- **[Cursor](install-cursor.md)** - Installation guide for Cursor IDE  
+- **[Windsurf](install-windsurf.md)** - Installation guide for Windsurf IDE
+
+For a complete overview of all installation options, see our **[Installation Guides Index](installation-guides.md)**.
+
+> **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.
 
 ### Build from source
 

docs/installation-guides/install-claude.md

@@ -0,0 +1,175 @@
+# Install GitHub MCP Server in Claude Applications
+
+This guide covers installation for both Claude Code CLI and Claude Desktop applications.
+
+## Claude Code CLI
+
+Claude Code CLI provides command-line access to Claude with MCP server integration.
+
+### Prerequisites
+
+1. Claude Code CLI installed
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
+
+### Installation
+
+Run the following command in the Claude Code CLI, referencing your GitHub PAT:
+
+```bash
+claude mcp add-json github '{"command": "github-mcp-server", "args": ["stdio"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_pat"}}'
+```
+
+### Configuration Steps
+
+1. Replace `your_github_pat` with your actual GitHub Personal Access Token
+2. Ensure you have the necessary permissions on your GitHub PAT for the operations you want to perform
+3. The command will add the GitHub MCP Server to your Claude Code configuration
+
+### Troubleshooting Claude Code
+
+- Verify the Claude Code CLI is properly installed and accessible
+- Check that your GitHub PAT is valid and has the required permissions
+- Ensure the command syntax is correct (note the single quotes around the JSON)
+- Review Claude Code documentation for any specific MCP server requirements
+
+---
+
+## Claude Desktop
+
+Claude Desktop provides a user-friendly interface for interacting with the GitHub MCP Server.
+
+### Prerequisites
+
+1. Claude Desktop installed
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
+3. [Docker](https://www.docker.com/) installed and running
+
+### Installation Steps
+
+1. Follow the Claude Desktop [MCP install guide](https://modelcontextprotocol.io/quickstart/user)
+2. Add the following configuration to your Claude Desktop configuration file
+
+### Configuration
+
+Add the following JSON to your Claude Desktop configuration file, replacing `your_github_pat` with your actual GitHub Personal Access Token:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_pat"
+      }
+    }
+  }
+}
+```
+
+### Using Environment Variables
+
+You can also use environment variables for better security. Replace `your_github_pat` with a variable reference like `$GITHUB_PAT`:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT"
+      }
+    }
+  }
+}
+```
+
+### Configuration File Location
+
+The Claude Desktop configuration file is typically located at:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+- **Linux**: `~/.config/claude/claude_desktop_config.json`
+
+### Troubleshooting Claude Desktop
+
+- Verify Docker is running and accessible
+- Check that your GitHub PAT is valid and has the required permissions
+- Ensure the configuration file is valid JSON
+- Restart Claude Desktop after making configuration changes
+- Check Claude Desktop logs for any error messages
+
+### Prerequisites
+
+1. Claude Code CLI installed
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
+
+### Installation
+
+Run the following command in the Claude Code CLI, referencing your GitHub PAT:
+
+```bash
+claude mcp add-json github '{"command": "github-mcp-server", "args": ["stdio"], "env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_pat"}}'
+```
+
+### Configuration Steps
+
+1. Replace `your_github_pat` with your actual GitHub Personal Access Token
+2. Ensure you have the necessary permissions on your GitHub PAT for the operations you want to perform
+3. The command will add the GitHub MCP Server to your Claude Code configuration
+
+### Troubleshooting Claude Code
+
+- Verify the Claude Code CLI is properly installed and accessible
+- Check that your GitHub PAT is valid and has the required permissions
+- Ensure the command syntax is correct (note the single quotes around the JSON)
+- Review Claude Code documentation for any specific MCP server requirements
+
+---
+
+## Security Best Practices
+
+Regardless of which Claude application you're using, follow these security guidelines:
+
+- **Keep your GitHub PAT secure** and never commit it to version control
+- **Limit the scope** of your GitHub PAT to only the permissions you need
+- **Consider using environment variables** for token storage when supported by your setup
+- **Regularly rotate** your GitHub Personal Access Tokens
+- **Ensure Docker environment is secure** (for Claude Desktop installations)
+
+## Installation Methods
+
+The GitHub MCP Server supports multiple installation approaches:
+
+### Docker (Recommended for Claude Desktop)
+- **Pros**: No local build required, consistent environment, easy updates
+- **Cons**: Requires Docker installed and running
+- **Used by**: Claude Desktop configuration above
+
+### Direct Binary (Used by Claude Code)
+- **Pros**: No Docker required, direct execution via stdio
+- **Cons**: Requires the `github-mcp-server` binary to be available in PATH
+- **Used by**: Claude Code CLI configuration above
+
+### Build from Source (Alternative)
+- **Pros**: Latest features, customizable, no Docker dependency
+- **Cons**: Requires Go development environment
+- **Prerequisites**: [Go 1.24+](https://go.dev/doc/install)
+- **Build command**: `go build -o github-mcp-server cmd/github-mcp-server/main.go`
+
+Choose the method that best fits your environment and requirements.

docs/installation-guides/install-cursor.md

@@ -0,0 +1,68 @@
+# Install GitHub MCP Server in Cursor
+
+## Prerequisites
+
+1. Cursor IDE installed
+2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new)
+3. [Docker](https://www.docker.com/) installed and running
+
+## Installation Steps
+
+1. Go to `Cursor Settings` → `Tools & Integrations` → Click `Add Custom MCP` or `New MCP Server`
+2. Use the following `mcp.json` structure:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "docker",
+      "args": [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_pat"
+      }
+    }
+  }
+}
+```
+
+3. Replace `your_github_pat` with your actual GitHub PAT
+4. Restart Cursor for changes to apply
+
+## Important Security Notes
+
+⚠️ **Environment Variable Limitations**: Environment-variable interpolation (using a `$GITHUB_PAT` variable) is not supported in Cursor.
+
+### Security Best Practices
+
+- **File Permissions**: Lock down file permissions for the configuration file:
+  ```bash
+  chmod 600 ~/.codeium/windsurf/mcp.json
+  ```
+- **Version Control**: Avoid committing configuration files with tokens to version control
+- **Token Scope**: Limit PAT scopes to necessary repositories and tools only
+- **Token Rotation**: Regularly rotate your GitHub Personal Access Tokens
+
+## Configuration File Location
+
+The MCP configuration is typically stored at:
+- `~/.codeium/windsurf/mcp.json`
+
+## Troubleshooting
+
+- Ensure Docker is running and accessible
+- Verify your GitHub PAT is valid and has required permissions
+- Check that the JSON configuration is valid
+- Restart Cursor after making configuration changes
+- Review Cursor logs for any MCP server startup errors
+- Ensure the GitHub MCP Server Docker image is accessible (`ghcr.io/github/github-mcp-server`)
+
+## Alternative Setup
+
+If you prefer to manually edit the configuration file, you can directly edit the `mcp.json` file at the location mentioned above with the same JSON structure.