Merge branch 'main' into omgitsads/api-error-type

Author: omgitsads

Dockerfile

@@ -1,4 +1,4 @@
-FROM golang:1.24.3-alpine AS build
+FROM golang:1.24.4-alpine AS build
 ARG VERSION="dev"
 
 # Set the working directory

README.md

@@ -31,7 +31,7 @@ The `--stdio-server-cmd` flag is required for all commands and specifies the com
 
 ### Examples
 
-List available tools in Anthropic's MCP server:
+List available tools in Github's MCP server:
 
 ```console
 % ./mcpcurl --stdio-server-cmd "docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN mcp/github" tools --help

cmd/mcpcurl/README.md

@@ -0,0 +1,193 @@
+# GitHub Remote MCP Integration Guide for MCP Host Authors
+
+This guide outlines high-level considerations for MCP Host authors who want to allow installation of the Remote GitHub MCP server.
+
+The goal is to explain the architecture at a high-level, define key requirements, and provide guidance to get you started, while pointing to official documentation for deeper implementation details.
+
+---
+
+## Table of Contents
+
+- [Understanding MCP Architecture](#understanding-mcp-architecture)
+- [Connecting to the Remote GitHub MCP Server](#connecting-to-the-remote-github-mcp-server)
+  - [Authentication and Authorization](#authentication-and-authorization)
+  - [OAuth Support on GitHub](#oauth-support-on-github)
+  - [Create an OAuth-enabled App Using the GitHub UI](#create-an-oauth-enabled-app-using-the-github-ui)
+  - [Things to Consider](#things-to-consider)
+  - [Initiating the OAuth Flow from your Client Application](#initiating-the-oauth-flow-from-your-client-application)
+- [Handling Organization Access Restrictions](#handling-organization-access-restrictions)
+- [Essential Security Considerations](#essential-security-considerations)
+- [Additional Resources](#additional-resources)
+
+---
+
+## Understanding MCP Architecture
+
+The Model Context Protocol (MCP) enables seamless communication between your application and various external tools through an architecture defined by the [MCP Standard](https://modelcontextprotocol.io/).
+
+### High-level Architecture
+
+The diagram below illustrates how a single client application can connect to multiple MCP Servers, each providing access to a unique set of resources.  Notice that some MCP Servers are running locally (side-by-side with the client application) while others are hosted remotely.  GitHub's MCP offerings are available to run either locally or remotely.
+
+```mermaid
+flowchart LR
+  subgraph "Local Runtime Environment"
+    subgraph "Client Application (e.g., IDE)"
+      CLIENTAPP[Application Runtime]
+      CX["MCP Client (FileSystem)"]
+      CY["MCP Client (GitHub)"]
+      CZ["MCP Client (Other)"]
+    end
+
+    LOCALMCP[File System MCP Server]
+  end
+
+  subgraph "Internet"
+    GITHUBMCP[GitHub Remote MCP Server]
+    OTHERMCP[Other Remote MCP Server]
+  end
+
+  CLIENTAPP --> CX
+  CLIENTAPP --> CY
+  CLIENTAPP --> CZ
+
+  CX <-->|"stdio"| LOCALMCP
+  CY <-->|"OAuth 2.0 + HTTP/SSE"| GITHUBMCP
+  CZ <-->|"OAuth 2.0 + HTTP/SSE"| OTHERMCP
+```
+
+### Runtime Environment
+
+- **Application**: The user-facing application you are building. It instantiates one or more MCP clients and orchestrates tool calls.
+- **MCP Client**: A component within your client application that maintains a 1:1 connection with a single MCP server.
+- **MCP Server**: A service that provides access to a specific set of tools.
+  - **Local MCP Server**: An MCP Server running locally, side-by-side with the Application.
+  - **Remote MCP Server**: An MCP Server running remotely, accessed via the internet.  Most Remote MCP Servers require authentication via OAuth.
+
+For more detail, see the [official MCP specification](https://modelcontextprotocol.io/specification/draft).
+
+> [!NOTE]
+> GitHub offers both a Local MCP Server and a Remote MCP Server.
+
+---
+
+## Connecting to the Remote GitHub MCP Server
+
+### Authentication and Authorization
+
+GitHub MCP Servers require a valid access token in the `Authorization` header.  This is true for both the Local GitHub MCP Server and the Remote GitHub MCP Server.
+
+For the Remote GitHub MCP Server, the recommended way to obtain a valid access token is to ensure your client application supports [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-13).  It should be noted, however, that you may also supply any valid access token. For example, you may supply a pre-generated Personal Access Token (PAT).
+
+
+> [!IMPORTANT]
+> The Remote GitHub MCP Server itself does not provide Authentication services.
+> Your client application must obtain valid GitHub access tokens through one of the supported methods.
+
+The expected flow for obtaining a valid access token via OAuth is depicted in the [MCP Specification](https://modelcontextprotocol.io/specification/draft/basic/authorization#authorization-flow-steps).  For convenience, we've embedded a copy of the authorization flow below.  Please study it carefully as the remainder of this document is written with this flow in mind.
+
+```mermaid
+sequenceDiagram
+    participant B as User-Agent (Browser)
+    participant C as Client
+    participant M as MCP Server (Resource Server)
+    participant A as Authorization Server
+
+    C->>M: MCP request without token
+    M->>C: HTTP 401 Unauthorized with WWW-Authenticate header
+    Note over C: Extract resource_metadata URL from WWW-Authenticate
+
+    C->>M: Request Protected Resource Metadata
+    M->>C: Return metadata
+
+    Note over C: Parse metadata and extract authorization server(s)<br/>Client determines AS to use
+
+    C->>A: GET /.well-known/oauth-authorization-server
+    A->>C: Authorization server metadata response
+
+    alt Dynamic client registration
+        C->>A: POST /register
+        A->>C: Client Credentials
+    end
+
+    Note over C: Generate PKCE parameters
+    C->>B: Open browser with authorization URL + code_challenge
+    B->>A: Authorization request
+    Note over A: User authorizes
+    A->>B: Redirect to callback with authorization code
+    B->>C: Authorization code callback
+    C->>A: Token request + code_verifier
+    A->>C: Access token (+ refresh token)
+    C->>M: MCP request with access token
+    M-->>C: MCP response
+    Note over C,M: MCP communication continues with valid token
+```
+
+> [!NOTE]
+> Dynamic Client Registration is NOT supported by Remote GitHub MCP Server at this time.
+
+
+#### OAuth Support on GitHub
+
+GitHub offers two solutions for obtaining access tokens via OAuth:  [**GitHub Apps**](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps#about-github-apps) and [**OAuth Apps**](https://docs.github.com/en/apps/oauth-apps).  These solutions are typically created, administered, and maintained by GitHub Organization administrators.  Collaborate with a GitHub Organization administrator to configure either a **GitHub App** or an **OAuth App** to allow your client application to utilize GitHub OAuth support.  Furthermore, be aware that it may be necessary for users of your client application to register your **GitHub App** or **OAuth App** within their own GitHub Organization in order to generate authorization tokens capable of accessing Organization's GitHub resources.
+
+> [!TIP]
+> Before proceeding, check whether your organization already supports one of these solutions.  Administrators of your GitHub Organization can help you determine what **GitHub Apps** or **OAuth Apps** are already registered.  If there's an existing **GitHub App** or **OAuth App** that fits your use case, consider reusing it for Remote MCP Authorization.  That said, be sure to take heed of the following warning.
+
+> [!WARNING]
+> Both **GitHub Apps** and **OAuth Apps** require the client application to pass a "client secret" in order to initiate the OAuth flow.  If your client application is designed to run in an uncontrolled environment (i.e. customer-provided hardware), end users will be able to discover your "client secret" and potentially exploit it for other purposes.  In such cases, our recommendation is to register a new **GitHub App** (or **OAuth App**) exclusively dedicated to servicing OAuth requests from your client application.
+
+#### Create an OAuth-enabled App Using the GitHub UI
+
+Detailed instructions for creating a **GitHub App** can be found at ["Creating GitHub Apps"](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps#building-a-github-app). (RECOMMENDED)<br/>
+Detailed instructions for creating an **OAuth App** can be found ["Creating an OAuth App"](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app).
+
+For guidance on which type of app to choose, see ["Differences Between GitHub Apps and OAuth Apps"](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps).
+
+#### Things to Consider:
+- Tokens provided by **GitHub Apps** are generally more secure because they:
+  - include an expiration
+  - include support for fine-grained permissions
+- **GitHub Apps** must be installed on a GitHub Organization before they can be used.<br/>In general, installation must be approved by someone in the Organization with administrator permissions.  For more details, see [this explanation](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps#who-can-install-github-apps-and-authorize-oauth-apps).<br/>By contrast, **OAuth Apps** don't require installation and, typically, can be used immediately.
+- Members of an Organization may use the GitHub UI to [request that a GitHub App be installed](https://docs.github.com/en/apps/using-github-apps/requesting-a-github-app-from-your-organization-owner) organization-wide.
+- While not strictly necessary, if you expect that a wide range of users will use your MCP Server, consider publishing its corresponding **GitHub App** or **OAuth App** on the [GitHub App Marketplace](https://github.com/marketplace?type=apps) to ensure that it's discoverable by your audience.
+
+
+#### Initiating the OAuth Flow from your Client Application
+
+For **GitHub Apps**, details on initiating the OAuth flow from a client application are described in detail [here](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app#using-the-web-application-flow-to-generate-a-user-access-token).
+
+For **OAuth Apps**, details on initiating the OAuth flow from a client application are described in detail [here](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#web-application-flow).
+
+> [!IMPORTANT]
+> For endpoint discovery, be sure to honor the [`WWW-Authenticate` information provided](https://modelcontextprotocol.io/specification/draft/basic/authorization#authorization-server-location) by the Remote GitHub MCP Server rather than relying on hard-coded endpoints like `https://github.com/login/oauth/authorize`.
+
+
+### Handling Organization Access Restrictions
+Organizations may block **GitHub Apps** and **OAuth Apps** until explicitly approved. Within your client application code, you can provide actionable next steps for a smooth user experience in the event that OAuth-related calls fail due to your **GitHub App** or **OAuth App** being unavailable (i.e. not registered within the user's organization).
+
+1. Detect the specific error.
+2. Notify the user clearly.
+3. Depending on their GitHub organization privileges:
+    - Org Members: Prompt them to request approval from a GitHub organization admin, within the organization where access has not been approved.
+    - Org Admins: Link them to the corresponding GitHub organization’s App approval settings at `https://github.com/organizations/[ORG_NAME]/settings/oauth_application_policy`
+
+
+## Essential Security Considerations
+- **Token Storage**: Use secure platform APIs (e.g. keytar for Node.js).
+- **Input Validation**: Sanitize all tool arguments.
+- **HTTPS Only**: Never send requests over plaintext HTTP. Always use HTTPS in production.
+- **PKCE:** We strongly recommend implementing [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) for all OAuth flows to prevent code interception, to prepare for upcoming PKCE support.
+
+## Additional Resources
+- [MCP Official Spec](https://modelcontextprotocol.io/specification/draft)
+- [MCP SDKs](https://modelcontextprotocol.io/sdk/java/mcp-overview)
+- [GitHub Docs on Creating GitHub Apps](https://docs.github.com/en/apps/creating-github-apps)
+- [GitHub Docs on Using GitHub Apps](https://docs.github.com/en/apps/using-github-apps/about-using-github-apps)
+- [GitHub Docs on Creating OAuth Apps](https://docs.github.com/en/apps/oauth-apps)
+- GitHub Docs on Installing OAuth Apps into a [Personal Account](https://docs.github.com/en/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-personal-account) and [Organization](https://docs.github.com/en/apps/oauth-apps/using-oauth-apps/installing-an-oauth-app-in-your-organization)
+- [Managing OAuth Apps at the Organization Level](https://docs.github.com/en/organizations/managing-oauth-access-to-your-organizations-data)
+- [Managing Programmatic Access at the GitHub Organization Level](https://docs.github.com/en/organizations/managing-programmatic-access-to-your-organization)
+- [Building Copilot Extensions](https://docs.github.com/en/copilot/building-copilot-extensions)
+- [Managing App/Extension Visibility](https://docs.github.com/en/copilot/building-copilot-extensions/managing-the-availability-of-your-copilot-extension) (including GitHub Marketplace information)
+- [Example Implementation in VS Code Repository](https://github.com/microsoft/vscode/blob/main/src/vs/workbench/api/common/extHostMcp.ts#L313)