diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 1ac04f672..9b6c6ea89 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -15,6 +15,10 @@ A clear and concise description of what the feature or problem is. How will it benefit GitHub MCP Server and its users? +### Example prompts or workflows (for tools/toolsets only) + +If it's a new tool or improvement, share 3–5 example prompts or workflows it would enable. Just enough detail to show the value. Clear, valuable use cases are more likely to get approved. + ### Additional context -Add any other context like screenshots or mockups are helpful, if applicable. \ No newline at end of file +Add any other context like screenshots or mockups are helpful, if applicable. diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml index 35ffc47db..cd2d923cb 100644 --- a/.github/workflows/docker-publish.yml +++ b/.github/workflows/docker-publish.yml @@ -9,11 +9,11 @@ on: schedule: - cron: "27 0 * * *" push: - branches: ["main"] + branches: ["main", "next"] # Publish semver tags as releases. tags: ["v*.*.*"] pull_request: - branches: ["main"] + branches: ["main", "next"] env: # Use docker.io for Docker Hub if empty diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 000000000..c28c528b2 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,47 @@ +name: Documentation Check + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +permissions: + contents: read + +jobs: + docs-check: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version-file: 'go.mod' + + - name: Build docs generator + run: go build -o github-mcp-server ./cmd/github-mcp-server + + - name: Generate documentation + run: ./github-mcp-server generate-docs + + - name: Check for documentation changes + run: | + if ! git diff --exit-code README.md; then + echo "❌ Documentation is out of date!" + echo "" + echo "The generated documentation differs from what's committed." + echo "Please run the following command to update the documentation:" + echo "" + echo " go run ./cmd/github-mcp-server generate-docs" + echo "" + echo "Then commit the changes." + echo "" + echo "Changes detected:" + git diff README.md + exit 1 + else + echo "✅ Documentation is up to date!" + fi diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml index cd67b9653..e3ef25022 100644 --- a/.github/workflows/go.yml +++ b/.github/workflows/go.yml @@ -1,4 +1,4 @@ -name: Unit Tests +name: Build and Test Go Project on: [push, pull_request] permissions: @@ -26,7 +26,7 @@ jobs: run: go mod download - name: Run unit tests - run: go test -race ./... + run: script/test - name: Build run: go build -v ./cmd/github-mcp-server diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml deleted file mode 100644 index 9fa416abd..000000000 --- a/.github/workflows/lint.yaml +++ /dev/null @@ -1,45 +0,0 @@ -name: Lint -on: - push: - pull_request: - -permissions: - contents: read - -jobs: - lint: - runs-on: ubuntu-latest - - steps: - - name: Check out code - uses: actions/checkout@v4 - - - name: Set up Go - uses: actions/setup-go@v5 - with: - go-version-file: 'go.mod' - - - name: Verify dependencies - run: | - go mod verify - go mod download - - - name: Run checks - run: | - STATUS=0 - assert-nothing-changed() { - local diff - "$@" >/dev/null || return 1 - if ! diff="$(git diff -U1 --color --exit-code)"; then - printf '\e[31mError: running `\e[1m%s\e[22m` results in modifications that you must check into version control:\e[0m\n%s\n\n' "$*" "$diff" >&2 - git checkout -- . - STATUS=1 - fi - } - assert-nothing-changed go mod tidy - exit $STATUS - - - name: golangci-lint - uses: golangci/golangci-lint-action@4afd733a84b1f43292c63897423277bb7f4313a9 - with: - version: v2.1.6 diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml new file mode 100644 index 000000000..b40193e72 --- /dev/null +++ b/.github/workflows/lint.yml @@ -0,0 +1,23 @@ +name: golangci-lint +on: + push: + branches: + - main + pull_request: + +permissions: + contents: read + +jobs: + golangci: + name: lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-go@v5 + with: + go-version: stable + - name: golangci-lint + uses: golangci/golangci-lint-action@v8 + with: + version: v2.1 diff --git a/.gitignore b/.gitignore index 12649366d..0ad709cbf 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,7 @@ __debug_bin* # Go vendor +bin/ + +# macOS +.DS_Store \ No newline at end of file diff --git a/.golangci.yml b/.golangci.yml index 61302f6f7..f86326cfa 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -1,47 +1,37 @@ -# https://golangci-lint.run/usage/configuration version: "2" - run: - timeout: 5m - tests: true concurrency: 4 - + tests: true linters: enable: - - govet - - errcheck - - staticcheck - - revive - - ineffassign - - unused - - misspell - - nakedret - bodyclose - gocritic - - makezero - gosec + - makezero + - misspell + - nakedret + - revive + exclusions: + generated: lax + presets: + - comments + - common-false-positives + - legacy + - std-error-handling + paths: + - third_party$ + - builtin$ + - examples$ settings: staticcheck: checks: - - all - - '-QF1008' # Allow embedded structs to be referenced by field - - '-ST1000' # Do not require package comments - revive: - rules: - - name: exported - disabled: true - - name: exported - disabled: true - - name: package-comments - disabled: true - + - "all" + - -QF1008 + - -ST1000 formatters: - enable: - - gofmt - - goimports - -output: - formats: - text: - print-linter-name: true - print-issued-lines: true + exclusions: + generated: lax + paths: + - third_party$ + - builtin$ + - examples$ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 11d63a389..2307f6a28 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,22 +10,36 @@ Contributions to this project are [released](https://help.github.com/articles/gi 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. +## What we're looking for + +We can't guarantee that every tool, feature, or pull request will be approved or merged. Our focus is on supporting high-quality, high-impact capabilities that advance agentic workflows and deliver clear value to developers. + +To increase the chances your request is accepted: +* Include real use cases or examples that demonstrate practical value +* If your request stalls, you can open a Discussion post and link to your issue or PR +* We actively revisit requests that gain strong community engagement (👍s, comments, or evidence of real-world use) + +Thanks for contributing and for helping us build toolsets that are truly valuable! + ## Prerequisites for running and testing code These are one time installations required to be able to test your changes locally as part of the pull request (PR) submission process. -1. install Go [through download](https://go.dev/doc/install) | [through Homebrew](https://formulae.brew.sh/formula/go) -1. [install golangci-lint v2](https://golangci-lint.run/welcome/install/#local-installation) +1. Install Go [through download](https://go.dev/doc/install) | [through Homebrew](https://formulae.brew.sh/formula/go) +2. [Install golangci-lint v2](https://golangci-lint.run/welcome/install/#local-installation) ## Submitting a pull request 1. [Fork][fork] and clone the repository -1. Make sure the tests pass on your machine: `go test -v ./...` -1. Make sure linter passes on your machine: `golangci-lint run` -1. Create a new branch: `git checkout -b my-branch-name` -1. Make your change, add tests, and make sure the tests and linter still pass -1. Push to your fork and [submit a pull request][pr] -1. Pat yourself on the back and wait for your pull request to be reviewed and merged. +2. Make sure the tests pass on your machine: `go test -v ./...` +3. Make sure linter passes on your machine: `golangci-lint run` +4. Create a new branch: `git checkout -b my-branch-name` +5. Add your changes and tests, and make sure the Action workflows still pass + - Run linter: `script/lint` + - Update snapshots and run tests: `UPDATE_TOOLSNAPS=true go test ./...` + - Update readme documentation: `script/generate-docs` +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. Here are a few things you can do that will increase the likelihood of your pull request being accepted: diff --git a/Dockerfile b/Dockerfile index 333ac0106..a26f19a81 100644 --- a/Dockerfile +++ b/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 @@ -22,5 +22,7 @@ FROM gcr.io/distroless/base-debian12 WORKDIR /server # Copy the binary from the build stage COPY --from=build /bin/github-mcp-server . -# Command to run the server -CMD ["./github-mcp-server", "stdio"] +# Set the entrypoint to the server binary +ENTRYPOINT ["/server/github-mcp-server"] +# Default arguments for ENTRYPOINT +CMD ["stdio"] diff --git a/README.md b/README.md index 7b9e20fc3..ae4d3627e 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,170 @@ # 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 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. -[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&inputs=%5B%7B%22id%22%3A%22github_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22GitHub%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agithub_token%7D%22%7D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&inputs=%5B%7B%22id%22%3A%22github_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22GitHub%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agithub_token%7D%22%7D%7D&quality=insiders) +### Use Cases + +- Repository Management: Browse and query 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. + +--- + +## Remote GitHub MCP Server + +[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D&quality=insiders) + +The remote GitHub MCP Server is hosted by GitHub and provides the easiest method for getting up and running. If your MCP host does not support remote MCP servers, don't worry! You can use the [local version of the GitHub MCP Server](https://github.com/github/github-mcp-server?tab=readme-ov-file#local-github-mcp-server) instead. + +### Prerequisites + +1. A compatible MCP host with remote server support (VS Code 1.101+, Claude Desktop, Cursor, Windsurf, etc.) +2. Any applicable [policies enabled](https://github.com/github/github-mcp-server/blob/main/docs/policies-and-governance.md) + +### Install in VS Code + +For quick installation, use one of the one-click install buttons above. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start. Make sure you're using [VS Code 1.101](https://code.visualstudio.com/updates/v1_101) or [later](https://code.visualstudio.com/updates) for remote MCP and OAuth support. + +Alternatively, to manually configure VS Code, choose the appropriate JSON block from the examples below and add it to your host configuration: + + + + + + + + +
Using OAuthUsing a GitHub PAT
VS Code (version 1.101 or greater)
+ +```json +{ + "servers": { + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/" + } + } +} +``` + + + +```json +{ + "servers": { + "github": { + "type": "http", + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "Authorization": "Bearer ${input:github_mcp_pat}" + } + } + }, + "inputs": [ + { + "type": "promptString", + "id": "github_mcp_pat", + "description": "GitHub Personal Access Token", + "password": true + } + ] +} +``` + +
+ +### 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 Web, Claude Desktop and Claude Code CLI +- **[Cursor](/docs/installation-guides/install-cursor.md)** - Installation guide for Cursor IDE +- **[Windsurf](/docs/installation-guides/install-windsurf.md)** - Installation guide for Windsurf IDE -## Use Cases +> **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. -- Automating GitHub workflows and processes. -- Extracting and analyzing data from GitHub repositories. -- Building AI powered tools and applications that interact with GitHub's ecosystem. +> ⚠️ **Public Preview Status:** The **remote** GitHub MCP Server is currently in Public Preview. During preview, access may be gated depending on authentication type and surface: +> - OAuth: Subject to GitHub Copilot Editor Preview Policy until GA +> - PAT: Controlled via your organization's PAT policies +> - MCP Servers in Copilot policy: Enables/disables access to all MCP servers in VS Code, with other Copilot editors migrating to this policy in the coming months. -## Prerequisites +### Configuration +See [Remote Server Documentation](/docs/remote-server.md) on how to pass additional configuration settings to the remote GitHub MCP Server. + +--- + +## Local GitHub MCP Server + +[![Install with Docker in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&inputs=%5B%7B%22id%22%3A%22github_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22GitHub%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agithub_token%7D%22%7D%7D) [![Install with Docker in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&inputs=%5B%7B%22id%22%3A%22github_token%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22GitHub%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22-e%22%2C%22GITHUB_PERSONAL_ACCESS_TOKEN%22%2C%22ghcr.io%2Fgithub%2Fgithub-mcp-server%22%5D%2C%22env%22%3A%7B%22GITHUB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agithub_token%7D%22%7D%7D&quality=insiders) + +### Prerequisites 1. To run the server in a container, you will need to have [Docker](https://www.docker.com/) installed. 2. Once Docker is installed, you will also need to ensure Docker is running. The image is public; if you get errors on pull, you may have an expired token and need to `docker logout ghcr.io`. 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)). +
Handling PATs Securely + +### Environment Variables (Recommended) +To keep your GitHub PAT secure and reusable across different MCP hosts: + +1. **Store your PAT in environment variables** + ```bash + export GITHUB_PAT=your_token_here + ``` + Or create a `.env` file: + ```env + GITHUB_PAT=your_token_here + ``` + +2. **Protect your `.env` file** + ```bash + # Add to .gitignore to prevent accidental commits + echo ".env" >> .gitignore + ``` + +3. **Reference the token in configurations** + ```bash + # CLI usage + claude mcp update github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT + + # In config files (where supported) + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PAT" + } + ``` + +> **Note**: Environment variable support varies by host app and IDE. Some applications (like Windsurf) require hardcoded tokens in config files. + +### Token Security Best Practices + +- **Minimum scopes**: Only grant necessary permissions + - `repo` - Repository operations + - `read:packages` - Docker image access +- **Separate tokens**: Use different PATs for different projects/environments +- **Regular rotation**: Update tokens periodically +- **Never commit**: Keep tokens out of version control +- **File permissions**: Restrict access to config files containing tokens + ```bash + chmod 600 ~/.your-app/config.json + ``` + +
+ ## Installation -### Usage with VS Code +### Install in GitHub Copilot on VS Code + +For quick installation, use one of the one-click install buttons above. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start. -For quick installation, use one of the one-click install buttons at the top of this README. Once you complete that flow, toggle Agent mode (located by the Copilot Chat text input) and the server will start. +More about using MCP server tools in VS Code's [agent mode documentation](https://code.visualstudio.com/docs/copilot/chat/mcp-servers). -For manual installation, add the following JSON block to your User Settings (JSON) file in VS Code. You can do this by pressing `Ctrl + Shift + P` and typing `Preferences: Open User Settings (JSON)`. +Install in GitHub Copilot on other IDEs (JetBrains, Visual Studio, Eclipse, etc.) + +Add the following JSON block to your IDE's MCP settings. ```json { @@ -58,8 +197,11 @@ For manual installation, add the following JSON block to your User Settings (JSO } ``` -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. +
+Example JSON block without the MCP key included +
```json { @@ -88,33 +230,22 @@ 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). +
-### Usage with Claude Desktop +### Install in Other MCP Hosts -```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": "" - } - } - } -} -``` +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 +- **[Windsurf](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/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 @@ -141,531 +272,745 @@ If you don't have Docker, you can use `go build` to build the binary in the The GitHub MCP Server supports enabling or disabling specific groups of functionalities via the `--toolsets` flag. This allows you to control which GitHub API capabilities are available to your AI tools. Enabling only the toolsets that you need can help the LLM with tool choice and reduce the context size. +_Toolsets are not limited to Tools. Relevant MCP Resources and Prompts are also included where applicable._ + ### Available Toolsets The following sets of tools are available (all are on by default): + | Toolset | Description | | ----------------------- | ------------------------------------------------------------- | -| `repos` | Repository-related tools (file operations, branches, commits) | -| `issues` | Issue-related tools (create, read, update, comment) | -| `users` | Anything relating to GitHub Users | -| `pull_requests` | Pull request operations (create, merge, review) | -| `code_security` | Code scanning alerts and security features | -| `experiments` | Experimental features (not considered stable) | +| `context` | **Strongly recommended**: Tools that provide context about the current user and GitHub context you are operating in | +| `actions` | GitHub Actions workflows and CI/CD operations | +| `code_security` | Code security related tools, such as GitHub Code Scanning | +| `dependabot` | Dependabot tools | +| `discussions` | GitHub Discussions related tools | +| `experiments` | Experimental features that are not considered stable yet | +| `issues` | GitHub Issues related tools | +| `notifications` | GitHub Notifications related tools | +| `orgs` | GitHub Organization related tools | +| `pull_requests` | GitHub Pull Request related tools | +| `repos` | GitHub Repository related tools | +| `secret_protection` | Secret protection related tools, such as GitHub Secret Scanning | +| `users` | GitHub User related tools | + -#### Specifying Toolsets +## Tools -To specify toolsets you want available to the LLM, you can pass an allow-list in two ways: -1. **Using Command Line Argument**: + +
- ```bash - github-mcp-server --toolsets repos,issues,pull_requests,code_security - ``` +Actions -2. **Using Environment Variable**: - ```bash - GITHUB_TOOLSETS="repos,issues,pull_requests,code_security" ./github-mcp-server - ``` - -The environment variable `GITHUB_TOOLSETS` takes precedence over the command line argument if both are provided. - -### Using Toolsets With Docker +- **cancel_workflow_run** - Cancel workflow run + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) + - `run_id`: The unique identifier of the workflow run (number, required) -When using Docker, you can pass the toolsets as environment variables: +- **delete_workflow_run_logs** - Delete workflow logs + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) + - `run_id`: The unique identifier of the workflow run (number, required) -```bash -docker run -i --rm \ - -e GITHUB_PERSONAL_ACCESS_TOKEN= \ - -e GITHUB_TOOLSETS="repos,issues,pull_requests,code_security,experiments" \ - ghcr.io/github/github-mcp-server -``` +- **download_workflow_run_artifact** - Download workflow artifact + - `artifact_id`: The unique identifier of the artifact (number, required) + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) -### The "all" Toolset +- **get_job_logs** - Get job logs + - `failed_only`: When true, gets logs for all failed jobs in run_id (boolean, optional) + - `job_id`: The unique identifier of the workflow job (required for single job logs) (number, optional) + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) + - `return_content`: Returns actual log content instead of URLs (boolean, optional) + - `run_id`: Workflow run ID (required when using failed_only) (number, optional) + - `tail_lines`: Number of lines to return from the end of the log (number, optional) -The special toolset `all` can be provided to enable all available toolsets regardless of any other configuration: +- **get_workflow_run** - Get workflow run + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) + - `run_id`: The unique identifier of the workflow run (number, required) -```bash -./github-mcp-server --toolsets all -``` +- **get_workflow_run_logs** - Get workflow run logs + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) + - `run_id`: The unique identifier of the workflow run (number, required) -Or using the environment variable: +- **get_workflow_run_usage** - Get workflow usage + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) + - `run_id`: The unique identifier of the workflow run (number, required) -```bash -GITHUB_TOOLSETS="all" ./github-mcp-server -``` +- **list_workflow_jobs** - List workflow jobs + - `filter`: Filters jobs by their completed_at timestamp (string, optional) + - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `repo`: Repository name (string, required) + - `run_id`: The unique identifier of the workflow run (number, required) -## Dynamic Tool Discovery +- **list_workflow_run_artifacts** - List workflow artifacts + - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `repo`: Repository name (string, required) + - `run_id`: The unique identifier of the workflow run (number, required) -**Note**: This feature is currently in beta and may not be available in all environments. Please test it out and let us know if you encounter any issues. +- **list_workflow_runs** - List workflow runs + - `actor`: Returns someone's workflow runs. Use the login for the user who created the workflow run. (string, optional) + - `branch`: Returns workflow runs associated with a branch. Use the name of the branch. (string, optional) + - `event`: Returns workflow runs for a specific event type (string, optional) + - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `repo`: Repository name (string, required) + - `status`: Returns workflow runs with the check run status (string, optional) + - `workflow_id`: The workflow ID or workflow file name (string, required) -Instead of starting with all tools enabled, you can turn on dynamic toolset discovery. Dynamic toolsets allow the MCP host to list and enable toolsets in response to a user prompt. This should help to avoid situations where the model gets confused by the sheer number of tools available. +- **list_workflows** - List workflows + - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `repo`: Repository name (string, required) -### Using Dynamic Tool Discovery +- **rerun_failed_jobs** - Rerun failed jobs + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) + - `run_id`: The unique identifier of the workflow run (number, required) -When using the binary, you can pass the `--dynamic-toolsets` flag. +- **rerun_workflow_run** - Rerun workflow run + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) + - `run_id`: The unique identifier of the workflow run (number, required) -```bash -./github-mcp-server --dynamic-toolsets -``` +- **run_workflow** - Run workflow + - `inputs`: Inputs the workflow accepts (object, optional) + - `owner`: Repository owner (string, required) + - `ref`: The git reference for the workflow. The reference can be a branch or tag name. (string, required) + - `repo`: Repository name (string, required) + - `workflow_id`: The workflow ID (numeric) or workflow file name (e.g., main.yml, ci.yaml) (string, required) -When using Docker, you can pass the toolsets as environment variables: +
-```bash -docker run -i --rm \ - -e GITHUB_PERSONAL_ACCESS_TOKEN= \ - -e GITHUB_DYNAMIC_TOOLSETS=1 \ - ghcr.io/github/github-mcp-server -``` +
-## GitHub Enterprise Server +Code Security -The flag `--gh-host` and the environment variable `GITHUB_HOST` can be used to set -the GitHub Enterprise Server hostname. -Prefix the hostname with the `https://` URI scheme, as it otherwise defaults to `http://` which GitHub Enterprise Server does not support. +- **get_code_scanning_alert** - Get code scanning alert + - `alertNumber`: The number of the alert. (number, required) + - `owner`: The owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) -``` json -"github": { - "command": "docker", - "args": [ - "run", - "-i", - "--rm", - "-e", - "GITHUB_PERSONAL_ACCESS_TOKEN", - "-e", - "GITHUB_HOST", - "ghcr.io/github/github-mcp-server" - ], - "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}", - "GITHUB_HOST": "https://" - } -} -``` +- **list_code_scanning_alerts** - List code scanning alerts + - `owner`: The owner of the repository. (string, required) + - `ref`: The Git reference for the results you want to list. (string, optional) + - `repo`: The name of the repository. (string, required) + - `severity`: Filter code scanning alerts by severity (string, optional) + - `state`: Filter code scanning alerts by state. Defaults to open (string, optional) + - `tool_name`: The name of the tool used for code scanning. (string, optional) -## i18n / Overriding Descriptions +
-The descriptions of the tools can be overridden by creating a -`github-mcp-server-config.json` file in the same directory as the binary. +
-The file should contain a JSON object with the tool names as keys and the new -descriptions as values. For example: +Context -```json -{ - "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description", - "TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository" -} -``` +- **get_me** - Get my user profile + - No parameters required -You can create an export of the current translations by running the binary with -the `--export-translations` flag. +
-This flag will preserve any translations/overrides you have made, while adding -any new translations that have been added to the binary since the last time you -exported. +
-```sh -./github-mcp-server --export-translations -cat github-mcp-server-config.json -``` +Dependabot -You can also use ENV vars to override the descriptions. The environment -variable names are the same as the keys in the JSON file, prefixed with -`GITHUB_MCP_` and all uppercase. +- **get_dependabot_alert** - Get dependabot alert + - `alertNumber`: The number of the alert. (number, required) + - `owner`: The owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) -For example, to override the `TOOL_ADD_ISSUE_COMMENT_DESCRIPTION` tool, you can -set the following environment variable: +- **list_dependabot_alerts** - List dependabot alerts + - `owner`: The owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) + - `severity`: Filter dependabot alerts by severity (string, optional) + - `state`: Filter dependabot alerts by state. Defaults to open (string, optional) -```sh -export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description" -``` +
-## Tools +
-### Users +Discussions -- **get_me** - Get details of the authenticated user - - No parameters required +- **get_discussion** - Get discussion + - `discussionNumber`: Discussion Number (number, required) + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) -### Issues +- **get_discussion_comments** - Get discussion comments + - `discussionNumber`: Discussion Number (number, required) + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) -- **get_issue** - Gets the contents of an issue within a repository +- **list_discussion_categories** - List discussion categories + - `after`: Cursor for pagination, use the 'after' field from the previous response (string, optional) + - `before`: Cursor for pagination, use the 'before' field from the previous response (string, optional) + - `first`: Number of categories to return per page (min 1, max 100) (number, optional) + - `last`: Number of categories to return from the end (min 1, max 100) (number, optional) + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) +- **list_discussions** - List discussions + - `category`: Optional filter by discussion category ID. If provided, only discussions with this category are listed. (string, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `issue_number`: Issue number (number, required) -- **get_issue_comments** - Get comments for a GitHub issue +
+ +
+Issues + +- **add_issue_comment** - Add comment to issue + - `body`: Comment content (string, required) + - `issue_number`: Issue number to comment on (number, required) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `issue_number`: Issue number (number, required) - -- **create_issue** - Create a new issue in a GitHub repository +- **assign_copilot_to_issue** - Assign Copilot to issue + - `issueNumber`: Issue number (number, required) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `title`: Issue title (string, required) - - `body`: Issue body content (string, optional) + +- **create_issue** - Open new issue - `assignees`: Usernames to assign to this issue (string[], optional) + - `body`: Issue body content (string, optional) - `labels`: Labels to apply to this issue (string[], optional) - -- **add_issue_comment** - Add a comment to an issue - + - `milestone`: Milestone number (number, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `issue_number`: Issue number (number, required) - - `body`: Comment text (string, required) + - `title`: Issue title (string, required) -- **list_issues** - List and filter repository issues +- **get_issue** - Get issue details + - `issue_number`: The number of the issue (number, required) + - `owner`: The owner of the repository (string, required) + - `repo`: The name of the repository (string, required) +- **get_issue_comments** - Get issue comments + - `issue_number`: Issue number (number, required) - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `state`: Filter by state ('open', 'closed', 'all') (string, optional) - - `labels`: Labels to filter by (string[], optional) - - `sort`: Sort by ('created', 'updated', 'comments') (string, optional) - - `direction`: Sort direction ('asc', 'desc') (string, optional) - - `since`: Filter by date (ISO 8601 timestamp) (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **update_issue** - Update an existing issue in a GitHub repository +- **list_issues** - List issues + - `direction`: Sort direction (string, optional) + - `labels`: Filter by labels (string[], optional) - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `issue_number`: Issue number to update (number, required) - - `title`: New title (string, optional) + - `since`: Filter by date (ISO 8601 timestamp) (string, optional) + - `sort`: Sort order (string, optional) + - `state`: Filter by state (string, optional) + +- **search_issues** - Search issues + - `order`: Sort order (string, optional) + - `owner`: Optional repository owner. If provided with repo, only notifications for this repository are listed. (string, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query using GitHub issues search syntax (string, required) + - `repo`: Optional repository name. If provided with owner, only notifications for this repository are listed. (string, optional) + - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional) + +- **update_issue** - Edit issue + - `assignees`: New assignees (string[], optional) - `body`: New description (string, optional) - - `state`: New state ('open' or 'closed') (string, optional) + - `issue_number`: Issue number to update (number, required) - `labels`: New labels (string[], optional) - - `assignees`: New assignees (string[], optional) - `milestone`: New milestone number (number, optional) + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) + - `state`: New state (string, optional) + - `title`: New title (string, optional) -- **search_issues** - Search for issues and pull requests - - `query`: Search query (string, required) - - `sort`: Sort field (string, optional) +
+ +
+ +Notifications + +- **dismiss_notification** - Dismiss notification + - `state`: The new state of the notification (read/done) (string, optional) + - `threadID`: The ID of the notification thread (string, required) + +- **get_notification_details** - Get notification details + - `notificationID`: The ID of the notification (string, required) + +- **list_notifications** - List notifications + - `before`: Only show notifications updated before the given time (ISO 8601 format) (string, optional) + - `filter`: Filter notifications to, use default unless specified. Read notifications are ones that have already been acknowledged by the user. Participating notifications are those that the user is directly involved in, such as issues or pull requests they have commented on or created. (string, optional) + - `owner`: Optional repository owner. If provided with repo, only notifications for this repository are listed. (string, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `repo`: Optional repository name. If provided with owner, only notifications for this repository are listed. (string, optional) + - `since`: Only show notifications updated after the given time (ISO 8601 format) (string, optional) + +- **manage_notification_subscription** - Manage notification subscription + - `action`: Action to perform: ignore, watch, or delete the notification subscription. (string, required) + - `notificationID`: The ID of the notification thread. (string, required) + +- **manage_repository_notification_subscription** - Manage repository notification subscription + - `action`: Action to perform: ignore, watch, or delete the repository notification subscription. (string, required) + - `owner`: The account owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) + +- **mark_all_notifications_read** - Mark all notifications as read + - `lastReadAt`: Describes the last point that notifications were checked (optional). Default: Now (string, optional) + - `owner`: Optional repository owner. If provided with repo, only notifications for this repository are marked as read. (string, optional) + - `repo`: Optional repository name. If provided with owner, only notifications for this repository are marked as read. (string, optional) + +
+ +
+ +Organizations + +- **search_orgs** - Search organizations - `order`: Sort order (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query using GitHub organizations search syntax scoped to type:org (string, required) + - `sort`: Sort field by category (string, optional) -### Pull Requests +
-- **get_pull_request** - Get details of a specific pull request +
+Pull Requests + +- **add_comment_to_pending_review** - Add review comment to the requester's latest pending pull request review + - `body`: The text of the review comment (string, required) + - `line`: The line of the blob in the pull request diff that the comment applies to. For multi-line comments, the last line of the range (number, optional) - `owner`: Repository owner (string, required) + - `path`: The relative path to the file that necessitates a comment (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) + - `side`: The side of the diff to comment on. LEFT indicates the previous state, RIGHT indicates the new state (string, optional) + - `startLine`: For multi-line comments, the first line of the range that the comment applies to (number, optional) + - `startSide`: For multi-line comments, the starting side of the diff that the comment applies to. LEFT indicates the previous state, RIGHT indicates the new state (string, optional) + - `subjectType`: The level at which the comment is targeted (string, required) + +- **create_and_submit_pull_request_review** - Create and submit a pull request review without comments + - `body`: Review comment text (string, required) + - `commitID`: SHA of commit to review (string, optional) + - `event`: Review action to perform (string, required) + - `owner`: Repository owner (string, required) - `pullNumber`: Pull request number (number, required) + - `repo`: Repository name (string, required) -- **list_pull_requests** - List and filter repository pull requests - +- **create_pending_pull_request_review** - Create pending pull request review + - `commitID`: SHA of commit to review (string, optional) - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `state`: PR state (string, optional) - - `sort`: Sort field (string, optional) - - `direction`: Sort direction (string, optional) - - `perPage`: Results per page (number, optional) - - `page`: Page number (number, optional) - -- **merge_pull_request** - Merge a pull request +- **create_pull_request** - Open new pull request + - `base`: Branch to merge into (string, required) + - `body`: PR description (string, optional) + - `draft`: Create as draft PR (boolean, optional) + - `head`: Branch containing changes (string, required) + - `maintainer_can_modify`: Allow maintainer edits (boolean, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - - `commit_title`: Title for the merge commit (string, optional) - - `commit_message`: Message for the merge commit (string, optional) - - `merge_method`: Merge method (string, optional) - -- **get_pull_request_files** - Get the list of files changed in a pull request + - `title`: PR title (string, required) +- **delete_pending_pull_request_review** - Delete the requester's latest pending pull request review - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - `pullNumber`: Pull request number (number, required) + - `repo`: Repository name (string, required) -- **get_pull_request_status** - Get the combined status of all status checks for a pull request - +- **get_pull_request** - Get pull request details - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - `pullNumber`: Pull request number (number, required) + - `repo`: Repository name (string, required) -- **update_pull_request_branch** - Update a pull request branch with the latest changes from the base branch - +- **get_pull_request_comments** - Get pull request comments - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - `pullNumber`: Pull request number (number, required) - - `expectedHeadSha`: The expected SHA of the pull request's HEAD ref (string, optional) - -- **get_pull_request_comments** - Get the review comments on a pull request + - `repo`: Repository name (string, required) +- **get_pull_request_diff** - Get pull request diff - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - `pullNumber`: Pull request number (number, required) + - `repo`: Repository name (string, required) -- **get_pull_request_reviews** - Get the reviews on a pull request - +- **get_pull_request_files** - Get pull request files - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `pullNumber`: Pull request number (number, required) + - `repo`: Repository name (string, required) -- **create_pull_request_review** - Create a review on a pull request review - +- **get_pull_request_reviews** - Get pull request reviews - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - `pullNumber`: Pull request number (number, required) - - `body`: Review comment text (string, optional) - - `event`: Review action ('APPROVE', 'REQUEST_CHANGES', 'COMMENT') (string, required) - - `commitId`: SHA of commit to review (string, optional) - - `comments`: Line-specific comments array of objects to place comments on pull request changes (array, optional) - - For inline comments: provide `path`, `position` (or `line`), and `body` - - For multi-line comments: provide `path`, `start_line`, `line`, optional `side`/`start_side`, and `body` - -- **create_pull_request** - Create a new pull request + - `repo`: Repository name (string, required) +- **get_pull_request_status** - Get pull request status checks - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `title`: PR title (string, required) - - `body`: PR description (string, optional) - - `head`: Branch containing changes (string, required) - - `base`: Branch to merge into (string, required) - - `draft`: Create as draft PR (boolean, optional) - - `maintainer_can_modify`: Allow maintainer edits (boolean, optional) -- **add_pull_request_review_comment** - Add a review comment to a pull request or reply to an existing comment +- **list_pull_requests** - List pull requests + - `base`: Filter by base branch (string, optional) + - `direction`: Sort direction (string, optional) + - `head`: Filter by head user/org and branch (string, optional) + - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `repo`: Repository name (string, required) + - `sort`: Sort by (string, optional) + - `state`: Filter by state (string, optional) +- **merge_pull_request** - Merge pull request + - `commit_message`: Extra detail for merge commit (string, optional) + - `commit_title`: Title for merge commit (string, optional) + - `merge_method`: Merge method (string, optional) - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `pull_number`: Pull request number (number, required) - - `body`: The text of the review comment (string, required) - - `commit_id`: The SHA of the commit to comment on (string, required unless using in_reply_to) - - `path`: The relative path to the file that necessitates a comment (string, required unless using in_reply_to) - - `line`: The line of the blob in the pull request diff that the comment applies to (number, optional) - - `side`: The side of the diff to comment on (LEFT or RIGHT) (string, optional) - - `start_line`: For multi-line comments, the first line of the range (number, optional) - - `start_side`: For multi-line comments, the starting side of the diff (LEFT or RIGHT) (string, optional) - - `subject_type`: The level at which the comment is targeted (line or file) (string, optional) - - `in_reply_to`: The ID of the review comment to reply to (number, optional). When specified, only body is required and other parameters are ignored. -- **update_pull_request** - Update an existing pull request in a GitHub repository +- **request_copilot_review** - Request Copilot review + - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) + - `repo`: Repository name (string, required) +- **search_pull_requests** - Search pull requests + - `order`: Sort order (string, optional) + - `owner`: Optional repository owner. If provided with repo, only notifications for this repository are listed. (string, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query using GitHub pull request search syntax (string, required) + - `repo`: Optional repository name. If provided with owner, only notifications for this repository are listed. (string, optional) + - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional) + +- **submit_pending_pull_request_review** - Submit the requester's latest pending pull request review + - `body`: The text of the review comment (string, optional) + - `event`: The event to perform (string, required) - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number to update (number, required) - - `title`: New title (string, optional) - - `body`: New description (string, optional) - - `state`: New state ('open' or 'closed') (string, optional) + +- **update_pull_request** - Edit pull request - `base`: New base branch name (string, optional) + - `body`: New description (string, optional) - `maintainer_can_modify`: Allow maintainer edits (boolean, optional) - -- **request_copilot_review** - Request a GitHub Copilot review for a pull request (experimental; subject to GitHub API support) - - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number to update (number, required) - `repo`: Repository name (string, required) + - `state`: New state (string, optional) + - `title`: New title (string, optional) + +- **update_pull_request_branch** - Update pull request branch + - `expectedHeadSha`: The expected SHA of the pull request's HEAD ref (string, optional) + - `owner`: Repository owner (string, required) - `pullNumber`: Pull request number (number, required) - - _Note_: Currently, this tool will only work for github.com + - `repo`: Repository name (string, required) + +
+ +
-### Repositories +Repositories -- **create_or_update_file** - Create or update a single file in a repository +- **create_branch** - Create branch + - `branch`: Name for new branch (string, required) + - `from_branch`: Source branch (defaults to repo default) (string, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `path`: File path (string, required) + +- **create_or_update_file** - Create or update file + - `branch`: Branch to create/update the file in (string, required) + - `content`: Content of the file (string, required) - `message`: Commit message (string, required) - - `content`: File content (string, required) - - `branch`: Branch name (string, optional) - - `sha`: File SHA if updating (string, optional) + - `owner`: Repository owner (username or organization) (string, required) + - `path`: Path where to create/update the file (string, required) + - `repo`: Repository name (string, required) + - `sha`: Required if updating an existing file. The blob SHA of the file being replaced. (string, optional) -- **list_branches** - List branches in a GitHub repository - - `owner`: Repository owner (string, required) +- **create_repository** - Create repository + - `autoInit`: Initialize with README (boolean, optional) + - `description`: Repository description (string, optional) + - `name`: Repository name (string, required) + - `private`: Whether repo should be private (boolean, optional) + +- **delete_file** - Delete file + - `branch`: Branch to delete the file from (string, required) + - `message`: Commit message (string, required) + - `owner`: Repository owner (username or organization) (string, required) + - `path`: Path to the file to delete (string, required) - `repo`: Repository name (string, required) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) -- **push_files** - Push multiple files in a single commit +- **fork_repository** - Fork repository + - `organization`: Organization to fork to (string, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `branch`: Branch to push to (string, required) - - `files`: Files to push, each with path and content (array, required) - - `message`: Commit message (string, required) -- **search_repositories** - Search for GitHub repositories - - `query`: Search query (string, required) - - `sort`: Sort field (string, optional) - - `order`: Sort order (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) +- **get_commit** - Get commit details + - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `repo`: Repository name (string, required) + - `sha`: Commit SHA, branch name, or tag name (string, required) -- **create_repository** - Create a new GitHub repository - - `name`: Repository name (string, required) - - `description`: Repository description (string, optional) - - `private`: Whether the repository is private (boolean, optional) - - `autoInit`: Auto-initialize with README (boolean, optional) +- **get_file_contents** - Get file or directory contents + - `owner`: Repository owner (username or organization) (string, required) + - `path`: Path to file/directory (directories must end with a slash '/') (string, optional) + - `ref`: Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` (string, optional) + - `repo`: Repository name (string, required) + - `sha`: Accepts optional commit SHA. If specified, it will be used instead of ref (string, optional) -- **get_file_contents** - Get contents of a file or directory +- **get_tag** - Get tag details - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `path`: File path (string, required) - - `ref`: Git reference (string, optional) + - `tag`: Tag name (string, required) -- **fork_repository** - Fork a repository +- **list_branches** - List branches - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `organization`: Target organization name (string, optional) -- **create_branch** - Create a new branch +- **list_commits** - List commits + - `author`: Author username or email address to filter commits by (string, optional) - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `branch`: New branch name (string, required) - - `sha`: SHA to create branch from (string, required) + - `sha`: Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA. (string, optional) -- **list_commits** - Get a list of commits of a branch in a repository +- **list_tags** - List tags - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `sha`: Branch name, tag, or commit SHA (string, optional) - - `path`: Only commits containing this file path (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) -- **get_commit** - Get details for a commit from a repository +- **push_files** - Push files to repository + - `branch`: Branch to push to (string, required) + - `files`: Array of file objects to push, each object with path (string) and content (string) (object[], required) + - `message`: Commit message (string, required) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `sha`: Commit SHA, branch name, or tag name (string, required) - - `page`: Page number, for files in the commit (number, optional) - - `perPage`: Results per page, for files in the commit (number, optional) -- **search_code** - Search for code across GitHub repositories - - `query`: Search query (string, required) - - `sort`: Sort field (string, optional) +- **search_code** - Search code - `order`: Sort order (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `q`: Search query using GitHub code search syntax (string, required) + - `sort`: Sort field ('indexed' only) (string, optional) + +- **search_repositories** - Search repositories + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query (string, required) + +
+ +
+ +Secret Protection + +- **get_secret_scanning_alert** - Get secret scanning alert + - `alertNumber`: The number of the alert. (number, required) + - `owner`: The owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) -### Users +- **list_secret_scanning_alerts** - List secret scanning alerts + - `owner`: The owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) + - `resolution`: Filter by resolution (string, optional) + - `secret_type`: A comma-separated list of secret types to return. All default secret patterns are returned. To return generic patterns, pass the token name(s) in the parameter. (string, optional) + - `state`: Filter by state (string, optional) -- **search_users** - Search for GitHub users - - `q`: Search query (string, required) - - `sort`: Sort field (string, optional) +
+ +
+ +Users + +- **search_users** - Search users - `order`: Sort order (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query using GitHub users search syntax scoped to type:user (string, required) + - `sort`: Sort field by category (string, optional) -### Code Scanning +
+ -- **get_code_scanning_alert** - Get a code scanning alert +### Additional Tools in Remote Github MCP Server - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `alertNumber`: Alert number (number, required) +
-- **list_code_scanning_alerts** - List code scanning alerts for a repository - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `ref`: Git reference (string, optional) - - `state`: Alert state (string, optional) - - `severity`: Alert severity (string, optional) - - `tool_name`: The name of the tool used for code scanning (string, optional) +Copilot coding agent -### Secret Scanning +- **create_pull_request_with_copilot** - Perform task with GitHub Copilot coding agent + - `owner`: Repository owner. You can guess the owner, but confirm it with the user before proceeding. (string, required) + - `repo`: Repository name. You can guess the repository name, but confirm it with the user before proceeding. (string, required) + - `problem_statement`: Detailed description of the task to be performed (e.g., 'Implement a feature that does X', 'Fix bug Y', etc.) (string, required) + - `title`: Title for the pull request that will be created (string, required) + - `base_ref`: Git reference (e.g., branch) that the agent will start its work from. If not specified, defaults to the repository's default branch (string, optional) -- **get_secret_scanning_alert** - Get a secret scanning alert +
- - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `alertNumber`: Alert number (number, required) +#### Specifying Toolsets -- **list_secret_scanning_alerts** - List secret scanning alerts for a repository - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `state`: Alert state (string, optional) - - `secret_type`: The secret types to be filtered for in a comma-separated list (string, optional) - - `resolution`: The resolution status (string, optional) +To specify toolsets you want available to the LLM, you can pass an allow-list in two ways: + +1. **Using Command Line Argument**: -### Notifications + ```bash + github-mcp-server --toolsets repos,issues,pull_requests,actions,code_security + ``` -- **list_notifications** – List notifications for a GitHub user - - `filter`: Filter to apply to the response (`default`, `include_read_notifications`, `only_participating`) - - `since`: Only show notifications updated after the given time (ISO 8601 format) - - `before`: Only show notifications updated before the given time (ISO 8601 format) - - `owner`: Optional repository owner (string) - - `repo`: Optional repository name (string) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) +2. **Using Environment Variable**: + ```bash + GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security" ./github-mcp-server + ``` +The environment variable `GITHUB_TOOLSETS` takes precedence over the command line argument if both are provided. -- **get_notification_details** – Get detailed information for a specific GitHub notification - - `notificationID`: The ID of the notification (string, required) +### Using Toolsets With Docker -- **dismiss_notification** – Dismiss a notification by marking it as read or done - - `threadID`: The ID of the notification thread (string, required) - - `state`: The new state of the notification (`read` or `done`) +When using Docker, you can pass the toolsets as environment variables: -- **mark_all_notifications_read** – Mark all notifications as read - - `lastReadAt`: Describes the last point that notifications were checked (optional, RFC3339/ISO8601 string, default: now) - - `owner`: Optional repository owner (string) - - `repo`: Optional repository name (string) +```bash +docker run -i --rm \ + -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + -e GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security,experiments" \ + ghcr.io/github/github-mcp-server +``` -- **manage_notification_subscription** – Manage a notification subscription (ignore, watch, or delete) for a notification thread - - `notificationID`: The ID of the notification thread (string, required) - - `action`: Action to perform: `ignore`, `watch`, or `delete` (string, required) +### The "all" Toolset -- **manage_repository_notification_subscription** – Manage a repository notification subscription (ignore, watch, or delete) - - `owner`: The account owner of the repository (string, required) - - `repo`: The name of the repository (string, required) - - `action`: Action to perform: `ignore`, `watch`, or `delete` (string, required) - -## Resources - -### Repository Content - -- **Get Repository Content** - Retrieves the content of a repository at a specific path. - - - **Template**: `repo://{owner}/{repo}/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `path`: File or directory path (string, optional) - -- **Get Repository Content for a Specific Branch** - Retrieves the content of a repository at a specific path for a given branch. - - - **Template**: `repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `branch`: Branch name (string, required) - - `path`: File or directory path (string, optional) - -- **Get Repository Content for a Specific Commit** - Retrieves the content of a repository at a specific path for a given commit. - - - **Template**: `repo://{owner}/{repo}/sha/{sha}/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `sha`: Commit SHA (string, required) - - `path`: File or directory path (string, optional) - -- **Get Repository Content for a Specific Tag** - Retrieves the content of a repository at a specific path for a given tag. - - - **Template**: `repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `tag`: Tag name (string, required) - - `path`: File or directory path (string, optional) - -- **Get Repository Content for a Specific Pull Request** - Retrieves the content of a repository at a specific path for a given pull request. - - - **Template**: `repo://{owner}/{repo}/refs/pull/{prNumber}/head/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `prNumber`: Pull request number (string, required) - - `path`: File or directory path (string, optional) +The special toolset `all` can be provided to enable all available toolsets regardless of any other configuration: + +```bash +./github-mcp-server --toolsets all +``` + +Or using the environment variable: + +```bash +GITHUB_TOOLSETS="all" ./github-mcp-server +``` + +## Dynamic Tool Discovery + +**Note**: This feature is currently in beta and may not be available in all environments. Please test it out and let us know if you encounter any issues. + +Instead of starting with all tools enabled, you can turn on dynamic toolset discovery. Dynamic toolsets allow the MCP host to list and enable toolsets in response to a user prompt. This should help to avoid situations where the model gets confused by the sheer number of tools available. + +### Using Dynamic Tool Discovery + +When using the binary, you can pass the `--dynamic-toolsets` flag. + +```bash +./github-mcp-server --dynamic-toolsets +``` + +When using Docker, you can pass the toolsets as environment variables: + +```bash +docker run -i --rm \ + -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + -e GITHUB_DYNAMIC_TOOLSETS=1 \ + ghcr.io/github/github-mcp-server +``` + +## Read-Only Mode + +To run the server in read-only mode, you can use the `--read-only` flag. This will only offer read-only tools, preventing any modifications to repositories, issues, pull requests, etc. + +```bash +./github-mcp-server --read-only +``` + +When using Docker, you can pass the read-only mode as an environment variable: + +```bash +docker run -i --rm \ + -e GITHUB_PERSONAL_ACCESS_TOKEN= \ + -e GITHUB_READ_ONLY=1 \ + ghcr.io/github/github-mcp-server +``` + +## GitHub Enterprise Server and Enterprise Cloud with data residency (ghe.com) + +The flag `--gh-host` and the environment variable `GITHUB_HOST` can be used to set +the hostname for GitHub Enterprise Server or GitHub Enterprise Cloud with data residency. + +- For GitHub Enterprise Server, prefix the hostname with the `https://` URI scheme, as it otherwise defaults to `http://`, which GitHub Enterprise Server does not support. +- For GitHub Enterprise Cloud with data residency, use `https://YOURSUBDOMAIN.ghe.com` as the hostname. +``` json +"github": { + "command": "docker", + "args": [ + "run", + "-i", + "--rm", + "-e", + "GITHUB_PERSONAL_ACCESS_TOKEN", + "-e", + "GITHUB_HOST", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}", + "GITHUB_HOST": "https://" + } +} +``` + +## i18n / Overriding Descriptions + +The descriptions of the tools can be overridden by creating a +`github-mcp-server-config.json` file in the same directory as the binary. + +The file should contain a JSON object with the tool names as keys and the new +descriptions as values. For example: + +```json +{ + "TOOL_ADD_ISSUE_COMMENT_DESCRIPTION": "an alternative description", + "TOOL_CREATE_BRANCH_DESCRIPTION": "Create a new branch in a GitHub repository" +} +``` + +You can create an export of the current translations by running the binary with +the `--export-translations` flag. + +This flag will preserve any translations/overrides you have made, while adding +any new translations that have been added to the binary since the last time you +exported. + +```sh +./github-mcp-server --export-translations +cat github-mcp-server-config.json +``` + +You can also use ENV vars to override the descriptions. The environment +variable names are the same as the keys in the JSON file, prefixed with +`GITHUB_MCP_` and all uppercase. + +For example, to override the `TOOL_ADD_ISSUE_COMMENT_DESCRIPTION` tool, you can +set the following environment variable: + +```sh +export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description" +``` ## Library Usage diff --git a/cmd/github-mcp-server/generate_docs.go b/cmd/github-mcp-server/generate_docs.go new file mode 100644 index 000000000..983ed4398 --- /dev/null +++ b/cmd/github-mcp-server/generate_docs.go @@ -0,0 +1,354 @@ +package main + +import ( + "context" + "fmt" + "net/url" + "os" + "regexp" + "sort" + "strings" + + "github.com/github/github-mcp-server/pkg/github" + "github.com/github/github-mcp-server/pkg/raw" + "github.com/github/github-mcp-server/pkg/toolsets" + "github.com/github/github-mcp-server/pkg/translations" + gogithub "github.com/google/go-github/v73/github" + "github.com/mark3labs/mcp-go/mcp" + "github.com/shurcooL/githubv4" + "github.com/spf13/cobra" +) + +var generateDocsCmd = &cobra.Command{ + Use: "generate-docs", + Short: "Generate documentation for tools and toolsets", + Long: `Generate the automated sections of README.md and docs/remote-server.md with current tool and toolset information.`, + RunE: func(_ *cobra.Command, _ []string) error { + return generateAllDocs() + }, +} + +func init() { + rootCmd.AddCommand(generateDocsCmd) +} + +// mockGetClient returns a mock GitHub client for documentation generation +func mockGetClient(_ context.Context) (*gogithub.Client, error) { + return gogithub.NewClient(nil), nil +} + +// mockGetGQLClient returns a mock GraphQL client for documentation generation +func mockGetGQLClient(_ context.Context) (*githubv4.Client, error) { + return githubv4.NewClient(nil), nil +} + +// mockGetRawClient returns a mock raw client for documentation generation +func mockGetRawClient(_ context.Context) (*raw.Client, error) { + return nil, nil +} + +func generateAllDocs() error { + if err := generateReadmeDocs("README.md"); err != nil { + return fmt.Errorf("failed to generate README docs: %w", err) + } + + if err := generateRemoteServerDocs("docs/remote-server.md"); err != nil { + return fmt.Errorf("failed to generate remote-server docs: %w", err) + } + + return nil +} + +func generateReadmeDocs(readmePath string) error { + // Create translation helper + t, _ := translations.TranslationHelper() + + // Create toolset group with mock clients + tsg := github.DefaultToolsetGroup(false, mockGetClient, mockGetGQLClient, mockGetRawClient, t) + + // Generate toolsets documentation + toolsetsDoc := generateToolsetsDoc(tsg) + + // Generate tools documentation + toolsDoc := generateToolsDoc(tsg) + + // Read the current README.md + // #nosec G304 - readmePath is controlled by command line flag, not user input + content, err := os.ReadFile(readmePath) + if err != nil { + return fmt.Errorf("failed to read README.md: %w", err) + } + + // Replace toolsets section + updatedContent := replaceSection(string(content), "START AUTOMATED TOOLSETS", "END AUTOMATED TOOLSETS", toolsetsDoc) + + // Replace tools section + updatedContent = replaceSection(updatedContent, "START AUTOMATED TOOLS", "END AUTOMATED TOOLS", toolsDoc) + + // Write back to file + err = os.WriteFile(readmePath, []byte(updatedContent), 0600) + if err != nil { + return fmt.Errorf("failed to write README.md: %w", err) + } + + fmt.Println("Successfully updated README.md with automated documentation") + return nil +} + +func generateRemoteServerDocs(docsPath string) error { + content, err := os.ReadFile(docsPath) //#nosec G304 + if err != nil { + return fmt.Errorf("failed to read docs file: %w", err) + } + + toolsetsDoc := generateRemoteToolsetsDoc() + + // Replace content between markers + startMarker := "" + endMarker := "" + + contentStr := string(content) + startIndex := strings.Index(contentStr, startMarker) + endIndex := strings.Index(contentStr, endMarker) + + if startIndex == -1 || endIndex == -1 { + return fmt.Errorf("automation markers not found in %s", docsPath) + } + + newContent := contentStr[:startIndex] + startMarker + "\n" + toolsetsDoc + "\n" + endMarker + contentStr[endIndex+len(endMarker):] + + return os.WriteFile(docsPath, []byte(newContent), 0600) //#nosec G306 +} + +func generateToolsetsDoc(tsg *toolsets.ToolsetGroup) string { + var lines []string + + // Add table header and separator + lines = append(lines, "| Toolset | Description |") + lines = append(lines, "| ----------------------- | ------------------------------------------------------------- |") + + // Add the context toolset row (handled separately in README) + lines = append(lines, "| `context` | **Strongly recommended**: Tools that provide context about the current user and GitHub context you are operating in |") + + // Get all toolsets except context (which is handled separately above) + var toolsetNames []string + for name := range tsg.Toolsets { + if name != "context" && name != "dynamic" { // Skip context and dynamic toolsets as they're handled separately + toolsetNames = append(toolsetNames, name) + } + } + + // Sort toolset names for consistent output + sort.Strings(toolsetNames) + + for _, name := range toolsetNames { + toolset := tsg.Toolsets[name] + lines = append(lines, fmt.Sprintf("| `%s` | %s |", name, toolset.Description)) + } + + return strings.Join(lines, "\n") +} + +func generateToolsDoc(tsg *toolsets.ToolsetGroup) string { + var sections []string + + // Get all toolset names and sort them alphabetically for deterministic order + var toolsetNames []string + for name := range tsg.Toolsets { + if name != "dynamic" { // Skip dynamic toolset as it's handled separately + toolsetNames = append(toolsetNames, name) + } + } + sort.Strings(toolsetNames) + + for _, toolsetName := range toolsetNames { + toolset := tsg.Toolsets[toolsetName] + + tools := toolset.GetAvailableTools() + if len(tools) == 0 { + continue + } + + // Sort tools by name for deterministic order + sort.Slice(tools, func(i, j int) bool { + return tools[i].Tool.Name < tools[j].Tool.Name + }) + + // Generate section header - capitalize first letter and replace underscores + sectionName := formatToolsetName(toolsetName) + + var toolDocs []string + for _, serverTool := range tools { + toolDoc := generateToolDoc(serverTool.Tool) + toolDocs = append(toolDocs, toolDoc) + } + + if len(toolDocs) > 0 { + section := fmt.Sprintf("
\n\n%s\n\n%s\n\n
", + sectionName, strings.Join(toolDocs, "\n\n")) + sections = append(sections, section) + } + } + + return strings.Join(sections, "\n\n") +} + +func formatToolsetName(name string) string { + switch name { + case "pull_requests": + return "Pull Requests" + case "repos": + return "Repositories" + case "code_security": + return "Code Security" + case "secret_protection": + return "Secret Protection" + case "orgs": + return "Organizations" + default: + // Fallback: capitalize first letter and replace underscores with spaces + parts := strings.Split(name, "_") + for i, part := range parts { + if len(part) > 0 { + parts[i] = strings.ToUpper(string(part[0])) + part[1:] + } + } + return strings.Join(parts, " ") + } +} + +func generateToolDoc(tool mcp.Tool) string { + var lines []string + + // Tool name only (using annotation name instead of verbose description) + lines = append(lines, fmt.Sprintf("- **%s** - %s", tool.Name, tool.Annotations.Title)) + + // Parameters + schema := tool.InputSchema + if len(schema.Properties) > 0 { + // Get parameter names and sort them for deterministic order + var paramNames []string + for propName := range schema.Properties { + paramNames = append(paramNames, propName) + } + sort.Strings(paramNames) + + for _, propName := range paramNames { + prop := schema.Properties[propName] + required := contains(schema.Required, propName) + requiredStr := "optional" + if required { + requiredStr = "required" + } + + // Get the type and description + typeStr := "unknown" + description := "" + + if propMap, ok := prop.(map[string]interface{}); ok { + if typeVal, ok := propMap["type"].(string); ok { + if typeVal == "array" { + if items, ok := propMap["items"].(map[string]interface{}); ok { + if itemType, ok := items["type"].(string); ok { + typeStr = itemType + "[]" + } + } else { + typeStr = "array" + } + } else { + typeStr = typeVal + } + } + + if desc, ok := propMap["description"].(string); ok { + description = desc + } + } + + paramLine := fmt.Sprintf(" - `%s`: %s (%s, %s)", propName, description, typeStr, requiredStr) + lines = append(lines, paramLine) + } + } else { + lines = append(lines, " - No parameters required") + } + + return strings.Join(lines, "\n") +} + +func contains(slice []string, item string) bool { + for _, s := range slice { + if s == item { + return true + } + } + return false +} + +func replaceSection(content, startMarker, endMarker, newContent string) string { + startPattern := fmt.Sprintf(``, regexp.QuoteMeta(startMarker)) + endPattern := fmt.Sprintf(``, regexp.QuoteMeta(endMarker)) + + re := regexp.MustCompile(fmt.Sprintf(`(?s)%s.*?%s`, startPattern, endPattern)) + + replacement := fmt.Sprintf("\n%s\n", startMarker, newContent, endMarker) + + return re.ReplaceAllString(content, replacement) +} + +func generateRemoteToolsetsDoc() string { + var buf strings.Builder + + // Create translation helper + t, _ := translations.TranslationHelper() + + // Create toolset group with mock clients + tsg := github.DefaultToolsetGroup(false, mockGetClient, mockGetGQLClient, mockGetRawClient, t) + + // Generate table header + buf.WriteString("| Name | Description | API URL | 1-Click Install (VS Code) | Read-only Link | 1-Click Read-only Install (VS Code) |\n") + buf.WriteString("|----------------|--------------------------------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n") + + // Get all toolsets + toolsetNames := make([]string, 0, len(tsg.Toolsets)) + for name := range tsg.Toolsets { + if name != "context" && name != "dynamic" { // Skip context and dynamic toolsets as they're handled separately + toolsetNames = append(toolsetNames, name) + } + } + sort.Strings(toolsetNames) + + // Add "all" toolset first (special case) + buf.WriteString("| all | All available GitHub MCP tools | https://api.githubcopilot.com/mcp/ | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D) | [read-only](https://api.githubcopilot.com/mcp/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Freadonly%22%7D) |\n") + + // Add individual toolsets + for _, name := range toolsetNames { + toolset := tsg.Toolsets[name] + + formattedName := formatToolsetName(name) + description := toolset.Description + apiURL := fmt.Sprintf("https://api.githubcopilot.com/mcp/x/%s", name) + readonlyURL := fmt.Sprintf("https://api.githubcopilot.com/mcp/x/%s/readonly", name) + + // Create install config JSON (URL encoded) + installConfig := url.QueryEscape(fmt.Sprintf(`{"type": "http","url": "%s"}`, apiURL)) + readonlyConfig := url.QueryEscape(fmt.Sprintf(`{"type": "http","url": "%s"}`, readonlyURL)) + + // Fix URL encoding to use %20 instead of + for spaces + installConfig = strings.ReplaceAll(installConfig, "+", "%20") + readonlyConfig = strings.ReplaceAll(readonlyConfig, "+", "%20") + + installLink := fmt.Sprintf("[Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-%s&config=%s)", name, installConfig) + readonlyInstallLink := fmt.Sprintf("[Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-%s&config=%s)", name, readonlyConfig) + + buf.WriteString(fmt.Sprintf("| %-14s | %-48s | %-53s | %-218s | %-110s | %-288s |\n", + formattedName, + description, + apiURL, + installLink, + fmt.Sprintf("[read-only](%s)", readonlyURL), + readonlyInstallLink, + )) + } + + return buf.String() +} diff --git a/cmd/github-mcp-server/main.go b/cmd/github-mcp-server/main.go index fb716f78d..cad002666 100644 --- a/cmd/github-mcp-server/main.go +++ b/cmd/github-mcp-server/main.go @@ -4,10 +4,12 @@ import ( "errors" "fmt" "os" + "strings" "github.com/github/github-mcp-server/internal/ghmcp" "github.com/github/github-mcp-server/pkg/github" "github.com/spf13/cobra" + "github.com/spf13/pflag" "github.com/spf13/viper" ) @@ -54,7 +56,6 @@ var ( EnableCommandLogging: viper.GetBool("enable-command-logging"), LogFilePath: viper.GetString("log-file"), } - return ghmcp.RunStdioServer(stdioServerConfig) }, } @@ -62,6 +63,7 @@ var ( func init() { cobra.OnInitialize(initConfig) + rootCmd.SetGlobalNormalizationFunc(wordSepNormalizeFunc) rootCmd.SetVersionTemplate("{{.Short}}\n{{.Version}}\n") @@ -91,6 +93,7 @@ func initConfig() { // Initialize Viper configuration viper.SetEnvPrefix("github") viper.AutomaticEnv() + } func main() { @@ -99,3 +102,12 @@ func main() { os.Exit(1) } } + +func wordSepNormalizeFunc(_ *pflag.FlagSet, name string) pflag.NormalizedName { + from := []string{"_"} + to := "-" + for _, sep := range from { + name = strings.ReplaceAll(name, sep, to) + } + return pflag.NormalizedName(name) +} diff --git a/cmd/mcpcurl/README.md b/cmd/mcpcurl/README.md index 493ce5b18..317c2b8e5 100644 --- a/cmd/mcpcurl/README.md +++ b/cmd/mcpcurl/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 diff --git a/docs/error-handling.md b/docs/error-handling.md new file mode 100644 index 000000000..9bb27e0fa --- /dev/null +++ b/docs/error-handling.md @@ -0,0 +1,125 @@ +# Error Handling + +This document describes the error handling patterns used in the GitHub MCP Server, specifically how we handle GitHub API errors and avoid direct use of mcp-go error types. + +## Overview + +The GitHub MCP Server implements a custom error handling approach that serves two primary purposes: + +1. **Tool Response Generation**: Return appropriate MCP tool error responses to clients +2. **Middleware Inspection**: Store detailed error information in the request context for middleware analysis + +This dual approach enables better observability and debugging capabilities, particularly for remote server deployments where understanding the nature of failures (rate limiting, authentication, 404s, 500s, etc.) is crucial for validation and monitoring. + +## Error Types + +### GitHubAPIError + +Used for REST API errors from the GitHub API: + +```go +type GitHubAPIError struct { + Message string `json:"message"` + Response *github.Response `json:"-"` + Err error `json:"-"` +} +``` + +### GitHubGraphQLError + +Used for GraphQL API errors from the GitHub API: + +```go +type GitHubGraphQLError struct { + Message string `json:"message"` + Err error `json:"-"` +} +``` + +## Usage Patterns + +### For GitHub REST API Errors + +Instead of directly returning `mcp.NewToolResultError()`, use: + +```go +return ghErrors.NewGitHubAPIErrorResponse(ctx, message, response, err), nil +``` + +This function: +- Creates a `GitHubAPIError` with the provided message, response, and error +- Stores the error in the context for middleware inspection +- Returns an appropriate MCP tool error response + +### For GitHub GraphQL API Errors + +```go +return ghErrors.NewGitHubGraphQLErrorResponse(ctx, message, err), nil +``` + +### Context Management + +The error handling system uses context to store errors for later inspection: + +```go +// Initialize context with error tracking +ctx = errors.ContextWithGitHubErrors(ctx) + +// Retrieve errors for inspection (typically in middleware) +apiErrors, err := errors.GetGitHubAPIErrors(ctx) +graphqlErrors, err := errors.GetGitHubGraphQLErrors(ctx) +``` + +## Design Principles + +### User-Actionable vs. Developer Errors + +- **User-actionable errors** (authentication failures, rate limits, 404s) should be returned as failed tool calls using the error response functions +- **Developer errors** (JSON marshaling failures, internal logic errors) should be returned as actual Go errors that bubble up through the MCP framework + +### Context Limitations + +This approach was designed to work around current limitations in mcp-go where context is not propagated through each step of request processing. By storing errors in context values, middleware can inspect them without requiring context propagation. + +### Graceful Error Handling + +Error storage operations in context are designed to fail gracefully - if context storage fails, the tool will still return an appropriate error response to the client. + +## Benefits + +1. **Observability**: Middleware can inspect the specific types of GitHub API errors occurring +2. **Debugging**: Detailed error information is preserved without exposing potentially sensitive data in logs +3. **Validation**: Remote servers can use error types and HTTP status codes to validate that changes don't break functionality +4. **Privacy**: Error inspection can be done programmatically using `errors.Is` checks without logging PII + +## Example Implementation + +```go +func GetIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("get_issue", /* ... */), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + issue, resp, err := client.Issues.Get(ctx, owner, repo, issueNumber) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get issue", + resp, + err, + ), nil + } + + return MarshalledTextResult(issue), nil + } +} +``` + +This approach ensures that both the client receives an appropriate error response and any middleware can inspect the underlying GitHub API error for monitoring and debugging purposes. diff --git a/docs/host-integration.md b/docs/host-integration.md new file mode 100644 index 000000000..9a1d9396f --- /dev/null +++ b/docs/host-integration.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/2025-06-18). + +> [!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/2025-06-18/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)
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)
+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.
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).
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) diff --git a/docs/installation-guides/README.md b/docs/installation-guides/README.md new file mode 100644 index 000000000..f55cc6bef --- /dev/null +++ b/docs/installation-guides/README.md @@ -0,0 +1,95 @@ +# GitHub MCP Server Installation Guides + +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 +- **[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 +- **[Windsurf](install-windsurf.md)** - Installation guide for Windsurf IDE + +## Support by Host Application + +| Host Application | Local GitHub MCP Support | Remote GitHub MCP Support | Prerequisites | Difficulty | +|-----------------|---------------|----------------|---------------|------------| +| Copilot in VS Code | ✅ | ✅ Full (OAuth + PAT) | Local: Docker or Go build, GitHub PAT
Remote: VS Code 1.101+ | Easy | +| Copilot Coding Agent | ✅ | ✅ Full (on by default; no auth needed) | Any _paid_ copilot license | Default on | +| Copilot in Visual Studio | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker or Go build, GitHub PAT
Remote: Visual Studio 17.14+ | Easy | +| Copilot in JetBrains | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker or Go build, GitHub PAT
Remote: JetBrains Copilot Extension v1.5.35+ | Easy | +| Claude Code | ✅ | ✅ PAT + ❌ No OAuth| GitHub MCP Server binary or remote URL, GitHub PAT | Easy | +| Claude Desktop | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Moderate | +| Cursor | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy | +| Windsurf | ✅ | ✅ PAT + ❌ No OAuth | Docker or Go build, GitHub PAT | Easy | +| Copilot in Xcode | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker or Go build, GitHub PAT
Remote: Copilot for Xcode latest version | Easy | +| Copilot in Eclipse | ✅ | ✅ PAT + ❌ No OAuth | Local: Docker or Go build, GitHub PAT
Remote: TBD | Easy | + +**Legend:** +- ✅ = Fully supported +- ❌ = Not yet supported + +**Note:** Remote MCP support requires host applications to register a GitHub App or OAuth app for OAuth flow support – even if the new OAuth spec is supported by that host app. Currently, only VS Code has full remote GitHub server support. + +## Installation Methods + +The GitHub MCP Server can be installed using several methods. **Docker is the most popular and recommended approach** for most users, but alternatives are available depending on your needs: + +### 🐳 Docker (Most Common & Recommended) +- **Pros**: No local build required, consistent environment, easy updates, works across all platforms +- **Cons**: Requires Docker installed and running +- **Best for**: Most users, especially those already using Docker or wanting the simplest setup +- **Used by**: Claude Desktop, Copilot in VS Code, Cursor, Windsurf, etc. + +### 📦 Pre-built Binary (Lightweight Alternative) +- **Pros**: No Docker required, direct execution via stdio, minimal setup +- **Cons**: Need to manually download and manage updates, platform-specific binaries +- **Best for**: Minimal environments, users who prefer not to use Docker +- **Used by**: Claude Code CLI, lightweight setups + +### 🔨 Build from Source (Advanced Users) +- **Pros**: Latest features, full customization, no external dependencies +- **Cons**: Requires Go development environment, more complex setup +- **Prerequisites**: [Go 1.24+](https://go.dev/doc/install) +- **Build command**: `go build -o github-mcp-server cmd/github-mcp-server/main.go` +- **Best for**: Developers who want the latest features or need custom modifications + +### Important Notes on the GitHub MCP Server + +- **Docker Image**: The official Docker image is now `ghcr.io/github/github-mcp-server` +- **npm Package**: The npm package @modelcontextprotocol/server-github is no longer supported as of April 2025 +- **Remote Server**: The remote server URL is `https://api.githubcopilot.com/mcp/` + +## General Prerequisites + +All installations with Personal Access Tokens (PAT) require: +- **GitHub Personal Access Token (PAT)**: [Create one here](https://github.com/settings/personal-access-tokens/new) + +Optional (depending on installation method): +- **Docker** (for Docker-based installations): [Download Docker](https://www.docker.com/) +- **Go 1.24+** (for building from source): [Install Go](https://go.dev/doc/install) + +## Security Best Practices + +Regardless of which installation method you choose, follow these security guidelines: + +1. **Secure Token Storage**: Never commit your GitHub PAT to version control +2. **Limit Token Scope**: Only grant necessary permissions to your GitHub PAT +3. **File Permissions**: Restrict access to configuration files containing tokens +4. **Regular Rotation**: Periodically rotate your GitHub Personal Access Tokens +5. **Environment Variables**: Use environment variables when supported by your host + +## Getting Help + +If you encounter issues: +1. Check the troubleshooting section in your specific installation guide +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 + +## Configuration Options + +After installation, you may want to explore: +- **Toolsets**: Enable/disable specific GitHub API capabilities +- **Read-Only Mode**: Restrict to read-only operations +- **Dynamic Tool Discovery**: Enable tools on-demand + diff --git a/docs/installation-guides/install-claude.md b/docs/installation-guides/install-claude.md new file mode 100644 index 000000000..2c50be2f9 --- /dev/null +++ b/docs/installation-guides/install-claude.md @@ -0,0 +1,204 @@ +# Install GitHub MCP Server in Claude Applications + +This guide covers installation of the GitHub MCP server for Claude Code CLI, Claude Desktop, and Claude Web applications. + +## Claude Web (claude.ai) + +Claude Web supports remote MCP servers through the Integrations built-in feature. + +### Prerequisites + +1. Claude Pro, Team, or Enterprise account (Integrations not available on free plan) +2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) + +### Installation + +**Note**: As of July 2025, the remote GitHub MCP Server has known compatibility issues with Claude Web. While Claude Web supports remote MCP servers from other providers (like Atlassian, Zapier, Notion), the GitHub MCP Server integration may not work reliably. + +For other remote MCP servers that do work with Claude Web: + +1. Go to [claude.ai](https://claude.ai) and log in +2. Click your profile icon → **Settings** +3. Navigate to **Integrations** section +4. Click **+ Add integration** or **Add More** +5. Enter the remote server URL +6. Follow the OAuth authentication flow when prompted + +**Alternative**: Use Claude Desktop or Claude Code CLI for reliable GitHub MCP Server integration. + +--- + +## 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) +3. [Docker](https://www.docker.com/) installed and running + +### Installation + +Run the following command to add the GitHub MCP server using Docker: + +```bash +claude mcp add github -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server +``` + +Then set the environment variable: +```bash +claude mcp update github -e GITHUB_PERSONAL_ACCESS_TOKEN=your_github_pat +``` + +Or as a single command with the token inline: +```bash +claude mcp add-json 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"}}' +``` + +**Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead. + +### Configuration Options + +- Use `-s user` to add the server to your user configuration (available across all projects) +- Use `-s project` to add the server to project-specific configuration (shared via `.mcp.json`) +- Default scope is `local` (available only to you in the current project) + +### Verification + +Run the following command to verify the installation: +```bash +claude mcp list +``` + +--- + +## Claude Desktop + +Claude Desktop provides a graphical 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 + +### Configuration File Location + +- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` +- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` +- **Linux**: `~/.config/Claude/claude_desktop_config.json` (unofficial support) + +### Installation + +Add the following to your `claude_desktop_config.json`: + +```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" + } + } + } +} +``` + +**Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead. + +### Using Environment Variables + +Claude Desktop supports environment variable references. You can use: + +```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" + } + } + } +} +``` + +Then set the environment variable in your system before starting Claude Desktop. + +### Installation Steps + +1. Open Claude Desktop +2. Go to Settings (from the Claude menu) → Developer → Edit Config +3. Add your chosen configuration +4. Save the file +5. Restart Claude Desktop + +### Verification + +After restarting, you should see: +- An MCP icon in the Claude Desktop interface +- The GitHub server listed as "running" in Developer settings + +--- + +## Troubleshooting + +### Claude Web +- Currently experiencing compatibility issues with the GitHub MCP Server +- Try other remote MCP servers (Atlassian, Zapier, Notion) which work reliably +- Use Claude Desktop or Claude Code CLI as alternatives for GitHub integration + +### Claude Code CLI +- Verify the command syntax is correct (note the single quotes around the JSON) +- Ensure Docker is running: `docker --version` +- Use `/mcp` command within Claude Code to check server status + +### Claude Desktop +- Check logs at: + - **macOS**: `~/Library/Logs/Claude/` + - **Windows**: `%APPDATA%\Claude\logs\` +- Look for `mcp-server-github.log` for server-specific errors +- Ensure configuration file is valid JSON +- Try running the Docker command manually in terminal to diagnose issues + +### Common Issues +- **Invalid JSON**: Validate your configuration at [jsonlint.com](https://jsonlint.com) +- **PAT issues**: Ensure your GitHub PAT has required scopes +- **Docker not found**: Install Docker Desktop and ensure it's running +- **Docker image pull fails**: Try `docker logout ghcr.io` then retry + +--- + +## Security Best Practices + +- **Protect configuration files**: Set appropriate file permissions +- **Use environment variables** when possible instead of hardcoding tokens +- **Limit PAT scope** to only necessary permissions +- **Regularly rotate** your GitHub Personal Access Tokens +- **Never commit** configuration files containing tokens to version control + +--- + +## Additional Resources + +- [Model Context Protocol Documentation](https://modelcontextprotocol.io) +- [Claude Code MCP Documentation](https://docs.anthropic.com/en/docs/claude-code/mcp) +- [Claude Web Integrations Support](https://support.anthropic.com/en/articles/11175166-about-custom-integrations-using-remote-mcp) diff --git a/docs/installation-guides/install-cursor.md b/docs/installation-guides/install-cursor.md new file mode 100644 index 000000000..b069addd3 --- /dev/null +++ b/docs/installation-guides/install-cursor.md @@ -0,0 +1,107 @@ +# Install GitHub MCP Server in Cursor + +## Prerequisites +1. Cursor IDE installed (latest version) +2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes +3. For local installation: [Docker](https://www.docker.com/) installed and running + +## Remote Server Setup (Recommended) + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=github&config=eyJ1cmwiOiJodHRwczovL2FwaS5naXRodWJjb3BpbG90LmNvbS9tY3AvIiwiaGVhZGVycyI6eyJBdXRob3JpemF0aW9uIjoiQmVhcmVyIFlPVVJfR0lUSFVCX1BBVCJ9LCJ0eXBlIjoiaHR0cCJ9) + +Uses GitHub's hosted server at https://api.githubcopilot.com/mcp/. Requires Cursor v0.48.0+ for Streamable HTTP support. While Cursor supports OAuth for some MCP servers, the GitHub server currently requires a Personal Access Token. + +### Install steps +1. Click the install button above and follow the flow, or go directly to your global MCP configuration file at `~/.cursor/mcp.json` and enter the code block below +2. In Tools & Integrations > MCP tools, click the pencil icon next to "github" +3. Replace `YOUR_GITHUB_PAT` with your actual [GitHub Personal Access Token](https://github.com/settings/tokens) +4. Save the file +5. Restart Cursor + +### Streamable HTTP Configuration + +```json +{ + "mcpServers": { + "github": { + "url": "https://api.githubcopilot.com/mcp/", + "headers": { + "Authorization": "Bearer YOUR_GITHUB_PAT" + } + } + } +} +``` + +## Local Server Setup + +[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=github&config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCItZSIsIkdJVEhVQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU4iLCJnaGNyLmlvL2dpdGh1Yi9naXRodWItbWNwLXNlcnZlciJdLCJlbnYiOnsiR0lUSFVCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IllPVVJfR0lUSFVCX1BHVCJ9fQ==) + +The local GitHub MCP server runs via Docker and requires Docker Desktop to be installed and running. + +### Install steps +1. Click the install button above and follow the flow, or go directly to your global MCP configuration file at `~/.cursor/mcp.json` and enter the code block below +2. In Tools & Integrations > MCP tools, click the pencil icon next to "github" +3. Replace `YOUR_GITHUB_PAT` with your actual [GitHub Personal Access Token](https://github.com/settings/tokens) +4. Save the file +5. Restart Cursor + +### Docker Configuration + +```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" + } + } + } +} +``` + +> **Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead. + +## Configuration Files + +- **Global (all projects)**: `~/.cursor/mcp.json` +- **Project-specific**: `.cursor/mcp.json` in project root + +## Verify Installation +1. Restart Cursor completely +2. Check for green dot in Settings → Tools & Integrations → MCP Tools +3. In chat/composer, check "Available Tools" +4. Test with: "List my GitHub repositories" + +## Troubleshooting + +### Remote Server Issues +- **Streamable HTTP not working**: Ensure you're using Cursor v0.48.0 or later +- **Authentication failures**: Verify PAT has correct scopes +- **Connection errors**: Check firewall/proxy settings + +### Local Server Issues +- **Docker errors**: Ensure Docker Desktop is running +- **Image pull failures**: Try `docker logout ghcr.io` then retry +- **Docker not found**: Install Docker Desktop and ensure it's running + +### General Issues +- **MCP not loading**: Restart Cursor completely after configuration +- **Invalid JSON**: Validate that json format is correct +- **Tools not appearing**: Check server shows green dot in MCP settings +- **Check logs**: Look for MCP-related errors in Cursor logs + +## Important Notes + +- **Docker image**: `ghcr.io/github/github-mcp-server` (official and supported) +- **npm package**: `@modelcontextprotocol/server-github` (deprecated as of April 2025 - no longer functional) +- **Cursor specifics**: Supports both project and global configurations, uses `mcpServers` key diff --git a/docs/installation-guides/install-other-copilot-ides.md b/docs/installation-guides/install-other-copilot-ides.md new file mode 100644 index 000000000..38b48bbbd --- /dev/null +++ b/docs/installation-guides/install-other-copilot-ides.md @@ -0,0 +1,265 @@ +# 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) + +### Requirements: +- **GitHub Copilot License**: Any Copilot plan (Free, Pro, Pro+, Business, Enterprise) for Copilot access +- **GitHub Account**: Individual GitHub account (organization/enterprise membership optional) for GitHub MCP server access +- **MCP Servers in Copilot Policy**: Organizations assigning Copilot seats must enable this policy for all MCP access in Copilot for VS Code and Copilot Coding Agent – all other Copilot IDEs will migrate to this policy in the coming months +- **Editor Preview Policy**: Organizations assigning Copilot seats must enable this policy for OAuth access while the Remote GitHub MCP Server is in public preview + +> **Note:** All Copilot IDEs now support the remote GitHub MCP server. VS Code offers OAuth authentication, while Visual Studio, JetBrains IDEs, Xcode, and Eclipse currently use PAT authentication with OAuth support coming soon. + +## Visual Studio + +Requires Visual Studio 2022 version 17.14 or later. + +### Remote Server (Recommended) + +The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required. + +#### Configuration +1. Go to **Tools** → **Options** → **GitHub** → **Copilot** → **MCP Servers** +2. Add this configuration: +```json +{ + "servers": { + "github": { + "url": "https://api.githubcopilot.com/mcp/", + "authorization_token": "Bearer YOUR_GITHUB_PAT" + } + } +} +``` +3. Restart Visual Studio + +### Local Server + +For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running. + +#### Configuration +1. Create an `.mcp.json` file in your solution directory +2. Add this configuration: +```json +{ + "inputs": [ + { + "id": "github_pat", + "description": "GitHub personal access token", + "type": "promptString", + "password": true + } + ], + "servers": { + "github": { + "type": "stdio", + "command": "docker", + "args": [ + "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", + "ghcr.io/github/github-mcp-server" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_pat}" + } + } + } +} +``` +3. Save the file and restart Visual Studio + +**Documentation:** [Visual Studio MCP Guide](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers?view=vs-2022) + +--- + +## JetBrains IDEs + +Agent mode and MCP support available in public preview across IntelliJ IDEA, PyCharm, WebStorm, and other JetBrains IDEs. + +### Remote Server (Recommended) + +The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required. + +> **Note**: OAuth authentication for the remote GitHub server is not yet supported in JetBrains IDEs. You must use a Personal Access Token (PAT). + +#### Configuration Steps +1. Install/update the GitHub Copilot plugin +2. Click **GitHub Copilot icon in the status bar** → **Edit Settings** → **Model Context Protocol** → **Configure** +3. Add configuration: +```json +{ + "servers": { + "github": { + "url": "https://api.githubcopilot.com/mcp/", + "requestInit": { + "headers": { + "Authorization": "Bearer YOUR_GITHUB_PAT" + } + } + } + } +} +``` +4. Press `Ctrl + S` or `Command + S` to save, or close the `mcp.json` file. The configuration should take effect immediately and restart all the MCP servers defined. You can restart the IDE if needed. + +### Local Server + +For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running. + +#### Configuration +```json +{ + "servers": { + "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" + } + } + } +} +``` + +**Documentation:** [JetBrains Copilot Guide](https://plugins.jetbrains.com/plugin/17718-github-copilot) + +--- + +## Xcode + +Agent mode and MCP support now available in public preview for Xcode. + +### Remote Server (Recommended) + +The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required. + +> **Note**: OAuth authentication for the remote GitHub server is not yet supported in Xcode. You must use a Personal Access Token (PAT). + +#### Configuration Steps +1. Install/update [GitHub Copilot for Xcode](https://github.com/github/CopilotForXcode) +2. Open **GitHub Copilot for Xcode app** → **Agent Mode** → **🛠️ Tool Picker** → **Edit Config** +3. Configure your MCP servers: +```json +{ + "servers": { + "github": { + "url": "https://api.githubcopilot.com/mcp/", + "requestInit": { + "headers": { + "Authorization": "Bearer YOUR_GITHUB_PAT" + } + } + } + } +} +``` + +### Local Server + +For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running. + +#### Configuration +```json +{ + "servers": { + "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" + } + } + } +} +``` + +**Documentation:** [Xcode Copilot Guide](https://devblogs.microsoft.com/xcode/github-copilot-exploring-agent-mode-and-mcp-support-in-public-preview-for-xcode/) + +--- + +## Eclipse + +MCP support available with Eclipse 2024-03+ and latest version of the GitHub Copilot plugin. + +### Remote Server (Recommended) + +The remote GitHub MCP server is hosted by GitHub and provides automatic updates with no local setup required. + +> **Note**: OAuth authentication for the remote GitHub server is not yet supported in Eclipse. You must use a Personal Access Token (PAT). + +#### Configuration Steps +1. Install GitHub Copilot extension from Eclipse Marketplace +2. Click the **GitHub Copilot icon** → **Edit Preferences** → **MCP** (under **GitHub Copilot**) +3. Add GitHub MCP server configuration: +```json +{ + "servers": { + "github": { + "url": "https://api.githubcopilot.com/mcp/", + "requestInit": { + "headers": { + "Authorization": "Bearer YOUR_GITHUB_PAT" + } + } + } + } +} +``` +4. Click the "Apply and Close" button in the preference dialog and the configuration will take effect automatically. + +### Local Server + +For users who prefer to run the GitHub MCP server locally. Requires Docker installed and running. + +#### Configuration +```json +{ + "servers": { + "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" + } + } + } +} +``` + +**Documentation:** [Eclipse Copilot plugin](https://marketplace.eclipse.org/content/github-copilot) + +--- + +## GitHub Personal Access Token + +For PAT authentication, see our [Personal Access Token documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) for setup instructions. + +--- + +## Usage + +After setup: +1. Restart your IDE completely +2. Open Agent mode in Copilot Chat +3. Try: *"List recent issues in this repository"* +4. Copilot can now access GitHub data and perform repository operations + +--- + +## Troubleshooting + +- **Connection issues**: Verify GitHub PAT permissions and IDE version compatibility +- **Authentication errors**: Check if your organization has enabled the MCP policy for Copilot +- **Tools not appearing**: Restart IDE after configuration changes and check error logs +- **Local server issues**: Ensure Docker is running for Docker-based setups diff --git a/docs/installation-guides/install-windsurf.md b/docs/installation-guides/install-windsurf.md new file mode 100644 index 000000000..8793e2edb --- /dev/null +++ b/docs/installation-guides/install-windsurf.md @@ -0,0 +1,107 @@ +# Install GitHub MCP Server in Windsurf + +## Prerequisites +1. Windsurf IDE installed (latest version) +2. [GitHub Personal Access Token](https://github.com/settings/personal-access-tokens/new) with appropriate scopes +3. For local installation: [Docker](https://www.docker.com/) installed and running + +## Remote Server Setup (Recommended) + +The remote GitHub MCP server is hosted by GitHub at `https://api.githubcopilot.com/mcp/` and supports Streamable HTTP protocol. Windsurf currently supports PAT authentication only. + +### Streamable HTTP Configuration +Windsurf supports Streamable HTTP servers with a `serverUrl` field: + +```json +{ + "mcpServers": { + "github": { + "serverUrl": "https://api.githubcopilot.com/mcp/", + "headers": { + "Authorization": "Bearer YOUR_GITHUB_PAT" + } + } + } +} +``` + +## Local Server Setup + +### Docker Installation (Required) +**Important**: The npm package `@modelcontextprotocol/server-github` is no longer supported as of April 2025. Use the official Docker image `ghcr.io/github/github-mcp-server` instead. + +```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" + } + } + } +} +``` + +## Installation Steps + +### Via Plugin Store +1. Open Windsurf and navigate to Cascade +2. Click the **Plugins** icon or **hammer icon** (🔨) +3. Search for "GitHub MCP Server" +4. Click **Install** and enter your PAT when prompted +5. Click **Refresh** (🔄) + +### Manual Configuration +1. Click the hammer icon (🔨) in Cascade +2. Click **Configure** to open `~/.codeium/windsurf/mcp_config.json` +3. Add your chosen configuration from above +4. Save the file +5. Click **Refresh** (🔄) in the MCP toolbar + +## Configuration Details + +- **File path**: `~/.codeium/windsurf/mcp_config.json` +- **Scope**: Global configuration only (no per-project support) +- **Format**: Must be valid JSON (use a linter to verify) + +## Verification + +After installation: +1. Look for "1 available MCP server" in the MCP toolbar +2. Click the hammer icon to see available GitHub tools +3. Test with: "List my GitHub repositories" +4. Check for green dot next to the server name + +## Troubleshooting + +### Remote Server Issues +- **Authentication failures**: Verify PAT has correct scopes and hasn't expired +- **Connection errors**: Check firewall/proxy settings for HTTPS connections +- **Streamable HTTP not working**: Ensure you're using the correct `serverUrl` field format + +### Local Server Issues +- **Docker errors**: Ensure Docker Desktop is running +- **Image pull failures**: Try `docker logout ghcr.io` then retry +- **Docker not found**: Install Docker Desktop and ensure it's running + +### General Issues +- **Invalid JSON**: Validate with [jsonlint.com](https://jsonlint.com) +- **Tools not appearing**: Restart Windsurf completely +- **Check logs**: `~/.codeium/windsurf/logs/` + +## Important Notes + +- **Official repository**: [github/github-mcp-server](https://github.com/github/github-mcp-server) +- **Remote server URL**: `https://api.githubcopilot.com/mcp/` +- **Docker image**: `ghcr.io/github/github-mcp-server` (official and supported) +- **npm package**: `@modelcontextprotocol/server-github` (deprecated as of April 2025 - no longer functional) +- **Windsurf limitations**: No environment variable interpolation, global config only diff --git a/docs/policies-and-governance.md b/docs/policies-and-governance.md new file mode 100644 index 000000000..d7f52212a --- /dev/null +++ b/docs/policies-and-governance.md @@ -0,0 +1,216 @@ +# Policies & Governance for the GitHub MCP Server + +Organizations and enterprises have several existing control mechanisms for the GitHub MCP server on GitHub.com: +- MCP servers in Copilot Policy +- Copilot Editor Preview Policy (temporary) +- OAuth App Access Policies +- GitHub App Installation +- Personal Access Token (PAT) policies +- SSO Enforcement + +This document outlines how these policies apply to different deployment modes, authentication methods, and host applications – while providing guidance for managing GitHub MCP Server access across your organization. + +## How the GitHub MCP Server Works + +The GitHub MCP Server provides access to GitHub resources and capabilities through a standardized protocol, with flexible deployment and authentication options tailored to different use cases. It supports two deployment modes, both built on the same underlying codebase. + +### 1. Local GitHub MCP Server +* **Runs:** Locally alongside your IDE or application +* **Authentication & Controls:** Requires Personal Access Tokens (PATs). Users must generate and configure a PAT to connect. Managed via [PAT policies](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#restricting-access-by-personal-access-tokens). + * Can optionally use GitHub App installation tokens when embedded in a GitHub App-based tool (rare). + +**Supported SKUs:** Can be used with GitHub Enterprise Server (GHES) and GitHub Enterprise Cloud (GHEC). + +### 2. Remote GitHub MCP Server +* **Runs:** As a hosted service accessed over the internet +* **Authentication & Controls:** (determined by the chosen authentication method) + * **GitHub App Installation Tokens:** Uses a signed JWT to request installation access tokens (similar to the OAuth 2.0 client credentials flow) to operate as the application itself. Provides granular control via [installation](https://docs.github.com/apps/using-github-apps/installing-a-github-app-from-a-third-party#requirements-to-install-a-github-app), [permissions](https://docs.github.com/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app) and [repository access controls](https://docs.github.com/apps/using-github-apps/reviewing-and-modifying-installed-github-apps#modifying-repository-access). + * **OAuth Authorization Code Flow:** Uses the standard OAuth 2.0 Authorization Code flow. Controlled via [OAuth App access policies](https://docs.github.com/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) for OAuth apps. For GitHub Apps that sign in ([are authorized by](https://docs.github.com/apps/using-github-apps/authorizing-github-apps)) a user, control access to your organization via [installation](https://docs.github.com/apps/using-github-apps/installing-a-github-app-from-a-third-party#requirements-to-install-a-github-app). + * **Personal Access Tokens (PATs):** Managed via [PAT policies](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization#restricting-access-by-personal-access-tokens). + * **SSO enforcement:** Applies when using OAuth Apps, GitHub Apps, and PATs to access resources in organizations and enterprises with SSO enabled. Acts as an overlay control. Users must have a valid SSO session for your organization or enterprise when signing into the app or creating the token in order for the token to access your resources. Learn more in the [SSO documentation](https://docs.github.com/enterprise-cloud@latest/authentication/authenticating-with-single-sign-on/about-authentication-with-single-sign-on#about-oauth-apps-github-apps-and-sso). + +**Supported Platforms:** Currently available only on GitHub Enterprise Cloud (GHEC). Remote hosting for GHES is not supported at this time. + +> **Note:** This does not apply to the Local GitHub MCP Server, which uses PATs and does not rely on GitHub App installations. + +#### Enterprise Install Considerations + +- When using the Remote GitHub MCP Server, if authenticating with OAuth instead of PAT, each host application must have a registered GitHub App (or OAuth App) to authenticate on behalf of the user. +- Enterprises may choose to install these apps in multiple organizations (e.g., per team or department) to scope access narrowly, or at the enterprise level to centralize access control across all child organizations. +- Enterprise installation is only supported for GitHub Apps. OAuth Apps can only be installed on a per organization basis in multi-org enterprises. + +### Security Principles for Both Modes +* **Authentication:** Required for all operations, no anonymous access +* **Authorization:** Access enforced by GitHub's native permission model. Users and apps cannot use an MCP server to access more resources than they could otherwise access normally via the API. +* **Communication:** All data transmitted over HTTPS with optional SSE for real-time updates +* **Rate Limiting:** Subject to GitHub API rate limits based on authentication method +* **Token Storage:** Tokens should be stored securely using platform-appropriate credential storage +* **Audit Trail:** All underlying API calls are logged in GitHub's audit log when available + +For integration architecture and implementation details, see the [Host Integration Guide](https://github.com/github/github-mcp-server/blob/main/docs/host-integration.md). + +## Where It's Used + +The GitHub MCP server can be accessed in various environments (referred to as "host" applications): +* **First-party Hosts:** GitHub Copilot in VS Code, Visual Studio, JetBrains, Eclipse, and Xcode with integrated MCP support, as well as Copilot Coding Agent. +* **Third-party Hosts:** Editors outside the GitHub ecosystem, such as Claude, Cursor, Windsurf, and Cline, that support connecting to MCP servers, as well as AI chat applications like Claude Desktop and other AI assistants that connect to MCP servers to fetch GitHub context or execute write actions. + +## What It Can Access + +The MCP server accesses GitHub resources based on the permissions granted through the chosen authentication method (PAT, OAuth, or GitHub App). These may include: +* Repository contents (files, branches, commits) +* Issues and pull requests +* Organization and team metadata +* User profile information +* Actions workflow runs, logs, and statuses +* Security and vulnerability alerts (if explicitly granted) + +Access is always constrained by GitHub's public API permission model and the authenticated user's privileges. + +## Control Mechanisms + +### 1. Copilot Editors (first-party) → MCP Servers in Copilot Policy + +* **Policy:** MCP servers in Copilot +* **Location:** Enterprise/Org → Policies → Copilot +* **What it controls:** When disabled, **completely blocks all GitHub MCP Server access** (both remote and local) for affected Copilot editors. Currently applies to VS Code and Copilot Coding Agent, with more Copilot editors expected to migrate to this policy over time. +* **Impact when disabled:** Host applications governed by this policy cannot connect to the GitHub MCP Server through any authentication method (OAuth, PAT, or GitHub App). +* **What it does NOT affect:** + * MCP support in Copilot on IDEs that are still in public preview (Visual Studio, JetBrains, Xcode, Eclipse) + * Third-party IDE or host apps (like Claude, Cursor, Windsurf) not governed by GitHub's Copilot policies + * Community-authored MCP servers using GitHub's public APIs + +> **Important:** This policy provides comprehensive control over GitHub MCP Server access in Copilot editors. When disabled, users in affected applications will not be able to use the GitHub MCP Server regardless of deployment mode (remote or local) or authentication method. + +#### Temporary: Copilot Editor Preview Policy + +* **Policy:** Editor Preview Features +* **Status:** Being phased out as editors migrate to the "MCP servers in Copilot" policy above, and once the Remote GitHub MCP server goes GA +* **What it controls:** When disabled, prevents remaining Copilot editors from using the Remote GitHub MCP Server through OAuth connections in all first-party and third-party host applications (does not affect local deployments or PAT authentication) + +> **Note:** As Copilot editors migrate from the "Copilot Editor Preview" policy to the "MCP servers in Copilot" policy, the scope of control becomes more centralized, blocking both remote and local GitHub MCP Server access when disabled. Access in third-party hosts is governed separately by OAuth App, GitHub App, and PAT policies. + +### 2. Third-Party Host Apps (e.g., Claude, Cursor, Windsurf) → OAuth App or GitHub App Controls + +#### a. OAuth App Access Policies +* **Control Mechanism:** OAuth App access restrictions +* **Location:** Org → Settings → Third-party Access → OAuth app policy +* **How it works:** + * Organization admins must approve OAuth App requests before host apps can access organization data + * Only applies when the host registers an OAuth App AND the user connects via OAuth 2.0 flow + +#### b. GitHub App Installation +* **Control Mechanism:** GitHub App installation and permissions +* **Location:** Org → Settings → Third-party Access → GitHub Apps +* **What it controls:** Organization admins must install the app, select repositories, and grant permissions before the app can access organization-owned data or resources through the Remote GitHub Server. +* **How it works:** + * Organization admins must install the app, specify repositories, and approve permissions + * Only applies when the host registers a GitHub App AND the user authenticates through that flow + +> **Note:** The authentication methods available depend on what your host application supports. While PATs work with any remote MCP-compatible host, OAuth and GitHub App authentication are only available if the host has registered an app with GitHub. Check your host application's documentation or support for more info. + +### 3. PAT Access from Any Host → PAT Restrictions + +* **Types:** Fine-grained PATs (recommended) and Classic tokens (legacy) +* **Location:** + * User level: [Personal Settings → Developer Settings → Personal Access Tokens](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) + * Enterprise/Organization level: [Enterprise/Organization → Settings → Personal Access Tokens](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) (to control PAT creation/access policies) +* **What it controls:** Applies to all host apps and both local & remote GitHub MCP servers when users authenticate via PAT. +* **How it works:** Access limited to the repositories and scopes selected on the token. +* **Limitations:** PATs do not adhere to OAuth App policies and GitHub App installation controls. They are user-scoped and not recommended for production automation. +* **Organization controls:** + * Classic PATs: Can be completely disabled organization-wide + * Fine-grained PATs: Cannot be disabled but require explicit approval for organization access + +> **Recommendation:** We recommend using fine-grained PATs over classic tokens. Classic tokens have broader scopes and can be disabled in organization settings. + +### 4. SSO Enforcement (overlay control) + +* **Location:** Enterprise/Organization → SSO settings +* **What it controls:** OAuth tokens and PATs must map to a recent SSO login to access SSO-protected organization data. +* **How it works:** Applies to ALL host apps when using OAuth or PATs. + +> **Exception:** Does NOT apply to GitHub App installation tokens (these are installation-scoped, not user-scoped) + +## Current Limitations + +While the GitHub MCP Server provides dynamic tooling and capabilities, the following enterprise governance features are not yet available: + +### Single Enterprise/Organization-Level Toggle + +GitHub does not provide a single toggle that blocks all GitHub MCP server traffic for every user. Admins can achieve equivalent coverage by combining the controls shown here: +* **First-party Copilot Editors (GitHub Copilot in VS Code, Visual Studio, JetBrains, Eclipse):** + * Disable the "MCP servers in Copilot" policy for comprehensive control + * Or disable the Editor Preview Features policy (for editors still using the legacy policy) +* **Third-party Host Applications:** + * Configure OAuth app restrictions + * Manage GitHub App installations +* **PAT Access in All Host Applications:** + * Implement fine-grained PAT policies (applies to both remote and local deployments) + +### MCP-Specific Audit Logging + +At present, MCP traffic appears in standard GitHub audit logs as normal API calls. Purpose-built logging for MCP is on the roadmap, but the following views are not yet available: +* Real-time list of active MCP connections +* Dashboards showing granular MCP usage data, like tools or host apps +* Granular, action-by-action audit logs + +Until those arrive, teams can continue to monitor MCP activity through existing API log entries and OAuth/GitHub App events. + +## Security Best Practices + +### For Organizations + +**GitHub App Management** +* Review [GitHub App installations](https://docs.github.com/apps/using-github-apps/reviewing-and-modifying-installed-github-apps) regularly +* Audit permissions and repository access +* Monitor installation events in audit logs +* Document approved GitHub Apps and their business purposes + +**OAuth App Governance** +* Manage [OAuth App access policies](https://docs.github.com/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) +* Establish review processes for approved applications +* Monitor which third-party applications are requesting access +* Maintain an allowlist of approved OAuth applications + +**Token Management** +* Mandate fine-grained Personal Access Tokens over classic tokens +* Establish token expiration policies (90 days maximum recommended) +* Implement automated token rotation reminders +* Review and enforce [PAT restrictions](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) at the appropriate level + +### For Developers and Users + +**Authentication Security** +* Prioritize OAuth 2.0 flows over long-lived tokens +* Prefer fine-grained PATs to PATs (Classic) +* Store tokens securely using platform-appropriate credential management +* Store credentials in secret management systems, not source code + +**Scope Minimization** +* Request only the minimum required scopes for your use case +* Regularly review and revoke unused token permissions +* Use repository-specific access instead of organization-wide access +* Document why each permission is needed for your integration + +## Resources + +**MCP:** +* [Model Context Protocol Specification](https://modelcontextprotocol.io/specification/2025-03-26) +* [Model Context Protocol Authorization](https://modelcontextprotocol.io/specification/draft/basic/authorization) + +**GitHub Governance & Controls:** +* [Managing OAuth App Access](https://docs.github.com/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) +* [GitHub App Permissions](https://docs.github.com/apps/creating-github-apps/registering-a-github-app/choosing-permissions-for-a-github-app) +* [Updating permissions for a GitHub App](https://docs.github.com/apps/using-github-apps/approving-updated-permissions-for-a-github-app) +* [PAT Policies](https://docs.github.com/organizations/managing-programmatic-access-to-your-organization/setting-a-personal-access-token-policy-for-your-organization) +* [Fine-grained PATs](https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens) +* [Setting a PAT policy for your organization](https://docs.github.com/organizations/managing-oauth-access-to-your-organizations-data/about-oauth-app-access-restrictions) + +--- + +**Questions or Feedback?** + +Open an [issue in the github-mcp-server repository](https://github.com/github/github-mcp-server/issues) with the label "policies & governance" attached. + +This document reflects GitHub MCP Server policies as of July 2025. Policies and capabilities continue to evolve based on customer feedback and security best practices. diff --git a/docs/remote-server.md b/docs/remote-server.md new file mode 100644 index 000000000..49794c605 --- /dev/null +++ b/docs/remote-server.md @@ -0,0 +1,52 @@ +# Remote GitHub MCP Server 🚀 + +[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D&quality=insiders) + +Easily connect to the GitHub MCP Server using the hosted version – no local setup or runtime required. + +**URL:** https://api.githubcopilot.com/mcp/ + +## About + +The remote GitHub MCP server is built using this repository as a library, and binding it into GitHub server infrastructure with an internal repository. You can open issues and propose changes in this repository, and we regularly update the remote server to include the latest version of this code. + +The remote server has [additional tools](#toolsets-only-available-in-the-remote-mcp-server) that are not available in the local MCP server, such as the `create_pull_request_with_copilot` tool for invoking Copilot coding agent. + +## Remote MCP Toolsets + +Below is a table of available toolsets for the remote GitHub MCP Server. Each toolset is provided as a distinct URL so you can mix and match to create the perfect combination of tools for your use-case. Add `/readonly` to the end of any URL to restrict the tools in the toolset to only those that enable read access. We also provide the option to use [headers](#headers) instead. + + +| Name | Description | API URL | 1-Click Install (VS Code) | Read-only Link | 1-Click Read-only Install (VS Code) | +|----------------|--------------------------------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| all | All available GitHub MCP tools | https://api.githubcopilot.com/mcp/ | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D) | [read-only](https://api.githubcopilot.com/mcp/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Freadonly%22%7D) | +| Actions | GitHub Actions workflows and CI/CD operations | https://api.githubcopilot.com/mcp/x/actions | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-actions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Factions%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/actions/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-actions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Factions%2Freadonly%22%7D) | +| Code Security | Code security related tools, such as GitHub Code Scanning | https://api.githubcopilot.com/mcp/x/code_security | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/code_security/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%2Freadonly%22%7D) | +| Dependabot | Dependabot tools | https://api.githubcopilot.com/mcp/x/dependabot | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-dependabot&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdependabot%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/dependabot/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-dependabot&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdependabot%2Freadonly%22%7D) | +| Discussions | GitHub Discussions related tools | https://api.githubcopilot.com/mcp/x/discussions | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-discussions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdiscussions%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/discussions/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-discussions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fdiscussions%2Freadonly%22%7D) | +| Experiments | Experimental features that are not considered stable yet | https://api.githubcopilot.com/mcp/x/experiments | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-experiments&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fexperiments%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/experiments/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-experiments&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fexperiments%2Freadonly%22%7D) | +| Issues | GitHub Issues related tools | https://api.githubcopilot.com/mcp/x/issues | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/issues/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%2Freadonly%22%7D) | +| Notifications | GitHub Notifications related tools | https://api.githubcopilot.com/mcp/x/notifications | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-notifications&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fnotifications%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/notifications/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-notifications&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fnotifications%2Freadonly%22%7D) | +| Organizations | GitHub Organization related tools | https://api.githubcopilot.com/mcp/x/orgs | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-orgs&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Forgs%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/orgs/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-orgs&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Forgs%2Freadonly%22%7D) | +| Pull Requests | GitHub Pull Request related tools | https://api.githubcopilot.com/mcp/x/pull_requests | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-pull_requests&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fpull_requests%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/pull_requests/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-pull_requests&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fpull_requests%2Freadonly%22%7D) | +| Repositories | GitHub Repository related tools | https://api.githubcopilot.com/mcp/x/repos | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-repos&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Frepos%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/repos/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-repos&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Frepos%2Freadonly%22%7D) | +| Secret Protection | Secret protection related tools, such as GitHub Secret Scanning | https://api.githubcopilot.com/mcp/x/secret_protection | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-secret_protection&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fsecret_protection%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/secret_protection/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-secret_protection&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fsecret_protection%2Freadonly%22%7D) | +| Users | GitHub User related tools | https://api.githubcopilot.com/mcp/x/users | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-users&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fusers%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/users/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-users&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fusers%2Freadonly%22%7D) | + + + +### Additional _Remote_ Server Toolsets + +These toolsets are only available in the remote GitHub MCP Server and are not included in the local MCP server. + +| Name | Description | API URL | 1-Click Install (VS Code) | Read-only Link | 1-Click Read-only Install (VS Code) | +| -------------------- | --------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Copilot coding agent | Perform task with GitHub Copilot coding agent | https://api.githubcopilot.com/mcp/x/copilot | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-copilot&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcopilot%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/copilot/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-copilot&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcopilot%2Freadonly%22%7D) | + +### Headers + +You can configure toolsets and readonly mode by providing HTTP headers in your server configuration. + +The headers are: +- `X-MCP-Toolsets=,...` +- `X-MCP-Readonly=true` diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 000000000..dbdc3e080 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,34 @@ +# Testing + +This project uses a combination of unit tests and end-to-end (e2e) tests to ensure correctness and stability. + +## Unit Testing Patterns + +- Unit tests are located alongside implementation, with filenames ending in `_test.go`. +- Currently the preference is to use internal tests i.e. test files do not have `_test` package suffix. +- Tests use [testify](https://github.com/stretchr/testify) for assertions and require statements. Use `require` when continuing the test is not meaningful, for example it is almost never correct to continue after an error expectation. +- Mocking is performed using [go-github-mock](https://github.com/migueleliasweb/go-github-mock) or `githubv4mock` for simulating GitHub rest and GQL API responses. +- Each tool's schema is snapshotted and checked for changes using the `toolsnaps` utility (see below). +- Tests are designed to be explicit and verbose to aid maintainability and clarity. +- Handler unit tests should take the form of: + 1. Test tool snapshot + 1. Very important expectations against the schema (e.g. `ReadOnly` annotation) + 1. Behavioural tests in table-driven form + +## 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. + +## toolsnaps: Tool Schema Snapshots + +- The `toolsnaps` utility ensures that the JSON schema for each tool does not change unexpectedly. +- Snapshots are stored in `__toolsnaps__/*.snap` files , where `*` represents the name of the tool +- When running tests, the current tool schema is compared to the snapshot. If there is a difference, the test will fail and show a diff. +- If you intentionally change a tool's schema, update the snapshots by running tests with the environment variable: `UPDATE_TOOLSNAPS=true go test ./...` +- In CI (when `GITHUB_ACTIONS=true`), missing snapshots will cause a test failure to ensure snapshots are always +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). diff --git a/e2e/e2e_test.go b/e2e/e2e_test.go index 71bd5a8ab..64c5729ba 100644 --- a/e2e/e2e_test.go +++ b/e2e/e2e_test.go @@ -4,7 +4,6 @@ package e2e_test import ( "context" - "encoding/base64" "encoding/json" "fmt" "net/http" @@ -19,7 +18,7 @@ import ( "github.com/github/github-mcp-server/internal/ghmcp" "github.com/github/github-mcp-server/pkg/github" "github.com/github/github-mcp-server/pkg/translations" - gogithub "github.com/google/go-github/v69/github" + gogithub "github.com/google/go-github/v73/github" mcpClient "github.com/mark3labs/mcp-go/client" "github.com/mark3labs/mcp-go/mcp" "github.com/stretchr/testify/require" @@ -508,17 +507,14 @@ func TestFileDeletion(t *testing.T) { require.NoError(t, err, "expected to call 'get_file_contents' tool successfully") require.False(t, resp.IsError, fmt.Sprintf("expected result not to be an error: %+v", resp)) - textContent, ok = resp.Content[0].(mcp.TextContent) - require.True(t, ok, "expected content to be of type TextContent") + embeddedResource, ok := resp.Content[1].(mcp.EmbeddedResource) + require.True(t, ok, "expected content to be of type EmbeddedResource") - var trimmedGetFileText struct { - Content string `json:"content"` - } - err = json.Unmarshal([]byte(textContent.Text), &trimmedGetFileText) - require.NoError(t, err, "expected to unmarshal text content successfully") - b, err := base64.StdEncoding.DecodeString(trimmedGetFileText.Content) - require.NoError(t, err, "expected to decode base64 content successfully") - require.Equal(t, fmt.Sprintf("Created by e2e test %s", t.Name()), string(b), "expected file content to match") + // raw api + textResource, ok := embeddedResource.Resource.(mcp.TextResourceContents) + require.True(t, ok, "expected embedded resource to be of type TextResourceContents") + + require.Equal(t, fmt.Sprintf("Created by e2e test %s", t.Name()), textResource.Text, "expected file content to match") // Delete the file deleteFileRequest := mcp.CallToolRequest{} @@ -703,17 +699,14 @@ func TestDirectoryDeletion(t *testing.T) { require.NoError(t, err, "expected to call 'get_file_contents' tool successfully") require.False(t, resp.IsError, fmt.Sprintf("expected result not to be an error: %+v", resp)) - textContent, ok = resp.Content[0].(mcp.TextContent) - require.True(t, ok, "expected content to be of type TextContent") + embeddedResource, ok := resp.Content[1].(mcp.EmbeddedResource) + require.True(t, ok, "expected content to be of type EmbeddedResource") - var trimmedGetFileText struct { - Content string `json:"content"` - } - err = json.Unmarshal([]byte(textContent.Text), &trimmedGetFileText) - require.NoError(t, err, "expected to unmarshal text content successfully") - b, err := base64.StdEncoding.DecodeString(trimmedGetFileText.Content) - require.NoError(t, err, "expected to decode base64 content successfully") - require.Equal(t, fmt.Sprintf("Created by e2e test %s", t.Name()), string(b), "expected file content to match") + // raw api + textResource, ok := embeddedResource.Resource.(mcp.TextResourceContents) + require.True(t, ok, "expected embedded resource to be of type TextResourceContents") + + require.Equal(t, fmt.Sprintf("Created by e2e test %s", t.Name()), textResource.Text, "expected file content to match") // Delete the directory containing the file deleteFileRequest := mcp.CallToolRequest{} @@ -1345,7 +1338,7 @@ func TestPullRequestReviewCommentSubmit(t *testing.T) { // Add a file review comment addFileReviewCommentRequest := mcp.CallToolRequest{} - addFileReviewCommentRequest.Params.Name = "add_pull_request_review_comment_to_pending_review" + addFileReviewCommentRequest.Params.Name = "add_comment_to_pending_review" addFileReviewCommentRequest.Params.Arguments = map[string]any{ "owner": currentOwner, "repo": repoName, @@ -1357,12 +1350,12 @@ func TestPullRequestReviewCommentSubmit(t *testing.T) { t.Logf("Adding file review comment to pull request in %s/%s...", currentOwner, repoName) resp, err = mcpClient.CallTool(ctx, addFileReviewCommentRequest) - require.NoError(t, err, "expected to call 'add_pull_request_review_comment_to_pending_review' tool successfully") + require.NoError(t, err, "expected to call 'add_comment_to_pending_review' tool successfully") require.False(t, resp.IsError, fmt.Sprintf("expected result not to be an error: %+v", resp)) // Add a single line review comment addSingleLineReviewCommentRequest := mcp.CallToolRequest{} - addSingleLineReviewCommentRequest.Params.Name = "add_pull_request_review_comment_to_pending_review" + addSingleLineReviewCommentRequest.Params.Name = "add_comment_to_pending_review" addSingleLineReviewCommentRequest.Params.Arguments = map[string]any{ "owner": currentOwner, "repo": repoName, @@ -1377,12 +1370,12 @@ func TestPullRequestReviewCommentSubmit(t *testing.T) { t.Logf("Adding single line review comment to pull request in %s/%s...", currentOwner, repoName) resp, err = mcpClient.CallTool(ctx, addSingleLineReviewCommentRequest) - require.NoError(t, err, "expected to call 'add_pull_request_review_comment_to_pending_review' tool successfully") + require.NoError(t, err, "expected to call 'add_comment_to_pending_review' tool successfully") require.False(t, resp.IsError, fmt.Sprintf("expected result not to be an error: %+v", resp)) // Add a multiline review comment addMultilineReviewCommentRequest := mcp.CallToolRequest{} - addMultilineReviewCommentRequest.Params.Name = "add_pull_request_review_comment_to_pending_review" + addMultilineReviewCommentRequest.Params.Name = "add_comment_to_pending_review" addMultilineReviewCommentRequest.Params.Arguments = map[string]any{ "owner": currentOwner, "repo": repoName, @@ -1399,7 +1392,7 @@ func TestPullRequestReviewCommentSubmit(t *testing.T) { t.Logf("Adding multi line review comment to pull request in %s/%s...", currentOwner, repoName) resp, err = mcpClient.CallTool(ctx, addMultilineReviewCommentRequest) - require.NoError(t, err, "expected to call 'add_pull_request_review_comment_to_pending_review' tool successfully") + require.NoError(t, err, "expected to call 'add_comment_to_pending_review' tool successfully") require.False(t, resp.IsError, fmt.Sprintf("expected result not to be an error: %+v", resp)) // Submit the review diff --git a/go.mod b/go.mod index 5c9bc081f..3df6bf3d5 100644 --- a/go.mod +++ b/go.mod @@ -3,8 +3,9 @@ module github.com/github/github-mcp-server go 1.23.7 require ( - github.com/google/go-github/v69 v69.2.0 - github.com/mark3labs/mcp-go v0.28.0 + github.com/google/go-github/v73 v73.0.0 + github.com/josephburnett/jd v1.9.2 + github.com/mark3labs/mcp-go v0.32.0 github.com/migueleliasweb/go-github-mock v1.3.0 github.com/sirupsen/logrus v1.9.3 github.com/spf13/cobra v1.9.1 @@ -12,10 +13,20 @@ require ( github.com/stretchr/testify v1.10.0 ) +require ( + github.com/go-openapi/jsonpointer v0.19.5 // indirect + github.com/go-openapi/swag v0.21.1 // indirect + github.com/josharian/intern v1.0.0 // indirect + github.com/mailru/easyjson v0.7.7 // indirect + github.com/yudai/golcs v0.0.0-20170316035057-ecda9a501e82 // indirect + golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 // indirect + gopkg.in/yaml.v2 v2.4.0 // indirect +) + require ( github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect github.com/fsnotify/fsnotify v1.8.0 // indirect - github.com/go-viper/mapstructure/v2 v2.2.1 + github.com/go-viper/mapstructure/v2 v2.3.0 github.com/google/go-github/v71 v71.0.0 // indirect github.com/google/go-querystring v1.1.0 // indirect github.com/google/uuid v1.6.0 // indirect @@ -30,7 +41,7 @@ require ( github.com/sourcegraph/conc v0.3.0 // indirect github.com/spf13/afero v1.14.0 // indirect github.com/spf13/cast v1.7.1 // indirect - github.com/spf13/pflag v1.0.6 // indirect + github.com/spf13/pflag v1.0.6 github.com/subosito/gotenv v1.6.0 // indirect github.com/yosida95/uritemplate/v3 v3.0.2 // indirect go.uber.org/multierr v1.11.0 // indirect diff --git a/go.sum b/go.sum index 6d3d29760..d77cdf0d9 100644 --- a/go.sum +++ b/go.sum @@ -1,4 +1,5 @@ github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g= +github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E= github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38= github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM= @@ -7,15 +8,20 @@ github.com/frankban/quicktest v1.14.6 h1:7Xjx+VpznH+oBnejlPUj8oUpdxnVs4f8XU8WnHk github.com/frankban/quicktest v1.14.6/go.mod h1:4ptaffx2x8+WTWXmUCuVU6aPUX1/Mz7zb5vbUoiM6w0= github.com/fsnotify/fsnotify v1.8.0 h1:dAwr6QBTBZIkG8roQaJjGof0pp0EeF+tNV7YBP3F/8M= github.com/fsnotify/fsnotify v1.8.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0= -github.com/go-viper/mapstructure/v2 v2.2.1 h1:ZAaOCxANMuZx5RCeg0mBdEZk7DZasvvZIxtHqx8aGss= -github.com/go-viper/mapstructure/v2 v2.2.1/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM= +github.com/go-openapi/jsonpointer v0.19.5 h1:gZr+CIYByUqjcgeLXnQu2gHYQC9o73G2XUeOFYEICuY= +github.com/go-openapi/jsonpointer v0.19.5/go.mod h1:Pl9vOtqEWErmShwVjC8pYs9cog34VGT37dQOVbmoatg= +github.com/go-openapi/swag v0.19.5/go.mod h1:POnQmlKehdgb5mhVOsnJFsivZCEZ/vjK9gh66Z9tfKk= +github.com/go-openapi/swag v0.21.1 h1:wm0rhTb5z7qpJRHBdPOMuY4QjVUMbF6/kwoYeRAOrKU= +github.com/go-openapi/swag v0.21.1/go.mod h1:QYRuS/SOXUCsnplDa677K7+DxSOj6IPNl/eQntq43wQ= +github.com/go-viper/mapstructure/v2 v2.3.0 h1:27XbWsHIqhbdR5TIC911OfYvgSaW93HM+dX7970Q7jk= +github.com/go-viper/mapstructure/v2 v2.3.0/go.mod h1:oJDH3BJKyqBA2TXFhDsKDGDTlndYOZ6rGS0BRZIxGhM= github.com/google/go-cmp v0.5.2/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE= github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8= github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU= -github.com/google/go-github/v69 v69.2.0 h1:wR+Wi/fN2zdUx9YxSmYE0ktiX9IAR/BeePzeaUUbEHE= -github.com/google/go-github/v69 v69.2.0/go.mod h1:xne4jymxLR6Uj9b7J7PyTpkMYstEMMwGZa0Aehh1azM= github.com/google/go-github/v71 v71.0.0 h1:Zi16OymGKZZMm8ZliffVVJ/Q9YZreDKONCr+WUd0Z30= github.com/google/go-github/v71 v71.0.0/go.mod h1:URZXObp2BLlMjwu0O8g4y6VBneUj2bCHgnI8FfgZ51M= +github.com/google/go-github/v73 v73.0.0 h1:aR+Utnh+Y4mMkS+2qLQwcQ/cF9mOTpdwnzlaw//rG24= +github.com/google/go-github/v73 v73.0.0/go.mod h1:fa6w8+/V+edSU0muqdhCVY7Beh1M8F1IlQPZIANKIYw= github.com/google/go-querystring v1.1.0 h1:AnCroh3fv4ZBgVIf1Iwtovgjaw/GiKJo8M8yD/fhyJ8= github.com/google/go-querystring v1.1.0/go.mod h1:Kcdr2DB4koayq7X8pmAG4sNG59So17icRSOU623lUBU= github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0= @@ -24,6 +30,11 @@ github.com/gorilla/mux v1.8.0 h1:i40aqfkR1h2SlN9hojwV5ZA91wcXFOvkdNIeFDP5koI= github.com/gorilla/mux v1.8.0/go.mod h1:DVbg23sWSpFRCP0SfiEN6jmj59UnW/n46BH5rLB71So= github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8= github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw= +github.com/josephburnett/jd v1.9.2 h1:ECJRRFXCCqbtidkAHckHGSZm/JIaAxS1gygHLF8MI5Y= +github.com/josephburnett/jd v1.9.2/go.mod h1:bImDr8QXpxMb3SD+w1cDRHp97xP6UwI88xUAuxwDQfM= +github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8HmY= +github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y= +github.com/kr/pretty v0.1.0/go.mod h1:dAy3ld7l9f0ibDNOQOHHMYYIIbhfbHSm3C4ZsoJORNo= github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI= github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE= github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk= @@ -31,10 +42,16 @@ github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ= github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI= github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY= github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE= -github.com/mark3labs/mcp-go v0.28.0 h1:7yl4y5D1KYU2f/9Uxp7xfLIggfunHoESCRbrjcytcLM= -github.com/mark3labs/mcp-go v0.28.0/go.mod h1:rXqOudj/djTORU/ThxYx8fqEVj/5pvTuuebQ2RC7uk4= +github.com/mailru/easyjson v0.0.0-20190614124828-94de47d64c63/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc= +github.com/mailru/easyjson v0.0.0-20190626092158-b2ccc519800e/go.mod h1:C1wdFJiN94OJF2b5HbByQZoLdCWB1Yqtg26g4irojpc= +github.com/mailru/easyjson v0.7.6/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= +github.com/mailru/easyjson v0.7.7 h1:UGYAvKxe3sBsEDzO8ZeWOSlIQfWFlxbzLZe7hwFURr0= +github.com/mailru/easyjson v0.7.7/go.mod h1:xzfreul335JAWq5oZzymOObrkdz5UnU4kGfJJLY9Nlc= +github.com/mark3labs/mcp-go v0.32.0 h1:fgwmbfL2gbd67obg57OfV2Dnrhs1HtSdlY/i5fn7MU8= +github.com/mark3labs/mcp-go v0.32.0/go.mod h1:rXqOudj/djTORU/ThxYx8fqEVj/5pvTuuebQ2RC7uk4= github.com/migueleliasweb/go-github-mock v1.3.0 h1:2sVP9JEMB2ubQw1IKto3/fzF51oFC6eVWOOFDgQoq88= github.com/migueleliasweb/go-github-mock v1.3.0/go.mod h1:ipQhV8fTcj/G6m7BKzin08GaJ/3B5/SonRAkgrk0zCY= +github.com/niemeyer/pretty v0.0.0-20200227124842-a10e7caefd8e/go.mod h1:zD1mROLANZcx1PVRCS0qkT7pwLkGfwJo4zjcN/Tysno= github.com/pelletier/go-toml/v2 v2.2.3 h1:YmeHyLY8mFWbdkNWwpr+qIL2bEqT0o95WSdkNHvL12M= github.com/pelletier/go-toml/v2 v2.2.3/go.mod h1:MfCQTFTvCcUyyvvwm1+G6H/jORL20Xlb6rzQu9GuUkc= github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4= @@ -64,6 +81,8 @@ github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An github.com/spf13/viper v1.20.1 h1:ZMi+z/lvLyPSCoNtFCpqjy0S4kPbirhpTMwl8BkW9X4= github.com/spf13/viper v1.20.1/go.mod h1:P9Mdzt1zoHIG8m2eZQinpiBjo6kCmZSKBClNNqjJvu4= github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME= +github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI= +github.com/stretchr/testify v1.6.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg= github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA= github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY= @@ -71,8 +90,12 @@ github.com/subosito/gotenv v1.6.0 h1:9NlTDc1FTs4qu0DDq7AEtTPNw6SVm7uBMsUCUjABIf8 github.com/subosito/gotenv v1.6.0/go.mod h1:Dk4QP5c2W3ibzajGcXpNraDfq2IrhjMIvMSWPKKo0FU= github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4= github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4= +github.com/yudai/golcs v0.0.0-20170316035057-ecda9a501e82 h1:BHyfKlQyqbsFN5p3IfnEUduWvb9is428/nNb5L3U01M= +github.com/yudai/golcs v0.0.0-20170316035057-ecda9a501e82/go.mod h1:lgjkn3NuSvDfVJdfcVVdX+jpBxNmX4rDAzaS45IcYoM= go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0= go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y= +golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56 h1:2dVuKD2vS7b0QIHQbpyTISPd0LeHDbnYEryqj5Q1ug8= +golang.org/x/exp v0.0.0-20240719175910-8a7402abbf56/go.mod h1:M4RDyNAINzryxdtnbRXRL/OHtkFuWGRjvuhBJpk2IlY= golang.org/x/oauth2 v0.29.0 h1:WdYw2tdTK1S8olAzWHdgeqfy+Mtm9XNhv/xJsY65d98= golang.org/x/oauth2 v0.29.0/go.mod h1:onh5ek6nERTohokkhCD/y2cV4Do3fxFHFuAejCkRWT8= golang.org/x/sys v0.0.0-20220715151400-c0bba94af5f8/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg= @@ -84,8 +107,14 @@ golang.org/x/time v0.5.0 h1:o7cqy6amK/52YcAKIPlM3a+Fpj35zvRj2TP+e1xFSfk= golang.org/x/time v0.5.0/go.mod h1:3BpzKBy/shNhVucY/MWOyx10tF3SFh9QdLuxbVysPQM= golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0= gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/check.v1 v1.0.0-20180628173108-788fd7840127/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= +gopkg.in/check.v1 v1.0.0-20200227125254-8fa46927fb4f/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk= gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q= +gopkg.in/yaml.v2 v2.2.2/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI= +gopkg.in/yaml.v2 v2.4.0 h1:D8xgwECY7CYvx+Y2n4sBz93Jn9JRvxdiyyo8CTfuKaY= +gopkg.in/yaml.v2 v2.4.0/go.mod h1:RDklbk79AGWmwhnvt/jBztapEOGDOx6ZbXqjP6csGnQ= gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= +gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA= gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM= diff --git a/internal/ghmcp/server.go b/internal/ghmcp/server.go index a75a9e0cb..d993b130a 100644 --- a/internal/ghmcp/server.go +++ b/internal/ghmcp/server.go @@ -12,10 +12,12 @@ import ( "strings" "syscall" + "github.com/github/github-mcp-server/pkg/errors" "github.com/github/github-mcp-server/pkg/github" mcplog "github.com/github/github-mcp-server/pkg/log" + "github.com/github/github-mcp-server/pkg/raw" "github.com/github/github-mcp-server/pkg/translations" - gogithub "github.com/google/go-github/v69/github" + gogithub "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" "github.com/shurcooL/githubv4" @@ -89,6 +91,13 @@ func NewMCPServer(cfg MCPServerConfig) (*server.MCPServer, error) { hooks := &server.Hooks{ OnBeforeInitialize: []server.OnBeforeInitializeFunc{beforeInit}, + OnBeforeAny: []server.BeforeAnyHookFunc{ + func(ctx context.Context, _ any, _ mcp.MCPMethod, _ any) { + // Ensure the context is cleared of any previous errors + // as context isn't propagated through middleware + errors.ContextWithGitHubErrors(ctx) + }, + }, } ghServer := github.NewServer(cfg.Version, server.WithHooks(hooks)) @@ -112,27 +121,27 @@ func NewMCPServer(cfg MCPServerConfig) (*server.MCPServer, error) { return gqlClient, nil // closing over client } + getRawClient := func(ctx context.Context) (*raw.Client, error) { + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + return raw.NewClient(client, apiHost.rawURL), nil // closing over client + } + // Create default toolsets - toolsets, err := github.InitToolsets( - enabledToolsets, - cfg.ReadOnly, - getClient, - getGQLClient, - cfg.Translator, - ) + tsg := github.DefaultToolsetGroup(cfg.ReadOnly, getClient, getGQLClient, getRawClient, cfg.Translator) + err = tsg.EnableToolsets(enabledToolsets) + if err != nil { - return nil, fmt.Errorf("failed to initialize toolsets: %w", err) + return nil, fmt.Errorf("failed to enable toolsets: %w", err) } - context := github.InitContextToolset(getClient, cfg.Translator) - github.RegisterResources(ghServer, getClient, cfg.Translator) - - // Register the tools with the server - toolsets.RegisterTools(ghServer) - context.RegisterTools(ghServer) + // Register all mcp functionality with the server + tsg.RegisterAll(ghServer) if cfg.DynamicToolsets { - dynamic := github.InitDynamicToolset(ghServer, toolsets, cfg.Translator) + dynamic := github.InitDynamicToolset(ghServer, tsg, cfg.Translator) dynamic.RegisterTools(ghServer) } @@ -221,7 +230,8 @@ func RunStdioServer(cfg StdioServerConfig) error { loggedIO := mcplog.NewIOLogger(in, out, logrusLogger) in, out = loggedIO, loggedIO } - + // enable GitHub errors in the context + ctx := errors.ContextWithGitHubErrors(ctx) errC <- stdioServer.Listen(ctx, in, out) }() @@ -245,6 +255,7 @@ type apiHost struct { baseRESTURL *url.URL graphqlURL *url.URL uploadURL *url.URL + rawURL *url.URL } func newDotcomHost() (apiHost, error) { @@ -263,10 +274,16 @@ func newDotcomHost() (apiHost, error) { return apiHost{}, fmt.Errorf("failed to parse dotcom Upload URL: %w", err) } + rawURL, err := url.Parse("https://raw.githubusercontent.com/") + if err != nil { + return apiHost{}, fmt.Errorf("failed to parse dotcom Raw URL: %w", err) + } + return apiHost{ baseRESTURL: baseRestURL, graphqlURL: gqlURL, uploadURL: uploadURL, + rawURL: rawURL, }, nil } @@ -296,10 +313,16 @@ func newGHECHost(hostname string) (apiHost, error) { return apiHost{}, fmt.Errorf("failed to parse GHEC Upload URL: %w", err) } + rawURL, err := url.Parse(fmt.Sprintf("https://raw.%s/", u.Hostname())) + if err != nil { + return apiHost{}, fmt.Errorf("failed to parse GHEC Raw URL: %w", err) + } + return apiHost{ baseRESTURL: restURL, graphqlURL: gqlURL, uploadURL: uploadURL, + rawURL: rawURL, }, nil } @@ -323,11 +346,16 @@ func newGHESHost(hostname string) (apiHost, error) { if err != nil { return apiHost{}, fmt.Errorf("failed to parse GHES Upload URL: %w", err) } + rawURL, err := url.Parse(fmt.Sprintf("%s://%s/raw/", u.Scheme, u.Hostname())) + if err != nil { + return apiHost{}, fmt.Errorf("failed to parse GHES Raw URL: %w", err) + } return apiHost{ baseRESTURL: restURL, graphqlURL: gqlURL, uploadURL: uploadURL, + rawURL: rawURL, }, nil } diff --git a/internal/toolsnaps/toolsnaps.go b/internal/toolsnaps/toolsnaps.go new file mode 100644 index 000000000..89d02e1ee --- /dev/null +++ b/internal/toolsnaps/toolsnaps.go @@ -0,0 +1,81 @@ +// Package toolsnaps provides test utilities for ensuring json schemas for tools +// have not changed unexpectedly. +package toolsnaps + +import ( + "encoding/json" + "fmt" + "os" + "path/filepath" + + "github.com/josephburnett/jd/v2" +) + +// Test checks that the JSON schema for a tool has not changed unexpectedly. +// It compares the marshaled JSON of the provided tool against a stored snapshot file. +// If the UPDATE_TOOLSNAPS environment variable is set to "true", it updates the snapshot file instead. +// If the snapshot does not exist and not running in CI, it creates the snapshot file. +// If the snapshot does not exist and running in CI (GITHUB_ACTIONS="true"), it returns an error. +// If the snapshot exists, it compares the tool's JSON to the snapshot and returns an error if they differ. +// Returns an error if marshaling, reading, or comparing fails. +func Test(toolName string, tool any) error { + toolJSON, err := json.MarshalIndent(tool, "", " ") + if err != nil { + return fmt.Errorf("failed to marshal tool %s: %w", toolName, err) + } + + snapPath := fmt.Sprintf("__toolsnaps__/%s.snap", toolName) + + // If UPDATE_TOOLSNAPS is set, then we write the tool JSON to the snapshot file and exit + if os.Getenv("UPDATE_TOOLSNAPS") == "true" { + return writeSnap(snapPath, toolJSON) + } + + snapJSON, err := os.ReadFile(snapPath) //nolint:gosec // filepaths are controlled by the test suite, so this is safe. + // If the snapshot file does not exist, this must be the first time this test is run. + // We write the tool JSON to the snapshot file and exit. + if os.IsNotExist(err) { + // If we're running in CI, we will error if there is not snapshot because it's important that snapshots + // are committed alongside the tests, rather than just being constructed and not committed during a CI run. + if os.Getenv("GITHUB_ACTIONS") == "true" { + return fmt.Errorf("tool snapshot does not exist for %s. Please run the tests with UPDATE_TOOLSNAPS=true to create it", toolName) + } + + return writeSnap(snapPath, toolJSON) + } + + // Otherwise we will compare the tool JSON to the snapshot JSON + toolNode, err := jd.ReadJsonString(string(toolJSON)) + if err != nil { + return fmt.Errorf("failed to parse tool JSON for %s: %w", toolName, err) + } + + snapNode, err := jd.ReadJsonString(string(snapJSON)) + if err != nil { + return fmt.Errorf("failed to parse snapshot JSON for %s: %w", toolName, err) + } + + // jd.Set allows arrays to be compared without order sensitivity, + // which is useful because we don't really care about this when exposing tool schemas. + diff := toolNode.Diff(snapNode, jd.SET).Render() + if diff != "" { + // If there is a difference, we return an error with the diff + return fmt.Errorf("tool schema for %s has changed unexpectedly:\n%s\nrun with `UPDATE_TOOLSNAPS=true` if this is expected", toolName, diff) + } + + return nil +} + +func writeSnap(snapPath string, contents []byte) error { + // Ensure the directory exists + if err := os.MkdirAll(filepath.Dir(snapPath), 0700); err != nil { + return fmt.Errorf("failed to create snapshot directory: %w", err) + } + + // Write the snapshot file + if err := os.WriteFile(snapPath, contents, 0600); err != nil { + return fmt.Errorf("failed to write snapshot file: %w", err) + } + + return nil +} diff --git a/internal/toolsnaps/toolsnaps_test.go b/internal/toolsnaps/toolsnaps_test.go new file mode 100644 index 000000000..be9cadf7f --- /dev/null +++ b/internal/toolsnaps/toolsnaps_test.go @@ -0,0 +1,133 @@ +package toolsnaps + +import ( + "encoding/json" + "os" + "path/filepath" + "testing" + + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +type dummyTool struct { + Name string `json:"name"` + Value int `json:"value"` +} + +// withIsolatedWorkingDir creates a temp dir, changes to it, and restores the original working dir after the test. +func withIsolatedWorkingDir(t *testing.T) { + dir := t.TempDir() + origDir, err := os.Getwd() + require.NoError(t, err) + t.Cleanup(func() { require.NoError(t, os.Chdir(origDir)) }) + require.NoError(t, os.Chdir(dir)) +} + +func TestSnapshotDoesNotExistNotInCI(t *testing.T) { + withIsolatedWorkingDir(t) + + // Given we are not running in CI + t.Setenv("GITHUB_ACTIONS", "false") // This REALLY is required because the tests run in CI + tool := dummyTool{"foo", 42} + + // When we test the snapshot + err := Test("dummy", tool) + + // Then it should succeed and write the snapshot file + require.NoError(t, err) + path := filepath.Join("__toolsnaps__", "dummy.snap") + _, statErr := os.Stat(path) + assert.NoError(t, statErr, "expected snapshot file to be written") +} + +func TestSnapshotDoesNotExistInCI(t *testing.T) { + withIsolatedWorkingDir(t) + // Ensure that UPDATE_TOOLSNAPS is not set for this test, which it might be if someone is running + // UPDATE_TOOLSNAPS=true go test ./... + t.Setenv("UPDATE_TOOLSNAPS", "false") + + // Given we are running in CI + t.Setenv("GITHUB_ACTIONS", "true") + tool := dummyTool{"foo", 42} + + // When we test the snapshot + err := Test("dummy", tool) + + // Then it should error about missing snapshot in CI + require.Error(t, err) + assert.Contains(t, err.Error(), "tool snapshot does not exist", "expected error about missing snapshot in CI") +} + +func TestSnapshotExistsMatch(t *testing.T) { + withIsolatedWorkingDir(t) + + // Given a matching snapshot file exists + tool := dummyTool{"foo", 42} + b, _ := json.MarshalIndent(tool, "", " ") + require.NoError(t, os.MkdirAll("__toolsnaps__", 0700)) + require.NoError(t, os.WriteFile(filepath.Join("__toolsnaps__", "dummy.snap"), b, 0600)) + + // When we test the snapshot + err := Test("dummy", tool) + + // Then it should succeed (no error) + require.NoError(t, err) +} + +func TestSnapshotExistsDiff(t *testing.T) { + withIsolatedWorkingDir(t) + // Ensure that UPDATE_TOOLSNAPS is not set for this test, which it might be if someone is running + // UPDATE_TOOLSNAPS=true go test ./... + t.Setenv("UPDATE_TOOLSNAPS", "false") + + // Given a non-matching snapshot file exists + require.NoError(t, os.MkdirAll("__toolsnaps__", 0700)) + require.NoError(t, os.WriteFile(filepath.Join("__toolsnaps__", "dummy.snap"), []byte(`{"name":"foo","value":1}`), 0600)) + tool := dummyTool{"foo", 2} + + // When we test the snapshot + err := Test("dummy", tool) + + // Then it should error about the schema diff + require.Error(t, err) + assert.Contains(t, err.Error(), "tool schema for dummy has changed unexpectedly", "expected error about diff") +} + +func TestUpdateToolsnaps(t *testing.T) { + withIsolatedWorkingDir(t) + + // Given UPDATE_TOOLSNAPS is set, regardless of whether a matching snapshot file exists + t.Setenv("UPDATE_TOOLSNAPS", "true") + require.NoError(t, os.MkdirAll("__toolsnaps__", 0700)) + require.NoError(t, os.WriteFile(filepath.Join("__toolsnaps__", "dummy.snap"), []byte(`{"name":"foo","value":1}`), 0600)) + tool := dummyTool{"foo", 42} + + // When we test the snapshot + err := Test("dummy", tool) + + // Then it should succeed and write the snapshot file + require.NoError(t, err) + path := filepath.Join("__toolsnaps__", "dummy.snap") + _, statErr := os.Stat(path) + assert.NoError(t, statErr, "expected snapshot file to be written") +} + +func TestMalformedSnapshotJSON(t *testing.T) { + withIsolatedWorkingDir(t) + // Ensure that UPDATE_TOOLSNAPS is not set for this test, which it might be if someone is running + // UPDATE_TOOLSNAPS=true go test ./... + t.Setenv("UPDATE_TOOLSNAPS", "false") + + // Given a malformed snapshot file exists + require.NoError(t, os.MkdirAll("__toolsnaps__", 0700)) + require.NoError(t, os.WriteFile(filepath.Join("__toolsnaps__", "dummy.snap"), []byte(`not-json`), 0600)) + tool := dummyTool{"foo", 42} + + // When we test the snapshot + err := Test("dummy", tool) + + // Then it should error about malformed snapshot JSON + require.Error(t, err) + assert.Contains(t, err.Error(), "failed to parse snapshot JSON for dummy", "expected error about malformed snapshot JSON") +} diff --git a/pkg/errors/error.go b/pkg/errors/error.go new file mode 100644 index 000000000..c89ab2d79 --- /dev/null +++ b/pkg/errors/error.go @@ -0,0 +1,125 @@ +package errors + +import ( + "context" + "fmt" + + "github.com/google/go-github/v73/github" + "github.com/mark3labs/mcp-go/mcp" +) + +type GitHubAPIError struct { + Message string `json:"message"` + Response *github.Response `json:"-"` + Err error `json:"-"` +} + +// NewGitHubAPIError creates a new GitHubAPIError with the provided message, response, and error. +func newGitHubAPIError(message string, resp *github.Response, err error) *GitHubAPIError { + return &GitHubAPIError{ + Message: message, + Response: resp, + Err: err, + } +} + +func (e *GitHubAPIError) Error() string { + return fmt.Errorf("%s: %w", e.Message, e.Err).Error() +} + +type GitHubGraphQLError struct { + Message string `json:"message"` + Err error `json:"-"` +} + +func newGitHubGraphQLError(message string, err error) *GitHubGraphQLError { + return &GitHubGraphQLError{ + Message: message, + Err: err, + } +} + +func (e *GitHubGraphQLError) Error() string { + return fmt.Errorf("%s: %w", e.Message, e.Err).Error() +} + +type GitHubErrorKey struct{} +type GitHubCtxErrors struct { + api []*GitHubAPIError + graphQL []*GitHubGraphQLError +} + +// ContextWithGitHubErrors updates or creates a context with a pointer to GitHub error information (to be used by middleware). +func ContextWithGitHubErrors(ctx context.Context) context.Context { + if ctx == nil { + ctx = context.Background() + } + if val, ok := ctx.Value(GitHubErrorKey{}).(*GitHubCtxErrors); ok { + // If the context already has GitHubCtxErrors, we just empty the slices to start fresh + val.api = []*GitHubAPIError{} + val.graphQL = []*GitHubGraphQLError{} + } else { + // If not, we create a new GitHubCtxErrors and set it in the context + ctx = context.WithValue(ctx, GitHubErrorKey{}, &GitHubCtxErrors{}) + } + + return ctx +} + +// GetGitHubAPIErrors retrieves the slice of GitHubAPIErrors from the context. +func GetGitHubAPIErrors(ctx context.Context) ([]*GitHubAPIError, error) { + if val, ok := ctx.Value(GitHubErrorKey{}).(*GitHubCtxErrors); ok { + return val.api, nil // return the slice of API errors from the context + } + return nil, fmt.Errorf("context does not contain GitHubCtxErrors") +} + +// GetGitHubGraphQLErrors retrieves the slice of GitHubGraphQLErrors from the context. +func GetGitHubGraphQLErrors(ctx context.Context) ([]*GitHubGraphQLError, error) { + if val, ok := ctx.Value(GitHubErrorKey{}).(*GitHubCtxErrors); ok { + return val.graphQL, nil // return the slice of GraphQL errors from the context + } + return nil, fmt.Errorf("context does not contain GitHubCtxErrors") +} + +func NewGitHubAPIErrorToCtx(ctx context.Context, message string, resp *github.Response, err error) (context.Context, error) { + apiErr := newGitHubAPIError(message, resp, err) + if ctx != nil { + _, _ = addGitHubAPIErrorToContext(ctx, apiErr) // Explicitly ignore error for graceful handling + } + return ctx, nil +} + +func addGitHubAPIErrorToContext(ctx context.Context, err *GitHubAPIError) (context.Context, error) { + if val, ok := ctx.Value(GitHubErrorKey{}).(*GitHubCtxErrors); ok { + val.api = append(val.api, err) // append the error to the existing slice in the context + return ctx, nil + } + return nil, fmt.Errorf("context does not contain GitHubCtxErrors") +} + +func addGitHubGraphQLErrorToContext(ctx context.Context, err *GitHubGraphQLError) (context.Context, error) { + if val, ok := ctx.Value(GitHubErrorKey{}).(*GitHubCtxErrors); ok { + val.graphQL = append(val.graphQL, err) // append the error to the existing slice in the context + return ctx, nil + } + return nil, fmt.Errorf("context does not contain GitHubCtxErrors") +} + +// NewGitHubAPIErrorResponse returns an mcp.NewToolResultError and retains the error in the context for access via middleware +func NewGitHubAPIErrorResponse(ctx context.Context, message string, resp *github.Response, err error) *mcp.CallToolResult { + apiErr := newGitHubAPIError(message, resp, err) + if ctx != nil { + _, _ = addGitHubAPIErrorToContext(ctx, apiErr) // Explicitly ignore error for graceful handling + } + return mcp.NewToolResultErrorFromErr(message, err) +} + +// NewGitHubGraphQLErrorResponse returns an mcp.NewToolResultError and retains the error in the context for access via middleware +func NewGitHubGraphQLErrorResponse(ctx context.Context, message string, err error) *mcp.CallToolResult { + graphQLErr := newGitHubGraphQLError(message, err) + if ctx != nil { + _, _ = addGitHubGraphQLErrorToContext(ctx, graphQLErr) // Explicitly ignore error for graceful handling + } + return mcp.NewToolResultErrorFromErr(message, err) +} diff --git a/pkg/errors/error_test.go b/pkg/errors/error_test.go new file mode 100644 index 000000000..3498e3d8a --- /dev/null +++ b/pkg/errors/error_test.go @@ -0,0 +1,379 @@ +package errors + +import ( + "context" + "fmt" + "net/http" + "testing" + + "github.com/google/go-github/v73/github" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func TestGitHubErrorContext(t *testing.T) { + t.Run("API errors can be added to context and retrieved", func(t *testing.T) { + // Given a context with GitHub error tracking enabled + ctx := ContextWithGitHubErrors(context.Background()) + + // Create a mock GitHub response + resp := &github.Response{ + Response: &http.Response{ + StatusCode: 404, + Status: "404 Not Found", + }, + } + originalErr := fmt.Errorf("resource not found") + + // When we add an API error to the context + updatedCtx, err := NewGitHubAPIErrorToCtx(ctx, "failed to fetch resource", resp, originalErr) + require.NoError(t, err) + + // Then we should be able to retrieve the error from the updated context + apiErrors, err := GetGitHubAPIErrors(updatedCtx) + require.NoError(t, err) + require.Len(t, apiErrors, 1) + + apiError := apiErrors[0] + assert.Equal(t, "failed to fetch resource", apiError.Message) + assert.Equal(t, resp, apiError.Response) + assert.Equal(t, originalErr, apiError.Err) + assert.Equal(t, "failed to fetch resource: resource not found", apiError.Error()) + }) + + t.Run("GraphQL errors can be added to context and retrieved", func(t *testing.T) { + // Given a context with GitHub error tracking enabled + ctx := ContextWithGitHubErrors(context.Background()) + + originalErr := fmt.Errorf("GraphQL query failed") + + // When we add a GraphQL error to the context + graphQLErr := newGitHubGraphQLError("failed to execute mutation", originalErr) + updatedCtx, err := addGitHubGraphQLErrorToContext(ctx, graphQLErr) + require.NoError(t, err) + + // Then we should be able to retrieve the error from the updated context + gqlErrors, err := GetGitHubGraphQLErrors(updatedCtx) + require.NoError(t, err) + require.Len(t, gqlErrors, 1) + + gqlError := gqlErrors[0] + assert.Equal(t, "failed to execute mutation", gqlError.Message) + assert.Equal(t, originalErr, gqlError.Err) + assert.Equal(t, "failed to execute mutation: GraphQL query failed", gqlError.Error()) + }) + + t.Run("multiple errors can be accumulated in context", func(t *testing.T) { + // Given a context with GitHub error tracking enabled + ctx := ContextWithGitHubErrors(context.Background()) + + // When we add multiple API errors + resp1 := &github.Response{Response: &http.Response{StatusCode: 404}} + resp2 := &github.Response{Response: &http.Response{StatusCode: 403}} + + ctx, err := NewGitHubAPIErrorToCtx(ctx, "first error", resp1, fmt.Errorf("not found")) + require.NoError(t, err) + + ctx, err = NewGitHubAPIErrorToCtx(ctx, "second error", resp2, fmt.Errorf("forbidden")) + require.NoError(t, err) + + // And add a GraphQL error + gqlErr := newGitHubGraphQLError("graphql error", fmt.Errorf("query failed")) + ctx, err = addGitHubGraphQLErrorToContext(ctx, gqlErr) + require.NoError(t, err) + + // Then we should be able to retrieve all errors + apiErrors, err := GetGitHubAPIErrors(ctx) + require.NoError(t, err) + assert.Len(t, apiErrors, 2) + + gqlErrors, err := GetGitHubGraphQLErrors(ctx) + require.NoError(t, err) + assert.Len(t, gqlErrors, 1) + + // Verify error details + assert.Equal(t, "first error", apiErrors[0].Message) + assert.Equal(t, "second error", apiErrors[1].Message) + assert.Equal(t, "graphql error", gqlErrors[0].Message) + }) + + t.Run("context pointer sharing allows middleware to inspect errors without context propagation", func(t *testing.T) { + // This test demonstrates the key behavior: even when the context itself + // isn't propagated through function calls, the pointer to the error slice + // is shared, allowing middleware to inspect errors that were added later. + + // Given a context with GitHub error tracking enabled + originalCtx := ContextWithGitHubErrors(context.Background()) + + // Simulate a middleware that captures the context early + var middlewareCtx context.Context + + // Middleware function that captures the context + middleware := func(ctx context.Context) { + middlewareCtx = ctx // Middleware saves the context reference + } + + // Call middleware with the original context + middleware(originalCtx) + + // Simulate some business logic that adds errors to the context + // but doesn't propagate the updated context back to middleware + businessLogic := func(ctx context.Context) { + resp := &github.Response{Response: &http.Response{StatusCode: 500}} + + // Add an error to the context (this modifies the shared pointer) + _, err := NewGitHubAPIErrorToCtx(ctx, "business logic failed", resp, fmt.Errorf("internal error")) + require.NoError(t, err) + + // Add another error + _, err = NewGitHubAPIErrorToCtx(ctx, "second failure", resp, fmt.Errorf("another error")) + require.NoError(t, err) + } + + // Execute business logic - note that we don't propagate the returned context + businessLogic(originalCtx) + + // Then the middleware should be able to see the errors that were added + // even though it only has a reference to the original context + apiErrors, err := GetGitHubAPIErrors(middlewareCtx) + require.NoError(t, err) + assert.Len(t, apiErrors, 2, "Middleware should see errors added after it captured the context") + + assert.Equal(t, "business logic failed", apiErrors[0].Message) + assert.Equal(t, "second failure", apiErrors[1].Message) + }) + + t.Run("context without GitHub errors returns error", func(t *testing.T) { + // Given a regular context without GitHub error tracking + ctx := context.Background() + + // When we try to retrieve errors + apiErrors, err := GetGitHubAPIErrors(ctx) + + // Then it should return an error + assert.Error(t, err) + assert.Contains(t, err.Error(), "context does not contain GitHubCtxErrors") + assert.Nil(t, apiErrors) + + // Same for GraphQL errors + gqlErrors, err := GetGitHubGraphQLErrors(ctx) + assert.Error(t, err) + assert.Contains(t, err.Error(), "context does not contain GitHubCtxErrors") + assert.Nil(t, gqlErrors) + }) + + t.Run("ContextWithGitHubErrors resets existing errors", func(t *testing.T) { + // Given a context with existing errors + ctx := ContextWithGitHubErrors(context.Background()) + resp := &github.Response{Response: &http.Response{StatusCode: 404}} + ctx, err := NewGitHubAPIErrorToCtx(ctx, "existing error", resp, fmt.Errorf("error")) + require.NoError(t, err) + + // Verify error exists + apiErrors, err := GetGitHubAPIErrors(ctx) + require.NoError(t, err) + assert.Len(t, apiErrors, 1) + + // When we call ContextWithGitHubErrors again + resetCtx := ContextWithGitHubErrors(ctx) + + // Then the errors should be cleared + apiErrors, err = GetGitHubAPIErrors(resetCtx) + require.NoError(t, err) + assert.Len(t, apiErrors, 0, "Errors should be reset") + }) + + t.Run("NewGitHubAPIErrorResponse creates MCP error result and stores context error", func(t *testing.T) { + // Given a context with GitHub error tracking enabled + ctx := ContextWithGitHubErrors(context.Background()) + + resp := &github.Response{Response: &http.Response{StatusCode: 422}} + originalErr := fmt.Errorf("validation failed") + + // When we create an API error response + result := NewGitHubAPIErrorResponse(ctx, "API call failed", resp, originalErr) + + // Then it should return an MCP error result + require.NotNil(t, result) + assert.True(t, result.IsError) + + // And the error should be stored in the context + apiErrors, err := GetGitHubAPIErrors(ctx) + require.NoError(t, err) + require.Len(t, apiErrors, 1) + + apiError := apiErrors[0] + assert.Equal(t, "API call failed", apiError.Message) + assert.Equal(t, resp, apiError.Response) + assert.Equal(t, originalErr, apiError.Err) + }) + + t.Run("NewGitHubGraphQLErrorResponse creates MCP error result and stores context error", func(t *testing.T) { + // Given a context with GitHub error tracking enabled + ctx := ContextWithGitHubErrors(context.Background()) + + originalErr := fmt.Errorf("mutation failed") + + // When we create a GraphQL error response + result := NewGitHubGraphQLErrorResponse(ctx, "GraphQL call failed", originalErr) + + // Then it should return an MCP error result + require.NotNil(t, result) + assert.True(t, result.IsError) + + // And the error should be stored in the context + gqlErrors, err := GetGitHubGraphQLErrors(ctx) + require.NoError(t, err) + require.Len(t, gqlErrors, 1) + + gqlError := gqlErrors[0] + assert.Equal(t, "GraphQL call failed", gqlError.Message) + assert.Equal(t, originalErr, gqlError.Err) + }) + + t.Run("NewGitHubAPIErrorToCtx with uninitialized context does not error", func(t *testing.T) { + // Given a regular context without GitHub error tracking initialized + ctx := context.Background() + + // Create a mock GitHub response + resp := &github.Response{ + Response: &http.Response{ + StatusCode: 500, + Status: "500 Internal Server Error", + }, + } + originalErr := fmt.Errorf("internal server error") + + // When we try to add an API error to an uninitialized context + updatedCtx, err := NewGitHubAPIErrorToCtx(ctx, "failed operation", resp, originalErr) + + // Then it should not return an error (graceful handling) + assert.NoError(t, err, "NewGitHubAPIErrorToCtx should handle uninitialized context gracefully") + assert.Equal(t, ctx, updatedCtx, "Context should be returned unchanged when not initialized") + + // And attempting to retrieve errors should still return an error since context wasn't initialized + apiErrors, err := GetGitHubAPIErrors(updatedCtx) + assert.Error(t, err) + assert.Contains(t, err.Error(), "context does not contain GitHubCtxErrors") + assert.Nil(t, apiErrors) + }) + + t.Run("NewGitHubAPIErrorToCtx with nil context does not error", func(t *testing.T) { + // Given a nil context + var ctx context.Context + + // Create a mock GitHub response + resp := &github.Response{ + Response: &http.Response{ + StatusCode: 400, + Status: "400 Bad Request", + }, + } + originalErr := fmt.Errorf("bad request") + + // When we try to add an API error to a nil context + updatedCtx, err := NewGitHubAPIErrorToCtx(ctx, "failed with nil context", resp, originalErr) + + // Then it should not return an error (graceful handling) + assert.NoError(t, err, "NewGitHubAPIErrorToCtx should handle nil context gracefully") + assert.Nil(t, updatedCtx, "Context should remain nil when passed as nil") + }) +} + +func TestGitHubErrorTypes(t *testing.T) { + t.Run("GitHubAPIError implements error interface", func(t *testing.T) { + resp := &github.Response{Response: &http.Response{StatusCode: 404}} + originalErr := fmt.Errorf("not found") + + apiErr := newGitHubAPIError("test message", resp, originalErr) + + // Should implement error interface + var err error = apiErr + assert.Equal(t, "test message: not found", err.Error()) + }) + + t.Run("GitHubGraphQLError implements error interface", func(t *testing.T) { + originalErr := fmt.Errorf("query failed") + + gqlErr := newGitHubGraphQLError("test message", originalErr) + + // Should implement error interface + var err error = gqlErr + assert.Equal(t, "test message: query failed", err.Error()) + }) +} + +// TestMiddlewareScenario demonstrates a realistic middleware scenario +func TestMiddlewareScenario(t *testing.T) { + t.Run("realistic middleware error collection scenario", func(t *testing.T) { + // Simulate a realistic HTTP middleware scenario + + // 1. Request comes in, middleware sets up error tracking + ctx := ContextWithGitHubErrors(context.Background()) + + // 2. Middleware stores reference to context for later inspection + var middlewareCtx context.Context + setupMiddleware := func(ctx context.Context) context.Context { + middlewareCtx = ctx + return ctx + } + + // 3. Setup middleware + ctx = setupMiddleware(ctx) + + // 4. Simulate multiple service calls that add errors + simulateServiceCall1 := func(ctx context.Context) { + resp := &github.Response{Response: &http.Response{StatusCode: 403}} + _, err := NewGitHubAPIErrorToCtx(ctx, "insufficient permissions", resp, fmt.Errorf("forbidden")) + require.NoError(t, err) + } + + simulateServiceCall2 := func(ctx context.Context) { + resp := &github.Response{Response: &http.Response{StatusCode: 404}} + _, err := NewGitHubAPIErrorToCtx(ctx, "resource not found", resp, fmt.Errorf("not found")) + require.NoError(t, err) + } + + simulateGraphQLCall := func(ctx context.Context) { + gqlErr := newGitHubGraphQLError("mutation failed", fmt.Errorf("invalid input")) + _, err := addGitHubGraphQLErrorToContext(ctx, gqlErr) + require.NoError(t, err) + } + + // 5. Execute service calls (without context propagation) + simulateServiceCall1(ctx) + simulateServiceCall2(ctx) + simulateGraphQLCall(ctx) + + // 6. Middleware inspects errors at the end of request processing + finalizeMiddleware := func(ctx context.Context) ([]string, []string) { + var apiErrorMessages []string + var gqlErrorMessages []string + + if apiErrors, err := GetGitHubAPIErrors(ctx); err == nil { + for _, apiErr := range apiErrors { + apiErrorMessages = append(apiErrorMessages, apiErr.Message) + } + } + + if gqlErrors, err := GetGitHubGraphQLErrors(ctx); err == nil { + for _, gqlErr := range gqlErrors { + gqlErrorMessages = append(gqlErrorMessages, gqlErr.Message) + } + } + + return apiErrorMessages, gqlErrorMessages + } + + // 7. Middleware can see all errors that were added during request processing + apiMessages, gqlMessages := finalizeMiddleware(middlewareCtx) + + // Verify all errors were captured + assert.Len(t, apiMessages, 2) + assert.Contains(t, apiMessages, "insufficient permissions") + assert.Contains(t, apiMessages, "resource not found") + + assert.Len(t, gqlMessages, 1) + assert.Contains(t, gqlMessages, "mutation failed") + }) +} diff --git a/pkg/github/__toolsnaps__/add_comment_to_pending_review.snap b/pkg/github/__toolsnaps__/add_comment_to_pending_review.snap new file mode 100644 index 000000000..08fa42df5 --- /dev/null +++ b/pkg/github/__toolsnaps__/add_comment_to_pending_review.snap @@ -0,0 +1,73 @@ +{ + "annotations": { + "title": "Add review comment to the requester's latest pending pull request review", + "readOnlyHint": false + }, + "description": "Add review comment to the requester's latest pending pull request review. A pending review needs to already exist to call this (check with the user if not sure).", + "inputSchema": { + "properties": { + "body": { + "description": "The text of the review comment", + "type": "string" + }, + "line": { + "description": "The line of the blob in the pull request diff that the comment applies to. For multi-line comments, the last line of the range", + "type": "number" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "path": { + "description": "The relative path to the file that necessitates a comment", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "side": { + "description": "The side of the diff to comment on. LEFT indicates the previous state, RIGHT indicates the new state", + "enum": [ + "LEFT", + "RIGHT" + ], + "type": "string" + }, + "startLine": { + "description": "For multi-line comments, the first line of the range that the comment applies to", + "type": "number" + }, + "startSide": { + "description": "For multi-line comments, the starting side of the diff that the comment applies to. LEFT indicates the previous state, RIGHT indicates the new state", + "enum": [ + "LEFT", + "RIGHT" + ], + "type": "string" + }, + "subjectType": { + "description": "The level at which the comment is targeted", + "enum": [ + "FILE", + "LINE" + ], + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber", + "path", + "body", + "subjectType" + ], + "type": "object" + }, + "name": "add_comment_to_pending_review" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/add_issue_comment.snap b/pkg/github/__toolsnaps__/add_issue_comment.snap new file mode 100644 index 000000000..92eeb1ce8 --- /dev/null +++ b/pkg/github/__toolsnaps__/add_issue_comment.snap @@ -0,0 +1,35 @@ +{ + "annotations": { + "title": "Add comment to issue", + "readOnlyHint": false + }, + "description": "Add a comment to a specific issue in a GitHub repository.", + "inputSchema": { + "properties": { + "body": { + "description": "Comment content", + "type": "string" + }, + "issue_number": { + "description": "Issue number to comment on", + "type": "number" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "issue_number", + "body" + ], + "type": "object" + }, + "name": "add_issue_comment" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/assign_copilot_to_issue.snap b/pkg/github/__toolsnaps__/assign_copilot_to_issue.snap new file mode 100644 index 000000000..2d61ccfbd --- /dev/null +++ b/pkg/github/__toolsnaps__/assign_copilot_to_issue.snap @@ -0,0 +1,31 @@ +{ + "annotations": { + "title": "Assign Copilot to issue", + "readOnlyHint": false, + "idempotentHint": true + }, + "description": "Assign Copilot to a specific issue in a GitHub repository.\n\nThis tool can help with the following outcomes:\n- a Pull Request created with source code changes to resolve the issue\n\n\nMore information can be found at:\n- https://docs.github.com/en/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/about-assigning-tasks-to-copilot\n", + "inputSchema": { + "properties": { + "issueNumber": { + "description": "Issue number", + "type": "number" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "issueNumber" + ], + "type": "object" + }, + "name": "assign_copilot_to_issue" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/create_and_submit_pull_request_review.snap b/pkg/github/__toolsnaps__/create_and_submit_pull_request_review.snap new file mode 100644 index 000000000..85874cfc7 --- /dev/null +++ b/pkg/github/__toolsnaps__/create_and_submit_pull_request_review.snap @@ -0,0 +1,49 @@ +{ + "annotations": { + "title": "Create and submit a pull request review without comments", + "readOnlyHint": false + }, + "description": "Create and submit a review for a pull request without review comments.", + "inputSchema": { + "properties": { + "body": { + "description": "Review comment text", + "type": "string" + }, + "commitID": { + "description": "SHA of commit to review", + "type": "string" + }, + "event": { + "description": "Review action to perform", + "enum": [ + "APPROVE", + "REQUEST_CHANGES", + "COMMENT" + ], + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber", + "body", + "event" + ], + "type": "object" + }, + "name": "create_and_submit_pull_request_review" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/create_branch.snap b/pkg/github/__toolsnaps__/create_branch.snap new file mode 100644 index 000000000..d5756fcc9 --- /dev/null +++ b/pkg/github/__toolsnaps__/create_branch.snap @@ -0,0 +1,34 @@ +{ + "annotations": { + "title": "Create branch", + "readOnlyHint": false + }, + "description": "Create a new branch in a GitHub repository", + "inputSchema": { + "properties": { + "branch": { + "description": "Name for new branch", + "type": "string" + }, + "from_branch": { + "description": "Source branch (defaults to repo default)", + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "branch" + ], + "type": "object" + }, + "name": "create_branch" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/create_issue.snap b/pkg/github/__toolsnaps__/create_issue.snap new file mode 100644 index 000000000..f065b0183 --- /dev/null +++ b/pkg/github/__toolsnaps__/create_issue.snap @@ -0,0 +1,52 @@ +{ + "annotations": { + "title": "Open new issue", + "readOnlyHint": false + }, + "description": "Create a new issue in a GitHub repository.", + "inputSchema": { + "properties": { + "assignees": { + "description": "Usernames to assign to this issue", + "items": { + "type": "string" + }, + "type": "array" + }, + "body": { + "description": "Issue body content", + "type": "string" + }, + "labels": { + "description": "Labels to apply to this issue", + "items": { + "type": "string" + }, + "type": "array" + }, + "milestone": { + "description": "Milestone number", + "type": "number" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "title": { + "description": "Issue title", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "title" + ], + "type": "object" + }, + "name": "create_issue" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/create_or_update_file.snap b/pkg/github/__toolsnaps__/create_or_update_file.snap new file mode 100644 index 000000000..61adef72c --- /dev/null +++ b/pkg/github/__toolsnaps__/create_or_update_file.snap @@ -0,0 +1,49 @@ +{ + "annotations": { + "title": "Create or update file", + "readOnlyHint": false + }, + "description": "Create or update a single file in a GitHub repository. If updating, you must provide the SHA of the file you want to update. Use this tool to create or update a file in a GitHub repository remotely; do not use it for local file operations.", + "inputSchema": { + "properties": { + "branch": { + "description": "Branch to create/update the file in", + "type": "string" + }, + "content": { + "description": "Content of the file", + "type": "string" + }, + "message": { + "description": "Commit message", + "type": "string" + }, + "owner": { + "description": "Repository owner (username or organization)", + "type": "string" + }, + "path": { + "description": "Path where to create/update the file", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "sha": { + "description": "Required if updating an existing file. The blob SHA of the file being replaced.", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "path", + "content", + "message", + "branch" + ], + "type": "object" + }, + "name": "create_or_update_file" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/create_pending_pull_request_review.snap b/pkg/github/__toolsnaps__/create_pending_pull_request_review.snap new file mode 100644 index 000000000..3eea5e6af --- /dev/null +++ b/pkg/github/__toolsnaps__/create_pending_pull_request_review.snap @@ -0,0 +1,34 @@ +{ + "annotations": { + "title": "Create pending pull request review", + "readOnlyHint": false + }, + "description": "Create a pending review for a pull request. Call this first before attempting to add comments to a pending review, and ultimately submitting it. A pending pull request review means a pull request review, it is pending because you create it first and submit it later, and the PR author will not see it until it is submitted.", + "inputSchema": { + "properties": { + "commitID": { + "description": "SHA of commit to review", + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "create_pending_pull_request_review" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/create_pull_request.snap b/pkg/github/__toolsnaps__/create_pull_request.snap new file mode 100644 index 000000000..44142a79e --- /dev/null +++ b/pkg/github/__toolsnaps__/create_pull_request.snap @@ -0,0 +1,52 @@ +{ + "annotations": { + "title": "Open new pull request", + "readOnlyHint": false + }, + "description": "Create a new pull request in a GitHub repository.", + "inputSchema": { + "properties": { + "base": { + "description": "Branch to merge into", + "type": "string" + }, + "body": { + "description": "PR description", + "type": "string" + }, + "draft": { + "description": "Create as draft PR", + "type": "boolean" + }, + "head": { + "description": "Branch containing changes", + "type": "string" + }, + "maintainer_can_modify": { + "description": "Allow maintainer edits", + "type": "boolean" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "title": { + "description": "PR title", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "title", + "head", + "base" + ], + "type": "object" + }, + "name": "create_pull_request" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/create_repository.snap b/pkg/github/__toolsnaps__/create_repository.snap new file mode 100644 index 000000000..aaba75f3c --- /dev/null +++ b/pkg/github/__toolsnaps__/create_repository.snap @@ -0,0 +1,32 @@ +{ + "annotations": { + "title": "Create repository", + "readOnlyHint": false + }, + "description": "Create a new GitHub repository in your account", + "inputSchema": { + "properties": { + "autoInit": { + "description": "Initialize with README", + "type": "boolean" + }, + "description": { + "description": "Repository description", + "type": "string" + }, + "name": { + "description": "Repository name", + "type": "string" + }, + "private": { + "description": "Whether repo should be private", + "type": "boolean" + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "name": "create_repository" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/delete_file.snap b/pkg/github/__toolsnaps__/delete_file.snap new file mode 100644 index 000000000..2588ea5c5 --- /dev/null +++ b/pkg/github/__toolsnaps__/delete_file.snap @@ -0,0 +1,41 @@ +{ + "annotations": { + "title": "Delete file", + "readOnlyHint": false, + "destructiveHint": true + }, + "description": "Delete a file from a GitHub repository", + "inputSchema": { + "properties": { + "branch": { + "description": "Branch to delete the file from", + "type": "string" + }, + "message": { + "description": "Commit message", + "type": "string" + }, + "owner": { + "description": "Repository owner (username or organization)", + "type": "string" + }, + "path": { + "description": "Path to the file to delete", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "path", + "message", + "branch" + ], + "type": "object" + }, + "name": "delete_file" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/delete_pending_pull_request_review.snap b/pkg/github/__toolsnaps__/delete_pending_pull_request_review.snap new file mode 100644 index 000000000..9aff7356c --- /dev/null +++ b/pkg/github/__toolsnaps__/delete_pending_pull_request_review.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Delete the requester's latest pending pull request review", + "readOnlyHint": false + }, + "description": "Delete the requester's latest pending pull request review. Use this after the user decides not to submit a pending review, if you don't know if they already created one then check first.", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "delete_pending_pull_request_review" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/dismiss_notification.snap b/pkg/github/__toolsnaps__/dismiss_notification.snap new file mode 100644 index 000000000..80646a802 --- /dev/null +++ b/pkg/github/__toolsnaps__/dismiss_notification.snap @@ -0,0 +1,28 @@ +{ + "annotations": { + "title": "Dismiss notification", + "readOnlyHint": false + }, + "description": "Dismiss a notification by marking it as read or done", + "inputSchema": { + "properties": { + "state": { + "description": "The new state of the notification (read/done)", + "enum": [ + "read", + "done" + ], + "type": "string" + }, + "threadID": { + "description": "The ID of the notification thread", + "type": "string" + } + }, + "required": [ + "threadID" + ], + "type": "object" + }, + "name": "dismiss_notification" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/fork_repository.snap b/pkg/github/__toolsnaps__/fork_repository.snap new file mode 100644 index 000000000..6e4d27823 --- /dev/null +++ b/pkg/github/__toolsnaps__/fork_repository.snap @@ -0,0 +1,29 @@ +{ + "annotations": { + "title": "Fork repository", + "readOnlyHint": false + }, + "description": "Fork a GitHub repository to your account or specified organization", + "inputSchema": { + "properties": { + "organization": { + "description": "Organization to fork to", + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo" + ], + "type": "object" + }, + "name": "fork_repository" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_code_scanning_alert.snap b/pkg/github/__toolsnaps__/get_code_scanning_alert.snap new file mode 100644 index 000000000..eedc20b46 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_code_scanning_alert.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Get code scanning alert", + "readOnlyHint": true + }, + "description": "Get details of a specific code scanning alert in a GitHub repository.", + "inputSchema": { + "properties": { + "alertNumber": { + "description": "The number of the alert.", + "type": "number" + }, + "owner": { + "description": "The owner of the repository.", + "type": "string" + }, + "repo": { + "description": "The name of the repository.", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "alertNumber" + ], + "type": "object" + }, + "name": "get_code_scanning_alert" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_commit.snap b/pkg/github/__toolsnaps__/get_commit.snap new file mode 100644 index 000000000..af0038110 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_commit.snap @@ -0,0 +1,41 @@ +{ + "annotations": { + "title": "Get commit details", + "readOnlyHint": true + }, + "description": "Get details for a commit from a GitHub repository", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "sha": { + "description": "Commit SHA, branch name, or tag name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "sha" + ], + "type": "object" + }, + "name": "get_commit" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_dependabot_alert.snap b/pkg/github/__toolsnaps__/get_dependabot_alert.snap new file mode 100644 index 000000000..76b5ef126 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_dependabot_alert.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Get dependabot alert", + "readOnlyHint": true + }, + "description": "Get details of a specific dependabot alert in a GitHub repository.", + "inputSchema": { + "properties": { + "alertNumber": { + "description": "The number of the alert.", + "type": "number" + }, + "owner": { + "description": "The owner of the repository.", + "type": "string" + }, + "repo": { + "description": "The name of the repository.", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "alertNumber" + ], + "type": "object" + }, + "name": "get_dependabot_alert" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_file_contents.snap b/pkg/github/__toolsnaps__/get_file_contents.snap new file mode 100644 index 000000000..53f5a29e5 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_file_contents.snap @@ -0,0 +1,38 @@ +{ + "annotations": { + "title": "Get file or directory contents", + "readOnlyHint": true + }, + "description": "Get the contents of a file or directory from a GitHub repository", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner (username or organization)", + "type": "string" + }, + "path": { + "default": "/", + "description": "Path to file/directory (directories must end with a slash '/')", + "type": "string" + }, + "ref": { + "description": "Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head`", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "sha": { + "description": "Accepts optional commit SHA. If specified, it will be used instead of ref", + "type": "string" + } + }, + "required": [ + "owner", + "repo" + ], + "type": "object" + }, + "name": "get_file_contents" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_issue.snap b/pkg/github/__toolsnaps__/get_issue.snap new file mode 100644 index 000000000..eab2b8722 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_issue.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Get issue details", + "readOnlyHint": true + }, + "description": "Get details of a specific issue in a GitHub repository.", + "inputSchema": { + "properties": { + "issue_number": { + "description": "The number of the issue", + "type": "number" + }, + "owner": { + "description": "The owner of the repository", + "type": "string" + }, + "repo": { + "description": "The name of the repository", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "issue_number" + ], + "type": "object" + }, + "name": "get_issue" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_issue_comments.snap b/pkg/github/__toolsnaps__/get_issue_comments.snap new file mode 100644 index 000000000..b28f45204 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_issue_comments.snap @@ -0,0 +1,41 @@ +{ + "annotations": { + "title": "Get issue comments", + "readOnlyHint": true + }, + "description": "Get comments for a specific issue in a GitHub repository.", + "inputSchema": { + "properties": { + "issue_number": { + "description": "Issue number", + "type": "number" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "issue_number" + ], + "type": "object" + }, + "name": "get_issue_comments" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_me.snap b/pkg/github/__toolsnaps__/get_me.snap new file mode 100644 index 000000000..13b061741 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_me.snap @@ -0,0 +1,12 @@ +{ + "annotations": { + "title": "Get my user profile", + "readOnlyHint": true + }, + "description": "Get details of the authenticated GitHub user. Use this when a request is about the user's own profile for GitHub. Or when information is missing to build other tool calls.", + "inputSchema": { + "properties": {}, + "type": "object" + }, + "name": "get_me" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_notification_details.snap b/pkg/github/__toolsnaps__/get_notification_details.snap new file mode 100644 index 000000000..62bc6bf1b --- /dev/null +++ b/pkg/github/__toolsnaps__/get_notification_details.snap @@ -0,0 +1,20 @@ +{ + "annotations": { + "title": "Get notification details", + "readOnlyHint": true + }, + "description": "Get detailed information for a specific GitHub notification, always call this tool when the user asks for details about a specific notification, if you don't know the ID list notifications first.", + "inputSchema": { + "properties": { + "notificationID": { + "description": "The ID of the notification", + "type": "string" + } + }, + "required": [ + "notificationID" + ], + "type": "object" + }, + "name": "get_notification_details" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_pull_request.snap b/pkg/github/__toolsnaps__/get_pull_request.snap new file mode 100644 index 000000000..cbcf1f425 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_pull_request.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Get pull request details", + "readOnlyHint": true + }, + "description": "Get details of a specific pull request in a GitHub repository.", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "get_pull_request" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_pull_request_comments.snap b/pkg/github/__toolsnaps__/get_pull_request_comments.snap new file mode 100644 index 000000000..6699f6d97 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_pull_request_comments.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Get pull request comments", + "readOnlyHint": true + }, + "description": "Get comments for a specific pull request.", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "get_pull_request_comments" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_pull_request_diff.snap b/pkg/github/__toolsnaps__/get_pull_request_diff.snap new file mode 100644 index 000000000..e054eab92 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_pull_request_diff.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Get pull request diff", + "readOnlyHint": true + }, + "description": "Get the diff of a pull request.", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "get_pull_request_diff" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_pull_request_files.snap b/pkg/github/__toolsnaps__/get_pull_request_files.snap new file mode 100644 index 000000000..148053b17 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_pull_request_files.snap @@ -0,0 +1,41 @@ +{ + "annotations": { + "title": "Get pull request files", + "readOnlyHint": true + }, + "description": "Get the files changed in a specific pull request.", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "get_pull_request_files" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_pull_request_reviews.snap b/pkg/github/__toolsnaps__/get_pull_request_reviews.snap new file mode 100644 index 000000000..61dee53ee --- /dev/null +++ b/pkg/github/__toolsnaps__/get_pull_request_reviews.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Get pull request reviews", + "readOnlyHint": true + }, + "description": "Get reviews for a specific pull request.", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "get_pull_request_reviews" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_pull_request_status.snap b/pkg/github/__toolsnaps__/get_pull_request_status.snap new file mode 100644 index 000000000..8ffebc3a4 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_pull_request_status.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Get pull request status checks", + "readOnlyHint": true + }, + "description": "Get the status of a specific pull request.", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "get_pull_request_status" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/get_tag.snap b/pkg/github/__toolsnaps__/get_tag.snap new file mode 100644 index 000000000..42089f872 --- /dev/null +++ b/pkg/github/__toolsnaps__/get_tag.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Get tag details", + "readOnlyHint": true + }, + "description": "Get details about a specific git tag in a GitHub repository", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "tag": { + "description": "Tag name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "tag" + ], + "type": "object" + }, + "name": "get_tag" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/list_branches.snap b/pkg/github/__toolsnaps__/list_branches.snap new file mode 100644 index 000000000..492b6d527 --- /dev/null +++ b/pkg/github/__toolsnaps__/list_branches.snap @@ -0,0 +1,36 @@ +{ + "annotations": { + "title": "List branches", + "readOnlyHint": true + }, + "description": "List branches in a GitHub repository", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo" + ], + "type": "object" + }, + "name": "list_branches" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/list_code_scanning_alerts.snap b/pkg/github/__toolsnaps__/list_code_scanning_alerts.snap new file mode 100644 index 000000000..470f0d01f --- /dev/null +++ b/pkg/github/__toolsnaps__/list_code_scanning_alerts.snap @@ -0,0 +1,57 @@ +{ + "annotations": { + "title": "List code scanning alerts", + "readOnlyHint": true + }, + "description": "List code scanning alerts in a GitHub repository.", + "inputSchema": { + "properties": { + "owner": { + "description": "The owner of the repository.", + "type": "string" + }, + "ref": { + "description": "The Git reference for the results you want to list.", + "type": "string" + }, + "repo": { + "description": "The name of the repository.", + "type": "string" + }, + "severity": { + "description": "Filter code scanning alerts by severity", + "enum": [ + "critical", + "high", + "medium", + "low", + "warning", + "note", + "error" + ], + "type": "string" + }, + "state": { + "default": "open", + "description": "Filter code scanning alerts by state. Defaults to open", + "enum": [ + "open", + "closed", + "dismissed", + "fixed" + ], + "type": "string" + }, + "tool_name": { + "description": "The name of the tool used for code scanning.", + "type": "string" + } + }, + "required": [ + "owner", + "repo" + ], + "type": "object" + }, + "name": "list_code_scanning_alerts" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/list_commits.snap b/pkg/github/__toolsnaps__/list_commits.snap new file mode 100644 index 000000000..a802436c2 --- /dev/null +++ b/pkg/github/__toolsnaps__/list_commits.snap @@ -0,0 +1,44 @@ +{ + "annotations": { + "title": "List commits", + "readOnlyHint": true + }, + "description": "Get list of commits of a branch in a GitHub repository. Returns at least 30 results per page by default, but can return more if specified using the perPage parameter (up to 100).", + "inputSchema": { + "properties": { + "author": { + "description": "Author username or email address to filter commits by", + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "sha": { + "description": "Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA.", + "type": "string" + } + }, + "required": [ + "owner", + "repo" + ], + "type": "object" + }, + "name": "list_commits" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/list_dependabot_alerts.snap b/pkg/github/__toolsnaps__/list_dependabot_alerts.snap new file mode 100644 index 000000000..681d640b7 --- /dev/null +++ b/pkg/github/__toolsnaps__/list_dependabot_alerts.snap @@ -0,0 +1,46 @@ +{ + "annotations": { + "title": "List dependabot alerts", + "readOnlyHint": true + }, + "description": "List dependabot alerts in a GitHub repository.", + "inputSchema": { + "properties": { + "owner": { + "description": "The owner of the repository.", + "type": "string" + }, + "repo": { + "description": "The name of the repository.", + "type": "string" + }, + "severity": { + "description": "Filter dependabot alerts by severity", + "enum": [ + "low", + "medium", + "high", + "critical" + ], + "type": "string" + }, + "state": { + "default": "open", + "description": "Filter dependabot alerts by state. Defaults to open", + "enum": [ + "open", + "fixed", + "dismissed", + "auto_dismissed" + ], + "type": "string" + } + }, + "required": [ + "owner", + "repo" + ], + "type": "object" + }, + "name": "list_dependabot_alerts" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/list_issues.snap b/pkg/github/__toolsnaps__/list_issues.snap new file mode 100644 index 000000000..4fe155f09 --- /dev/null +++ b/pkg/github/__toolsnaps__/list_issues.snap @@ -0,0 +1,73 @@ +{ + "annotations": { + "title": "List issues", + "readOnlyHint": true + }, + "description": "List issues in a GitHub repository.", + "inputSchema": { + "properties": { + "direction": { + "description": "Sort direction", + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "labels": { + "description": "Filter by labels", + "items": { + "type": "string" + }, + "type": "array" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "since": { + "description": "Filter by date (ISO 8601 timestamp)", + "type": "string" + }, + "sort": { + "description": "Sort order", + "enum": [ + "created", + "updated", + "comments" + ], + "type": "string" + }, + "state": { + "description": "Filter by state", + "enum": [ + "open", + "closed", + "all" + ], + "type": "string" + } + }, + "required": [ + "owner", + "repo" + ], + "type": "object" + }, + "name": "list_issues" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/list_notifications.snap b/pkg/github/__toolsnaps__/list_notifications.snap new file mode 100644 index 000000000..92f25eb4c --- /dev/null +++ b/pkg/github/__toolsnaps__/list_notifications.snap @@ -0,0 +1,49 @@ +{ + "annotations": { + "title": "List notifications", + "readOnlyHint": true + }, + "description": "Lists all GitHub notifications for the authenticated user, including unread notifications, mentions, review requests, assignments, and updates on issues or pull requests. Use this tool whenever the user asks what to work on next, requests a summary of their GitHub activity, wants to see pending reviews, or needs to check for new updates or tasks. This tool is the primary way to discover actionable items, reminders, and outstanding work on GitHub. Always call this tool when asked what to work on next, what is pending, or what needs attention in GitHub.", + "inputSchema": { + "properties": { + "before": { + "description": "Only show notifications updated before the given time (ISO 8601 format)", + "type": "string" + }, + "filter": { + "description": "Filter notifications to, use default unless specified. Read notifications are ones that have already been acknowledged by the user. Participating notifications are those that the user is directly involved in, such as issues or pull requests they have commented on or created.", + "enum": [ + "default", + "include_read_notifications", + "only_participating" + ], + "type": "string" + }, + "owner": { + "description": "Optional repository owner. If provided with repo, only notifications for this repository are listed.", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "repo": { + "description": "Optional repository name. If provided with owner, only notifications for this repository are listed.", + "type": "string" + }, + "since": { + "description": "Only show notifications updated after the given time (ISO 8601 format)", + "type": "string" + } + }, + "type": "object" + }, + "name": "list_notifications" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/list_pull_requests.snap b/pkg/github/__toolsnaps__/list_pull_requests.snap new file mode 100644 index 000000000..fee7e2ff1 --- /dev/null +++ b/pkg/github/__toolsnaps__/list_pull_requests.snap @@ -0,0 +1,71 @@ +{ + "annotations": { + "title": "List pull requests", + "readOnlyHint": true + }, + "description": "List pull requests in a GitHub repository. If the user specifies an author, then DO NOT use this tool and use the search_pull_requests tool instead.", + "inputSchema": { + "properties": { + "base": { + "description": "Filter by base branch", + "type": "string" + }, + "direction": { + "description": "Sort direction", + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "head": { + "description": "Filter by head user/org and branch", + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "sort": { + "description": "Sort by", + "enum": [ + "created", + "updated", + "popularity", + "long-running" + ], + "type": "string" + }, + "state": { + "description": "Filter by state", + "enum": [ + "open", + "closed", + "all" + ], + "type": "string" + } + }, + "required": [ + "owner", + "repo" + ], + "type": "object" + }, + "name": "list_pull_requests" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/list_tags.snap b/pkg/github/__toolsnaps__/list_tags.snap new file mode 100644 index 000000000..fcb9853fd --- /dev/null +++ b/pkg/github/__toolsnaps__/list_tags.snap @@ -0,0 +1,36 @@ +{ + "annotations": { + "title": "List tags", + "readOnlyHint": true + }, + "description": "List git tags in a GitHub repository", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo" + ], + "type": "object" + }, + "name": "list_tags" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/manage_notification_subscription.snap b/pkg/github/__toolsnaps__/manage_notification_subscription.snap new file mode 100644 index 000000000..0f7d91201 --- /dev/null +++ b/pkg/github/__toolsnaps__/manage_notification_subscription.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Manage notification subscription", + "readOnlyHint": false + }, + "description": "Manage a notification subscription: ignore, watch, or delete a notification thread subscription.", + "inputSchema": { + "properties": { + "action": { + "description": "Action to perform: ignore, watch, or delete the notification subscription.", + "enum": [ + "ignore", + "watch", + "delete" + ], + "type": "string" + }, + "notificationID": { + "description": "The ID of the notification thread.", + "type": "string" + } + }, + "required": [ + "notificationID", + "action" + ], + "type": "object" + }, + "name": "manage_notification_subscription" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/manage_repository_notification_subscription.snap b/pkg/github/__toolsnaps__/manage_repository_notification_subscription.snap new file mode 100644 index 000000000..9d09a5817 --- /dev/null +++ b/pkg/github/__toolsnaps__/manage_repository_notification_subscription.snap @@ -0,0 +1,35 @@ +{ + "annotations": { + "title": "Manage repository notification subscription", + "readOnlyHint": false + }, + "description": "Manage a repository notification subscription: ignore, watch, or delete repository notifications subscription for the provided repository.", + "inputSchema": { + "properties": { + "action": { + "description": "Action to perform: ignore, watch, or delete the repository notification subscription.", + "enum": [ + "ignore", + "watch", + "delete" + ], + "type": "string" + }, + "owner": { + "description": "The account owner of the repository.", + "type": "string" + }, + "repo": { + "description": "The name of the repository.", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "action" + ], + "type": "object" + }, + "name": "manage_repository_notification_subscription" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/mark_all_notifications_read.snap b/pkg/github/__toolsnaps__/mark_all_notifications_read.snap new file mode 100644 index 000000000..5a1fe24a5 --- /dev/null +++ b/pkg/github/__toolsnaps__/mark_all_notifications_read.snap @@ -0,0 +1,25 @@ +{ + "annotations": { + "title": "Mark all notifications as read", + "readOnlyHint": false + }, + "description": "Mark all notifications as read", + "inputSchema": { + "properties": { + "lastReadAt": { + "description": "Describes the last point that notifications were checked (optional). Default: Now", + "type": "string" + }, + "owner": { + "description": "Optional repository owner. If provided with repo, only notifications for this repository are marked as read.", + "type": "string" + }, + "repo": { + "description": "Optional repository name. If provided with owner, only notifications for this repository are marked as read.", + "type": "string" + } + }, + "type": "object" + }, + "name": "mark_all_notifications_read" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/merge_pull_request.snap b/pkg/github/__toolsnaps__/merge_pull_request.snap new file mode 100644 index 000000000..a5a1474cb --- /dev/null +++ b/pkg/github/__toolsnaps__/merge_pull_request.snap @@ -0,0 +1,47 @@ +{ + "annotations": { + "title": "Merge pull request", + "readOnlyHint": false + }, + "description": "Merge a pull request in a GitHub repository.", + "inputSchema": { + "properties": { + "commit_message": { + "description": "Extra detail for merge commit", + "type": "string" + }, + "commit_title": { + "description": "Title for merge commit", + "type": "string" + }, + "merge_method": { + "description": "Merge method", + "enum": [ + "merge", + "squash", + "rebase" + ], + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "merge_pull_request" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/push_files.snap b/pkg/github/__toolsnaps__/push_files.snap new file mode 100644 index 000000000..3ade75eeb --- /dev/null +++ b/pkg/github/__toolsnaps__/push_files.snap @@ -0,0 +1,58 @@ +{ + "annotations": { + "title": "Push files to repository", + "readOnlyHint": false + }, + "description": "Push multiple files to a GitHub repository in a single commit", + "inputSchema": { + "properties": { + "branch": { + "description": "Branch to push to", + "type": "string" + }, + "files": { + "description": "Array of file objects to push, each object with path (string) and content (string)", + "items": { + "additionalProperties": false, + "properties": { + "content": { + "description": "file content", + "type": "string" + }, + "path": { + "description": "path to the file", + "type": "string" + } + }, + "required": [ + "path", + "content" + ], + "type": "object" + }, + "type": "array" + }, + "message": { + "description": "Commit message", + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "branch", + "files", + "message" + ], + "type": "object" + }, + "name": "push_files" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/request_copilot_review.snap b/pkg/github/__toolsnaps__/request_copilot_review.snap new file mode 100644 index 000000000..1717ced01 --- /dev/null +++ b/pkg/github/__toolsnaps__/request_copilot_review.snap @@ -0,0 +1,30 @@ +{ + "annotations": { + "title": "Request Copilot review", + "readOnlyHint": false + }, + "description": "Request a GitHub Copilot code review for a pull request. Use this for automated feedback on pull requests, usually before requesting a human reviewer.", + "inputSchema": { + "properties": { + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "request_copilot_review" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/search_code.snap b/pkg/github/__toolsnaps__/search_code.snap new file mode 100644 index 000000000..c85d6674d --- /dev/null +++ b/pkg/github/__toolsnaps__/search_code.snap @@ -0,0 +1,43 @@ +{ + "annotations": { + "title": "Search code", + "readOnlyHint": true + }, + "description": "Search for code across GitHub repositories", + "inputSchema": { + "properties": { + "order": { + "description": "Sort order", + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "q": { + "description": "Search query using GitHub code search syntax", + "type": "string" + }, + "sort": { + "description": "Sort field ('indexed' only)", + "type": "string" + } + }, + "required": [ + "q" + ], + "type": "object" + }, + "name": "search_code" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/search_issues.snap b/pkg/github/__toolsnaps__/search_issues.snap new file mode 100644 index 000000000..7db502d94 --- /dev/null +++ b/pkg/github/__toolsnaps__/search_issues.snap @@ -0,0 +1,64 @@ +{ + "annotations": { + "title": "Search issues", + "readOnlyHint": true + }, + "description": "Search for issues in GitHub repositories using issues search syntax already scoped to is:issue", + "inputSchema": { + "properties": { + "order": { + "description": "Sort order", + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "owner": { + "description": "Optional repository owner. If provided with repo, only notifications for this repository are listed.", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "query": { + "description": "Search query using GitHub issues search syntax", + "type": "string" + }, + "repo": { + "description": "Optional repository name. If provided with owner, only notifications for this repository are listed.", + "type": "string" + }, + "sort": { + "description": "Sort field by number of matches of categories, defaults to best match", + "enum": [ + "comments", + "reactions", + "reactions-+1", + "reactions--1", + "reactions-smile", + "reactions-thinking_face", + "reactions-heart", + "reactions-tada", + "interactions", + "created", + "updated" + ], + "type": "string" + } + }, + "required": [ + "query" + ], + "type": "object" + }, + "name": "search_issues" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/search_pull_requests.snap b/pkg/github/__toolsnaps__/search_pull_requests.snap new file mode 100644 index 000000000..6a8d8e0e6 --- /dev/null +++ b/pkg/github/__toolsnaps__/search_pull_requests.snap @@ -0,0 +1,64 @@ +{ + "annotations": { + "title": "Search pull requests", + "readOnlyHint": true + }, + "description": "Search for pull requests in GitHub repositories using issues search syntax already scoped to is:pr", + "inputSchema": { + "properties": { + "order": { + "description": "Sort order", + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "owner": { + "description": "Optional repository owner. If provided with repo, only notifications for this repository are listed.", + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "query": { + "description": "Search query using GitHub pull request search syntax", + "type": "string" + }, + "repo": { + "description": "Optional repository name. If provided with owner, only notifications for this repository are listed.", + "type": "string" + }, + "sort": { + "description": "Sort field by number of matches of categories, defaults to best match", + "enum": [ + "comments", + "reactions", + "reactions-+1", + "reactions--1", + "reactions-smile", + "reactions-thinking_face", + "reactions-heart", + "reactions-tada", + "interactions", + "created", + "updated" + ], + "type": "string" + } + }, + "required": [ + "query" + ], + "type": "object" + }, + "name": "search_pull_requests" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/search_repositories.snap b/pkg/github/__toolsnaps__/search_repositories.snap new file mode 100644 index 000000000..b6b6d1d44 --- /dev/null +++ b/pkg/github/__toolsnaps__/search_repositories.snap @@ -0,0 +1,31 @@ +{ + "annotations": { + "title": "Search repositories", + "readOnlyHint": true + }, + "description": "Search for GitHub repositories", + "inputSchema": { + "properties": { + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "query": { + "description": "Search query", + "type": "string" + } + }, + "required": [ + "query" + ], + "type": "object" + }, + "name": "search_repositories" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/search_users.snap b/pkg/github/__toolsnaps__/search_users.snap new file mode 100644 index 000000000..5cf9796f2 --- /dev/null +++ b/pkg/github/__toolsnaps__/search_users.snap @@ -0,0 +1,48 @@ +{ + "annotations": { + "title": "Search users", + "readOnlyHint": true + }, + "description": "Search for GitHub users exclusively", + "inputSchema": { + "properties": { + "order": { + "description": "Sort order", + "enum": [ + "asc", + "desc" + ], + "type": "string" + }, + "page": { + "description": "Page number for pagination (min 1)", + "minimum": 1, + "type": "number" + }, + "perPage": { + "description": "Results per page for pagination (min 1, max 100)", + "maximum": 100, + "minimum": 1, + "type": "number" + }, + "query": { + "description": "Search query using GitHub users search syntax scoped to type:user", + "type": "string" + }, + "sort": { + "description": "Sort field by category", + "enum": [ + "followers", + "repositories", + "joined" + ], + "type": "string" + } + }, + "required": [ + "query" + ], + "type": "object" + }, + "name": "search_users" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/submit_pending_pull_request_review.snap b/pkg/github/__toolsnaps__/submit_pending_pull_request_review.snap new file mode 100644 index 000000000..f3541922b --- /dev/null +++ b/pkg/github/__toolsnaps__/submit_pending_pull_request_review.snap @@ -0,0 +1,44 @@ +{ + "annotations": { + "title": "Submit the requester's latest pending pull request review", + "readOnlyHint": false + }, + "description": "Submit the requester's latest pending pull request review, normally this is a final step after creating a pending review, adding comments first, unless you know that the user already did the first two steps, you should check before calling this.", + "inputSchema": { + "properties": { + "body": { + "description": "The text of the review comment", + "type": "string" + }, + "event": { + "description": "The event to perform", + "enum": [ + "APPROVE", + "REQUEST_CHANGES", + "COMMENT" + ], + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber", + "event" + ], + "type": "object" + }, + "name": "submit_pending_pull_request_review" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/update_issue.snap b/pkg/github/__toolsnaps__/update_issue.snap new file mode 100644 index 000000000..4bcae7ba7 --- /dev/null +++ b/pkg/github/__toolsnaps__/update_issue.snap @@ -0,0 +1,64 @@ +{ + "annotations": { + "title": "Edit issue", + "readOnlyHint": false + }, + "description": "Update an existing issue in a GitHub repository.", + "inputSchema": { + "properties": { + "assignees": { + "description": "New assignees", + "items": { + "type": "string" + }, + "type": "array" + }, + "body": { + "description": "New description", + "type": "string" + }, + "issue_number": { + "description": "Issue number to update", + "type": "number" + }, + "labels": { + "description": "New labels", + "items": { + "type": "string" + }, + "type": "array" + }, + "milestone": { + "description": "New milestone number", + "type": "number" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "state": { + "description": "New state", + "enum": [ + "open", + "closed" + ], + "type": "string" + }, + "title": { + "description": "New title", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "issue_number" + ], + "type": "object" + }, + "name": "update_issue" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/update_pull_request.snap b/pkg/github/__toolsnaps__/update_pull_request.snap new file mode 100644 index 000000000..765983afd --- /dev/null +++ b/pkg/github/__toolsnaps__/update_pull_request.snap @@ -0,0 +1,54 @@ +{ + "annotations": { + "title": "Edit pull request", + "readOnlyHint": false + }, + "description": "Update an existing pull request in a GitHub repository.", + "inputSchema": { + "properties": { + "base": { + "description": "New base branch name", + "type": "string" + }, + "body": { + "description": "New description", + "type": "string" + }, + "maintainer_can_modify": { + "description": "Allow maintainer edits", + "type": "boolean" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number to update", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + }, + "state": { + "description": "New state", + "enum": [ + "open", + "closed" + ], + "type": "string" + }, + "title": { + "description": "New title", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "update_pull_request" +} \ No newline at end of file diff --git a/pkg/github/__toolsnaps__/update_pull_request_branch.snap b/pkg/github/__toolsnaps__/update_pull_request_branch.snap new file mode 100644 index 000000000..60ec9c126 --- /dev/null +++ b/pkg/github/__toolsnaps__/update_pull_request_branch.snap @@ -0,0 +1,34 @@ +{ + "annotations": { + "title": "Update pull request branch", + "readOnlyHint": false + }, + "description": "Update the branch of a pull request with the latest changes from the base branch.", + "inputSchema": { + "properties": { + "expectedHeadSha": { + "description": "The expected SHA of the pull request's HEAD ref", + "type": "string" + }, + "owner": { + "description": "Repository owner", + "type": "string" + }, + "pullNumber": { + "description": "Pull request number", + "type": "number" + }, + "repo": { + "description": "Repository name", + "type": "string" + } + }, + "required": [ + "owner", + "repo", + "pullNumber" + ], + "type": "object" + }, + "name": "update_pull_request_branch" +} \ No newline at end of file diff --git a/pkg/github/actions.go b/pkg/github/actions.go new file mode 100644 index 000000000..3c441d5aa --- /dev/null +++ b/pkg/github/actions.go @@ -0,0 +1,1230 @@ +package github + +import ( + "context" + "encoding/json" + "fmt" + "io" + "net/http" + "strconv" + "strings" + + ghErrors "github.com/github/github-mcp-server/pkg/errors" + "github.com/github/github-mcp-server/pkg/translations" + "github.com/google/go-github/v73/github" + "github.com/mark3labs/mcp-go/mcp" + "github.com/mark3labs/mcp-go/server" +) + +const ( + DescriptionRepositoryOwner = "Repository owner" + DescriptionRepositoryName = "Repository name" +) + +// ListWorkflows creates a tool to list workflows in a repository +func ListWorkflows(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("list_workflows", + mcp.WithDescription(t("TOOL_LIST_WORKFLOWS_DESCRIPTION", "List workflows in a repository")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_LIST_WORKFLOWS_USER_TITLE", "List workflows"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + WithPagination(), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Get optional pagination parameters + pagination, err := OptionalPaginationParams(request) + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + // Set up list options + opts := &github.ListOptions{ + PerPage: pagination.perPage, + Page: pagination.page, + } + + workflows, resp, err := client.Actions.ListWorkflows(ctx, owner, repo, opts) + if err != nil { + return nil, fmt.Errorf("failed to list workflows: %w", err) + } + defer func() { _ = resp.Body.Close() }() + + r, err := json.Marshal(workflows) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// ListWorkflowRuns creates a tool to list workflow runs for a specific workflow +func ListWorkflowRuns(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("list_workflow_runs", + mcp.WithDescription(t("TOOL_LIST_WORKFLOW_RUNS_DESCRIPTION", "List workflow runs for a specific workflow")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_LIST_WORKFLOW_RUNS_USER_TITLE", "List workflow runs"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithString("workflow_id", + mcp.Required(), + mcp.Description("The workflow ID or workflow file name"), + ), + mcp.WithString("actor", + mcp.Description("Returns someone's workflow runs. Use the login for the user who created the workflow run."), + ), + mcp.WithString("branch", + mcp.Description("Returns workflow runs associated with a branch. Use the name of the branch."), + ), + mcp.WithString("event", + mcp.Description("Returns workflow runs for a specific event type"), + mcp.Enum( + "branch_protection_rule", + "check_run", + "check_suite", + "create", + "delete", + "deployment", + "deployment_status", + "discussion", + "discussion_comment", + "fork", + "gollum", + "issue_comment", + "issues", + "label", + "merge_group", + "milestone", + "page_build", + "public", + "pull_request", + "pull_request_review", + "pull_request_review_comment", + "pull_request_target", + "push", + "registry_package", + "release", + "repository_dispatch", + "schedule", + "status", + "watch", + "workflow_call", + "workflow_dispatch", + "workflow_run", + ), + ), + mcp.WithString("status", + mcp.Description("Returns workflow runs with the check run status"), + mcp.Enum("queued", "in_progress", "completed", "requested", "waiting"), + ), + WithPagination(), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + workflowID, err := RequiredParam[string](request, "workflow_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Get optional filtering parameters + actor, err := OptionalParam[string](request, "actor") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + branch, err := OptionalParam[string](request, "branch") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + event, err := OptionalParam[string](request, "event") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + status, err := OptionalParam[string](request, "status") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Get optional pagination parameters + pagination, err := OptionalPaginationParams(request) + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + // Set up list options + opts := &github.ListWorkflowRunsOptions{ + Actor: actor, + Branch: branch, + Event: event, + Status: status, + ListOptions: github.ListOptions{ + PerPage: pagination.perPage, + Page: pagination.page, + }, + } + + workflowRuns, resp, err := client.Actions.ListWorkflowRunsByFileName(ctx, owner, repo, workflowID, opts) + if err != nil { + return nil, fmt.Errorf("failed to list workflow runs: %w", err) + } + defer func() { _ = resp.Body.Close() }() + + r, err := json.Marshal(workflowRuns) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// RunWorkflow creates a tool to run an Actions workflow +func RunWorkflow(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("run_workflow", + mcp.WithDescription(t("TOOL_RUN_WORKFLOW_DESCRIPTION", "Run an Actions workflow by workflow ID or filename")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_RUN_WORKFLOW_USER_TITLE", "Run workflow"), + ReadOnlyHint: ToBoolPtr(false), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithString("workflow_id", + mcp.Required(), + mcp.Description("The workflow ID (numeric) or workflow file name (e.g., main.yml, ci.yaml)"), + ), + mcp.WithString("ref", + mcp.Required(), + mcp.Description("The git reference for the workflow. The reference can be a branch or tag name."), + ), + mcp.WithObject("inputs", + mcp.Description("Inputs the workflow accepts"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + workflowID, err := RequiredParam[string](request, "workflow_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + ref, err := RequiredParam[string](request, "ref") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Get optional inputs parameter + var inputs map[string]interface{} + if requestInputs, ok := request.GetArguments()["inputs"]; ok { + if inputsMap, ok := requestInputs.(map[string]interface{}); ok { + inputs = inputsMap + } + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + event := github.CreateWorkflowDispatchEventRequest{ + Ref: ref, + Inputs: inputs, + } + + var resp *github.Response + var workflowType string + + if workflowIDInt, parseErr := strconv.ParseInt(workflowID, 10, 64); parseErr == nil { + resp, err = client.Actions.CreateWorkflowDispatchEventByID(ctx, owner, repo, workflowIDInt, event) + workflowType = "workflow_id" + } else { + resp, err = client.Actions.CreateWorkflowDispatchEventByFileName(ctx, owner, repo, workflowID, event) + workflowType = "workflow_file" + } + + if err != nil { + return nil, fmt.Errorf("failed to run workflow: %w", err) + } + defer func() { _ = resp.Body.Close() }() + + result := map[string]any{ + "message": "Workflow run has been queued", + "workflow_type": workflowType, + "workflow_id": workflowID, + "ref": ref, + "inputs": inputs, + "status": resp.Status, + "status_code": resp.StatusCode, + } + + r, err := json.Marshal(result) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// GetWorkflowRun creates a tool to get details of a specific workflow run +func GetWorkflowRun(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("get_workflow_run", + mcp.WithDescription(t("TOOL_GET_WORKFLOW_RUN_DESCRIPTION", "Get details of a specific workflow run")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_GET_WORKFLOW_RUN_USER_TITLE", "Get workflow run"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("run_id", + mcp.Required(), + mcp.Description("The unique identifier of the workflow run"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runIDInt, err := RequiredInt(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID := int64(runIDInt) + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + workflowRun, resp, err := client.Actions.GetWorkflowRunByID(ctx, owner, repo, runID) + if err != nil { + return nil, fmt.Errorf("failed to get workflow run: %w", err) + } + defer func() { _ = resp.Body.Close() }() + + r, err := json.Marshal(workflowRun) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// GetWorkflowRunLogs creates a tool to download logs for a specific workflow run +func GetWorkflowRunLogs(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("get_workflow_run_logs", + mcp.WithDescription(t("TOOL_GET_WORKFLOW_RUN_LOGS_DESCRIPTION", "Download logs for a specific workflow run (EXPENSIVE: downloads ALL logs as ZIP. Consider using get_job_logs with failed_only=true for debugging failed jobs)")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_GET_WORKFLOW_RUN_LOGS_USER_TITLE", "Get workflow run logs"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("run_id", + mcp.Required(), + mcp.Description("The unique identifier of the workflow run"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runIDInt, err := RequiredInt(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID := int64(runIDInt) + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + // Get the download URL for the logs + url, resp, err := client.Actions.GetWorkflowRunLogs(ctx, owner, repo, runID, 1) + if err != nil { + return nil, fmt.Errorf("failed to get workflow run logs: %w", err) + } + defer func() { _ = resp.Body.Close() }() + + // Create response with the logs URL and information + result := map[string]any{ + "logs_url": url.String(), + "message": "Workflow run logs are available for download", + "note": "The logs_url provides a download link for the complete workflow run logs as a ZIP archive. You can download this archive to extract and examine individual job logs.", + "warning": "This downloads ALL logs as a ZIP file which can be large and expensive. For debugging failed jobs, consider using get_job_logs with failed_only=true and run_id instead.", + "optimization_tip": "Use: get_job_logs with parameters {run_id: " + fmt.Sprintf("%d", runID) + ", failed_only: true} for more efficient failed job debugging", + } + + r, err := json.Marshal(result) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// ListWorkflowJobs creates a tool to list jobs for a specific workflow run +func ListWorkflowJobs(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("list_workflow_jobs", + mcp.WithDescription(t("TOOL_LIST_WORKFLOW_JOBS_DESCRIPTION", "List jobs for a specific workflow run")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_LIST_WORKFLOW_JOBS_USER_TITLE", "List workflow jobs"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("run_id", + mcp.Required(), + mcp.Description("The unique identifier of the workflow run"), + ), + mcp.WithString("filter", + mcp.Description("Filters jobs by their completed_at timestamp"), + mcp.Enum("latest", "all"), + ), + WithPagination(), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runIDInt, err := RequiredInt(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID := int64(runIDInt) + + // Get optional filtering parameters + filter, err := OptionalParam[string](request, "filter") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Get optional pagination parameters + pagination, err := OptionalPaginationParams(request) + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + // Set up list options + opts := &github.ListWorkflowJobsOptions{ + Filter: filter, + ListOptions: github.ListOptions{ + PerPage: pagination.perPage, + Page: pagination.page, + }, + } + + jobs, resp, err := client.Actions.ListWorkflowJobs(ctx, owner, repo, runID, opts) + if err != nil { + return nil, fmt.Errorf("failed to list workflow jobs: %w", err) + } + defer func() { _ = resp.Body.Close() }() + + // Add optimization tip for failed job debugging + response := map[string]any{ + "jobs": jobs, + "optimization_tip": "For debugging failed jobs, consider using get_job_logs with failed_only=true and run_id=" + fmt.Sprintf("%d", runID) + " to get logs directly without needing to list jobs first", + } + + r, err := json.Marshal(response) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// GetJobLogs creates a tool to download logs for a specific workflow job or efficiently get all failed job logs for a workflow run +func GetJobLogs(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("get_job_logs", + mcp.WithDescription(t("TOOL_GET_JOB_LOGS_DESCRIPTION", "Download logs for a specific workflow job or efficiently get all failed job logs for a workflow run")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_GET_JOB_LOGS_USER_TITLE", "Get job logs"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("job_id", + mcp.Description("The unique identifier of the workflow job (required for single job logs)"), + ), + mcp.WithNumber("run_id", + mcp.Description("Workflow run ID (required when using failed_only)"), + ), + mcp.WithBoolean("failed_only", + mcp.Description("When true, gets logs for all failed jobs in run_id"), + ), + mcp.WithBoolean("return_content", + mcp.Description("Returns actual log content instead of URLs"), + ), + mcp.WithNumber("tail_lines", + mcp.Description("Number of lines to return from the end of the log"), + mcp.DefaultNumber(500), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Get optional parameters + jobID, err := OptionalIntParam(request, "job_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID, err := OptionalIntParam(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + failedOnly, err := OptionalParam[bool](request, "failed_only") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + returnContent, err := OptionalParam[bool](request, "return_content") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + tailLines, err := OptionalIntParam(request, "tail_lines") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + // Default to 500 lines if not specified + if tailLines == 0 { + tailLines = 500 + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + // Validate parameters + if failedOnly && runID == 0 { + return mcp.NewToolResultError("run_id is required when failed_only is true"), nil + } + if !failedOnly && jobID == 0 { + return mcp.NewToolResultError("job_id is required when failed_only is false"), nil + } + + if failedOnly && runID > 0 { + // Handle failed-only mode: get logs for all failed jobs in the workflow run + return handleFailedJobLogs(ctx, client, owner, repo, int64(runID), returnContent, tailLines) + } else if jobID > 0 { + // Handle single job mode + return handleSingleJobLogs(ctx, client, owner, repo, int64(jobID), returnContent, tailLines) + } + + return mcp.NewToolResultError("Either job_id must be provided for single job logs, or run_id with failed_only=true for failed job logs"), nil + } +} + +// handleFailedJobLogs gets logs for all failed jobs in a workflow run +func handleFailedJobLogs(ctx context.Context, client *github.Client, owner, repo string, runID int64, returnContent bool, tailLines int) (*mcp.CallToolResult, error) { + // First, get all jobs for the workflow run + jobs, resp, err := client.Actions.ListWorkflowJobs(ctx, owner, repo, runID, &github.ListWorkflowJobsOptions{ + Filter: "latest", + }) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to list workflow jobs", resp, err), nil + } + defer func() { _ = resp.Body.Close() }() + + // Filter for failed jobs + var failedJobs []*github.WorkflowJob + for _, job := range jobs.Jobs { + if job.GetConclusion() == "failure" { + failedJobs = append(failedJobs, job) + } + } + + if len(failedJobs) == 0 { + result := map[string]any{ + "message": "No failed jobs found in this workflow run", + "run_id": runID, + "total_jobs": len(jobs.Jobs), + "failed_jobs": 0, + } + r, _ := json.Marshal(result) + return mcp.NewToolResultText(string(r)), nil + } + + // Collect logs for all failed jobs + var logResults []map[string]any + for _, job := range failedJobs { + jobResult, resp, err := getJobLogData(ctx, client, owner, repo, job.GetID(), job.GetName(), returnContent, tailLines) + if err != nil { + // Continue with other jobs even if one fails + jobResult = map[string]any{ + "job_id": job.GetID(), + "job_name": job.GetName(), + "error": err.Error(), + } + // Enable reporting of status codes and error causes + _, _ = ghErrors.NewGitHubAPIErrorToCtx(ctx, "failed to get job logs", resp, err) // Explicitly ignore error for graceful handling + } + + logResults = append(logResults, jobResult) + } + + result := map[string]any{ + "message": fmt.Sprintf("Retrieved logs for %d failed jobs", len(failedJobs)), + "run_id": runID, + "total_jobs": len(jobs.Jobs), + "failed_jobs": len(failedJobs), + "logs": logResults, + "return_format": map[string]bool{"content": returnContent, "urls": !returnContent}, + } + + r, err := json.Marshal(result) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil +} + +// handleSingleJobLogs gets logs for a single job +func handleSingleJobLogs(ctx context.Context, client *github.Client, owner, repo string, jobID int64, returnContent bool, tailLines int) (*mcp.CallToolResult, error) { + jobResult, resp, err := getJobLogData(ctx, client, owner, repo, jobID, "", returnContent, tailLines) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to get job logs", resp, err), nil + } + + r, err := json.Marshal(jobResult) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil +} + +// getJobLogData retrieves log data for a single job, either as URL or content +func getJobLogData(ctx context.Context, client *github.Client, owner, repo string, jobID int64, jobName string, returnContent bool, tailLines int) (map[string]any, *github.Response, error) { + // Get the download URL for the job logs + url, resp, err := client.Actions.GetWorkflowJobLogs(ctx, owner, repo, jobID, 1) + if err != nil { + return nil, resp, fmt.Errorf("failed to get job logs for job %d: %w", jobID, err) + } + defer func() { _ = resp.Body.Close() }() + + result := map[string]any{ + "job_id": jobID, + } + if jobName != "" { + result["job_name"] = jobName + } + + if returnContent { + // Download and return the actual log content + content, originalLength, httpResp, err := downloadLogContent(url.String(), tailLines) //nolint:bodyclose // Response body is closed in downloadLogContent, but we need to return httpResp + if err != nil { + // To keep the return value consistent wrap the response as a GitHub Response + ghRes := &github.Response{ + Response: httpResp, + } + return nil, ghRes, fmt.Errorf("failed to download log content for job %d: %w", jobID, err) + } + result["logs_content"] = content + result["message"] = "Job logs content retrieved successfully" + result["original_length"] = originalLength + } else { + // Return just the URL + result["logs_url"] = url.String() + result["message"] = "Job logs are available for download" + result["note"] = "The logs_url provides a download link for the individual job logs in plain text format. Use return_content=true to get the actual log content." + } + + return result, resp, nil +} + +// downloadLogContent downloads the actual log content from a GitHub logs URL +func downloadLogContent(logURL string, tailLines int) (string, int, *http.Response, error) { + httpResp, err := http.Get(logURL) //nolint:gosec // URLs are provided by GitHub API and are safe + if err != nil { + return "", 0, httpResp, fmt.Errorf("failed to download logs: %w", err) + } + defer func() { _ = httpResp.Body.Close() }() + + if httpResp.StatusCode != http.StatusOK { + return "", 0, httpResp, fmt.Errorf("failed to download logs: HTTP %d", httpResp.StatusCode) + } + + content, err := io.ReadAll(httpResp.Body) + if err != nil { + return "", 0, httpResp, fmt.Errorf("failed to read log content: %w", err) + } + + // Clean up and format the log content for better readability + logContent := strings.TrimSpace(string(content)) + + trimmedContent, lineCount := trimContent(logContent, tailLines) + return trimmedContent, lineCount, httpResp, nil +} + +// trimContent trims the content to a maximum length and returns the trimmed content and an original length +func trimContent(content string, tailLines int) (string, int) { + // Truncate to tail_lines if specified + lineCount := 0 + if tailLines > 0 { + + // Count backwards to find the nth newline from the end and a total number of lines + for i := len(content) - 1; i >= 0 && lineCount < tailLines; i-- { + if content[i] == '\n' { + lineCount++ + // If we have reached the tailLines, trim the content + if lineCount == tailLines { + content = content[i+1:] + } + } + } + } + return content, lineCount +} + +// RerunWorkflowRun creates a tool to re-run an entire workflow run +func RerunWorkflowRun(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("rerun_workflow_run", + mcp.WithDescription(t("TOOL_RERUN_WORKFLOW_RUN_DESCRIPTION", "Re-run an entire workflow run")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_RERUN_WORKFLOW_RUN_USER_TITLE", "Rerun workflow run"), + ReadOnlyHint: ToBoolPtr(false), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("run_id", + mcp.Required(), + mcp.Description("The unique identifier of the workflow run"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runIDInt, err := RequiredInt(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID := int64(runIDInt) + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + resp, err := client.Actions.RerunWorkflowByID(ctx, owner, repo, runID) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to rerun workflow run", resp, err), nil + } + defer func() { _ = resp.Body.Close() }() + + result := map[string]any{ + "message": "Workflow run has been queued for re-run", + "run_id": runID, + "status": resp.Status, + "status_code": resp.StatusCode, + } + + r, err := json.Marshal(result) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// RerunFailedJobs creates a tool to re-run only the failed jobs in a workflow run +func RerunFailedJobs(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("rerun_failed_jobs", + mcp.WithDescription(t("TOOL_RERUN_FAILED_JOBS_DESCRIPTION", "Re-run only the failed jobs in a workflow run")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_RERUN_FAILED_JOBS_USER_TITLE", "Rerun failed jobs"), + ReadOnlyHint: ToBoolPtr(false), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("run_id", + mcp.Required(), + mcp.Description("The unique identifier of the workflow run"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runIDInt, err := RequiredInt(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID := int64(runIDInt) + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + resp, err := client.Actions.RerunFailedJobsByID(ctx, owner, repo, runID) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to rerun failed jobs", resp, err), nil + } + defer func() { _ = resp.Body.Close() }() + + result := map[string]any{ + "message": "Failed jobs have been queued for re-run", + "run_id": runID, + "status": resp.Status, + "status_code": resp.StatusCode, + } + + r, err := json.Marshal(result) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// CancelWorkflowRun creates a tool to cancel a workflow run +func CancelWorkflowRun(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("cancel_workflow_run", + mcp.WithDescription(t("TOOL_CANCEL_WORKFLOW_RUN_DESCRIPTION", "Cancel a workflow run")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_CANCEL_WORKFLOW_RUN_USER_TITLE", "Cancel workflow run"), + ReadOnlyHint: ToBoolPtr(false), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("run_id", + mcp.Required(), + mcp.Description("The unique identifier of the workflow run"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runIDInt, err := RequiredInt(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID := int64(runIDInt) + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + resp, err := client.Actions.CancelWorkflowRunByID(ctx, owner, repo, runID) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to cancel workflow run", resp, err), nil + } + defer func() { _ = resp.Body.Close() }() + + result := map[string]any{ + "message": "Workflow run has been cancelled", + "run_id": runID, + "status": resp.Status, + "status_code": resp.StatusCode, + } + + r, err := json.Marshal(result) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// ListWorkflowRunArtifacts creates a tool to list artifacts for a workflow run +func ListWorkflowRunArtifacts(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("list_workflow_run_artifacts", + mcp.WithDescription(t("TOOL_LIST_WORKFLOW_RUN_ARTIFACTS_DESCRIPTION", "List artifacts for a workflow run")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_LIST_WORKFLOW_RUN_ARTIFACTS_USER_TITLE", "List workflow artifacts"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("run_id", + mcp.Required(), + mcp.Description("The unique identifier of the workflow run"), + ), + WithPagination(), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runIDInt, err := RequiredInt(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID := int64(runIDInt) + + // Get optional pagination parameters + pagination, err := OptionalPaginationParams(request) + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + // Set up list options + opts := &github.ListOptions{ + PerPage: pagination.perPage, + Page: pagination.page, + } + + artifacts, resp, err := client.Actions.ListWorkflowRunArtifacts(ctx, owner, repo, runID, opts) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to list workflow run artifacts", resp, err), nil + } + defer func() { _ = resp.Body.Close() }() + + r, err := json.Marshal(artifacts) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// DownloadWorkflowRunArtifact creates a tool to download a workflow run artifact +func DownloadWorkflowRunArtifact(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("download_workflow_run_artifact", + mcp.WithDescription(t("TOOL_DOWNLOAD_WORKFLOW_RUN_ARTIFACT_DESCRIPTION", "Get download URL for a workflow run artifact")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_DOWNLOAD_WORKFLOW_RUN_ARTIFACT_USER_TITLE", "Download workflow artifact"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("artifact_id", + mcp.Required(), + mcp.Description("The unique identifier of the artifact"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + artifactIDInt, err := RequiredInt(request, "artifact_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + artifactID := int64(artifactIDInt) + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + // Get the download URL for the artifact + url, resp, err := client.Actions.DownloadArtifact(ctx, owner, repo, artifactID, 1) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to get artifact download URL", resp, err), nil + } + defer func() { _ = resp.Body.Close() }() + + // Create response with the download URL and information + result := map[string]any{ + "download_url": url.String(), + "message": "Artifact is available for download", + "note": "The download_url provides a download link for the artifact as a ZIP archive. The link is temporary and expires after a short time.", + "artifact_id": artifactID, + } + + r, err := json.Marshal(result) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// DeleteWorkflowRunLogs creates a tool to delete logs for a workflow run +func DeleteWorkflowRunLogs(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("delete_workflow_run_logs", + mcp.WithDescription(t("TOOL_DELETE_WORKFLOW_RUN_LOGS_DESCRIPTION", "Delete logs for a workflow run")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_DELETE_WORKFLOW_RUN_LOGS_USER_TITLE", "Delete workflow logs"), + ReadOnlyHint: ToBoolPtr(false), + DestructiveHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("run_id", + mcp.Required(), + mcp.Description("The unique identifier of the workflow run"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runIDInt, err := RequiredInt(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID := int64(runIDInt) + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + resp, err := client.Actions.DeleteWorkflowRunLogs(ctx, owner, repo, runID) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to delete workflow run logs", resp, err), nil + } + defer func() { _ = resp.Body.Close() }() + + result := map[string]any{ + "message": "Workflow run logs have been deleted", + "run_id": runID, + "status": resp.Status, + "status_code": resp.StatusCode, + } + + r, err := json.Marshal(result) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +// GetWorkflowRunUsage creates a tool to get usage metrics for a workflow run +func GetWorkflowRunUsage(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("get_workflow_run_usage", + mcp.WithDescription(t("TOOL_GET_WORKFLOW_RUN_USAGE_DESCRIPTION", "Get usage metrics for a workflow run")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_GET_WORKFLOW_RUN_USAGE_USER_TITLE", "Get workflow usage"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description(DescriptionRepositoryOwner), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description(DescriptionRepositoryName), + ), + mcp.WithNumber("run_id", + mcp.Required(), + mcp.Description("The unique identifier of the workflow run"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runIDInt, err := RequiredInt(request, "run_id") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + runID := int64(runIDInt) + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + usage, resp, err := client.Actions.GetWorkflowRunUsageByID(ctx, owner, repo, runID) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, "failed to get workflow run usage", resp, err), nil + } + defer func() { _ = resp.Body.Close() }() + + r, err := json.Marshal(usage) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} diff --git a/pkg/github/actions_test.go b/pkg/github/actions_test.go new file mode 100644 index 000000000..cb33cbe6b --- /dev/null +++ b/pkg/github/actions_test.go @@ -0,0 +1,1146 @@ +package github + +import ( + "context" + "encoding/json" + "net/http" + "net/http/httptest" + "testing" + + "github.com/github/github-mcp-server/pkg/translations" + "github.com/google/go-github/v73/github" + "github.com/migueleliasweb/go-github-mock/src/mock" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func Test_ListWorkflows(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := ListWorkflows(stubGetClientFn(mockClient), translations.NullTranslationHelper) + + assert.Equal(t, "list_workflows", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "perPage") + assert.Contains(t, tool.InputSchema.Properties, "page") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"}) + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]any + expectError bool + expectedErrMsg string + }{ + { + name: "successful workflow listing", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsWorkflowsByOwnerByRepo, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + workflows := &github.Workflows{ + TotalCount: github.Ptr(2), + Workflows: []*github.Workflow{ + { + ID: github.Ptr(int64(123)), + Name: github.Ptr("CI"), + Path: github.Ptr(".github/workflows/ci.yml"), + State: github.Ptr("active"), + CreatedAt: &github.Timestamp{}, + UpdatedAt: &github.Timestamp{}, + URL: github.Ptr("https://api.github.com/repos/owner/repo/actions/workflows/123"), + HTMLURL: github.Ptr("https://github.com/owner/repo/actions/workflows/ci.yml"), + BadgeURL: github.Ptr("https://github.com/owner/repo/workflows/CI/badge.svg"), + NodeID: github.Ptr("W_123"), + }, + { + ID: github.Ptr(int64(456)), + Name: github.Ptr("Deploy"), + Path: github.Ptr(".github/workflows/deploy.yml"), + State: github.Ptr("active"), + CreatedAt: &github.Timestamp{}, + UpdatedAt: &github.Timestamp{}, + URL: github.Ptr("https://api.github.com/repos/owner/repo/actions/workflows/456"), + HTMLURL: github.Ptr("https://github.com/owner/repo/actions/workflows/deploy.yml"), + BadgeURL: github.Ptr("https://github.com/owner/repo/workflows/Deploy/badge.svg"), + NodeID: github.Ptr("W_456"), + }, + }, + } + w.WriteHeader(http.StatusOK) + _ = json.NewEncoder(w).Encode(workflows) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + }, + expectError: false, + }, + { + name: "missing required parameter owner", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "repo": "repo", + }, + expectError: true, + expectedErrMsg: "missing required parameter: owner", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := ListWorkflows(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + require.NoError(t, err) + require.Equal(t, tc.expectError, result.IsError) + + // Parse the result and get the text content if no error + textContent := getTextResult(t, result) + + if tc.expectedErrMsg != "" { + assert.Equal(t, tc.expectedErrMsg, textContent.Text) + return + } + + // Unmarshal and verify the result + var response github.Workflows + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + assert.NotNil(t, response.TotalCount) + assert.Greater(t, *response.TotalCount, 0) + assert.NotEmpty(t, response.Workflows) + }) + } +} + +func Test_RunWorkflow(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := RunWorkflow(stubGetClientFn(mockClient), translations.NullTranslationHelper) + + assert.Equal(t, "run_workflow", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "workflow_id") + assert.Contains(t, tool.InputSchema.Properties, "ref") + assert.Contains(t, tool.InputSchema.Properties, "inputs") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "workflow_id", "ref"}) + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]any + expectError bool + expectedErrMsg string + }{ + { + name: "successful workflow run", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.PostReposActionsWorkflowsDispatchesByOwnerByRepoByWorkflowId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNoContent) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "workflow_id": "12345", + "ref": "main", + }, + expectError: false, + }, + { + name: "missing required parameter workflow_id", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "ref": "main", + }, + expectError: true, + expectedErrMsg: "missing required parameter: workflow_id", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := RunWorkflow(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + require.NoError(t, err) + require.Equal(t, tc.expectError, result.IsError) + + // Parse the result and get the text content if no error + textContent := getTextResult(t, result) + + if tc.expectedErrMsg != "" { + assert.Equal(t, tc.expectedErrMsg, textContent.Text) + return + } + + // Unmarshal and verify the result + var response map[string]any + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + assert.Equal(t, "Workflow run has been queued", response["message"]) + assert.Contains(t, response, "workflow_type") + }) + } +} + +func Test_RunWorkflow_WithFilename(t *testing.T) { + // Test the unified RunWorkflow function with filenames + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]any + expectError bool + expectedErrMsg string + }{ + { + name: "successful workflow run by filename", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.PostReposActionsWorkflowsDispatchesByOwnerByRepoByWorkflowId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNoContent) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "workflow_id": "ci.yml", + "ref": "main", + }, + expectError: false, + }, + { + name: "successful workflow run by numeric ID as string", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.PostReposActionsWorkflowsDispatchesByOwnerByRepoByWorkflowId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNoContent) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "workflow_id": "12345", + "ref": "main", + }, + expectError: false, + }, + { + name: "missing required parameter workflow_id", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "ref": "main", + }, + expectError: true, + expectedErrMsg: "missing required parameter: workflow_id", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := RunWorkflow(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + require.NoError(t, err) + require.Equal(t, tc.expectError, result.IsError) + + // Parse the result and get the text content if no error + textContent := getTextResult(t, result) + + if tc.expectedErrMsg != "" { + assert.Equal(t, tc.expectedErrMsg, textContent.Text) + return + } + + // Unmarshal and verify the result + var response map[string]any + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + assert.Equal(t, "Workflow run has been queued", response["message"]) + assert.Contains(t, response, "workflow_type") + }) + } +} + +func Test_CancelWorkflowRun(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := CancelWorkflowRun(stubGetClientFn(mockClient), translations.NullTranslationHelper) + + assert.Equal(t, "cancel_workflow_run", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "run_id") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "run_id"}) + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]any + expectError bool + expectedErrMsg string + }{ + { + name: "successful workflow run cancellation", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatch( + mock.EndpointPattern{ + Pattern: "/repos/owner/repo/actions/runs/12345/cancel", + Method: "POST", + }, + "", // Empty response body for 202 Accepted + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "run_id": float64(12345), + }, + expectError: false, + }, + { + name: "missing required parameter run_id", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + }, + expectError: true, + expectedErrMsg: "missing required parameter: run_id", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := CancelWorkflowRun(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + require.NoError(t, err) + require.Equal(t, tc.expectError, result.IsError) + + // Parse the result and get the text content + textContent := getTextResult(t, result) + + if tc.expectedErrMsg != "" { + assert.Equal(t, tc.expectedErrMsg, textContent.Text) + return + } + + // Unmarshal and verify the result + var response map[string]any + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + assert.Equal(t, "Workflow run has been cancelled", response["message"]) + assert.Equal(t, float64(12345), response["run_id"]) + }) + } +} + +func Test_ListWorkflowRunArtifacts(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := ListWorkflowRunArtifacts(stubGetClientFn(mockClient), translations.NullTranslationHelper) + + assert.Equal(t, "list_workflow_run_artifacts", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "run_id") + assert.Contains(t, tool.InputSchema.Properties, "perPage") + assert.Contains(t, tool.InputSchema.Properties, "page") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "run_id"}) + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]any + expectError bool + expectedErrMsg string + }{ + { + name: "successful artifacts listing", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsRunsArtifactsByOwnerByRepoByRunId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + artifacts := &github.ArtifactList{ + TotalCount: github.Ptr(int64(2)), + Artifacts: []*github.Artifact{ + { + ID: github.Ptr(int64(1)), + NodeID: github.Ptr("A_1"), + Name: github.Ptr("build-artifacts"), + SizeInBytes: github.Ptr(int64(1024)), + URL: github.Ptr("https://api.github.com/repos/owner/repo/actions/artifacts/1"), + ArchiveDownloadURL: github.Ptr("https://api.github.com/repos/owner/repo/actions/artifacts/1/zip"), + Expired: github.Ptr(false), + CreatedAt: &github.Timestamp{}, + UpdatedAt: &github.Timestamp{}, + ExpiresAt: &github.Timestamp{}, + WorkflowRun: &github.ArtifactWorkflowRun{ + ID: github.Ptr(int64(12345)), + RepositoryID: github.Ptr(int64(1)), + HeadRepositoryID: github.Ptr(int64(1)), + HeadBranch: github.Ptr("main"), + HeadSHA: github.Ptr("abc123"), + }, + }, + { + ID: github.Ptr(int64(2)), + NodeID: github.Ptr("A_2"), + Name: github.Ptr("test-results"), + SizeInBytes: github.Ptr(int64(512)), + URL: github.Ptr("https://api.github.com/repos/owner/repo/actions/artifacts/2"), + ArchiveDownloadURL: github.Ptr("https://api.github.com/repos/owner/repo/actions/artifacts/2/zip"), + Expired: github.Ptr(false), + CreatedAt: &github.Timestamp{}, + UpdatedAt: &github.Timestamp{}, + ExpiresAt: &github.Timestamp{}, + WorkflowRun: &github.ArtifactWorkflowRun{ + ID: github.Ptr(int64(12345)), + RepositoryID: github.Ptr(int64(1)), + HeadRepositoryID: github.Ptr(int64(1)), + HeadBranch: github.Ptr("main"), + HeadSHA: github.Ptr("abc123"), + }, + }, + }, + } + w.WriteHeader(http.StatusOK) + _ = json.NewEncoder(w).Encode(artifacts) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "run_id": float64(12345), + }, + expectError: false, + }, + { + name: "missing required parameter run_id", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + }, + expectError: true, + expectedErrMsg: "missing required parameter: run_id", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := ListWorkflowRunArtifacts(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + require.NoError(t, err) + require.Equal(t, tc.expectError, result.IsError) + + // Parse the result and get the text content if no error + textContent := getTextResult(t, result) + + if tc.expectedErrMsg != "" { + assert.Equal(t, tc.expectedErrMsg, textContent.Text) + return + } + + // Unmarshal and verify the result + var response github.ArtifactList + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + assert.NotNil(t, response.TotalCount) + assert.Greater(t, *response.TotalCount, int64(0)) + assert.NotEmpty(t, response.Artifacts) + }) + } +} + +func Test_DownloadWorkflowRunArtifact(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := DownloadWorkflowRunArtifact(stubGetClientFn(mockClient), translations.NullTranslationHelper) + + assert.Equal(t, "download_workflow_run_artifact", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "artifact_id") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "artifact_id"}) + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]any + expectError bool + expectedErrMsg string + }{ + { + name: "successful artifact download URL", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.EndpointPattern{ + Pattern: "/repos/owner/repo/actions/artifacts/123/zip", + Method: "GET", + }, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + // GitHub returns a 302 redirect to the download URL + w.Header().Set("Location", "https://api.github.com/repos/owner/repo/actions/artifacts/123/download") + w.WriteHeader(http.StatusFound) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "artifact_id": float64(123), + }, + expectError: false, + }, + { + name: "missing required parameter artifact_id", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + }, + expectError: true, + expectedErrMsg: "missing required parameter: artifact_id", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := DownloadWorkflowRunArtifact(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + require.NoError(t, err) + require.Equal(t, tc.expectError, result.IsError) + + // Parse the result and get the text content if no error + textContent := getTextResult(t, result) + + if tc.expectedErrMsg != "" { + assert.Equal(t, tc.expectedErrMsg, textContent.Text) + return + } + + // Unmarshal and verify the result + var response map[string]any + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + assert.Contains(t, response, "download_url") + assert.Contains(t, response, "message") + assert.Equal(t, "Artifact is available for download", response["message"]) + assert.Equal(t, float64(123), response["artifact_id"]) + }) + } +} + +func Test_DeleteWorkflowRunLogs(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := DeleteWorkflowRunLogs(stubGetClientFn(mockClient), translations.NullTranslationHelper) + + assert.Equal(t, "delete_workflow_run_logs", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "run_id") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "run_id"}) + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]any + expectError bool + expectedErrMsg string + }{ + { + name: "successful logs deletion", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.DeleteReposActionsRunsLogsByOwnerByRepoByRunId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNoContent) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "run_id": float64(12345), + }, + expectError: false, + }, + { + name: "missing required parameter run_id", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + }, + expectError: true, + expectedErrMsg: "missing required parameter: run_id", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := DeleteWorkflowRunLogs(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + require.NoError(t, err) + require.Equal(t, tc.expectError, result.IsError) + + // Parse the result and get the text content if no error + textContent := getTextResult(t, result) + + if tc.expectedErrMsg != "" { + assert.Equal(t, tc.expectedErrMsg, textContent.Text) + return + } + + // Unmarshal and verify the result + var response map[string]any + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + assert.Equal(t, "Workflow run logs have been deleted", response["message"]) + assert.Equal(t, float64(12345), response["run_id"]) + }) + } +} + +func Test_GetWorkflowRunUsage(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := GetWorkflowRunUsage(stubGetClientFn(mockClient), translations.NullTranslationHelper) + + assert.Equal(t, "get_workflow_run_usage", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "run_id") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "run_id"}) + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]any + expectError bool + expectedErrMsg string + }{ + { + name: "successful workflow run usage", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsRunsTimingByOwnerByRepoByRunId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + usage := &github.WorkflowRunUsage{ + Billable: &github.WorkflowRunBillMap{ + "UBUNTU": &github.WorkflowRunBill{ + TotalMS: github.Ptr(int64(120000)), + Jobs: github.Ptr(2), + JobRuns: []*github.WorkflowRunJobRun{ + { + JobID: github.Ptr(1), + DurationMS: github.Ptr(int64(60000)), + }, + { + JobID: github.Ptr(2), + DurationMS: github.Ptr(int64(60000)), + }, + }, + }, + }, + RunDurationMS: github.Ptr(int64(120000)), + } + w.WriteHeader(http.StatusOK) + _ = json.NewEncoder(w).Encode(usage) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "run_id": float64(12345), + }, + expectError: false, + }, + { + name: "missing required parameter run_id", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + }, + expectError: true, + expectedErrMsg: "missing required parameter: run_id", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := GetWorkflowRunUsage(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + require.NoError(t, err) + require.Equal(t, tc.expectError, result.IsError) + + // Parse the result and get the text content if no error + textContent := getTextResult(t, result) + + if tc.expectedErrMsg != "" { + assert.Equal(t, tc.expectedErrMsg, textContent.Text) + return + } + + // Unmarshal and verify the result + var response github.WorkflowRunUsage + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + assert.NotNil(t, response.RunDurationMS) + assert.NotNil(t, response.Billable) + }) + } +} + +func Test_GetJobLogs(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := GetJobLogs(stubGetClientFn(mockClient), translations.NullTranslationHelper) + + assert.Equal(t, "get_job_logs", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "job_id") + assert.Contains(t, tool.InputSchema.Properties, "run_id") + assert.Contains(t, tool.InputSchema.Properties, "failed_only") + assert.Contains(t, tool.InputSchema.Properties, "return_content") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"}) + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]any + expectError bool + expectedErrMsg string + checkResponse func(t *testing.T, response map[string]any) + }{ + { + name: "successful single job logs with URL", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsJobsLogsByOwnerByRepoByJobId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Location", "https://github.com/logs/job/123") + w.WriteHeader(http.StatusFound) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "job_id": float64(123), + }, + expectError: false, + checkResponse: func(t *testing.T, response map[string]any) { + assert.Equal(t, float64(123), response["job_id"]) + assert.Contains(t, response, "logs_url") + assert.Equal(t, "Job logs are available for download", response["message"]) + assert.Contains(t, response, "note") + }, + }, + { + name: "successful failed jobs logs", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsRunsJobsByOwnerByRepoByRunId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + jobs := &github.Jobs{ + TotalCount: github.Ptr(3), + Jobs: []*github.WorkflowJob{ + { + ID: github.Ptr(int64(1)), + Name: github.Ptr("test-job-1"), + Conclusion: github.Ptr("success"), + }, + { + ID: github.Ptr(int64(2)), + Name: github.Ptr("test-job-2"), + Conclusion: github.Ptr("failure"), + }, + { + ID: github.Ptr(int64(3)), + Name: github.Ptr("test-job-3"), + Conclusion: github.Ptr("failure"), + }, + }, + } + w.WriteHeader(http.StatusOK) + _ = json.NewEncoder(w).Encode(jobs) + }), + ), + mock.WithRequestMatchHandler( + mock.GetReposActionsJobsLogsByOwnerByRepoByJobId, + http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Location", "https://github.com/logs/job/"+r.URL.Path[len(r.URL.Path)-1:]) + w.WriteHeader(http.StatusFound) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "run_id": float64(456), + "failed_only": true, + }, + expectError: false, + checkResponse: func(t *testing.T, response map[string]any) { + assert.Equal(t, float64(456), response["run_id"]) + assert.Equal(t, float64(3), response["total_jobs"]) + assert.Equal(t, float64(2), response["failed_jobs"]) + assert.Contains(t, response, "logs") + assert.Equal(t, "Retrieved logs for 2 failed jobs", response["message"]) + + logs, ok := response["logs"].([]interface{}) + assert.True(t, ok) + assert.Len(t, logs, 2) + }, + }, + { + name: "no failed jobs found", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsRunsJobsByOwnerByRepoByRunId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + jobs := &github.Jobs{ + TotalCount: github.Ptr(2), + Jobs: []*github.WorkflowJob{ + { + ID: github.Ptr(int64(1)), + Name: github.Ptr("test-job-1"), + Conclusion: github.Ptr("success"), + }, + { + ID: github.Ptr(int64(2)), + Name: github.Ptr("test-job-2"), + Conclusion: github.Ptr("success"), + }, + }, + } + w.WriteHeader(http.StatusOK) + _ = json.NewEncoder(w).Encode(jobs) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "run_id": float64(456), + "failed_only": true, + }, + expectError: false, + checkResponse: func(t *testing.T, response map[string]any) { + assert.Equal(t, "No failed jobs found in this workflow run", response["message"]) + assert.Equal(t, float64(456), response["run_id"]) + assert.Equal(t, float64(2), response["total_jobs"]) + assert.Equal(t, float64(0), response["failed_jobs"]) + }, + }, + { + name: "missing job_id when not using failed_only", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + }, + expectError: true, + expectedErrMsg: "job_id is required when failed_only is false", + }, + { + name: "missing run_id when using failed_only", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "failed_only": true, + }, + expectError: true, + expectedErrMsg: "run_id is required when failed_only is true", + }, + { + name: "missing required parameter owner", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "repo": "repo", + "job_id": float64(123), + }, + expectError: true, + expectedErrMsg: "missing required parameter: owner", + }, + { + name: "missing required parameter repo", + mockedClient: mock.NewMockedHTTPClient(), + requestArgs: map[string]any{ + "owner": "owner", + "job_id": float64(123), + }, + expectError: true, + expectedErrMsg: "missing required parameter: repo", + }, + { + name: "API error when getting single job logs", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsJobsLogsByOwnerByRepoByJobId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNotFound) + _ = json.NewEncoder(w).Encode(map[string]string{ + "message": "Not Found", + }) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "job_id": float64(999), + }, + expectError: true, + }, + { + name: "API error when listing workflow jobs for failed_only", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsRunsJobsByOwnerByRepoByRunId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNotFound) + _ = json.NewEncoder(w).Encode(map[string]string{ + "message": "Not Found", + }) + }), + ), + ), + requestArgs: map[string]any{ + "owner": "owner", + "repo": "repo", + "run_id": float64(999), + "failed_only": true, + }, + expectError: true, + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := GetJobLogs(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + require.NoError(t, err) + require.Equal(t, tc.expectError, result.IsError) + + // Parse the result and get the text content + textContent := getTextResult(t, result) + + if tc.expectedErrMsg != "" { + assert.Equal(t, tc.expectedErrMsg, textContent.Text) + return + } + + if tc.expectError { + // For API errors, just verify we got an error + assert.True(t, result.IsError) + return + } + + // Unmarshal and verify the result + var response map[string]any + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + + if tc.checkResponse != nil { + tc.checkResponse(t, response) + } + }) + } +} + +func Test_GetJobLogs_WithContentReturn(t *testing.T) { + // Test the return_content functionality with a mock HTTP server + logContent := "2023-01-01T10:00:00.000Z Starting job...\n2023-01-01T10:00:01.000Z Running tests...\n2023-01-01T10:00:02.000Z Job completed successfully" + + // Create a test server to serve log content + testServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(logContent)) + })) + defer testServer.Close() + + mockedClient := mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsJobsLogsByOwnerByRepoByJobId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Location", testServer.URL) + w.WriteHeader(http.StatusFound) + }), + ), + ) + + client := github.NewClient(mockedClient) + _, handler := GetJobLogs(stubGetClientFn(client), translations.NullTranslationHelper) + + request := createMCPRequest(map[string]any{ + "owner": "owner", + "repo": "repo", + "job_id": float64(123), + "return_content": true, + }) + + result, err := handler(context.Background(), request) + require.NoError(t, err) + require.False(t, result.IsError) + + textContent := getTextResult(t, result) + var response map[string]any + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + + assert.Equal(t, float64(123), response["job_id"]) + assert.Equal(t, logContent, response["logs_content"]) + assert.Equal(t, "Job logs content retrieved successfully", response["message"]) + assert.NotContains(t, response, "logs_url") // Should not have URL when returning content +} + +func Test_GetJobLogs_WithContentReturnAndTailLines(t *testing.T) { + // Test the return_content functionality with a mock HTTP server + logContent := "2023-01-01T10:00:00.000Z Starting job...\n2023-01-01T10:00:01.000Z Running tests...\n2023-01-01T10:00:02.000Z Job completed successfully" + expectedLogContent := "2023-01-01T10:00:02.000Z Job completed successfully" + + // Create a test server to serve log content + testServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(logContent)) + })) + defer testServer.Close() + + mockedClient := mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposActionsJobsLogsByOwnerByRepoByJobId, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Location", testServer.URL) + w.WriteHeader(http.StatusFound) + }), + ), + ) + + client := github.NewClient(mockedClient) + _, handler := GetJobLogs(stubGetClientFn(client), translations.NullTranslationHelper) + + request := createMCPRequest(map[string]any{ + "owner": "owner", + "repo": "repo", + "job_id": float64(123), + "return_content": true, + "tail_lines": float64(1), // Requesting last 1 line + }) + + result, err := handler(context.Background(), request) + require.NoError(t, err) + require.False(t, result.IsError) + + textContent := getTextResult(t, result) + var response map[string]any + err = json.Unmarshal([]byte(textContent.Text), &response) + require.NoError(t, err) + + assert.Equal(t, float64(123), response["job_id"]) + assert.Equal(t, float64(1), response["original_length"]) + assert.Equal(t, expectedLogContent, response["logs_content"]) + assert.Equal(t, "Job logs content retrieved successfully", response["message"]) + assert.NotContains(t, response, "logs_url") // Should not have URL when returning content +} diff --git a/pkg/github/code_scanning.go b/pkg/github/code_scanning.go index 34a1b9eda..6b15c0c45 100644 --- a/pkg/github/code_scanning.go +++ b/pkg/github/code_scanning.go @@ -7,8 +7,9 @@ import ( "io" "net/http" + ghErrors "github.com/github/github-mcp-server/pkg/errors" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) @@ -18,7 +19,7 @@ func GetCodeScanningAlert(getClient GetClientFn, t translations.TranslationHelpe mcp.WithDescription(t("TOOL_GET_CODE_SCANNING_ALERT_DESCRIPTION", "Get details of a specific code scanning alert in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_CODE_SCANNING_ALERT_USER_TITLE", "Get code scanning alert"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -34,11 +35,11 @@ func GetCodeScanningAlert(getClient GetClientFn, t translations.TranslationHelpe ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -54,7 +55,11 @@ func GetCodeScanningAlert(getClient GetClientFn, t translations.TranslationHelpe alert, resp, err := client.CodeScanning.GetAlert(ctx, owner, repo, int64(alertNumber)) if err != nil { - return nil, fmt.Errorf("failed to get alert: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get alert", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -80,7 +85,7 @@ func ListCodeScanningAlerts(getClient GetClientFn, t translations.TranslationHel mcp.WithDescription(t("TOOL_LIST_CODE_SCANNING_ALERTS_DESCRIPTION", "List code scanning alerts in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_LIST_CODE_SCANNING_ALERTS_USER_TITLE", "List code scanning alerts"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -90,14 +95,14 @@ func ListCodeScanningAlerts(getClient GetClientFn, t translations.TranslationHel mcp.Required(), mcp.Description("The name of the repository."), ), - mcp.WithString("ref", - mcp.Description("The Git reference for the results you want to list."), - ), mcp.WithString("state", mcp.Description("Filter code scanning alerts by state. Defaults to open"), mcp.DefaultString("open"), mcp.Enum("open", "closed", "dismissed", "fixed"), ), + mcp.WithString("ref", + mcp.Description("The Git reference for the results you want to list."), + ), mcp.WithString("severity", mcp.Description("Filter code scanning alerts by severity"), mcp.Enum("critical", "high", "medium", "low", "warning", "note", "error"), @@ -107,11 +112,11 @@ func ListCodeScanningAlerts(getClient GetClientFn, t translations.TranslationHel ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -138,7 +143,11 @@ func ListCodeScanningAlerts(getClient GetClientFn, t translations.TranslationHel } alerts, resp, err := client.CodeScanning.ListAlertsForRepo(ctx, owner, repo, &github.AlertListOptions{Ref: ref, State: state, Severity: severity, ToolName: toolName}) if err != nil { - return nil, fmt.Errorf("failed to list alerts: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to list alerts", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() diff --git a/pkg/github/code_scanning_test.go b/pkg/github/code_scanning_test.go index 40dabebdf..66f6fd6cc 100644 --- a/pkg/github/code_scanning_test.go +++ b/pkg/github/code_scanning_test.go @@ -6,8 +6,9 @@ import ( "net/http" "testing" + "github.com/github/github-mcp-server/internal/toolsnaps" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/migueleliasweb/go-github-mock/src/mock" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -17,6 +18,7 @@ func Test_GetCodeScanningAlert(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetCodeScanningAlert(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_code_scanning_alert", tool.Name) assert.NotEmpty(t, tool.Description) @@ -92,12 +94,15 @@ func Test_GetCodeScanningAlert(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -119,6 +124,7 @@ func Test_ListCodeScanningAlerts(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := ListCodeScanningAlerts(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "list_code_scanning_alerts", tool.Name) assert.NotEmpty(t, tool.Description) @@ -214,12 +220,15 @@ func Test_ListCodeScanningAlerts(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) diff --git a/pkg/github/context_tools.go b/pkg/github/context_tools.go index 180f32dd4..9817fea7b 100644 --- a/pkg/github/context_tools.go +++ b/pkg/github/context_tools.go @@ -2,52 +2,91 @@ package github import ( "context" - "encoding/json" - "fmt" - "io" - "net/http" + "time" + ghErrors "github.com/github/github-mcp-server/pkg/errors" "github.com/github/github-mcp-server/pkg/translations" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) +// UserDetails contains additional fields about a GitHub user not already +// present in MinimalUser. Used by get_me context tool but omitted from search_users. +type UserDetails struct { + Name string `json:"name,omitempty"` + Company string `json:"company,omitempty"` + Blog string `json:"blog,omitempty"` + Location string `json:"location,omitempty"` + Email string `json:"email,omitempty"` + Hireable bool `json:"hireable,omitempty"` + Bio string `json:"bio,omitempty"` + TwitterUsername string `json:"twitter_username,omitempty"` + PublicRepos int `json:"public_repos"` + PublicGists int `json:"public_gists"` + Followers int `json:"followers"` + Following int `json:"following"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` + PrivateGists int `json:"private_gists,omitempty"` + TotalPrivateRepos int64 `json:"total_private_repos,omitempty"` + OwnedPrivateRepos int64 `json:"owned_private_repos,omitempty"` +} + // GetMe creates a tool to get details of the authenticated user. -func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { - return mcp.NewTool("get_me", - mcp.WithDescription(t("TOOL_GET_ME_DESCRIPTION", "Get details of the authenticated GitHub user. Use this when a request includes \"me\", \"my\". The output will not change unless the user changes their profile, so only call this once.")), - mcp.WithToolAnnotation(mcp.ToolAnnotation{ - Title: t("TOOL_GET_ME_USER_TITLE", "Get my user profile"), - ReadOnlyHint: toBoolPtr(true), - }), - mcp.WithString("reason", - mcp.Description("Optional: the reason for requesting the user information"), - ), - ), - func(ctx context.Context, _ mcp.CallToolRequest) (*mcp.CallToolResult, error) { - client, err := getClient(ctx) - if err != nil { - return nil, fmt.Errorf("failed to get GitHub client: %w", err) - } - user, resp, err := client.Users.Get(ctx, "") - if err != nil { - return nil, fmt.Errorf("failed to get user: %w", err) - } - defer func() { _ = resp.Body.Close() }() - - if resp.StatusCode != http.StatusOK { - body, err := io.ReadAll(resp.Body) - if err != nil { - return nil, fmt.Errorf("failed to read response body: %w", err) - } - return mcp.NewToolResultError(fmt.Sprintf("failed to get user: %s", string(body))), nil - } - - r, err := json.Marshal(user) - if err != nil { - return nil, fmt.Errorf("failed to marshal user: %w", err) - } - - return mcp.NewToolResultText(string(r)), nil +func GetMe(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) { + tool := mcp.NewTool("get_me", + mcp.WithDescription(t("TOOL_GET_ME_DESCRIPTION", "Get details of the authenticated GitHub user. Use this when a request is about the user's own profile for GitHub. Or when information is missing to build other tool calls.")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_GET_ME_USER_TITLE", "Get my user profile"), + ReadOnlyHint: ToBoolPtr(true), + }), + ) + + type args struct{} + handler := mcp.NewTypedToolHandler(func(ctx context.Context, _ mcp.CallToolRequest, _ args) (*mcp.CallToolResult, error) { + client, err := getClient(ctx) + if err != nil { + return mcp.NewToolResultErrorFromErr("failed to get GitHub client", err), nil + } + + user, res, err := client.Users.Get(ctx, "") + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get user", + res, + err, + ), nil } + + // Create minimal user representation instead of returning full user object + minimalUser := MinimalUser{ + Login: user.GetLogin(), + ID: user.GetID(), + ProfileURL: user.GetHTMLURL(), + AvatarURL: user.GetAvatarURL(), + Details: &UserDetails{ + Name: user.GetName(), + Company: user.GetCompany(), + Blog: user.GetBlog(), + Location: user.GetLocation(), + Email: user.GetEmail(), + Hireable: user.GetHireable(), + Bio: user.GetBio(), + TwitterUsername: user.GetTwitterUsername(), + PublicRepos: user.GetPublicRepos(), + PublicGists: user.GetPublicGists(), + Followers: user.GetFollowers(), + Following: user.GetFollowing(), + CreatedAt: user.GetCreatedAt().Time, + UpdatedAt: user.GetUpdatedAt().Time, + PrivateGists: user.GetPrivateGists(), + TotalPrivateRepos: user.GetTotalPrivateRepos(), + OwnedPrivateRepos: user.GetOwnedPrivateRepos(), + }, + } + + return MarshalledTextResult(minimalUser), nil + }) + + return tool, handler } diff --git a/pkg/github/context_tools_test.go b/pkg/github/context_tools_test.go index c9d220dd9..56f61e936 100644 --- a/pkg/github/context_tools_test.go +++ b/pkg/github/context_tools_test.go @@ -3,130 +3,139 @@ package github import ( "context" "encoding/json" - "net/http" "testing" "time" + "github.com/github/github-mcp-server/internal/toolsnaps" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/migueleliasweb/go-github-mock/src/mock" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" ) func Test_GetMe(t *testing.T) { - // Verify tool definition - mockClient := github.NewClient(nil) - tool, _ := GetMe(stubGetClientFn(mockClient), translations.NullTranslationHelper) + t.Parallel() + tool, _ := GetMe(nil, translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + + // Verify some basic very important properties assert.Equal(t, "get_me", tool.Name) - assert.NotEmpty(t, tool.Description) - assert.Contains(t, tool.InputSchema.Properties, "reason") - assert.Empty(t, tool.InputSchema.Required) // No required parameters + assert.True(t, *tool.Annotations.ReadOnlyHint, "get_me tool should be read-only") // Setup mock user response mockUser := &github.User{ - Login: github.Ptr("testuser"), - Name: github.Ptr("Test User"), - Email: github.Ptr("test@example.com"), - Bio: github.Ptr("GitHub user for testing"), - Company: github.Ptr("Test Company"), - Location: github.Ptr("Test Location"), - HTMLURL: github.Ptr("https://github.com/testuser"), - CreatedAt: &github.Timestamp{Time: time.Now().Add(-365 * 24 * time.Hour)}, - Type: github.Ptr("User"), + Login: github.Ptr("testuser"), + Name: github.Ptr("Test User"), + Email: github.Ptr("test@example.com"), + Bio: github.Ptr("GitHub user for testing"), + Company: github.Ptr("Test Company"), + Location: github.Ptr("Test Location"), + HTMLURL: github.Ptr("https://github.com/testuser"), + CreatedAt: &github.Timestamp{Time: time.Now().Add(-365 * 24 * time.Hour)}, + Type: github.Ptr("User"), + Hireable: github.Ptr(true), + TwitterUsername: github.Ptr("testuser_twitter"), Plan: &github.Plan{ Name: github.Ptr("pro"), }, } tests := []struct { - name string - mockedClient *http.Client - requestArgs map[string]interface{} - expectError bool - expectedUser *github.User - expectedErrMsg string + name string + stubbedGetClientFn GetClientFn + requestArgs map[string]any + expectToolError bool + expectedUser *github.User + expectedToolErrMsg string }{ { name: "successful get user", - mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatch( - mock.GetUser, - mockUser, + stubbedGetClientFn: stubGetClientFromHTTPFn( + mock.NewMockedHTTPClient( + mock.WithRequestMatch( + mock.GetUser, + mockUser, + ), ), ), - requestArgs: map[string]interface{}{}, - expectError: false, - expectedUser: mockUser, + requestArgs: map[string]any{}, + expectToolError: false, + expectedUser: mockUser, }, { name: "successful get user with reason", - mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatch( - mock.GetUser, - mockUser, + stubbedGetClientFn: stubGetClientFromHTTPFn( + mock.NewMockedHTTPClient( + mock.WithRequestMatch( + mock.GetUser, + mockUser, + ), ), ), - requestArgs: map[string]interface{}{ + requestArgs: map[string]any{ "reason": "Testing API", }, - expectError: false, - expectedUser: mockUser, + expectToolError: false, + expectedUser: mockUser, + }, + { + name: "getting client fails", + stubbedGetClientFn: stubGetClientFnErr("expected test error"), + requestArgs: map[string]any{}, + expectToolError: true, + expectedToolErrMsg: "failed to get GitHub client: expected test error", }, { name: "get user fails", - mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatchHandler( - mock.GetUser, - http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { - w.WriteHeader(http.StatusUnauthorized) - _, _ = w.Write([]byte(`{"message": "Unauthorized"}`)) - }), + stubbedGetClientFn: stubGetClientFromHTTPFn( + mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetUser, + badRequestHandler("expected test failure"), + ), ), ), - requestArgs: map[string]interface{}{}, - expectError: true, - expectedErrMsg: "failed to get user", + requestArgs: map[string]any{}, + expectToolError: true, + expectedToolErrMsg: "expected test failure", }, } for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { - // Setup client with mock - client := github.NewClient(tc.mockedClient) - _, handler := GetMe(stubGetClientFn(client), translations.NullTranslationHelper) + _, handler := GetMe(tc.stubbedGetClientFn, translations.NullTranslationHelper) - // Create call request request := createMCPRequest(tc.requestArgs) - - // Call handler result, err := handler(context.Background(), request) + require.NoError(t, err) + textContent := getTextResult(t, result) - // Verify results - if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + if tc.expectToolError { + assert.True(t, result.IsError, "expected tool call result to be an error") + assert.Contains(t, textContent.Text, tc.expectedToolErrMsg) return } - require.NoError(t, err) - - // Parse result and get text content if no error - textContent := getTextResult(t, result) - // Unmarshal and verify the result - var returnedUser github.User + var returnedUser MinimalUser err = json.Unmarshal([]byte(textContent.Text), &returnedUser) require.NoError(t, err) + // Verify minimal user details + assert.Equal(t, *tc.expectedUser.Login, returnedUser.Login) + assert.Equal(t, *tc.expectedUser.HTMLURL, returnedUser.ProfileURL) + // Verify user details - assert.Equal(t, *tc.expectedUser.Login, *returnedUser.Login) - assert.Equal(t, *tc.expectedUser.Name, *returnedUser.Name) - assert.Equal(t, *tc.expectedUser.Email, *returnedUser.Email) - assert.Equal(t, *tc.expectedUser.Bio, *returnedUser.Bio) - assert.Equal(t, *tc.expectedUser.HTMLURL, *returnedUser.HTMLURL) - assert.Equal(t, *tc.expectedUser.Type, *returnedUser.Type) + require.NotNil(t, returnedUser.Details) + assert.Equal(t, *tc.expectedUser.Name, returnedUser.Details.Name) + assert.Equal(t, *tc.expectedUser.Email, returnedUser.Details.Email) + assert.Equal(t, *tc.expectedUser.Bio, returnedUser.Details.Bio) + assert.Equal(t, *tc.expectedUser.Company, returnedUser.Details.Company) + assert.Equal(t, *tc.expectedUser.Location, returnedUser.Details.Location) + assert.Equal(t, *tc.expectedUser.Hireable, returnedUser.Details.Hireable) + assert.Equal(t, *tc.expectedUser.TwitterUsername, returnedUser.Details.TwitterUsername) }) } } diff --git a/pkg/github/dependabot.go b/pkg/github/dependabot.go new file mode 100644 index 000000000..c2a4d5b0d --- /dev/null +++ b/pkg/github/dependabot.go @@ -0,0 +1,161 @@ +package github + +import ( + "context" + "encoding/json" + "fmt" + "io" + "net/http" + + ghErrors "github.com/github/github-mcp-server/pkg/errors" + "github.com/github/github-mcp-server/pkg/translations" + "github.com/google/go-github/v73/github" + "github.com/mark3labs/mcp-go/mcp" + "github.com/mark3labs/mcp-go/server" +) + +func GetDependabotAlert(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool( + "get_dependabot_alert", + mcp.WithDescription(t("TOOL_GET_DEPENDABOT_ALERT_DESCRIPTION", "Get details of a specific dependabot alert in a GitHub repository.")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_GET_DEPENDABOT_ALERT_USER_TITLE", "Get dependabot alert"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description("The owner of the repository."), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description("The name of the repository."), + ), + mcp.WithNumber("alertNumber", + mcp.Required(), + mcp.Description("The number of the alert."), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + alertNumber, err := RequiredInt(request, "alertNumber") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + alert, resp, err := client.Dependabot.GetRepoAlert(ctx, owner, repo, alertNumber) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to get alert with number '%d'", alertNumber), + resp, + err, + ), nil + } + defer func() { _ = resp.Body.Close() }() + + if resp.StatusCode != http.StatusOK { + body, err := io.ReadAll(resp.Body) + if err != nil { + return nil, fmt.Errorf("failed to read response body: %w", err) + } + return mcp.NewToolResultError(fmt.Sprintf("failed to get alert: %s", string(body))), nil + } + + r, err := json.Marshal(alert) + if err != nil { + return nil, fmt.Errorf("failed to marshal alert: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} + +func ListDependabotAlerts(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool( + "list_dependabot_alerts", + mcp.WithDescription(t("TOOL_LIST_DEPENDABOT_ALERTS_DESCRIPTION", "List dependabot alerts in a GitHub repository.")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_LIST_DEPENDABOT_ALERTS_USER_TITLE", "List dependabot alerts"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description("The owner of the repository."), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description("The name of the repository."), + ), + mcp.WithString("state", + mcp.Description("Filter dependabot alerts by state. Defaults to open"), + mcp.DefaultString("open"), + mcp.Enum("open", "fixed", "dismissed", "auto_dismissed"), + ), + mcp.WithString("severity", + mcp.Description("Filter dependabot alerts by severity"), + mcp.Enum("low", "medium", "high", "critical"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + state, err := OptionalParam[string](request, "state") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + severity, err := OptionalParam[string](request, "severity") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + + alerts, resp, err := client.Dependabot.ListRepoAlerts(ctx, owner, repo, &github.ListAlertsOptions{ + State: ToStringPtr(state), + Severity: ToStringPtr(severity), + }) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to list alerts for repository '%s/%s'", owner, repo), + resp, + err, + ), nil + } + defer func() { _ = resp.Body.Close() }() + + if resp.StatusCode != http.StatusOK { + body, err := io.ReadAll(resp.Body) + if err != nil { + return nil, fmt.Errorf("failed to read response body: %w", err) + } + return mcp.NewToolResultError(fmt.Sprintf("failed to list alerts: %s", string(body))), nil + } + + r, err := json.Marshal(alerts) + if err != nil { + return nil, fmt.Errorf("failed to marshal alerts: %w", err) + } + + return mcp.NewToolResultText(string(r)), nil + } +} diff --git a/pkg/github/dependabot_test.go b/pkg/github/dependabot_test.go new file mode 100644 index 000000000..8a7270d7f --- /dev/null +++ b/pkg/github/dependabot_test.go @@ -0,0 +1,276 @@ +package github + +import ( + "context" + "encoding/json" + "net/http" + "testing" + + "github.com/github/github-mcp-server/internal/toolsnaps" + "github.com/github/github-mcp-server/pkg/translations" + "github.com/google/go-github/v73/github" + "github.com/migueleliasweb/go-github-mock/src/mock" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +func Test_GetDependabotAlert(t *testing.T) { + // Verify tool definition + mockClient := github.NewClient(nil) + tool, _ := GetDependabotAlert(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + + // Validate tool schema + assert.Equal(t, "get_dependabot_alert", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "alertNumber") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "alertNumber"}) + + // Setup mock alert for success case + mockAlert := &github.DependabotAlert{ + Number: github.Ptr(42), + State: github.Ptr("open"), + HTMLURL: github.Ptr("https://github.com/owner/repo/security/dependabot/42"), + } + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]interface{} + expectError bool + expectedAlert *github.DependabotAlert + expectedErrMsg string + }{ + { + name: "successful alert fetch", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatch( + mock.GetReposDependabotAlertsByOwnerByRepoByAlertNumber, + mockAlert, + ), + ), + requestArgs: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + "alertNumber": float64(42), + }, + expectError: false, + expectedAlert: mockAlert, + }, + { + name: "alert fetch fails", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposDependabotAlertsByOwnerByRepoByAlertNumber, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNotFound) + _, _ = w.Write([]byte(`{"message": "Not Found"}`)) + }), + ), + ), + requestArgs: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + "alertNumber": float64(9999), + }, + expectError: true, + expectedErrMsg: "failed to get alert", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := GetDependabotAlert(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + // Verify results + if tc.expectError { + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) + return + } + + require.NoError(t, err) + require.False(t, result.IsError) + + // Parse the result and get the text content if no error + textContent := getTextResult(t, result) + + // Unmarshal and verify the result + var returnedAlert github.DependabotAlert + err = json.Unmarshal([]byte(textContent.Text), &returnedAlert) + assert.NoError(t, err) + assert.Equal(t, *tc.expectedAlert.Number, *returnedAlert.Number) + assert.Equal(t, *tc.expectedAlert.State, *returnedAlert.State) + assert.Equal(t, *tc.expectedAlert.HTMLURL, *returnedAlert.HTMLURL) + }) + } +} + +func Test_ListDependabotAlerts(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := ListDependabotAlerts(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + + assert.Equal(t, "list_dependabot_alerts", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "state") + assert.Contains(t, tool.InputSchema.Properties, "severity") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"}) + + // Setup mock alerts for success case + criticalAlert := github.DependabotAlert{ + Number: github.Ptr(1), + HTMLURL: github.Ptr("https://github.com/owner/repo/security/dependabot/1"), + State: github.Ptr("open"), + SecurityAdvisory: &github.DependabotSecurityAdvisory{ + Severity: github.Ptr("critical"), + }, + } + highSeverityAlert := github.DependabotAlert{ + Number: github.Ptr(2), + HTMLURL: github.Ptr("https://github.com/owner/repo/security/dependabot/2"), + State: github.Ptr("fixed"), + SecurityAdvisory: &github.DependabotSecurityAdvisory{ + Severity: github.Ptr("high"), + }, + } + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]interface{} + expectError bool + expectedAlerts []*github.DependabotAlert + expectedErrMsg string + }{ + { + name: "successful open alerts listing", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposDependabotAlertsByOwnerByRepo, + expectQueryParams(t, map[string]string{ + "state": "open", + }).andThen( + mockResponse(t, http.StatusOK, []*github.DependabotAlert{&criticalAlert}), + ), + ), + ), + requestArgs: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + "state": "open", + }, + expectError: false, + expectedAlerts: []*github.DependabotAlert{&criticalAlert}, + }, + { + name: "successful severity filtered listing", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposDependabotAlertsByOwnerByRepo, + expectQueryParams(t, map[string]string{ + "severity": "high", + }).andThen( + mockResponse(t, http.StatusOK, []*github.DependabotAlert{&highSeverityAlert}), + ), + ), + ), + requestArgs: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + "severity": "high", + }, + expectError: false, + expectedAlerts: []*github.DependabotAlert{&highSeverityAlert}, + }, + { + name: "successful all alerts listing", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposDependabotAlertsByOwnerByRepo, + expectQueryParams(t, map[string]string{}).andThen( + mockResponse(t, http.StatusOK, []*github.DependabotAlert{&criticalAlert, &highSeverityAlert}), + ), + ), + ), + requestArgs: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + }, + expectError: false, + expectedAlerts: []*github.DependabotAlert{&criticalAlert, &highSeverityAlert}, + }, + { + name: "alerts listing fails", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposDependabotAlertsByOwnerByRepo, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusUnauthorized) + _, _ = w.Write([]byte(`{"message": "Unauthorized access"}`)) + }), + ), + ), + requestArgs: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + }, + expectError: true, + expectedErrMsg: "failed to list alerts", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + client := github.NewClient(tc.mockedClient) + _, handler := ListDependabotAlerts(stubGetClientFn(client), translations.NullTranslationHelper) + + request := createMCPRequest(tc.requestArgs) + + result, err := handler(context.Background(), request) + + if tc.expectError { + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) + return + } + + require.NoError(t, err) + require.False(t, result.IsError) + + textContent := getTextResult(t, result) + + // Unmarshal and verify the result + var returnedAlerts []*github.DependabotAlert + err = json.Unmarshal([]byte(textContent.Text), &returnedAlerts) + assert.NoError(t, err) + assert.Len(t, returnedAlerts, len(tc.expectedAlerts)) + for i, alert := range returnedAlerts { + assert.Equal(t, *tc.expectedAlerts[i].Number, *alert.Number) + assert.Equal(t, *tc.expectedAlerts[i].HTMLURL, *alert.HTMLURL) + assert.Equal(t, *tc.expectedAlerts[i].State, *alert.State) + if tc.expectedAlerts[i].SecurityAdvisory != nil && tc.expectedAlerts[i].SecurityAdvisory.Severity != nil && + alert.SecurityAdvisory != nil && alert.SecurityAdvisory.Severity != nil { + assert.Equal(t, *tc.expectedAlerts[i].SecurityAdvisory.Severity, *alert.SecurityAdvisory.Severity) + } + } + }) + } +} diff --git a/pkg/github/discussions.go b/pkg/github/discussions.go new file mode 100644 index 000000000..23e2724d4 --- /dev/null +++ b/pkg/github/discussions.go @@ -0,0 +1,383 @@ +package github + +import ( + "context" + "encoding/json" + "fmt" + + "github.com/github/github-mcp-server/pkg/translations" + "github.com/go-viper/mapstructure/v2" + "github.com/google/go-github/v73/github" + "github.com/mark3labs/mcp-go/mcp" + "github.com/mark3labs/mcp-go/server" + "github.com/shurcooL/githubv4" +) + +func ListDiscussions(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("list_discussions", + mcp.WithDescription(t("TOOL_LIST_DISCUSSIONS_DESCRIPTION", "List discussions for a repository")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_LIST_DISCUSSIONS_USER_TITLE", "List discussions"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description("Repository owner"), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description("Repository name"), + ), + mcp.WithString("category", + mcp.Description("Optional filter by discussion category ID. If provided, only discussions with this category are listed."), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + // Required params + owner, err := RequiredParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + repo, err := RequiredParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Optional params + category, err := OptionalParam[string](request, "category") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + client, err := getGQLClient(ctx) + if err != nil { + return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil + } + + // If category filter is specified, use it as the category ID for server-side filtering + var categoryID *githubv4.ID + if category != "" { + id := githubv4.ID(category) + categoryID = &id + } + + // Now execute the discussions query + var discussions []*github.Discussion + if categoryID != nil { + // Query with category filter (server-side filtering) + var query struct { + Repository struct { + Discussions struct { + Nodes []struct { + Number githubv4.Int + Title githubv4.String + CreatedAt githubv4.DateTime + Category struct { + Name githubv4.String + } `graphql:"category"` + URL githubv4.String `graphql:"url"` + } + } `graphql:"discussions(first: 100, categoryId: $categoryId)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + vars := map[string]interface{}{ + "owner": githubv4.String(owner), + "repo": githubv4.String(repo), + "categoryId": *categoryID, + } + if err := client.Query(ctx, &query, vars); err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Map nodes to GitHub Discussion objects + for _, n := range query.Repository.Discussions.Nodes { + di := &github.Discussion{ + Number: github.Ptr(int(n.Number)), + Title: github.Ptr(string(n.Title)), + HTMLURL: github.Ptr(string(n.URL)), + CreatedAt: &github.Timestamp{Time: n.CreatedAt.Time}, + DiscussionCategory: &github.DiscussionCategory{ + Name: github.Ptr(string(n.Category.Name)), + }, + } + discussions = append(discussions, di) + } + } else { + // Query without category filter + var query struct { + Repository struct { + Discussions struct { + Nodes []struct { + Number githubv4.Int + Title githubv4.String + CreatedAt githubv4.DateTime + Category struct { + Name githubv4.String + } `graphql:"category"` + URL githubv4.String `graphql:"url"` + } + } `graphql:"discussions(first: 100)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + vars := map[string]interface{}{ + "owner": githubv4.String(owner), + "repo": githubv4.String(repo), + } + if err := client.Query(ctx, &query, vars); err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Map nodes to GitHub Discussion objects + for _, n := range query.Repository.Discussions.Nodes { + di := &github.Discussion{ + Number: github.Ptr(int(n.Number)), + Title: github.Ptr(string(n.Title)), + HTMLURL: github.Ptr(string(n.URL)), + CreatedAt: &github.Timestamp{Time: n.CreatedAt.Time}, + DiscussionCategory: &github.DiscussionCategory{ + Name: github.Ptr(string(n.Category.Name)), + }, + } + discussions = append(discussions, di) + } + } + + // Marshal and return + out, err := json.Marshal(discussions) + if err != nil { + return nil, fmt.Errorf("failed to marshal discussions: %w", err) + } + return mcp.NewToolResultText(string(out)), nil + } +} + +func GetDiscussion(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("get_discussion", + mcp.WithDescription(t("TOOL_GET_DISCUSSION_DESCRIPTION", "Get a specific discussion by ID")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_GET_DISCUSSION_USER_TITLE", "Get discussion"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description("Repository owner"), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description("Repository name"), + ), + mcp.WithNumber("discussionNumber", + mcp.Required(), + mcp.Description("Discussion Number"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + // Decode params + var params struct { + Owner string + Repo string + DiscussionNumber int32 + } + if err := mapstructure.Decode(request.Params.Arguments, ¶ms); err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + client, err := getGQLClient(ctx) + if err != nil { + return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil + } + + var q struct { + Repository struct { + Discussion struct { + Number githubv4.Int + Body githubv4.String + CreatedAt githubv4.DateTime + URL githubv4.String `graphql:"url"` + Category struct { + Name githubv4.String + } `graphql:"category"` + } `graphql:"discussion(number: $discussionNumber)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + vars := map[string]interface{}{ + "owner": githubv4.String(params.Owner), + "repo": githubv4.String(params.Repo), + "discussionNumber": githubv4.Int(params.DiscussionNumber), + } + if err := client.Query(ctx, &q, vars); err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + d := q.Repository.Discussion + discussion := &github.Discussion{ + Number: github.Ptr(int(d.Number)), + Body: github.Ptr(string(d.Body)), + HTMLURL: github.Ptr(string(d.URL)), + CreatedAt: &github.Timestamp{Time: d.CreatedAt.Time}, + DiscussionCategory: &github.DiscussionCategory{ + Name: github.Ptr(string(d.Category.Name)), + }, + } + out, err := json.Marshal(discussion) + if err != nil { + return nil, fmt.Errorf("failed to marshal discussion: %w", err) + } + + return mcp.NewToolResultText(string(out)), nil + } +} + +func GetDiscussionComments(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("get_discussion_comments", + mcp.WithDescription(t("TOOL_GET_DISCUSSION_COMMENTS_DESCRIPTION", "Get comments from a discussion")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_GET_DISCUSSION_COMMENTS_USER_TITLE", "Get discussion comments"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", mcp.Required(), mcp.Description("Repository owner")), + mcp.WithString("repo", mcp.Required(), mcp.Description("Repository name")), + mcp.WithNumber("discussionNumber", mcp.Required(), mcp.Description("Discussion Number")), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + // Decode params + var params struct { + Owner string + Repo string + DiscussionNumber int32 + } + if err := mapstructure.Decode(request.Params.Arguments, ¶ms); err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + client, err := getGQLClient(ctx) + if err != nil { + return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil + } + + var q struct { + Repository struct { + Discussion struct { + Comments struct { + Nodes []struct { + Body githubv4.String + } + } `graphql:"comments(first:100)"` + } `graphql:"discussion(number: $discussionNumber)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + vars := map[string]interface{}{ + "owner": githubv4.String(params.Owner), + "repo": githubv4.String(params.Repo), + "discussionNumber": githubv4.Int(params.DiscussionNumber), + } + if err := client.Query(ctx, &q, vars); err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + var comments []*github.IssueComment + for _, c := range q.Repository.Discussion.Comments.Nodes { + comments = append(comments, &github.IssueComment{Body: github.Ptr(string(c.Body))}) + } + + out, err := json.Marshal(comments) + if err != nil { + return nil, fmt.Errorf("failed to marshal comments: %w", err) + } + + return mcp.NewToolResultText(string(out)), nil + } +} + +func ListDiscussionCategories(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("list_discussion_categories", + mcp.WithDescription(t("TOOL_LIST_DISCUSSION_CATEGORIES_DESCRIPTION", "List discussion categories with their id and name, for a repository")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_LIST_DISCUSSION_CATEGORIES_USER_TITLE", "List discussion categories"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("owner", + mcp.Required(), + mcp.Description("Repository owner"), + ), + mcp.WithString("repo", + mcp.Required(), + mcp.Description("Repository name"), + ), + mcp.WithNumber("first", + mcp.Description("Number of categories to return per page (min 1, max 100)"), + mcp.Min(1), + mcp.Max(100), + ), + mcp.WithNumber("last", + mcp.Description("Number of categories to return from the end (min 1, max 100)"), + mcp.Min(1), + mcp.Max(100), + ), + mcp.WithString("after", + mcp.Description("Cursor for pagination, use the 'after' field from the previous response"), + ), + mcp.WithString("before", + mcp.Description("Cursor for pagination, use the 'before' field from the previous response"), + ), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + // Decode params + var params struct { + Owner string + Repo string + First int32 + Last int32 + After string + Before string + } + if err := mapstructure.Decode(request.Params.Arguments, ¶ms); err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + // Validate pagination parameters + if params.First != 0 && params.Last != 0 { + return mcp.NewToolResultError("only one of 'first' or 'last' may be specified"), nil + } + if params.After != "" && params.Before != "" { + return mcp.NewToolResultError("only one of 'after' or 'before' may be specified"), nil + } + if params.After != "" && params.Last != 0 { + return mcp.NewToolResultError("'after' cannot be used with 'last'. Did you mean to use 'before' instead?"), nil + } + if params.Before != "" && params.First != 0 { + return mcp.NewToolResultError("'before' cannot be used with 'first'. Did you mean to use 'after' instead?"), nil + } + + client, err := getGQLClient(ctx) + if err != nil { + return mcp.NewToolResultError(fmt.Sprintf("failed to get GitHub GQL client: %v", err)), nil + } + var q struct { + Repository struct { + DiscussionCategories struct { + Nodes []struct { + ID githubv4.ID + Name githubv4.String + } + } `graphql:"discussionCategories(first: 100)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + vars := map[string]interface{}{ + "owner": githubv4.String(params.Owner), + "repo": githubv4.String(params.Repo), + } + if err := client.Query(ctx, &q, vars); err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + var categories []map[string]string + for _, c := range q.Repository.DiscussionCategories.Nodes { + categories = append(categories, map[string]string{ + "id": fmt.Sprint(c.ID), + "name": string(c.Name), + }) + } + out, err := json.Marshal(categories) + if err != nil { + return nil, fmt.Errorf("failed to marshal discussion categories: %w", err) + } + return mcp.NewToolResultText(string(out)), nil + } +} diff --git a/pkg/github/discussions_test.go b/pkg/github/discussions_test.go new file mode 100644 index 000000000..c6688a519 --- /dev/null +++ b/pkg/github/discussions_test.go @@ -0,0 +1,392 @@ +package github + +import ( + "context" + "encoding/json" + "net/http" + "testing" + "time" + + "github.com/github/github-mcp-server/internal/githubv4mock" + "github.com/github/github-mcp-server/pkg/translations" + "github.com/google/go-github/v73/github" + "github.com/shurcooL/githubv4" + "github.com/stretchr/testify/assert" + "github.com/stretchr/testify/require" +) + +var ( + discussionsGeneral = []map[string]any{ + {"number": 1, "title": "Discussion 1 title", "createdAt": "2023-01-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/1", "category": map[string]any{"name": "General"}}, + {"number": 3, "title": "Discussion 3 title", "createdAt": "2023-03-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/3", "category": map[string]any{"name": "General"}}, + } + discussionsAll = []map[string]any{ + {"number": 1, "title": "Discussion 1 title", "createdAt": "2023-01-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/1", "category": map[string]any{"name": "General"}}, + {"number": 2, "title": "Discussion 2 title", "createdAt": "2023-02-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/2", "category": map[string]any{"name": "Questions"}}, + {"number": 3, "title": "Discussion 3 title", "createdAt": "2023-03-01T00:00:00Z", "url": "https://github.com/owner/repo/discussions/3", "category": map[string]any{"name": "General"}}, + } + mockResponseListAll = githubv4mock.DataResponse(map[string]any{ + "repository": map[string]any{ + "discussions": map[string]any{"nodes": discussionsAll}, + }, + }) + mockResponseListGeneral = githubv4mock.DataResponse(map[string]any{ + "repository": map[string]any{ + "discussions": map[string]any{"nodes": discussionsGeneral}, + }, + }) + mockErrorRepoNotFound = githubv4mock.ErrorResponse("repository not found") +) + +func Test_ListDiscussions(t *testing.T) { + mockClient := githubv4.NewClient(nil) + // Verify tool definition and schema + toolDef, _ := ListDiscussions(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper) + assert.Equal(t, "list_discussions", toolDef.Name) + assert.NotEmpty(t, toolDef.Description) + assert.Contains(t, toolDef.InputSchema.Properties, "owner") + assert.Contains(t, toolDef.InputSchema.Properties, "repo") + assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo"}) + + // mock for the call to ListDiscussions without category filter + var qDiscussions struct { + Repository struct { + Discussions struct { + Nodes []struct { + Number githubv4.Int + Title githubv4.String + CreatedAt githubv4.DateTime + Category struct { + Name githubv4.String + } `graphql:"category"` + URL githubv4.String `graphql:"url"` + } + } `graphql:"discussions(first: 100)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + + // mock for the call to get discussions with category filter + var qDiscussionsFiltered struct { + Repository struct { + Discussions struct { + Nodes []struct { + Number githubv4.Int + Title githubv4.String + CreatedAt githubv4.DateTime + Category struct { + Name githubv4.String + } `graphql:"category"` + URL githubv4.String `graphql:"url"` + } + } `graphql:"discussions(first: 100, categoryId: $categoryId)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + + varsListAll := map[string]interface{}{ + "owner": githubv4.String("owner"), + "repo": githubv4.String("repo"), + } + + varsRepoNotFound := map[string]interface{}{ + "owner": githubv4.String("owner"), + "repo": githubv4.String("nonexistent-repo"), + } + + varsDiscussionsFiltered := map[string]interface{}{ + "owner": githubv4.String("owner"), + "repo": githubv4.String("repo"), + "categoryId": githubv4.ID("DIC_kwDOABC123"), + } + + tests := []struct { + name string + reqParams map[string]interface{} + expectError bool + errContains string + expectedCount int + }{ + { + name: "list all discussions without category filter", + reqParams: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + }, + expectError: false, + expectedCount: 3, // All discussions + }, + { + name: "filter by category ID", + reqParams: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + "category": "DIC_kwDOABC123", + }, + expectError: false, + expectedCount: 2, // Only General discussions (matching the category ID) + }, + { + name: "repository not found error", + reqParams: map[string]interface{}{ + "owner": "owner", + "repo": "nonexistent-repo", + }, + expectError: true, + errContains: "repository not found", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + var httpClient *http.Client + + switch tc.name { + case "list all discussions without category filter": + // Simple case - no category filter + matcher := githubv4mock.NewQueryMatcher(qDiscussions, varsListAll, mockResponseListAll) + httpClient = githubv4mock.NewMockedHTTPClient(matcher) + case "filter by category ID": + // Simple case - category filter using category ID directly + matcher := githubv4mock.NewQueryMatcher(qDiscussionsFiltered, varsDiscussionsFiltered, mockResponseListGeneral) + httpClient = githubv4mock.NewMockedHTTPClient(matcher) + case "repository not found error": + matcher := githubv4mock.NewQueryMatcher(qDiscussions, varsRepoNotFound, mockErrorRepoNotFound) + httpClient = githubv4mock.NewMockedHTTPClient(matcher) + } + + gqlClient := githubv4.NewClient(httpClient) + _, handler := ListDiscussions(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper) + + req := createMCPRequest(tc.reqParams) + res, err := handler(context.Background(), req) + text := getTextResult(t, res).Text + + if tc.expectError { + require.True(t, res.IsError) + assert.Contains(t, text, tc.errContains) + return + } + require.NoError(t, err) + + var returnedDiscussions []*github.Discussion + err = json.Unmarshal([]byte(text), &returnedDiscussions) + require.NoError(t, err) + + assert.Len(t, returnedDiscussions, tc.expectedCount, "Expected %d discussions, got %d", tc.expectedCount, len(returnedDiscussions)) + + // Verify that all returned discussions have a category if filtered + if _, hasCategory := tc.reqParams["category"]; hasCategory { + for _, discussion := range returnedDiscussions { + require.NotNil(t, discussion.DiscussionCategory, "Discussion should have category") + assert.NotEmpty(t, *discussion.DiscussionCategory.Name, "Discussion should have category name") + } + } + }) + } +} + +func Test_GetDiscussion(t *testing.T) { + // Verify tool definition and schema + toolDef, _ := GetDiscussion(nil, translations.NullTranslationHelper) + assert.Equal(t, "get_discussion", toolDef.Name) + assert.NotEmpty(t, toolDef.Description) + assert.Contains(t, toolDef.InputSchema.Properties, "owner") + assert.Contains(t, toolDef.InputSchema.Properties, "repo") + assert.Contains(t, toolDef.InputSchema.Properties, "discussionNumber") + assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo", "discussionNumber"}) + + var q struct { + Repository struct { + Discussion struct { + Number githubv4.Int + Body githubv4.String + CreatedAt githubv4.DateTime + URL githubv4.String `graphql:"url"` + Category struct { + Name githubv4.String + } `graphql:"category"` + } `graphql:"discussion(number: $discussionNumber)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + vars := map[string]interface{}{ + "owner": githubv4.String("owner"), + "repo": githubv4.String("repo"), + "discussionNumber": githubv4.Int(1), + } + tests := []struct { + name string + response githubv4mock.GQLResponse + expectError bool + expected *github.Discussion + errContains string + }{ + { + name: "successful retrieval", + response: githubv4mock.DataResponse(map[string]any{ + "repository": map[string]any{"discussion": map[string]any{ + "number": 1, + "body": "This is a test discussion", + "url": "https://github.com/owner/repo/discussions/1", + "createdAt": "2025-04-25T12:00:00Z", + "category": map[string]any{"name": "General"}, + }}, + }), + expectError: false, + expected: &github.Discussion{ + HTMLURL: github.Ptr("https://github.com/owner/repo/discussions/1"), + Number: github.Ptr(1), + Body: github.Ptr("This is a test discussion"), + CreatedAt: &github.Timestamp{Time: time.Date(2025, 4, 25, 12, 0, 0, 0, time.UTC)}, + DiscussionCategory: &github.DiscussionCategory{ + Name: github.Ptr("General"), + }, + }, + }, + { + name: "discussion not found", + response: githubv4mock.ErrorResponse("discussion not found"), + expectError: true, + errContains: "discussion not found", + }, + } + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + matcher := githubv4mock.NewQueryMatcher(q, vars, tc.response) + httpClient := githubv4mock.NewMockedHTTPClient(matcher) + gqlClient := githubv4.NewClient(httpClient) + _, handler := GetDiscussion(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper) + + req := createMCPRequest(map[string]interface{}{"owner": "owner", "repo": "repo", "discussionNumber": int32(1)}) + res, err := handler(context.Background(), req) + text := getTextResult(t, res).Text + + if tc.expectError { + require.True(t, res.IsError) + assert.Contains(t, text, tc.errContains) + return + } + + require.NoError(t, err) + var out github.Discussion + require.NoError(t, json.Unmarshal([]byte(text), &out)) + assert.Equal(t, *tc.expected.HTMLURL, *out.HTMLURL) + assert.Equal(t, *tc.expected.Number, *out.Number) + assert.Equal(t, *tc.expected.Body, *out.Body) + // Check category label + assert.Equal(t, *tc.expected.DiscussionCategory.Name, *out.DiscussionCategory.Name) + }) + } +} + +func Test_GetDiscussionComments(t *testing.T) { + // Verify tool definition and schema + toolDef, _ := GetDiscussionComments(nil, translations.NullTranslationHelper) + assert.Equal(t, "get_discussion_comments", toolDef.Name) + assert.NotEmpty(t, toolDef.Description) + assert.Contains(t, toolDef.InputSchema.Properties, "owner") + assert.Contains(t, toolDef.InputSchema.Properties, "repo") + assert.Contains(t, toolDef.InputSchema.Properties, "discussionNumber") + assert.ElementsMatch(t, toolDef.InputSchema.Required, []string{"owner", "repo", "discussionNumber"}) + + var q struct { + Repository struct { + Discussion struct { + Comments struct { + Nodes []struct { + Body githubv4.String + } + } `graphql:"comments(first:100)"` + } `graphql:"discussion(number: $discussionNumber)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + vars := map[string]interface{}{ + "owner": githubv4.String("owner"), + "repo": githubv4.String("repo"), + "discussionNumber": githubv4.Int(1), + } + mockResponse := githubv4mock.DataResponse(map[string]any{ + "repository": map[string]any{ + "discussion": map[string]any{ + "comments": map[string]any{ + "nodes": []map[string]any{ + {"body": "This is the first comment"}, + {"body": "This is the second comment"}, + }, + }, + }, + }, + }) + matcher := githubv4mock.NewQueryMatcher(q, vars, mockResponse) + httpClient := githubv4mock.NewMockedHTTPClient(matcher) + gqlClient := githubv4.NewClient(httpClient) + _, handler := GetDiscussionComments(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper) + + request := createMCPRequest(map[string]interface{}{ + "owner": "owner", + "repo": "repo", + "discussionNumber": int32(1), + }) + + result, err := handler(context.Background(), request) + require.NoError(t, err) + + textContent := getTextResult(t, result) + + var returnedComments []*github.IssueComment + err = json.Unmarshal([]byte(textContent.Text), &returnedComments) + require.NoError(t, err) + assert.Len(t, returnedComments, 2) + expectedBodies := []string{"This is the first comment", "This is the second comment"} + for i, comment := range returnedComments { + assert.Equal(t, expectedBodies[i], *comment.Body) + } +} + +func Test_ListDiscussionCategories(t *testing.T) { + var q struct { + Repository struct { + DiscussionCategories struct { + Nodes []struct { + ID githubv4.ID + Name githubv4.String + } + } `graphql:"discussionCategories(first: 100)"` + } `graphql:"repository(owner: $owner, name: $repo)"` + } + vars := map[string]interface{}{ + "owner": githubv4.String("owner"), + "repo": githubv4.String("repo"), + } + mockResp := githubv4mock.DataResponse(map[string]any{ + "repository": map[string]any{ + "discussionCategories": map[string]any{ + "nodes": []map[string]any{ + {"id": "123", "name": "CategoryOne"}, + {"id": "456", "name": "CategoryTwo"}, + }, + }, + }, + }) + matcher := githubv4mock.NewQueryMatcher(q, vars, mockResp) + httpClient := githubv4mock.NewMockedHTTPClient(matcher) + gqlClient := githubv4.NewClient(httpClient) + + tool, handler := ListDiscussionCategories(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper) + assert.Equal(t, "list_discussion_categories", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"}) + + request := createMCPRequest(map[string]interface{}{"owner": "owner", "repo": "repo"}) + result, err := handler(context.Background(), request) + require.NoError(t, err) + + text := getTextResult(t, result).Text + var categories []map[string]string + require.NoError(t, json.Unmarshal([]byte(text), &categories)) + assert.Len(t, categories, 2) + assert.Equal(t, "123", categories[0]["id"]) + assert.Equal(t, "CategoryOne", categories[0]["name"]) + assert.Equal(t, "456", categories[1]["id"]) + assert.Equal(t, "CategoryTwo", categories[1]["name"]) +} diff --git a/pkg/github/dynamic_tools.go b/pkg/github/dynamic_tools.go index 0b098fb39..e703a885e 100644 --- a/pkg/github/dynamic_tools.go +++ b/pkg/github/dynamic_tools.go @@ -25,7 +25,7 @@ func EnableToolset(s *server.MCPServer, toolsetGroup *toolsets.ToolsetGroup, t t mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_ENABLE_TOOLSET_USER_TITLE", "Enable a toolset"), // Not modifying GitHub data so no need to show a warning - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("toolset", mcp.Required(), @@ -35,7 +35,7 @@ func EnableToolset(s *server.MCPServer, toolsetGroup *toolsets.ToolsetGroup, t t ), func(_ context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { // We need to convert the toolsets back to a map for JSON serialization - toolsetName, err := requiredParam[string](request, "toolset") + toolsetName, err := RequiredParam[string](request, "toolset") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -64,7 +64,7 @@ func ListAvailableToolsets(toolsetGroup *toolsets.ToolsetGroup, t translations.T mcp.WithDescription(t("TOOL_LIST_AVAILABLE_TOOLSETS_DESCRIPTION", "List all available toolsets this GitHub MCP server can offer, providing the enabled status of each. Use this when a task could be achieved with a GitHub tool and the currently available tools aren't enough. Call get_toolset_tools with these toolset names to discover specific tools you can call")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_LIST_AVAILABLE_TOOLSETS_USER_TITLE", "List available toolsets"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), ), func(_ context.Context, _ mcp.CallToolRequest) (*mcp.CallToolResult, error) { @@ -98,7 +98,7 @@ func GetToolsetsTools(toolsetGroup *toolsets.ToolsetGroup, t translations.Transl mcp.WithDescription(t("TOOL_GET_TOOLSET_TOOLS_DESCRIPTION", "Lists all the capabilities that are enabled with the specified toolset, use this to get clarity on whether enabling a toolset would help you to complete a task")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_TOOLSET_TOOLS_USER_TITLE", "List all tools in a toolset"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("toolset", mcp.Required(), @@ -108,7 +108,7 @@ func GetToolsetsTools(toolsetGroup *toolsets.ToolsetGroup, t translations.Transl ), func(_ context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { // We need to convert the toolsetGroup back to a map for JSON serialization - toolsetName, err := requiredParam[string](request, "toolset") + toolsetName, err := RequiredParam[string](request, "toolset") if err != nil { return mcp.NewToolResultError(err.Error()), nil } diff --git a/pkg/github/helper_test.go b/pkg/github/helper_test.go index 06bc1d545..bc1ae412f 100644 --- a/pkg/github/helper_test.go +++ b/pkg/github/helper_test.go @@ -109,12 +109,12 @@ func mockResponse(t *testing.T, code int, body interface{}) http.HandlerFunc { } // createMCPRequest is a helper function to create a MCP request with the given arguments. -func createMCPRequest(args map[string]any) mcp.CallToolRequest { +func createMCPRequest(args any) mcp.CallToolRequest { return mcp.CallToolRequest{ Params: struct { - Name string `json:"name"` - Arguments map[string]any `json:"arguments,omitempty"` - Meta *mcp.Meta `json:"_meta,omitempty"` + Name string `json:"name"` + Arguments any `json:"arguments,omitempty"` + Meta *mcp.Meta `json:"_meta,omitempty"` }{ Arguments: args, }, @@ -132,6 +132,36 @@ func getTextResult(t *testing.T, result *mcp.CallToolResult) mcp.TextContent { return textContent } +func getErrorResult(t *testing.T, result *mcp.CallToolResult) mcp.TextContent { + res := getTextResult(t, result) + require.True(t, result.IsError, "expected tool call result to be an error") + return res +} + +// getTextResourceResult is a helper function that returns a text result from a tool call. +func getTextResourceResult(t *testing.T, result *mcp.CallToolResult) mcp.TextResourceContents { + t.Helper() + assert.NotNil(t, result) + require.Len(t, result.Content, 2) + content := result.Content[1] + require.IsType(t, mcp.EmbeddedResource{}, content) + resource := content.(mcp.EmbeddedResource) + require.IsType(t, mcp.TextResourceContents{}, resource.Resource) + return resource.Resource.(mcp.TextResourceContents) +} + +// getBlobResourceResult is a helper function that returns a blob result from a tool call. +func getBlobResourceResult(t *testing.T, result *mcp.CallToolResult) mcp.BlobResourceContents { + t.Helper() + assert.NotNil(t, result) + require.Len(t, result.Content, 2) + content := result.Content[1] + require.IsType(t, mcp.EmbeddedResource{}, content) + resource := content.(mcp.EmbeddedResource) + require.IsType(t, mcp.BlobResourceContents{}, resource.Resource) + return resource.Resource.(mcp.BlobResourceContents) +} + func TestOptionalParamOK(t *testing.T) { tests := []struct { name string diff --git a/pkg/github/issues.go b/pkg/github/issues.go index 68e7a36cd..29d32bd18 100644 --- a/pkg/github/issues.go +++ b/pkg/github/issues.go @@ -11,7 +11,7 @@ import ( "github.com/github/github-mcp-server/pkg/translations" "github.com/go-viper/mapstructure/v2" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" "github.com/shurcooL/githubv4" @@ -23,7 +23,7 @@ func GetIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.WithDescription(t("TOOL_GET_ISSUE_DESCRIPTION", "Get details of a specific issue in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_ISSUE_USER_TITLE", "Get issue details"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -39,11 +39,11 @@ func GetIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (tool ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -85,7 +85,7 @@ func AddIssueComment(getClient GetClientFn, t translations.TranslationHelperFunc mcp.WithDescription(t("TOOL_ADD_ISSUE_COMMENT_DESCRIPTION", "Add a comment to a specific issue in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_ADD_ISSUE_COMMENT_USER_TITLE", "Add comment to issue"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -105,11 +105,11 @@ func AddIssueComment(getClient GetClientFn, t translations.TranslationHelperFunc ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -117,7 +117,7 @@ func AddIssueComment(getClient GetClientFn, t translations.TranslationHelperFunc if err != nil { return mcp.NewToolResultError(err.Error()), nil } - body, err := requiredParam[string](request, "body") + body, err := RequiredParam[string](request, "body") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -153,18 +153,24 @@ func AddIssueComment(getClient GetClientFn, t translations.TranslationHelperFunc } } -// SearchIssues creates a tool to search for issues and pull requests. +// SearchIssues creates a tool to search for issues. func SearchIssues(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { return mcp.NewTool("search_issues", - mcp.WithDescription(t("TOOL_SEARCH_ISSUES_DESCRIPTION", "Search for issues in GitHub repositories.")), + mcp.WithDescription(t("TOOL_SEARCH_ISSUES_DESCRIPTION", "Search for issues in GitHub repositories using issues search syntax already scoped to is:issue")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_SEARCH_ISSUES_USER_TITLE", "Search issues"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), - mcp.WithString("q", + mcp.WithString("query", mcp.Required(), mcp.Description("Search query using GitHub issues search syntax"), ), + mcp.WithString("owner", + mcp.Description("Optional repository owner. If provided with repo, only notifications for this repository are listed."), + ), + mcp.WithString("repo", + mcp.Description("Optional repository name. If provided with owner, only notifications for this repository are listed."), + ), mcp.WithString("sort", mcp.Description("Sort field by number of matches of categories, defaults to best match"), mcp.Enum( @@ -188,56 +194,7 @@ func SearchIssues(getClient GetClientFn, t translations.TranslationHelperFunc) ( WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - query, err := requiredParam[string](request, "q") - if err != nil { - return mcp.NewToolResultError(err.Error()), nil - } - sort, err := OptionalParam[string](request, "sort") - if err != nil { - return mcp.NewToolResultError(err.Error()), nil - } - order, err := OptionalParam[string](request, "order") - if err != nil { - return mcp.NewToolResultError(err.Error()), nil - } - pagination, err := OptionalPaginationParams(request) - if err != nil { - return mcp.NewToolResultError(err.Error()), nil - } - - opts := &github.SearchOptions{ - Sort: sort, - Order: order, - ListOptions: github.ListOptions{ - PerPage: pagination.perPage, - Page: pagination.page, - }, - } - - client, err := getClient(ctx) - if err != nil { - return nil, fmt.Errorf("failed to get GitHub client: %w", err) - } - result, resp, err := client.Search.Issues(ctx, query, opts) - if err != nil { - return nil, fmt.Errorf("failed to search issues: %w", err) - } - defer func() { _ = resp.Body.Close() }() - - if resp.StatusCode != http.StatusOK { - body, err := io.ReadAll(resp.Body) - if err != nil { - return nil, fmt.Errorf("failed to read response body: %w", err) - } - return mcp.NewToolResultError(fmt.Sprintf("failed to search issues: %s", string(body))), nil - } - - r, err := json.Marshal(result) - if err != nil { - return nil, fmt.Errorf("failed to marshal response: %w", err) - } - - return mcp.NewToolResultText(string(r)), nil + return searchHandler(ctx, getClient, request, "issue", "failed to search issues") } } @@ -247,7 +204,7 @@ func CreateIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (t mcp.WithDescription(t("TOOL_CREATE_ISSUE_DESCRIPTION", "Create a new issue in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_CREATE_ISSUE_USER_TITLE", "Open new issue"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -285,15 +242,15 @@ func CreateIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (t ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - title, err := requiredParam[string](request, "title") + title, err := RequiredParam[string](request, "title") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -369,7 +326,7 @@ func ListIssues(getClient GetClientFn, t translations.TranslationHelperFunc) (to mcp.WithDescription(t("TOOL_LIST_ISSUES_DESCRIPTION", "List issues in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_LIST_ISSUES_USER_TITLE", "List issues"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -405,11 +362,11 @@ func ListIssues(getClient GetClientFn, t translations.TranslationHelperFunc) (to WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -450,12 +407,12 @@ func ListIssues(getClient GetClientFn, t translations.TranslationHelperFunc) (to opts.Since = timestamp } - if page, ok := request.Params.Arguments["page"].(float64); ok { - opts.Page = int(page) + if page, ok := request.GetArguments()["page"].(float64); ok { + opts.ListOptions.Page = int(page) } - if perPage, ok := request.Params.Arguments["perPage"].(float64); ok { - opts.PerPage = int(perPage) + if perPage, ok := request.GetArguments()["perPage"].(float64); ok { + opts.ListOptions.PerPage = int(perPage) } client, err := getClient(ctx) @@ -491,7 +448,7 @@ func UpdateIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (t mcp.WithDescription(t("TOOL_UPDATE_ISSUE_DESCRIPTION", "Update an existing issue in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_UPDATE_ISSUE_USER_TITLE", "Edit issue"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -536,11 +493,11 @@ func UpdateIssue(getClient GetClientFn, t translations.TranslationHelperFunc) (t ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -637,7 +594,7 @@ func GetIssueComments(getClient GetClientFn, t translations.TranslationHelperFun mcp.WithDescription(t("TOOL_GET_ISSUE_COMMENTS_DESCRIPTION", "Get comments for a specific issue in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_ISSUE_COMMENTS_USER_TITLE", "Get issue comments"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -651,19 +608,14 @@ func GetIssueComments(getClient GetClientFn, t translations.TranslationHelperFun mcp.Required(), mcp.Description("Issue number"), ), - mcp.WithNumber("page", - mcp.Description("Page number"), - ), - mcp.WithNumber("per_page", - mcp.Description("Number of records per page"), - ), + WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -671,19 +623,15 @@ func GetIssueComments(getClient GetClientFn, t translations.TranslationHelperFun if err != nil { return mcp.NewToolResultError(err.Error()), nil } - page, err := OptionalIntParamWithDefault(request, "page", 1) - if err != nil { - return mcp.NewToolResultError(err.Error()), nil - } - perPage, err := OptionalIntParamWithDefault(request, "per_page", 30) + pagination, err := OptionalPaginationParams(request) if err != nil { return mcp.NewToolResultError(err.Error()), nil } opts := &github.IssueListCommentsOptions{ ListOptions: github.ListOptions{ - Page: page, - PerPage: perPage, + Page: pagination.page, + PerPage: pagination.perPage, }, } @@ -759,8 +707,8 @@ func AssignCopilotToIssue(getGQLClient GetGQLClientFn, t translations.Translatio mcp.WithDescription(t("TOOL_ASSIGN_COPILOT_TO_ISSUE_DESCRIPTION", description.String())), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_ASSIGN_COPILOT_TO_ISSUE_USER_TITLE", "Assign Copilot to issue"), - ReadOnlyHint: toBoolPtr(false), - IdempotentHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(false), + IdempotentHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -931,3 +879,42 @@ func parseISOTimestamp(timestamp string) (time.Time, error) { // Return error with supported formats return time.Time{}, fmt.Errorf("invalid ISO 8601 timestamp: %s (supported formats: YYYY-MM-DDThh:mm:ssZ or YYYY-MM-DD)", timestamp) } + +func AssignCodingAgentPrompt(t translations.TranslationHelperFunc) (tool mcp.Prompt, handler server.PromptHandlerFunc) { + return mcp.NewPrompt("AssignCodingAgent", + mcp.WithPromptDescription(t("PROMPT_ASSIGN_CODING_AGENT_DESCRIPTION", "Assign GitHub Coding Agent to multiple tasks in a GitHub repository.")), + mcp.WithArgument("repo", mcp.ArgumentDescription("The repository to assign tasks in (owner/repo)."), mcp.RequiredArgument()), + ), func(_ context.Context, request mcp.GetPromptRequest) (*mcp.GetPromptResult, error) { + repo := request.Params.Arguments["repo"] + + messages := []mcp.PromptMessage{ + { + Role: "system", + Content: mcp.NewTextContent("You are a personal assistant for GitHub the Copilot GitHub Coding Agent. Your task is to help the user assign tasks to the Coding Agent based on their open GitHub issues. You can use `assign_copilot_to_issue` tool to assign the Coding Agent to issues that are suitable for autonomous work, and `search_issues` tool to find issues that match the user's criteria. You can also use `list_issues` to get a list of issues in the repository."), + }, + { + Role: "user", + Content: mcp.NewTextContent(fmt.Sprintf("Please go and get a list of the most recent 10 issues from the %s GitHub repository", repo)), + }, + { + Role: "assistant", + Content: mcp.NewTextContent(fmt.Sprintf("Sure! I will get a list of the 10 most recent issues for the repo %s.", repo)), + }, + { + Role: "user", + Content: mcp.NewTextContent("For each issue, please check if it is a clearly defined coding task with acceptance criteria and a low to medium complexity to identify issues that are suitable for an AI Coding Agent to work on. Then assign each of the identified issues to Copilot."), + }, + { + Role: "assistant", + Content: mcp.NewTextContent("Certainly! Let me carefully check which ones are clearly scoped issues that are good to assign to the coding agent, and I will summarize and assign them now."), + }, + { + Role: "user", + Content: mcp.NewTextContent("Great, if you are unsure if an issue is good to assign, ask me first, rather than assigning copilot. If you are certain the issue is clear and suitable you can assign it to Copilot without asking."), + }, + } + return &mcp.GetPromptResult{ + Messages: messages, + }, nil + } +} diff --git a/pkg/github/issues_test.go b/pkg/github/issues_test.go index cd715de68..146259477 100644 --- a/pkg/github/issues_test.go +++ b/pkg/github/issues_test.go @@ -9,8 +9,9 @@ import ( "time" "github.com/github/github-mcp-server/internal/githubv4mock" + "github.com/github/github-mcp-server/internal/toolsnaps" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/migueleliasweb/go-github-mock/src/mock" "github.com/shurcooL/githubv4" "github.com/stretchr/testify/assert" @@ -21,6 +22,7 @@ func Test_GetIssue(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetIssue(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_issue", tool.Name) assert.NotEmpty(t, tool.Description) @@ -117,6 +119,7 @@ func Test_AddIssueComment(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := AddIssueComment(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "add_issue_comment", tool.Name) assert.NotEmpty(t, tool.Description) @@ -230,15 +233,18 @@ func Test_SearchIssues(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := SearchIssues(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "search_issues", tool.Name) assert.NotEmpty(t, tool.Description) - assert.Contains(t, tool.InputSchema.Properties, "q") + assert.Contains(t, tool.InputSchema.Properties, "query") + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") assert.Contains(t, tool.InputSchema.Properties, "sort") assert.Contains(t, tool.InputSchema.Properties, "order") assert.Contains(t, tool.InputSchema.Properties, "perPage") assert.Contains(t, tool.InputSchema.Properties, "page") - assert.ElementsMatch(t, tool.InputSchema.Required, []string{"q"}) + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"query"}) // Setup mock search results mockSearchResult := &github.IssuesSearchResult{ @@ -286,7 +292,7 @@ func Test_SearchIssues(t *testing.T) { expectQueryParams( t, map[string]string{ - "q": "repo:owner/repo is:issue is:open", + "q": "is:issue repo:owner/repo is:open", "sort": "created", "order": "desc", "page": "1", @@ -298,7 +304,7 @@ func Test_SearchIssues(t *testing.T) { ), ), requestArgs: map[string]interface{}{ - "q": "repo:owner/repo is:issue is:open", + "query": "repo:owner/repo is:open", "sort": "created", "order": "desc", "page": float64(1), @@ -307,6 +313,83 @@ func Test_SearchIssues(t *testing.T) { expectError: false, expectedResult: mockSearchResult, }, + { + name: "issues search with owner and repo parameters", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchIssues, + expectQueryParams( + t, + map[string]string{ + "q": "repo:test-owner/test-repo is:issue is:open", + "sort": "created", + "order": "asc", + "page": "1", + "per_page": "30", + }, + ).andThen( + mockResponse(t, http.StatusOK, mockSearchResult), + ), + ), + ), + requestArgs: map[string]interface{}{ + "query": "is:open", + "owner": "test-owner", + "repo": "test-repo", + "sort": "created", + "order": "asc", + }, + expectError: false, + expectedResult: mockSearchResult, + }, + { + name: "issues search with only owner parameter (should ignore it)", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchIssues, + expectQueryParams( + t, + map[string]string{ + "q": "is:issue bug", + "page": "1", + "per_page": "30", + }, + ).andThen( + mockResponse(t, http.StatusOK, mockSearchResult), + ), + ), + ), + requestArgs: map[string]interface{}{ + "query": "bug", + "owner": "test-owner", + }, + expectError: false, + expectedResult: mockSearchResult, + }, + { + name: "issues search with only repo parameter (should ignore it)", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchIssues, + expectQueryParams( + t, + map[string]string{ + "q": "is:issue feature", + "page": "1", + "per_page": "30", + }, + ).andThen( + mockResponse(t, http.StatusOK, mockSearchResult), + ), + ), + ), + requestArgs: map[string]interface{}{ + "query": "feature", + "repo": "test-repo", + }, + expectError: false, + expectedResult: mockSearchResult, + }, { name: "issues search with minimal parameters", mockedClient: mock.NewMockedHTTPClient( @@ -316,7 +399,7 @@ func Test_SearchIssues(t *testing.T) { ), ), requestArgs: map[string]interface{}{ - "q": "repo:owner/repo is:issue is:open", + "query": "is:issue repo:owner/repo is:open", }, expectError: false, expectedResult: mockSearchResult, @@ -333,7 +416,7 @@ func Test_SearchIssues(t *testing.T) { ), ), requestArgs: map[string]interface{}{ - "q": "invalid:query", + "query": "invalid:query", }, expectError: true, expectedErrMsg: "failed to search issues", @@ -386,6 +469,7 @@ func Test_CreateIssue(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := CreateIssue(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "create_issue", tool.Name) assert.NotEmpty(t, tool.Description) @@ -560,6 +644,7 @@ func Test_ListIssues(t *testing.T) { // Verify tool definition mockClient := github.NewClient(nil) tool, _ := ListIssues(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "list_issues", tool.Name) assert.NotEmpty(t, tool.Description) @@ -736,6 +821,7 @@ func Test_UpdateIssue(t *testing.T) { // Verify tool definition mockClient := github.NewClient(nil) tool, _ := UpdateIssue(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "update_issue", tool.Name) assert.NotEmpty(t, tool.Description) @@ -993,6 +1079,7 @@ func Test_GetIssueComments(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetIssueComments(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_issue_comments", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1000,7 +1087,7 @@ func Test_GetIssueComments(t *testing.T) { assert.Contains(t, tool.InputSchema.Properties, "repo") assert.Contains(t, tool.InputSchema.Properties, "issue_number") assert.Contains(t, tool.InputSchema.Properties, "page") - assert.Contains(t, tool.InputSchema.Properties, "per_page") + assert.Contains(t, tool.InputSchema.Properties, "perPage") assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "issue_number"}) // Setup mock comments for success case @@ -1065,7 +1152,7 @@ func Test_GetIssueComments(t *testing.T) { "repo": "repo", "issue_number": float64(42), "page": float64(2), - "per_page": float64(10), + "perPage": float64(10), }, expectError: false, expectedComments: mockComments, @@ -1129,6 +1216,7 @@ func TestAssignCopilotToIssue(t *testing.T) { // Verify tool definition mockClient := githubv4.NewClient(nil) tool, _ := AssignCopilotToIssue(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "assign_copilot_to_issue", tool.Name) assert.NotEmpty(t, tool.Description) diff --git a/pkg/github/notifications.go b/pkg/github/notifications.go index ba9c6bc2b..a41edaf42 100644 --- a/pkg/github/notifications.go +++ b/pkg/github/notifications.go @@ -9,8 +9,9 @@ import ( "strconv" "time" + ghErrors "github.com/github/github-mcp-server/pkg/errors" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) @@ -27,7 +28,7 @@ func ListNotifications(getClient GetClientFn, t translations.TranslationHelperFu mcp.WithDescription(t("TOOL_LIST_NOTIFICATIONS_DESCRIPTION", "Lists all GitHub notifications for the authenticated user, including unread notifications, mentions, review requests, assignments, and updates on issues or pull requests. Use this tool whenever the user asks what to work on next, requests a summary of their GitHub activity, wants to see pending reviews, or needs to check for new updates or tasks. This tool is the primary way to discover actionable items, reminders, and outstanding work on GitHub. Always call this tool when asked what to work on next, what is pending, or what needs attention in GitHub.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_LIST_NOTIFICATIONS_USER_TITLE", "List notifications"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("filter", mcp.Description("Filter notifications to, use default unless specified. Read notifications are ones that have already been acknowledged by the user. Participating notifications are those that the user is directly involved in, such as issues or pull requests they have commented on or created."), @@ -118,7 +119,11 @@ func ListNotifications(getClient GetClientFn, t translations.TranslationHelperFu notifications, resp, err = client.Activity.ListNotifications(ctx, opts) } if err != nil { - return nil, fmt.Errorf("failed to get notifications: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to list notifications", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -146,7 +151,7 @@ func DismissNotification(getclient GetClientFn, t translations.TranslationHelper mcp.WithDescription(t("TOOL_DISMISS_NOTIFICATION_DESCRIPTION", "Dismiss a notification by marking it as read or done")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_DISMISS_NOTIFICATION_USER_TITLE", "Dismiss notification"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("threadID", mcp.Required(), @@ -160,12 +165,12 @@ func DismissNotification(getclient GetClientFn, t translations.TranslationHelper return nil, fmt.Errorf("failed to get GitHub client: %w", err) } - threadID, err := requiredParam[string](request, "threadID") + threadID, err := RequiredParam[string](request, "threadID") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - state, err := requiredParam[string](request, "state") + state, err := RequiredParam[string](request, "state") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -187,7 +192,11 @@ func DismissNotification(getclient GetClientFn, t translations.TranslationHelper } if err != nil { - return nil, fmt.Errorf("failed to mark notification as %s: %w", state, err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to mark notification as %s", state), + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -209,7 +218,7 @@ func MarkAllNotificationsRead(getClient GetClientFn, t translations.TranslationH mcp.WithDescription(t("TOOL_MARK_ALL_NOTIFICATIONS_READ_DESCRIPTION", "Mark all notifications as read")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_MARK_ALL_NOTIFICATIONS_READ_USER_TITLE", "Mark all notifications as read"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("lastReadAt", mcp.Description("Describes the last point that notifications were checked (optional). Default: Now"), @@ -262,7 +271,11 @@ func MarkAllNotificationsRead(getClient GetClientFn, t translations.TranslationH resp, err = client.Activity.MarkNotificationsRead(ctx, markReadOptions) } if err != nil { - return nil, fmt.Errorf("failed to mark all notifications as read: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to mark all notifications as read", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -284,7 +297,7 @@ func GetNotificationDetails(getClient GetClientFn, t translations.TranslationHel mcp.WithDescription(t("TOOL_GET_NOTIFICATION_DETAILS_DESCRIPTION", "Get detailed information for a specific GitHub notification, always call this tool when the user asks for details about a specific notification, if you don't know the ID list notifications first.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_NOTIFICATION_DETAILS_USER_TITLE", "Get notification details"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("notificationID", mcp.Required(), @@ -297,14 +310,18 @@ func GetNotificationDetails(getClient GetClientFn, t translations.TranslationHel return nil, fmt.Errorf("failed to get GitHub client: %w", err) } - notificationID, err := requiredParam[string](request, "notificationID") + notificationID, err := RequiredParam[string](request, "notificationID") if err != nil { return mcp.NewToolResultError(err.Error()), nil } thread, resp, err := client.Activity.GetThread(ctx, notificationID) if err != nil { - return nil, fmt.Errorf("failed to get notification details: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to get notification details for ID '%s'", notificationID), + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -338,7 +355,7 @@ func ManageNotificationSubscription(getClient GetClientFn, t translations.Transl mcp.WithDescription(t("TOOL_MANAGE_NOTIFICATION_SUBSCRIPTION_DESCRIPTION", "Manage a notification subscription: ignore, watch, or delete a notification thread subscription.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_MANAGE_NOTIFICATION_SUBSCRIPTION_USER_TITLE", "Manage notification subscription"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("notificationID", mcp.Required(), @@ -356,11 +373,11 @@ func ManageNotificationSubscription(getClient GetClientFn, t translations.Transl return nil, fmt.Errorf("failed to get GitHub client: %w", err) } - notificationID, err := requiredParam[string](request, "notificationID") + notificationID, err := RequiredParam[string](request, "notificationID") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - action, err := requiredParam[string](request, "action") + action, err := RequiredParam[string](request, "action") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -373,10 +390,10 @@ func ManageNotificationSubscription(getClient GetClientFn, t translations.Transl switch action { case NotificationActionIgnore: - sub := &github.Subscription{Ignored: toBoolPtr(true)} + sub := &github.Subscription{Ignored: ToBoolPtr(true)} result, resp, apiErr = client.Activity.SetThreadSubscription(ctx, notificationID, sub) case NotificationActionWatch: - sub := &github.Subscription{Ignored: toBoolPtr(false), Subscribed: toBoolPtr(true)} + sub := &github.Subscription{Ignored: ToBoolPtr(false), Subscribed: ToBoolPtr(true)} result, resp, apiErr = client.Activity.SetThreadSubscription(ctx, notificationID, sub) case NotificationActionDelete: resp, apiErr = client.Activity.DeleteThreadSubscription(ctx, notificationID) @@ -385,7 +402,11 @@ func ManageNotificationSubscription(getClient GetClientFn, t translations.Transl } if apiErr != nil { - return nil, fmt.Errorf("failed to %s notification subscription: %w", action, apiErr) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to %s notification subscription", action), + resp, + apiErr, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -419,7 +440,7 @@ func ManageRepositoryNotificationSubscription(getClient GetClientFn, t translati mcp.WithDescription(t("TOOL_MANAGE_REPOSITORY_NOTIFICATION_SUBSCRIPTION_DESCRIPTION", "Manage a repository notification subscription: ignore, watch, or delete repository notifications subscription for the provided repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_MANAGE_REPOSITORY_NOTIFICATION_SUBSCRIPTION_USER_TITLE", "Manage repository notification subscription"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -441,15 +462,15 @@ func ManageRepositoryNotificationSubscription(getClient GetClientFn, t translati return nil, fmt.Errorf("failed to get GitHub client: %w", err) } - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - action, err := requiredParam[string](request, "action") + action, err := RequiredParam[string](request, "action") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -462,10 +483,10 @@ func ManageRepositoryNotificationSubscription(getClient GetClientFn, t translati switch action { case RepositorySubscriptionActionIgnore: - sub := &github.Subscription{Ignored: toBoolPtr(true)} + sub := &github.Subscription{Ignored: ToBoolPtr(true)} result, resp, apiErr = client.Activity.SetRepositorySubscription(ctx, owner, repo, sub) case RepositorySubscriptionActionWatch: - sub := &github.Subscription{Ignored: toBoolPtr(false), Subscribed: toBoolPtr(true)} + sub := &github.Subscription{Ignored: ToBoolPtr(false), Subscribed: ToBoolPtr(true)} result, resp, apiErr = client.Activity.SetRepositorySubscription(ctx, owner, repo, sub) case RepositorySubscriptionActionDelete: resp, apiErr = client.Activity.DeleteRepositorySubscription(ctx, owner, repo) @@ -474,7 +495,11 @@ func ManageRepositoryNotificationSubscription(getClient GetClientFn, t translati } if apiErr != nil { - return nil, fmt.Errorf("failed to %s repository subscription: %w", action, apiErr) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to %s repository subscription", action), + resp, + apiErr, + ), nil } if resp != nil { defer func() { _ = resp.Body.Close() }() diff --git a/pkg/github/notifications_test.go b/pkg/github/notifications_test.go index 66400295a..1d2382369 100644 --- a/pkg/github/notifications_test.go +++ b/pkg/github/notifications_test.go @@ -6,8 +6,9 @@ import ( "net/http" "testing" + "github.com/github/github-mcp-server/internal/toolsnaps" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/migueleliasweb/go-github-mock/src/mock" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -17,6 +18,8 @@ func Test_ListNotifications(t *testing.T) { // Verify tool definition and schema mockClient := github.NewClient(nil) tool, _ := ListNotifications(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + assert.Equal(t, "list_notifications", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "filter") @@ -124,14 +127,17 @@ func Test_ListNotifications(t *testing.T) { result, err := handler(context.Background(), request) if tc.expectError { - require.Error(t, err) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) if tc.expectedErrMsg != "" { - assert.Contains(t, err.Error(), tc.expectedErrMsg) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) } return } require.NoError(t, err) + require.False(t, result.IsError) textContent := getTextResult(t, result) t.Logf("textContent: %s", textContent.Text) var returned []*github.Notification @@ -147,6 +153,8 @@ func Test_ManageNotificationSubscription(t *testing.T) { // Verify tool definition and schema mockClient := github.NewClient(nil) tool, _ := ManageNotificationSubscription(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + assert.Equal(t, "manage_notification_subscription", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "notificationID") @@ -283,6 +291,8 @@ func Test_ManageRepositoryNotificationSubscription(t *testing.T) { // Verify tool definition and schema mockClient := github.NewClient(nil) tool, _ := ManageRepositoryNotificationSubscription(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + assert.Equal(t, "manage_repository_notification_subscription", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "owner") @@ -444,6 +454,8 @@ func Test_DismissNotification(t *testing.T) { // Verify tool definition and schema mockClient := github.NewClient(nil) tool, _ := DismissNotification(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + assert.Equal(t, "dismiss_notification", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "threadID") @@ -574,6 +586,8 @@ func Test_MarkAllNotificationsRead(t *testing.T) { // Verify tool definition and schema mockClient := github.NewClient(nil) tool, _ := MarkAllNotificationsRead(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + assert.Equal(t, "mark_all_notifications_read", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "lastReadAt") @@ -652,14 +666,17 @@ func Test_MarkAllNotificationsRead(t *testing.T) { result, err := handler(context.Background(), request) if tc.expectError { - require.Error(t, err) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) if tc.expectedErrMsg != "" { - assert.Contains(t, err.Error(), tc.expectedErrMsg) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) } return } require.NoError(t, err) + require.False(t, result.IsError) textContent := getTextResult(t, result) if tc.expectMarked { assert.Contains(t, textContent.Text, "All notifications marked as read") @@ -672,6 +689,8 @@ func Test_GetNotificationDetails(t *testing.T) { // Verify tool definition and schema mockClient := github.NewClient(nil) tool, _ := GetNotificationDetails(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + assert.Equal(t, "get_notification_details", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "notificationID") @@ -725,14 +744,17 @@ func Test_GetNotificationDetails(t *testing.T) { result, err := handler(context.Background(), request) if tc.expectError { - require.Error(t, err) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) if tc.expectedErrMsg != "" { - assert.Contains(t, err.Error(), tc.expectedErrMsg) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) } return } require.NoError(t, err) + require.False(t, result.IsError) textContent := getTextResult(t, result) var returned github.Notification err = json.Unmarshal([]byte(textContent.Text), &returned) diff --git a/pkg/github/pullrequests.go b/pkg/github/pullrequests.go index d6dd3f96e..d98dc334d 100644 --- a/pkg/github/pullrequests.go +++ b/pkg/github/pullrequests.go @@ -7,12 +7,14 @@ import ( "io" "net/http" - "github.com/github/github-mcp-server/pkg/translations" "github.com/go-viper/mapstructure/v2" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" "github.com/shurcooL/githubv4" + + ghErrors "github.com/github/github-mcp-server/pkg/errors" + "github.com/github/github-mcp-server/pkg/translations" ) // GetPullRequest creates a tool to get details of a specific pull request. @@ -21,7 +23,7 @@ func GetPullRequest(getClient GetClientFn, t translations.TranslationHelperFunc) mcp.WithDescription(t("TOOL_GET_PULL_REQUEST_DESCRIPTION", "Get details of a specific pull request in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_PULL_REQUEST_USER_TITLE", "Get pull request details"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -37,11 +39,11 @@ func GetPullRequest(getClient GetClientFn, t translations.TranslationHelperFunc) ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -56,7 +58,11 @@ func GetPullRequest(getClient GetClientFn, t translations.TranslationHelperFunc) } pr, resp, err := client.PullRequests.Get(ctx, owner, repo, pullNumber) if err != nil { - return nil, fmt.Errorf("failed to get pull request: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get pull request", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -83,7 +89,7 @@ func CreatePullRequest(getClient GetClientFn, t translations.TranslationHelperFu mcp.WithDescription(t("TOOL_CREATE_PULL_REQUEST_DESCRIPTION", "Create a new pull request in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_CREATE_PULL_REQUEST_USER_TITLE", "Open new pull request"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -116,23 +122,23 @@ func CreatePullRequest(getClient GetClientFn, t translations.TranslationHelperFu ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - title, err := requiredParam[string](request, "title") + title, err := RequiredParam[string](request, "title") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - head, err := requiredParam[string](request, "head") + head, err := RequiredParam[string](request, "head") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - base, err := requiredParam[string](request, "base") + base, err := RequiredParam[string](request, "base") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -171,7 +177,11 @@ func CreatePullRequest(getClient GetClientFn, t translations.TranslationHelperFu } pr, resp, err := client.PullRequests.Create(ctx, owner, repo, newPR) if err != nil { - return nil, fmt.Errorf("failed to create pull request: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to create pull request", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -198,7 +208,7 @@ func UpdatePullRequest(getClient GetClientFn, t translations.TranslationHelperFu mcp.WithDescription(t("TOOL_UPDATE_PULL_REQUEST_DESCRIPTION", "Update an existing pull request in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_UPDATE_PULL_REQUEST_USER_TITLE", "Edit pull request"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -230,11 +240,11 @@ func UpdatePullRequest(getClient GetClientFn, t translations.TranslationHelperFu ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -292,7 +302,11 @@ func UpdatePullRequest(getClient GetClientFn, t translations.TranslationHelperFu } pr, resp, err := client.PullRequests.Edit(ctx, owner, repo, pullNumber, update) if err != nil { - return nil, fmt.Errorf("failed to update pull request: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to update pull request", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -316,10 +330,10 @@ func UpdatePullRequest(getClient GetClientFn, t translations.TranslationHelperFu // ListPullRequests creates a tool to list and filter repository pull requests. func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) { return mcp.NewTool("list_pull_requests", - mcp.WithDescription(t("TOOL_LIST_PULL_REQUESTS_DESCRIPTION", "List pull requests in a GitHub repository.")), + mcp.WithDescription(t("TOOL_LIST_PULL_REQUESTS_DESCRIPTION", "List pull requests in a GitHub repository. If the user specifies an author, then DO NOT use this tool and use the search_pull_requests tool instead.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_LIST_PULL_REQUESTS_USER_TITLE", "List pull requests"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -350,11 +364,11 @@ func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFun WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -382,7 +396,6 @@ func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFun if err != nil { return mcp.NewToolResultError(err.Error()), nil } - opts := &github.PullRequestListOptions{ State: state, Head: head, @@ -401,7 +414,11 @@ func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFun } prs, resp, err := client.PullRequests.List(ctx, owner, repo, opts) if err != nil { - return nil, fmt.Errorf("failed to list pull requests: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to list pull requests", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -428,7 +445,7 @@ func MergePullRequest(getClient GetClientFn, t translations.TranslationHelperFun mcp.WithDescription(t("TOOL_MERGE_PULL_REQUEST_DESCRIPTION", "Merge a pull request in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_MERGE_PULL_REQUEST_USER_TITLE", "Merge pull request"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -454,11 +471,11 @@ func MergePullRequest(getClient GetClientFn, t translations.TranslationHelperFun ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -490,7 +507,11 @@ func MergePullRequest(getClient GetClientFn, t translations.TranslationHelperFun } result, resp, err := client.PullRequests.Merge(ctx, owner, repo, pullNumber, commitMessage, options) if err != nil { - return nil, fmt.Errorf("failed to merge pull request: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to merge pull request", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -511,13 +532,58 @@ func MergePullRequest(getClient GetClientFn, t translations.TranslationHelperFun } } +// SearchPullRequests creates a tool to search for pull requests. +func SearchPullRequests(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("search_pull_requests", + mcp.WithDescription(t("TOOL_SEARCH_PULL_REQUESTS_DESCRIPTION", "Search for pull requests in GitHub repositories using issues search syntax already scoped to is:pr")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_SEARCH_PULL_REQUESTS_USER_TITLE", "Search pull requests"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("query", + mcp.Required(), + mcp.Description("Search query using GitHub pull request search syntax"), + ), + mcp.WithString("owner", + mcp.Description("Optional repository owner. If provided with repo, only notifications for this repository are listed."), + ), + mcp.WithString("repo", + mcp.Description("Optional repository name. If provided with owner, only notifications for this repository are listed."), + ), + mcp.WithString("sort", + mcp.Description("Sort field by number of matches of categories, defaults to best match"), + mcp.Enum( + "comments", + "reactions", + "reactions-+1", + "reactions--1", + "reactions-smile", + "reactions-thinking_face", + "reactions-heart", + "reactions-tada", + "interactions", + "created", + "updated", + ), + ), + mcp.WithString("order", + mcp.Description("Sort order"), + mcp.Enum("asc", "desc"), + ), + WithPagination(), + ), + func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + return searchHandler(ctx, getClient, request, "pr", "failed to search pull requests") + } +} + // GetPullRequestFiles creates a tool to get the list of files changed in a pull request. func GetPullRequestFiles(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) { return mcp.NewTool("get_pull_request_files", mcp.WithDescription(t("TOOL_GET_PULL_REQUEST_FILES_DESCRIPTION", "Get the files changed in a specific pull request.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_PULL_REQUEST_FILES_USER_TITLE", "Get pull request files"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -531,13 +597,14 @@ func GetPullRequestFiles(getClient GetClientFn, t translations.TranslationHelper mcp.Required(), mcp.Description("Pull request number"), ), + WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -545,15 +612,26 @@ func GetPullRequestFiles(getClient GetClientFn, t translations.TranslationHelper if err != nil { return mcp.NewToolResultError(err.Error()), nil } + pagination, err := OptionalPaginationParams(request) + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } client, err := getClient(ctx) if err != nil { return nil, fmt.Errorf("failed to get GitHub client: %w", err) } - opts := &github.ListOptions{} + opts := &github.ListOptions{ + PerPage: pagination.perPage, + Page: pagination.page, + } files, resp, err := client.PullRequests.ListFiles(ctx, owner, repo, pullNumber, opts) if err != nil { - return nil, fmt.Errorf("failed to get pull request files: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get pull request files", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -580,7 +658,7 @@ func GetPullRequestStatus(getClient GetClientFn, t translations.TranslationHelpe mcp.WithDescription(t("TOOL_GET_PULL_REQUEST_STATUS_DESCRIPTION", "Get the status of a specific pull request.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_PULL_REQUEST_STATUS_USER_TITLE", "Get pull request status checks"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -596,11 +674,11 @@ func GetPullRequestStatus(getClient GetClientFn, t translations.TranslationHelpe ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -615,7 +693,11 @@ func GetPullRequestStatus(getClient GetClientFn, t translations.TranslationHelpe } pr, resp, err := client.PullRequests.Get(ctx, owner, repo, pullNumber) if err != nil { - return nil, fmt.Errorf("failed to get pull request: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get pull request", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -630,7 +712,11 @@ func GetPullRequestStatus(getClient GetClientFn, t translations.TranslationHelpe // Get combined status for the head SHA status, resp, err := client.Repositories.GetCombinedStatus(ctx, owner, repo, *pr.Head.SHA, nil) if err != nil { - return nil, fmt.Errorf("failed to get combined status: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get combined status", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -657,7 +743,7 @@ func UpdatePullRequestBranch(getClient GetClientFn, t translations.TranslationHe mcp.WithDescription(t("TOOL_UPDATE_PULL_REQUEST_BRANCH_DESCRIPTION", "Update the branch of a pull request with the latest changes from the base branch.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_UPDATE_PULL_REQUEST_BRANCH_USER_TITLE", "Update pull request branch"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -676,11 +762,11 @@ func UpdatePullRequestBranch(getClient GetClientFn, t translations.TranslationHe ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -708,7 +794,11 @@ func UpdatePullRequestBranch(getClient GetClientFn, t translations.TranslationHe if resp != nil && resp.StatusCode == http.StatusAccepted && isAcceptedError(err) { return mcp.NewToolResultText("Pull request branch update is in progress"), nil } - return nil, fmt.Errorf("failed to update pull request branch: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to update pull request branch", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -735,7 +825,7 @@ func GetPullRequestComments(getClient GetClientFn, t translations.TranslationHel mcp.WithDescription(t("TOOL_GET_PULL_REQUEST_COMMENTS_DESCRIPTION", "Get comments for a specific pull request.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_PULL_REQUEST_COMMENTS_USER_TITLE", "Get pull request comments"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -751,11 +841,11 @@ func GetPullRequestComments(getClient GetClientFn, t translations.TranslationHel ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -776,7 +866,11 @@ func GetPullRequestComments(getClient GetClientFn, t translations.TranslationHel } comments, resp, err := client.PullRequests.ListComments(ctx, owner, repo, pullNumber, opts) if err != nil { - return nil, fmt.Errorf("failed to get pull request comments: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get pull request comments", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -803,7 +897,7 @@ func GetPullRequestReviews(getClient GetClientFn, t translations.TranslationHelp mcp.WithDescription(t("TOOL_GET_PULL_REQUEST_REVIEWS_DESCRIPTION", "Get reviews for a specific pull request.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_PULL_REQUEST_REVIEWS_USER_TITLE", "Get pull request reviews"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -819,11 +913,11 @@ func GetPullRequestReviews(getClient GetClientFn, t translations.TranslationHelp ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -838,7 +932,11 @@ func GetPullRequestReviews(getClient GetClientFn, t translations.TranslationHelp } reviews, resp, err := client.PullRequests.ListReviews(ctx, owner, repo, pullNumber, nil) if err != nil { - return nil, fmt.Errorf("failed to get pull request reviews: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get pull request reviews", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -864,7 +962,7 @@ func CreateAndSubmitPullRequestReview(getGQLClient GetGQLClientFn, t translation mcp.WithDescription(t("TOOL_CREATE_AND_SUBMIT_PULL_REQUEST_REVIEW_DESCRIPTION", "Create and submit a review for a pull request without review comments.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_CREATE_AND_SUBMIT_PULL_REQUEST_REVIEW_USER_TITLE", "Create and submit a pull request review without comments"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), // Either we need the PR GQL Id directly, or we need owner, repo and PR number to look it up. // Since our other Pull Request tools are working with the REST Client, will handle the lookup @@ -925,7 +1023,10 @@ func CreateAndSubmitPullRequestReview(getGQLClient GetGQLClientFn, t translation "repo": githubv4.String(params.Repo), "prNum": githubv4.Int(params.PullNumber), }); err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubGraphQLErrorResponse(ctx, + "failed to get pull request", + err, + ), nil } // Now we have the GQL ID, we can create a review @@ -964,7 +1065,7 @@ func CreatePendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. mcp.WithDescription(t("TOOL_CREATE_PENDING_PULL_REQUEST_REVIEW_DESCRIPTION", "Create a pending review for a pull request. Call this first before attempting to add comments to a pending review, and ultimately submitting it. A pending pull request review means a pull request review, it is pending because you create it first and submit it later, and the PR author will not see it until it is submitted.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_CREATE_PENDING_PULL_REQUEST_REVIEW_USER_TITLE", "Create pending pull request review"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), // Either we need the PR GQL Id directly, or we need owner, repo and PR number to look it up. // Since our other Pull Request tools are working with the REST Client, will handle the lookup @@ -1016,7 +1117,10 @@ func CreatePendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. "repo": githubv4.String(params.Repo), "prNum": githubv4.Int(params.PullNumber), }); err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubGraphQLErrorResponse(ctx, + "failed to get pull request", + err, + ), nil } // Now we have the GQL ID, we can create a pending review @@ -1047,13 +1151,13 @@ func CreatePendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. } } -// AddPullRequestReviewCommentToPendingReview creates a tool to add a comment to a pull request review. -func AddPullRequestReviewCommentToPendingReview(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) { - return mcp.NewTool("add_pull_request_review_comment_to_pending_review", - mcp.WithDescription(t("TOOL_ADD_PULL_REQUEST_REVIEW_COMMENT_TO_PENDING_REVIEW_DESCRIPTION", "Add a comment to the requester's latest pending pull request review, a pending review needs to already exist to call this (check with the user if not sure). If you are using the LINE subjectType, use the get_line_number_in_pull_request_file tool to get an exact line number before commenting.")), +// AddCommentToPendingReview creates a tool to add a comment to a pull request review. +func AddCommentToPendingReview(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) { + return mcp.NewTool("add_comment_to_pending_review", + mcp.WithDescription(t("TOOL_ADD_COMMENT_TO_PENDING_REVIEW_DESCRIPTION", "Add review comment to the requester's latest pending pull request review. A pending review needs to already exist to call this (check with the user if not sure).")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ - Title: t("TOOL_ADD_PULL_REQUEST_REVIEW_COMMENT_TO_PENDING_REVIEW_USER_TITLE", "Add comment to the requester's latest pending pull request review"), - ReadOnlyHint: toBoolPtr(false), + Title: t("TOOL_ADD_COMMENT_TO_PENDING_REVIEW_USER_TITLE", "Add review comment to the requester's latest pending pull request review"), + ReadOnlyHint: ToBoolPtr(false), }), // Ideally, for performance sake this would just accept the pullRequestReviewID. However, we would need to // add a new tool to get that ID for clients that aren't in the same context as the original pending review @@ -1134,7 +1238,10 @@ func AddPullRequestReviewCommentToPendingReview(getGQLClient GetGQLClientFn, t t } if err := client.Query(ctx, &getViewerQuery, nil); err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubGraphQLErrorResponse(ctx, + "failed to get current user", + err, + ), nil } var getLatestReviewForViewerQuery struct { @@ -1159,7 +1266,10 @@ func AddPullRequestReviewCommentToPendingReview(getGQLClient GetGQLClientFn, t t } if err := client.Query(context.Background(), &getLatestReviewForViewerQuery, vars); err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubGraphQLErrorResponse(ctx, + "failed to get latest review for current user", + err, + ), nil } // Validate there is one review and the state is pending @@ -1213,7 +1323,7 @@ func SubmitPendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. mcp.WithDescription(t("TOOL_SUBMIT_PENDING_PULL_REQUEST_REVIEW_DESCRIPTION", "Submit the requester's latest pending pull request review, normally this is a final step after creating a pending review, adding comments first, unless you know that the user already did the first two steps, you should check before calling this.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_SUBMIT_PENDING_PULL_REQUEST_REVIEW_USER_TITLE", "Submit the requester's latest pending pull request review"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), // Ideally, for performance sake this would just accept the pullRequestReviewID. However, we would need to // add a new tool to get that ID for clients that aren't in the same context as the original pending review @@ -1265,7 +1375,10 @@ func SubmitPendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. } if err := client.Query(ctx, &getViewerQuery, nil); err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubGraphQLErrorResponse(ctx, + "failed to get current user", + err, + ), nil } var getLatestReviewForViewerQuery struct { @@ -1290,7 +1403,10 @@ func SubmitPendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. } if err := client.Query(context.Background(), &getLatestReviewForViewerQuery, vars); err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubGraphQLErrorResponse(ctx, + "failed to get latest review for current user", + err, + ), nil } // Validate there is one review and the state is pending @@ -1323,7 +1439,10 @@ func SubmitPendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. }, nil, ); err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubGraphQLErrorResponse(ctx, + "failed to submit pull request review", + err, + ), nil } // Return nothing interesting, just indicate success for the time being. @@ -1338,7 +1457,7 @@ func DeletePendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. mcp.WithDescription(t("TOOL_DELETE_PENDING_PULL_REQUEST_REVIEW_DESCRIPTION", "Delete the requester's latest pending pull request review. Use this after the user decides not to submit a pending review, if you don't know if they already created one then check first.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_DELETE_PENDING_PULL_REQUEST_REVIEW_USER_TITLE", "Delete the requester's latest pending pull request review"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), // Ideally, for performance sake this would just accept the pullRequestReviewID. However, we would need to // add a new tool to get that ID for clients that aren't in the same context as the original pending review @@ -1380,7 +1499,10 @@ func DeletePendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. } if err := client.Query(ctx, &getViewerQuery, nil); err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubGraphQLErrorResponse(ctx, + "failed to get current user", + err, + ), nil } var getLatestReviewForViewerQuery struct { @@ -1405,7 +1527,10 @@ func DeletePendingPullRequestReview(getGQLClient GetGQLClientFn, t translations. } if err := client.Query(context.Background(), &getLatestReviewForViewerQuery, vars); err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubGraphQLErrorResponse(ctx, + "failed to get latest review for current user", + err, + ), nil } // Validate there is one review and the state is pending @@ -1451,7 +1576,7 @@ func GetPullRequestDiff(getClient GetClientFn, t translations.TranslationHelperF mcp.WithDescription(t("TOOL_GET_PULL_REQUEST_DIFF_DESCRIPTION", "Get the diff of a pull request.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_PULL_REQUEST_DIFF_USER_TITLE", "Get pull request diff"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -1489,7 +1614,11 @@ func GetPullRequestDiff(getClient GetClientFn, t translations.TranslationHelperF github.RawOptions{Type: github.Diff}, ) if err != nil { - return mcp.NewToolResultError(err.Error()), nil + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get pull request diff", + resp, + err, + ), nil } if resp.StatusCode != http.StatusOK { @@ -1515,7 +1644,7 @@ func RequestCopilotReview(getClient GetClientFn, t translations.TranslationHelpe mcp.WithDescription(t("TOOL_REQUEST_COPILOT_REVIEW_DESCRIPTION", "Request a GitHub Copilot code review for a pull request. Use this for automated feedback on pull requests, usually before requesting a human reviewer.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_REQUEST_COPILOT_REVIEW_USER_TITLE", "Request Copilot review"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -1531,12 +1660,12 @@ func RequestCopilotReview(getClient GetClientFn, t translations.TranslationHelpe ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -1562,7 +1691,11 @@ func RequestCopilotReview(getClient GetClientFn, t translations.TranslationHelpe }, ) if err != nil { - return nil, fmt.Errorf("failed to request copilot review: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to request copilot review", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() diff --git a/pkg/github/pullrequests_test.go b/pkg/github/pullrequests_test.go index 6202ec16c..42fd5bf03 100644 --- a/pkg/github/pullrequests_test.go +++ b/pkg/github/pullrequests_test.go @@ -8,8 +8,9 @@ import ( "time" "github.com/github/github-mcp-server/internal/githubv4mock" + "github.com/github/github-mcp-server/internal/toolsnaps" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/shurcooL/githubv4" "github.com/migueleliasweb/go-github-mock/src/mock" @@ -21,6 +22,7 @@ func Test_GetPullRequest(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetPullRequest(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_pull_request", tool.Name) assert.NotEmpty(t, tool.Description) @@ -107,12 +109,15 @@ func Test_GetPullRequest(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -133,6 +138,7 @@ func Test_UpdatePullRequest(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := UpdatePullRequest(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "update_pull_request", tool.Name) assert.NotEmpty(t, tool.Description) @@ -269,23 +275,22 @@ func Test_UpdatePullRequest(t *testing.T) { result, err := handler(context.Background(), request) // Verify results - if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + if tc.expectError || tc.expectedErrMsg != "" { + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + if tc.expectedErrMsg != "" { + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) + } return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content textContent := getTextResult(t, result) - // Check for expected error message within the result text - if tc.expectedErrMsg != "" { - assert.Contains(t, textContent.Text, tc.expectedErrMsg) - return - } - // Unmarshal and verify the successful result var returnedPR github.PullRequest err = json.Unmarshal([]byte(textContent.Text), &returnedPR) @@ -315,6 +320,7 @@ func Test_ListPullRequests(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := ListPullRequests(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "list_pull_requests", tool.Name) assert.NotEmpty(t, tool.Description) @@ -416,12 +422,15 @@ func Test_ListPullRequests(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -445,6 +454,7 @@ func Test_MergePullRequest(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := MergePullRequest(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "merge_pull_request", tool.Name) assert.NotEmpty(t, tool.Description) @@ -531,12 +541,15 @@ func Test_MergePullRequest(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -552,16 +565,254 @@ func Test_MergePullRequest(t *testing.T) { } } +func Test_SearchPullRequests(t *testing.T) { + mockClient := github.NewClient(nil) + tool, _ := SearchPullRequests(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) + + assert.Equal(t, "search_pull_requests", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "query") + assert.Contains(t, tool.InputSchema.Properties, "owner") + assert.Contains(t, tool.InputSchema.Properties, "repo") + assert.Contains(t, tool.InputSchema.Properties, "sort") + assert.Contains(t, tool.InputSchema.Properties, "order") + assert.Contains(t, tool.InputSchema.Properties, "perPage") + assert.Contains(t, tool.InputSchema.Properties, "page") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"query"}) + + mockSearchResult := &github.IssuesSearchResult{ + Total: github.Ptr(2), + IncompleteResults: github.Ptr(false), + Issues: []*github.Issue{ + { + Number: github.Ptr(42), + Title: github.Ptr("Test PR 1"), + Body: github.Ptr("Updated tests."), + State: github.Ptr("open"), + HTMLURL: github.Ptr("https://github.com/owner/repo/pull/1"), + Comments: github.Ptr(5), + User: &github.User{ + Login: github.Ptr("user1"), + }, + }, + { + Number: github.Ptr(43), + Title: github.Ptr("Test PR 2"), + Body: github.Ptr("Updated build scripts."), + State: github.Ptr("open"), + HTMLURL: github.Ptr("https://github.com/owner/repo/pull/2"), + Comments: github.Ptr(3), + User: &github.User{ + Login: github.Ptr("user2"), + }, + }, + }, + } + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]interface{} + expectError bool + expectedResult *github.IssuesSearchResult + expectedErrMsg string + }{ + { + name: "successful pull request search with all parameters", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchIssues, + expectQueryParams( + t, + map[string]string{ + "q": "is:pr repo:owner/repo is:open", + "sort": "created", + "order": "desc", + "page": "1", + "per_page": "30", + }, + ).andThen( + mockResponse(t, http.StatusOK, mockSearchResult), + ), + ), + ), + requestArgs: map[string]interface{}{ + "query": "repo:owner/repo is:open", + "sort": "created", + "order": "desc", + "page": float64(1), + "perPage": float64(30), + }, + expectError: false, + expectedResult: mockSearchResult, + }, + { + name: "pull request search with owner and repo parameters", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchIssues, + expectQueryParams( + t, + map[string]string{ + "q": "repo:test-owner/test-repo is:pr draft:false", + "sort": "updated", + "order": "asc", + "page": "1", + "per_page": "30", + }, + ).andThen( + mockResponse(t, http.StatusOK, mockSearchResult), + ), + ), + ), + requestArgs: map[string]interface{}{ + "query": "draft:false", + "owner": "test-owner", + "repo": "test-repo", + "sort": "updated", + "order": "asc", + }, + expectError: false, + expectedResult: mockSearchResult, + }, + { + name: "pull request search with only owner parameter (should ignore it)", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchIssues, + expectQueryParams( + t, + map[string]string{ + "q": "is:pr feature", + "page": "1", + "per_page": "30", + }, + ).andThen( + mockResponse(t, http.StatusOK, mockSearchResult), + ), + ), + ), + requestArgs: map[string]interface{}{ + "query": "feature", + "owner": "test-owner", + }, + expectError: false, + expectedResult: mockSearchResult, + }, + { + name: "pull request search with only repo parameter (should ignore it)", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchIssues, + expectQueryParams( + t, + map[string]string{ + "q": "is:pr review-required", + "page": "1", + "per_page": "30", + }, + ).andThen( + mockResponse(t, http.StatusOK, mockSearchResult), + ), + ), + ), + requestArgs: map[string]interface{}{ + "query": "review-required", + "repo": "test-repo", + }, + expectError: false, + expectedResult: mockSearchResult, + }, + { + name: "pull request search with minimal parameters", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatch( + mock.GetSearchIssues, + mockSearchResult, + ), + ), + requestArgs: map[string]interface{}{ + "query": "is:pr repo:owner/repo is:open", + }, + expectError: false, + expectedResult: mockSearchResult, + }, + { + name: "search pull requests fails", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchIssues, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusBadRequest) + _, _ = w.Write([]byte(`{"message": "Validation Failed"}`)) + }), + ), + ), + requestArgs: map[string]interface{}{ + "query": "invalid:query", + }, + expectError: true, + expectedErrMsg: "failed to search pull requests", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := SearchPullRequests(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + // Verify results + if tc.expectError { + require.Error(t, err) + assert.Contains(t, err.Error(), tc.expectedErrMsg) + return + } + + require.NoError(t, err) + + // Parse the result and get the text content if no error + textContent := getTextResult(t, result) + + // Unmarshal and verify the result + var returnedResult github.IssuesSearchResult + err = json.Unmarshal([]byte(textContent.Text), &returnedResult) + require.NoError(t, err) + assert.Equal(t, *tc.expectedResult.Total, *returnedResult.Total) + assert.Equal(t, *tc.expectedResult.IncompleteResults, *returnedResult.IncompleteResults) + assert.Len(t, returnedResult.Issues, len(tc.expectedResult.Issues)) + for i, issue := range returnedResult.Issues { + assert.Equal(t, *tc.expectedResult.Issues[i].Number, *issue.Number) + assert.Equal(t, *tc.expectedResult.Issues[i].Title, *issue.Title) + assert.Equal(t, *tc.expectedResult.Issues[i].State, *issue.State) + assert.Equal(t, *tc.expectedResult.Issues[i].HTMLURL, *issue.HTMLURL) + assert.Equal(t, *tc.expectedResult.Issues[i].User.Login, *issue.User.Login) + } + }) + } + +} + func Test_GetPullRequestFiles(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetPullRequestFiles(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_pull_request_files", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "owner") assert.Contains(t, tool.InputSchema.Properties, "repo") assert.Contains(t, tool.InputSchema.Properties, "pullNumber") + assert.Contains(t, tool.InputSchema.Properties, "page") + assert.Contains(t, tool.InputSchema.Properties, "perPage") assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "pullNumber"}) // Setup mock PR files for success case @@ -608,6 +859,24 @@ func Test_GetPullRequestFiles(t *testing.T) { expectError: false, expectedFiles: mockFiles, }, + { + name: "successful files fetch with pagination", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatch( + mock.GetReposPullsFilesByOwnerByRepoByPullNumber, + mockFiles, + ), + ), + requestArgs: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + "pullNumber": float64(42), + "page": float64(2), + "perPage": float64(10), + }, + expectError: false, + expectedFiles: mockFiles, + }, { name: "files fetch fails", mockedClient: mock.NewMockedHTTPClient( @@ -643,12 +912,15 @@ func Test_GetPullRequestFiles(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -672,6 +944,7 @@ func Test_GetPullRequestStatus(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetPullRequestStatus(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_pull_request_status", tool.Name) assert.NotEmpty(t, tool.Description) @@ -803,12 +1076,15 @@ func Test_GetPullRequestStatus(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -833,6 +1109,7 @@ func Test_UpdatePullRequestBranch(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := UpdatePullRequestBranch(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "update_pull_request_branch", tool.Name) assert.NotEmpty(t, tool.Description) @@ -930,12 +1207,15 @@ func Test_UpdatePullRequestBranch(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -949,6 +1229,7 @@ func Test_GetPullRequestComments(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetPullRequestComments(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_pull_request_comments", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1046,12 +1327,15 @@ func Test_GetPullRequestComments(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -1076,6 +1360,7 @@ func Test_GetPullRequestReviews(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetPullRequestReviews(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_pull_request_reviews", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1169,12 +1454,15 @@ func Test_GetPullRequestReviews(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -1199,6 +1487,7 @@ func Test_CreatePullRequest(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := CreatePullRequest(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "create_pull_request", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1358,6 +1647,7 @@ func TestCreateAndSubmitPullRequestReview(t *testing.T) { // Verify tool definition once mockClient := githubv4.NewClient(nil) tool, _ := CreateAndSubmitPullRequestReview(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "create_and_submit_pull_request_review", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1551,6 +1841,7 @@ func Test_RequestCopilotReview(t *testing.T) { mockClient := github.NewClient(nil) tool, _ := RequestCopilotReview(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "request_copilot_review", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1640,12 +1931,15 @@ func Test_RequestCopilotReview(t *testing.T) { result, err := handler(context.Background(), request) if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) assert.NotNil(t, result) assert.Len(t, result.Content, 1) @@ -1661,6 +1955,7 @@ func TestCreatePendingPullRequestReview(t *testing.T) { // Verify tool definition once mockClient := githubv4.NewClient(nil) tool, _ := CreatePendingPullRequestReview(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "create_pending_pull_request_review", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1842,9 +2137,10 @@ func TestAddPullRequestReviewCommentToPendingReview(t *testing.T) { // Verify tool definition once mockClient := githubv4.NewClient(nil) - tool, _ := AddPullRequestReviewCommentToPendingReview(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper) + tool, _ := AddCommentToPendingReview(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) - assert.Equal(t, "add_pull_request_review_comment_to_pending_review", tool.Name) + assert.Equal(t, "add_comment_to_pending_review", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "owner") assert.Contains(t, tool.InputSchema.Properties, "repo") @@ -1926,7 +2222,7 @@ func TestAddPullRequestReviewCommentToPendingReview(t *testing.T) { // Setup client with mock client := githubv4.NewClient(tc.mockedClient) - _, handler := AddPullRequestReviewCommentToPendingReview(stubGetGQLClientFn(client), translations.NullTranslationHelper) + _, handler := AddCommentToPendingReview(stubGetGQLClientFn(client), translations.NullTranslationHelper) // Create call request request := createMCPRequest(tc.requestArgs) @@ -1955,6 +2251,7 @@ func TestSubmitPendingPullRequestReview(t *testing.T) { // Verify tool definition once mockClient := githubv4.NewClient(nil) tool, _ := SubmitPendingPullRequestReview(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "submit_pending_pull_request_review", tool.Name) assert.NotEmpty(t, tool.Description) @@ -2052,6 +2349,7 @@ func TestDeletePendingPullRequestReview(t *testing.T) { // Verify tool definition once mockClient := githubv4.NewClient(nil) tool, _ := DeletePendingPullRequestReview(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "delete_pending_pull_request_review", tool.Name) assert.NotEmpty(t, tool.Description) @@ -2143,6 +2441,7 @@ func TestGetPullRequestDiff(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetPullRequestDiff(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_pull_request_diff", tool.Name) assert.NotEmpty(t, tool.Description) diff --git a/pkg/github/repositories.go b/pkg/github/repositories.go index 4403e2a19..2e56c8644 100644 --- a/pkg/github/repositories.go +++ b/pkg/github/repositories.go @@ -2,13 +2,18 @@ package github import ( "context" + "encoding/base64" "encoding/json" "fmt" "io" "net/http" + "net/url" + "strings" + ghErrors "github.com/github/github-mcp-server/pkg/errors" + "github.com/github/github-mcp-server/pkg/raw" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) @@ -18,7 +23,7 @@ func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc) (too mcp.WithDescription(t("TOOL_GET_COMMITS_DESCRIPTION", "Get details for a commit from a GitHub repository")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_COMMITS_USER_TITLE", "Get commit details"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -35,15 +40,15 @@ func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc) (too WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - sha, err := requiredParam[string](request, "sha") + sha, err := RequiredParam[string](request, "sha") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -63,7 +68,11 @@ func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc) (too } commit, resp, err := client.Repositories.GetCommit(ctx, owner, repo, sha, opts) if err != nil { - return nil, fmt.Errorf("failed to get commit: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to get commit: %s", sha), + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -87,10 +96,10 @@ func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc) (too // ListCommits creates a tool to get commits of a branch in a repository. func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { return mcp.NewTool("list_commits", - mcp.WithDescription(t("TOOL_LIST_COMMITS_DESCRIPTION", "Get list of commits of a branch in a GitHub repository")), + mcp.WithDescription(t("TOOL_LIST_COMMITS_DESCRIPTION", "Get list of commits of a branch in a GitHub repository. Returns at least 30 results per page by default, but can return more if specified using the perPage parameter (up to 100).")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_LIST_COMMITS_USER_TITLE", "List commits"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -101,16 +110,19 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t mcp.Description("Repository name"), ), mcp.WithString("sha", - mcp.Description("SHA or Branch name"), + mcp.Description("Commit SHA, branch or tag name to list commits of. If not provided, uses the default branch of the repository. If a commit SHA is provided, will list commits up to that SHA."), + ), + mcp.WithString("author", + mcp.Description("Author username or email address to filter commits by"), ), WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -118,16 +130,25 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t if err != nil { return mcp.NewToolResultError(err.Error()), nil } + author, err := OptionalParam[string](request, "author") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } pagination, err := OptionalPaginationParams(request) if err != nil { return mcp.NewToolResultError(err.Error()), nil } - + // Set default perPage to 30 if not provided + perPage := pagination.perPage + if perPage == 0 { + perPage = 30 + } opts := &github.CommitsListOptions{ - SHA: sha, + SHA: sha, + Author: author, ListOptions: github.ListOptions{ Page: pagination.page, - PerPage: pagination.perPage, + PerPage: perPage, }, } @@ -137,7 +158,11 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t } commits, resp, err := client.Repositories.ListCommits(ctx, owner, repo, opts) if err != nil { - return nil, fmt.Errorf("failed to list commits: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to list commits: %s", sha), + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -164,7 +189,7 @@ func ListBranches(getClient GetClientFn, t translations.TranslationHelperFunc) ( mcp.WithDescription(t("TOOL_LIST_BRANCHES_DESCRIPTION", "List branches in a GitHub repository")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_LIST_BRANCHES_USER_TITLE", "List branches"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -177,11 +202,11 @@ func ListBranches(getClient GetClientFn, t translations.TranslationHelperFunc) ( WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -204,7 +229,11 @@ func ListBranches(getClient GetClientFn, t translations.TranslationHelperFunc) ( branches, resp, err := client.Repositories.ListBranches(ctx, owner, repo, opts) if err != nil { - return nil, fmt.Errorf("failed to list branches: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to list branches", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -228,10 +257,10 @@ func ListBranches(getClient GetClientFn, t translations.TranslationHelperFunc) ( // CreateOrUpdateFile creates a tool to create or update a file in a GitHub repository. func CreateOrUpdateFile(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { return mcp.NewTool("create_or_update_file", - mcp.WithDescription(t("TOOL_CREATE_OR_UPDATE_FILE_DESCRIPTION", "Create or update a single file in a GitHub repository. If updating, you must provide the SHA of the file you want to update.")), + mcp.WithDescription(t("TOOL_CREATE_OR_UPDATE_FILE_DESCRIPTION", "Create or update a single file in a GitHub repository. If updating, you must provide the SHA of the file you want to update. Use this tool to create or update a file in a GitHub repository remotely; do not use it for local file operations.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_CREATE_OR_UPDATE_FILE_USER_TITLE", "Create or update file"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -258,31 +287,31 @@ func CreateOrUpdateFile(getClient GetClientFn, t translations.TranslationHelperF mcp.Description("Branch to create/update the file in"), ), mcp.WithString("sha", - mcp.Description("SHA of file being replaced (for updates)"), + mcp.Description("Required if updating an existing file. The blob SHA of the file being replaced."), ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - path, err := requiredParam[string](request, "path") + path, err := RequiredParam[string](request, "path") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - content, err := requiredParam[string](request, "content") + content, err := RequiredParam[string](request, "content") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - message, err := requiredParam[string](request, "message") + message, err := RequiredParam[string](request, "message") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - branch, err := requiredParam[string](request, "branch") + branch, err := RequiredParam[string](request, "branch") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -313,7 +342,11 @@ func CreateOrUpdateFile(getClient GetClientFn, t translations.TranslationHelperF } fileContent, resp, err := client.Repositories.CreateFile(ctx, owner, repo, path, opts) if err != nil { - return nil, fmt.Errorf("failed to create/update file: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to create/update file", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -340,7 +373,7 @@ func CreateRepository(getClient GetClientFn, t translations.TranslationHelperFun mcp.WithDescription(t("TOOL_CREATE_REPOSITORY_DESCRIPTION", "Create a new GitHub repository in your account")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_CREATE_REPOSITORY_USER_TITLE", "Create repository"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("name", mcp.Required(), @@ -357,7 +390,7 @@ func CreateRepository(getClient GetClientFn, t translations.TranslationHelperFun ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - name, err := requiredParam[string](request, "name") + name, err := RequiredParam[string](request, "name") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -387,7 +420,11 @@ func CreateRepository(getClient GetClientFn, t translations.TranslationHelperFun } createdRepo, resp, err := client.Repositories.Create(ctx, "", repo) if err != nil { - return nil, fmt.Errorf("failed to create repository: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to create repository", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -409,12 +446,12 @@ func CreateRepository(getClient GetClientFn, t translations.TranslationHelperFun } // GetFileContents creates a tool to get the contents of a file or directory from a GitHub repository. -func GetFileContents(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { +func GetFileContents(getClient GetClientFn, getRawClient raw.GetRawClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { return mcp.NewTool("get_file_contents", mcp.WithDescription(t("TOOL_GET_FILE_CONTENTS_DESCRIPTION", "Get the contents of a file or directory from a GitHub repository")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_FILE_CONTENTS_USER_TITLE", "Get file or directory contents"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -425,63 +462,182 @@ func GetFileContents(getClient GetClientFn, t translations.TranslationHelperFunc mcp.Description("Repository name"), ), mcp.WithString("path", - mcp.Required(), - mcp.Description("Path to file/directory"), + mcp.Description("Path to file/directory (directories must end with a slash '/')"), + mcp.DefaultString("/"), ), - mcp.WithString("branch", - mcp.Description("Branch to get contents from"), + mcp.WithString("ref", + mcp.Description("Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head`"), + ), + mcp.WithString("sha", + mcp.Description("Accepts optional commit SHA. If specified, it will be used instead of ref"), ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - path, err := requiredParam[string](request, "path") + path, err := RequiredParam[string](request, "path") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - branch, err := OptionalParam[string](request, "branch") + ref, err := OptionalParam[string](request, "ref") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + sha, err := OptionalParam[string](request, "sha") if err != nil { return mcp.NewToolResultError(err.Error()), nil } client, err := getClient(ctx) if err != nil { - return nil, fmt.Errorf("failed to get GitHub client: %w", err) + return mcp.NewToolResultError("failed to get GitHub client"), nil } - opts := &github.RepositoryContentGetOptions{Ref: branch} - fileContent, dirContent, resp, err := client.Repositories.GetContents(ctx, owner, repo, path, opts) + + rawOpts, err := resolveGitReference(ctx, client, owner, repo, ref, sha) if err != nil { - return nil, fmt.Errorf("failed to get file contents: %w", err) + return mcp.NewToolResultError(fmt.Sprintf("failed to resolve git reference: %s", err)), nil } - defer func() { _ = resp.Body.Close() }() - if resp.StatusCode != 200 { - body, err := io.ReadAll(resp.Body) + // If the path is (most likely) not to be a directory, we will + // first try to get the raw content from the GitHub raw content API. + if path != "" && !strings.HasSuffix(path, "/") { + // First, get file info from Contents API to retrieve SHA + var fileSHA string + opts := &github.RepositoryContentGetOptions{Ref: ref} + fileContent, _, respContents, err := client.Repositories.GetContents(ctx, owner, repo, path, opts) + if respContents != nil { + defer func() { _ = respContents.Body.Close() }() + } if err != nil { - return nil, fmt.Errorf("failed to read response body: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get file SHA", + respContents, + err, + ), nil + } + if fileContent == nil || fileContent.SHA == nil { + return mcp.NewToolResultError("file content SHA is nil"), nil + } + fileSHA = *fileContent.SHA + + rawClient, err := getRawClient(ctx) + if err != nil { + return mcp.NewToolResultError("failed to get GitHub raw content client"), nil + } + resp, err := rawClient.GetRawContent(ctx, owner, repo, path, rawOpts) + if err != nil { + return mcp.NewToolResultError("failed to get raw repository content"), nil + } + defer func() { + _ = resp.Body.Close() + }() + + if resp.StatusCode == http.StatusOK { + // If the raw content is found, return it directly + body, err := io.ReadAll(resp.Body) + if err != nil { + return mcp.NewToolResultError("failed to read response body"), nil + } + contentType := resp.Header.Get("Content-Type") + + var resourceURI string + switch { + case sha != "": + resourceURI, err = url.JoinPath("repo://", owner, repo, "sha", sha, "contents", path) + if err != nil { + return nil, fmt.Errorf("failed to create resource URI: %w", err) + } + case ref != "": + resourceURI, err = url.JoinPath("repo://", owner, repo, ref, "contents", path) + if err != nil { + return nil, fmt.Errorf("failed to create resource URI: %w", err) + } + default: + resourceURI, err = url.JoinPath("repo://", owner, repo, "contents", path) + if err != nil { + return nil, fmt.Errorf("failed to create resource URI: %w", err) + } + } + + if strings.HasPrefix(contentType, "application") || strings.HasPrefix(contentType, "text") { + result := mcp.TextResourceContents{ + URI: resourceURI, + Text: string(body), + MIMEType: contentType, + } + // Include SHA in the result metadata + if fileSHA != "" { + return mcp.NewToolResultResource(fmt.Sprintf("successfully downloaded text file (SHA: %s)", fileSHA), result), nil + } + return mcp.NewToolResultResource("successfully downloaded text file", result), nil + } + + result := mcp.BlobResourceContents{ + URI: resourceURI, + Blob: base64.StdEncoding.EncodeToString(body), + MIMEType: contentType, + } + // Include SHA in the result metadata + if fileSHA != "" { + return mcp.NewToolResultResource(fmt.Sprintf("successfully downloaded binary file (SHA: %s)", fileSHA), result), nil + } + return mcp.NewToolResultResource("successfully downloaded binary file", result), nil + } - return mcp.NewToolResultError(fmt.Sprintf("failed to get file contents: %s", string(body))), nil } - var result interface{} - if fileContent != nil { - result = fileContent - } else { - result = dirContent + if rawOpts.SHA != "" { + ref = rawOpts.SHA } + if strings.HasSuffix(path, "/") { + opts := &github.RepositoryContentGetOptions{Ref: ref} + _, dirContent, resp, err := client.Repositories.GetContents(ctx, owner, repo, path, opts) + if err == nil && resp.StatusCode == http.StatusOK { + defer func() { _ = resp.Body.Close() }() + r, err := json.Marshal(dirContent) + if err != nil { + return mcp.NewToolResultError("failed to marshal response"), nil + } + return mcp.NewToolResultText(string(r)), nil + } + } + + // The path does not point to a file or directory. + // Instead let's try to find it in the Git Tree by matching the end of the path. - r, err := json.Marshal(result) + // Step 1: Get Git Tree recursively + tree, resp, err := client.Git.GetTree(ctx, owner, repo, ref, true) if err != nil { - return nil, fmt.Errorf("failed to marshal response: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get git tree", + resp, + err, + ), nil } + defer func() { _ = resp.Body.Close() }() - return mcp.NewToolResultText(string(r)), nil + // Step 2: Filter tree for matching paths + const maxMatchingFiles = 3 + matchingFiles := filterPaths(tree.Entries, path, maxMatchingFiles) + if len(matchingFiles) > 0 { + matchingFilesJSON, err := json.Marshal(matchingFiles) + if err != nil { + return mcp.NewToolResultError(fmt.Sprintf("failed to marshal matching files: %s", err)), nil + } + resolvedRefs, err := json.Marshal(rawOpts) + if err != nil { + return mcp.NewToolResultError(fmt.Sprintf("failed to marshal resolved refs: %s", err)), nil + } + return mcp.NewToolResultText(fmt.Sprintf("Path did not point to a file or directory, but resolved git ref to %s with possible path matches: %s", resolvedRefs, matchingFilesJSON)), nil + } + + return mcp.NewToolResultError("Failed to get file contents. The path does not point to a file or directory, or the file does not exist in the repository."), nil } } @@ -491,7 +647,7 @@ func ForkRepository(getClient GetClientFn, t translations.TranslationHelperFunc) mcp.WithDescription(t("TOOL_FORK_REPOSITORY_DESCRIPTION", "Fork a GitHub repository to your account or specified organization")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_FORK_REPOSITORY_USER_TITLE", "Fork repository"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -506,11 +662,11 @@ func ForkRepository(getClient GetClientFn, t translations.TranslationHelperFunc) ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -535,7 +691,11 @@ func ForkRepository(getClient GetClientFn, t translations.TranslationHelperFunc) if resp != nil && resp.StatusCode == http.StatusAccepted && isAcceptedError(err) { return mcp.NewToolResultText("Fork is in progress"), nil } - return nil, fmt.Errorf("failed to fork repository: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to fork repository", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -567,8 +727,8 @@ func DeleteFile(getClient GetClientFn, t translations.TranslationHelperFunc) (to mcp.WithDescription(t("TOOL_DELETE_FILE_DESCRIPTION", "Delete a file from a GitHub repository")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_DELETE_FILE_USER_TITLE", "Delete file"), - ReadOnlyHint: toBoolPtr(false), - DestructiveHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(false), + DestructiveHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -592,23 +752,23 @@ func DeleteFile(getClient GetClientFn, t translations.TranslationHelperFunc) (to ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - path, err := requiredParam[string](request, "path") + path, err := RequiredParam[string](request, "path") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - message, err := requiredParam[string](request, "message") + message, err := RequiredParam[string](request, "message") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - branch, err := requiredParam[string](request, "branch") + branch, err := RequiredParam[string](request, "branch") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -628,7 +788,11 @@ func DeleteFile(getClient GetClientFn, t translations.TranslationHelperFunc) (to // Get the commit object that the branch points to baseCommit, resp, err := client.Git.GetCommit(ctx, owner, repo, *ref.Object.SHA) if err != nil { - return nil, fmt.Errorf("failed to get base commit: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get base commit", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -653,7 +817,11 @@ func DeleteFile(getClient GetClientFn, t translations.TranslationHelperFunc) (to // Create a new tree with the deletion newTree, resp, err := client.Git.CreateTree(ctx, owner, repo, *baseCommit.Tree.SHA, treeEntries) if err != nil { - return nil, fmt.Errorf("failed to create tree: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to create tree", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -673,7 +841,11 @@ func DeleteFile(getClient GetClientFn, t translations.TranslationHelperFunc) (to } newCommit, resp, err := client.Git.CreateCommit(ctx, owner, repo, commit, nil) if err != nil { - return nil, fmt.Errorf("failed to create commit: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to create commit", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -689,7 +861,11 @@ func DeleteFile(getClient GetClientFn, t translations.TranslationHelperFunc) (to ref.Object.SHA = newCommit.SHA _, resp, err = client.Git.UpdateRef(ctx, owner, repo, ref, false) if err != nil { - return nil, fmt.Errorf("failed to update reference: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to update reference", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -722,7 +898,7 @@ func CreateBranch(getClient GetClientFn, t translations.TranslationHelperFunc) ( mcp.WithDescription(t("TOOL_CREATE_BRANCH_DESCRIPTION", "Create a new branch in a GitHub repository")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_CREATE_BRANCH_USER_TITLE", "Create branch"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -741,15 +917,15 @@ func CreateBranch(getClient GetClientFn, t translations.TranslationHelperFunc) ( ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - branch, err := requiredParam[string](request, "branch") + branch, err := RequiredParam[string](request, "branch") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -770,7 +946,11 @@ func CreateBranch(getClient GetClientFn, t translations.TranslationHelperFunc) ( // Get default branch if from_branch not specified repository, resp, err := client.Repositories.Get(ctx, owner, repo) if err != nil { - return nil, fmt.Errorf("failed to get repository: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get repository", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -780,7 +960,11 @@ func CreateBranch(getClient GetClientFn, t translations.TranslationHelperFunc) ( // Get SHA of source branch ref, resp, err := client.Git.GetRef(ctx, owner, repo, "refs/heads/"+fromBranch) if err != nil { - return nil, fmt.Errorf("failed to get reference: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get reference", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -792,7 +976,11 @@ func CreateBranch(getClient GetClientFn, t translations.TranslationHelperFunc) ( createdRef, resp, err := client.Git.CreateRef(ctx, owner, repo, newRef) if err != nil { - return nil, fmt.Errorf("failed to create branch: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to create branch", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -811,7 +999,7 @@ func PushFiles(getClient GetClientFn, t translations.TranslationHelperFunc) (too mcp.WithDescription(t("TOOL_PUSH_FILES_DESCRIPTION", "Push multiple files to a GitHub repository in a single commit")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_PUSH_FILES_USER_TITLE", "Push files to repository"), - ReadOnlyHint: toBoolPtr(false), + ReadOnlyHint: ToBoolPtr(false), }), mcp.WithString("owner", mcp.Required(), @@ -851,25 +1039,25 @@ func PushFiles(getClient GetClientFn, t translations.TranslationHelperFunc) (too ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - branch, err := requiredParam[string](request, "branch") + branch, err := RequiredParam[string](request, "branch") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - message, err := requiredParam[string](request, "message") + message, err := RequiredParam[string](request, "message") if err != nil { return mcp.NewToolResultError(err.Error()), nil } // Parse files parameter - this should be an array of objects with path and content - filesObj, ok := request.Params.Arguments["files"].([]interface{}) + filesObj, ok := request.GetArguments()["files"].([]interface{}) if !ok { return mcp.NewToolResultError("files parameter must be an array of objects with path and content"), nil } @@ -882,14 +1070,22 @@ func PushFiles(getClient GetClientFn, t translations.TranslationHelperFunc) (too // Get the reference for the branch ref, resp, err := client.Git.GetRef(ctx, owner, repo, "refs/heads/"+branch) if err != nil { - return nil, fmt.Errorf("failed to get branch reference: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get branch reference", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() // Get the commit object that the branch points to baseCommit, resp, err := client.Git.GetCommit(ctx, owner, repo, *ref.Object.SHA) if err != nil { - return nil, fmt.Errorf("failed to get base commit: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get base commit", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -924,7 +1120,11 @@ func PushFiles(getClient GetClientFn, t translations.TranslationHelperFunc) (too // Create a new tree with the file entries newTree, resp, err := client.Git.CreateTree(ctx, owner, repo, *baseCommit.Tree.SHA, entries) if err != nil { - return nil, fmt.Errorf("failed to create tree: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to create tree", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -936,7 +1136,11 @@ func PushFiles(getClient GetClientFn, t translations.TranslationHelperFunc) (too } newCommit, resp, err := client.Git.CreateCommit(ctx, owner, repo, commit, nil) if err != nil { - return nil, fmt.Errorf("failed to create commit: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to create commit", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -944,7 +1148,11 @@ func PushFiles(getClient GetClientFn, t translations.TranslationHelperFunc) (too ref.Object.SHA = newCommit.SHA updatedRef, resp, err := client.Git.UpdateRef(ctx, owner, repo, ref, false) if err != nil { - return nil, fmt.Errorf("failed to update reference: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to update reference", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -963,7 +1171,7 @@ func ListTags(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.WithDescription(t("TOOL_LIST_TAGS_DESCRIPTION", "List git tags in a GitHub repository")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_LIST_TAGS_USER_TITLE", "List tags"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -976,11 +1184,11 @@ func ListTags(getClient GetClientFn, t translations.TranslationHelperFunc) (tool WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -1001,7 +1209,11 @@ func ListTags(getClient GetClientFn, t translations.TranslationHelperFunc) (tool tags, resp, err := client.Repositories.ListTags(ctx, owner, repo, opts) if err != nil { - return nil, fmt.Errorf("failed to list tags: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to list tags", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -1028,7 +1240,7 @@ func GetTag(getClient GetClientFn, t translations.TranslationHelperFunc) (tool m mcp.WithDescription(t("TOOL_GET_TAG_DESCRIPTION", "Get details about a specific git tag in a GitHub repository")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_TAG_USER_TITLE", "Get tag details"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -1044,15 +1256,15 @@ func GetTag(getClient GetClientFn, t translations.TranslationHelperFunc) (tool m ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - tag, err := requiredParam[string](request, "tag") + tag, err := RequiredParam[string](request, "tag") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -1065,7 +1277,11 @@ func GetTag(getClient GetClientFn, t translations.TranslationHelperFunc) (tool m // First get the tag reference ref, resp, err := client.Git.GetRef(ctx, owner, repo, "refs/tags/"+tag) if err != nil { - return nil, fmt.Errorf("failed to get tag reference: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get tag reference", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -1080,7 +1296,11 @@ func GetTag(getClient GetClientFn, t translations.TranslationHelperFunc) (tool m // Then get the tag object tagObj, resp, err := client.Git.GetTag(ctx, owner, repo, *ref.Object.SHA) if err != nil { - return nil, fmt.Errorf("failed to get tag object: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + "failed to get tag object", + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -1100,3 +1320,74 @@ func GetTag(getClient GetClientFn, t translations.TranslationHelperFunc) (tool m return mcp.NewToolResultText(string(r)), nil } } + +// filterPaths filters the entries in a GitHub tree to find paths that +// match the given suffix. +// maxResults limits the number of results returned to first maxResults entries, +// a maxResults of -1 means no limit. +// It returns a slice of strings containing the matching paths. +// Directories are returned with a trailing slash. +func filterPaths(entries []*github.TreeEntry, path string, maxResults int) []string { + // Remove trailing slash for matching purposes, but flag whether we + // only want directories. + dirOnly := false + if strings.HasSuffix(path, "/") { + dirOnly = true + path = strings.TrimSuffix(path, "/") + } + + matchedPaths := []string{} + for _, entry := range entries { + if len(matchedPaths) == maxResults { + break // Limit the number of results to maxResults + } + if dirOnly && entry.GetType() != "tree" { + continue // Skip non-directory entries if dirOnly is true + } + entryPath := entry.GetPath() + if entryPath == "" { + continue // Skip empty paths + } + if strings.HasSuffix(entryPath, path) { + if entry.GetType() == "tree" { + entryPath += "/" // Return directories with a trailing slash + } + matchedPaths = append(matchedPaths, entryPath) + } + } + return matchedPaths +} + +// resolveGitReference resolves git references with the following logic: +// 1. If SHA is provided, it takes precedence +// 2. If neither is provided, use the default branch as ref +// 3. Get commit SHA from the ref +// Refs can look like `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` +// The function returns the resolved ref, commit SHA and any error. +func resolveGitReference(ctx context.Context, githubClient *github.Client, owner, repo, ref, sha string) (*raw.ContentOpts, error) { + // 1. If SHA is provided, use it directly + if sha != "" { + return &raw.ContentOpts{Ref: "", SHA: sha}, nil + } + + // 2. If neither provided, use the default branch as ref + if ref == "" { + repoInfo, resp, err := githubClient.Repositories.Get(ctx, owner, repo) + if err != nil { + _, _ = ghErrors.NewGitHubAPIErrorToCtx(ctx, "failed to get repository info", resp, err) + return nil, fmt.Errorf("failed to get repository info: %w", err) + } + ref = fmt.Sprintf("refs/heads/%s", repoInfo.GetDefaultBranch()) + } + + // 3. Get the SHA from the ref + reference, resp, err := githubClient.Git.GetRef(ctx, owner, repo, ref) + if err != nil { + _, _ = ghErrors.NewGitHubAPIErrorToCtx(ctx, "failed to get reference", resp, err) + return nil, fmt.Errorf("failed to get reference: %w", err) + } + sha = reference.GetObject().GetSHA() + + // Use provided ref, or it will be empty which defaults to the default branch + return &raw.ContentOpts{Ref: ref, SHA: sha}, nil +} diff --git a/pkg/github/repositories_test.go b/pkg/github/repositories_test.go index e4edeee88..1572a12f4 100644 --- a/pkg/github/repositories_test.go +++ b/pkg/github/repositories_test.go @@ -2,13 +2,18 @@ package github import ( "context" + "encoding/base64" "encoding/json" "net/http" + "net/url" "testing" "time" + "github.com/github/github-mcp-server/internal/toolsnaps" + "github.com/github/github-mcp-server/pkg/raw" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" + "github.com/mark3labs/mcp-go/mcp" "github.com/migueleliasweb/go-github-mock/src/mock" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -17,27 +22,21 @@ import ( func Test_GetFileContents(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) - tool, _ := GetFileContents(stubGetClientFn(mockClient), translations.NullTranslationHelper) + mockRawClient := raw.NewClient(mockClient, &url.URL{Scheme: "https", Host: "raw.githubusercontent.com", Path: "/"}) + tool, _ := GetFileContents(stubGetClientFn(mockClient), stubGetRawClientFn(mockRawClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_file_contents", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "owner") assert.Contains(t, tool.InputSchema.Properties, "repo") assert.Contains(t, tool.InputSchema.Properties, "path") - assert.Contains(t, tool.InputSchema.Properties, "branch") - assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo", "path"}) - - // Setup mock file content for success case - mockFileContent := &github.RepositoryContent{ - Type: github.Ptr("file"), - Name: github.Ptr("README.md"), - Path: github.Ptr("README.md"), - Content: github.Ptr("IyBUZXN0IFJlcG9zaXRvcnkKClRoaXMgaXMgYSB0ZXN0IHJlcG9zaXRvcnku"), // Base64 encoded "# Test Repository\n\nThis is a test repository." - SHA: github.Ptr("abc123"), - Size: github.Ptr(42), - HTMLURL: github.Ptr("https://github.com/owner/repo/blob/main/README.md"), - DownloadURL: github.Ptr("https://raw.githubusercontent.com/owner/repo/main/README.md"), - } + assert.Contains(t, tool.InputSchema.Properties, "ref") + assert.Contains(t, tool.InputSchema.Properties, "sha") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"}) + + // Mock response for raw content + mockRawContent := []byte("# Test Repository\n\nThis is a test repository.") // Setup mock directory content for success case mockDirContent := []*github.RepositoryContent{ @@ -65,42 +64,134 @@ func Test_GetFileContents(t *testing.T) { expectError bool expectedResult interface{} expectedErrMsg string + expectStatus int }{ { - name: "successful file content fetch", + name: "successful text content fetch", mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposGitRefByOwnerByRepoByRef, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`)) + }), + ), mock.WithRequestMatchHandler( mock.GetReposContentsByOwnerByRepoByPath, - expectQueryParams(t, map[string]string{ - "ref": "main", - }).andThen( - mockResponse(t, http.StatusOK, mockFileContent), - ), + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + fileContent := &github.RepositoryContent{ + Name: github.Ptr("README.md"), + Path: github.Ptr("README.md"), + SHA: github.Ptr("abc123"), + Type: github.Ptr("file"), + } + contentBytes, _ := json.Marshal(fileContent) + _, _ = w.Write(contentBytes) + }), + ), + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoByBranchByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "text/markdown") + _, _ = w.Write(mockRawContent) + }), ), ), requestArgs: map[string]interface{}{ - "owner": "owner", - "repo": "repo", - "path": "README.md", - "branch": "main", + "owner": "owner", + "repo": "repo", + "path": "README.md", + "ref": "refs/heads/main", + }, + expectError: false, + expectedResult: mcp.TextResourceContents{ + URI: "repo://owner/repo/refs/heads/main/contents/README.md", + Text: "# Test Repository\n\nThis is a test repository.", + MIMEType: "text/markdown", + }, + }, + { + name: "successful file blob content fetch", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposGitRefByOwnerByRepoByRef, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`)) + }), + ), + mock.WithRequestMatchHandler( + mock.GetReposContentsByOwnerByRepoByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + fileContent := &github.RepositoryContent{ + Name: github.Ptr("test.png"), + Path: github.Ptr("test.png"), + SHA: github.Ptr("def456"), + Type: github.Ptr("file"), + } + contentBytes, _ := json.Marshal(fileContent) + _, _ = w.Write(contentBytes) + }), + ), + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoByBranchByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "image/png") + _, _ = w.Write(mockRawContent) + }), + ), + ), + requestArgs: map[string]interface{}{ + "owner": "owner", + "repo": "repo", + "path": "test.png", + "ref": "refs/heads/main", + }, + expectError: false, + expectedResult: mcp.BlobResourceContents{ + URI: "repo://owner/repo/refs/heads/main/contents/test.png", + Blob: base64.StdEncoding.EncodeToString(mockRawContent), + MIMEType: "image/png", }, - expectError: false, - expectedResult: mockFileContent, }, { name: "successful directory content fetch", mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposByOwnerByRepo, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(`{"name": "repo", "default_branch": "main"}`)) + }), + ), + mock.WithRequestMatchHandler( + mock.GetReposGitRefByOwnerByRepoByRef, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`)) + }), + ), mock.WithRequestMatchHandler( mock.GetReposContentsByOwnerByRepoByPath, expectQueryParams(t, map[string]string{}).andThen( mockResponse(t, http.StatusOK, mockDirContent), ), ), + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoByPath, + expectQueryParams(t, map[string]string{ + "branch": "main", + }).andThen( + mockResponse(t, http.StatusNotFound, nil), + ), + ), ), requestArgs: map[string]interface{}{ "owner": "owner", "repo": "repo", - "path": "src", + "path": "src/", }, expectError: false, expectedResult: mockDirContent, @@ -108,6 +199,13 @@ func Test_GetFileContents(t *testing.T) { { name: "content fetch fails", mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposGitRefByOwnerByRepoByRef, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": ""}}`)) + }), + ), mock.WithRequestMatchHandler( mock.GetReposContentsByOwnerByRepoByPath, http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { @@ -115,15 +213,22 @@ func Test_GetFileContents(t *testing.T) { _, _ = w.Write([]byte(`{"message": "Not Found"}`)) }), ), + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusNotFound) + _, _ = w.Write([]byte(`{"message": "Not Found"}`)) + }), + ), ), requestArgs: map[string]interface{}{ - "owner": "owner", - "repo": "repo", - "path": "nonexistent.md", - "branch": "main", + "owner": "owner", + "repo": "repo", + "path": "nonexistent.md", + "ref": "refs/heads/main", }, - expectError: true, - expectedErrMsg: "failed to get file contents", + expectError: false, + expectedResult: mcp.NewToolResultError("Failed to get file contents. The path does not point to a file or directory, or the file does not exist in the repository."), }, } @@ -131,7 +236,8 @@ func Test_GetFileContents(t *testing.T) { t.Run(tc.name, func(t *testing.T) { // Setup client with mock client := github.NewClient(tc.mockedClient) - _, handler := GetFileContents(stubGetClientFn(client), translations.NullTranslationHelper) + mockRawClient := raw.NewClient(client, &url.URL{Scheme: "https", Host: "raw.example.com", Path: "/"}) + _, handler := GetFileContents(stubGetClientFn(client), stubGetRawClientFn(mockRawClient), translations.NullTranslationHelper) // Create call request request := createMCPRequest(tc.requestArgs) @@ -147,29 +253,29 @@ func Test_GetFileContents(t *testing.T) { } require.NoError(t, err) - - // Parse the result and get the text content if no error - textContent := getTextResult(t, result) - - // Verify based on expected type + // Use the correct result helper based on the expected type switch expected := tc.expectedResult.(type) { - case *github.RepositoryContent: - var returnedContent github.RepositoryContent - err = json.Unmarshal([]byte(textContent.Text), &returnedContent) - require.NoError(t, err) - assert.Equal(t, *expected.Name, *returnedContent.Name) - assert.Equal(t, *expected.Path, *returnedContent.Path) - assert.Equal(t, *expected.Type, *returnedContent.Type) + case mcp.TextResourceContents: + textResource := getTextResourceResult(t, result) + assert.Equal(t, expected, textResource) + case mcp.BlobResourceContents: + blobResource := getBlobResourceResult(t, result) + assert.Equal(t, expected, blobResource) case []*github.RepositoryContent: + // Directory content fetch returns a text result (JSON array) + textContent := getTextResult(t, result) var returnedContents []*github.RepositoryContent err = json.Unmarshal([]byte(textContent.Text), &returnedContents) - require.NoError(t, err) + require.NoError(t, err, "Failed to unmarshal directory content result: %v", textContent.Text) assert.Len(t, returnedContents, len(expected)) for i, content := range returnedContents { assert.Equal(t, *expected[i].Name, *content.Name) assert.Equal(t, *expected[i].Path, *content.Path) assert.Equal(t, *expected[i].Type, *content.Type) } + case mcp.TextContent: + textContent := getErrorResult(t, result) + require.Equal(t, textContent, expected) } }) } @@ -179,6 +285,7 @@ func Test_ForkRepository(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := ForkRepository(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "fork_repository", tool.Name) assert.NotEmpty(t, tool.Description) @@ -258,12 +365,15 @@ func Test_ForkRepository(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -277,6 +387,7 @@ func Test_CreateBranch(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := CreateBranch(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "create_branch", tool.Name) assert.NotEmpty(t, tool.Description) @@ -444,12 +555,15 @@ func Test_CreateBranch(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -468,6 +582,7 @@ func Test_GetCommit(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetCommit(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_commit", tool.Name) assert.NotEmpty(t, tool.Description) @@ -566,12 +681,15 @@ func Test_GetCommit(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -593,12 +711,14 @@ func Test_ListCommits(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := ListCommits(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "list_commits", tool.Name) assert.NotEmpty(t, tool.Description) assert.Contains(t, tool.InputSchema.Properties, "owner") assert.Contains(t, tool.InputSchema.Properties, "repo") assert.Contains(t, tool.InputSchema.Properties, "sha") + assert.Contains(t, tool.InputSchema.Properties, "author") assert.Contains(t, tool.InputSchema.Properties, "page") assert.Contains(t, tool.InputSchema.Properties, "perPage") assert.ElementsMatch(t, tool.InputSchema.Required, []string{"owner", "repo"}) @@ -666,6 +786,7 @@ func Test_ListCommits(t *testing.T) { mock.WithRequestMatchHandler( mock.GetReposCommitsByOwnerByRepo, expectQueryParams(t, map[string]string{ + "author": "username", "sha": "main", "page": "1", "per_page": "30", @@ -675,9 +796,10 @@ func Test_ListCommits(t *testing.T) { ), ), requestArgs: map[string]interface{}{ - "owner": "owner", - "repo": "repo", - "sha": "main", + "owner": "owner", + "repo": "repo", + "sha": "main", + "author": "username", }, expectError: false, expectedCommits: mockCommits, @@ -738,12 +860,15 @@ func Test_ListCommits(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -754,6 +879,7 @@ func Test_ListCommits(t *testing.T) { require.NoError(t, err) assert.Len(t, returnedCommits, len(tc.expectedCommits)) for i, commit := range returnedCommits { + assert.Equal(t, *tc.expectedCommits[i].Author, *commit.Author) assert.Equal(t, *tc.expectedCommits[i].SHA, *commit.SHA) assert.Equal(t, *tc.expectedCommits[i].Commit.Message, *commit.Commit.Message) assert.Equal(t, *tc.expectedCommits[i].Author.Login, *commit.Author.Login) @@ -767,6 +893,7 @@ func Test_CreateOrUpdateFile(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := CreateOrUpdateFile(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "create_or_update_file", tool.Name) assert.NotEmpty(t, tool.Description) @@ -899,12 +1026,15 @@ func Test_CreateOrUpdateFile(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -930,6 +1060,7 @@ func Test_CreateRepository(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := CreateRepository(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "create_repository", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1047,12 +1178,15 @@ func Test_CreateRepository(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -1076,6 +1210,7 @@ func Test_PushFiles(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := PushFiles(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "push_files", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1380,19 +1515,23 @@ func Test_PushFiles(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } if tc.expectedErrMsg != "" { require.NotNil(t, result) - textContent := getTextResult(t, result) - assert.Contains(t, textContent.Text, tc.expectedErrMsg) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -1412,6 +1551,7 @@ func Test_ListBranches(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := ListBranches(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "list_branches", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1522,6 +1662,7 @@ func Test_DeleteFile(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := DeleteFile(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "delete_file", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1699,6 +1840,7 @@ func Test_ListTags(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := ListTags(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "list_tags", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1790,12 +1932,15 @@ func Test_ListTags(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -1819,6 +1964,7 @@ func Test_GetTag(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := GetTag(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "get_tag", tool.Name) assert.NotEmpty(t, tool.Description) @@ -1940,12 +2086,15 @@ func Test_GetTag(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -1963,3 +2112,170 @@ func Test_GetTag(t *testing.T) { }) } } + +func Test_filterPaths(t *testing.T) { + tests := []struct { + name string + tree []*github.TreeEntry + path string + maxResults int + expected []string + }{ + { + name: "file name", + tree: []*github.TreeEntry{ + {Path: github.Ptr("folder/foo.txt"), Type: github.Ptr("blob")}, + {Path: github.Ptr("bar.txt"), Type: github.Ptr("blob")}, + {Path: github.Ptr("nested/folder/foo.txt"), Type: github.Ptr("blob")}, + {Path: github.Ptr("nested/folder/baz.txt"), Type: github.Ptr("blob")}, + }, + path: "foo.txt", + maxResults: -1, + expected: []string{"folder/foo.txt", "nested/folder/foo.txt"}, + }, + { + name: "dir name", + tree: []*github.TreeEntry{ + {Path: github.Ptr("folder"), Type: github.Ptr("tree")}, + {Path: github.Ptr("bar.txt"), Type: github.Ptr("blob")}, + {Path: github.Ptr("nested/folder"), Type: github.Ptr("tree")}, + {Path: github.Ptr("nested/folder/baz.txt"), Type: github.Ptr("blob")}, + }, + path: "folder/", + maxResults: -1, + expected: []string{"folder/", "nested/folder/"}, + }, + { + name: "dir and file match", + tree: []*github.TreeEntry{ + {Path: github.Ptr("name"), Type: github.Ptr("tree")}, + {Path: github.Ptr("name"), Type: github.Ptr("blob")}, + }, + path: "name", // No trailing slash can match both files and directories + maxResults: -1, + expected: []string{"name/", "name"}, + }, + { + name: "dir only match", + tree: []*github.TreeEntry{ + {Path: github.Ptr("name"), Type: github.Ptr("tree")}, + {Path: github.Ptr("name"), Type: github.Ptr("blob")}, + }, + path: "name/", // Trialing slash ensures only directories are matched + maxResults: -1, + expected: []string{"name/"}, + }, + { + name: "max results limit 2", + tree: []*github.TreeEntry{ + {Path: github.Ptr("folder"), Type: github.Ptr("tree")}, + {Path: github.Ptr("nested/folder"), Type: github.Ptr("tree")}, + {Path: github.Ptr("nested/nested/folder"), Type: github.Ptr("tree")}, + }, + path: "folder/", + maxResults: 2, + expected: []string{"folder/", "nested/folder/"}, + }, + { + name: "max results limit 1", + tree: []*github.TreeEntry{ + {Path: github.Ptr("folder"), Type: github.Ptr("tree")}, + {Path: github.Ptr("nested/folder"), Type: github.Ptr("tree")}, + {Path: github.Ptr("nested/nested/folder"), Type: github.Ptr("tree")}, + }, + path: "folder/", + maxResults: 1, + expected: []string{"folder/"}, + }, + { + name: "max results limit 0", + tree: []*github.TreeEntry{ + {Path: github.Ptr("folder"), Type: github.Ptr("tree")}, + {Path: github.Ptr("nested/folder"), Type: github.Ptr("tree")}, + {Path: github.Ptr("nested/nested/folder"), Type: github.Ptr("tree")}, + }, + path: "folder/", + maxResults: 0, + expected: []string{}, + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + result := filterPaths(tc.tree, tc.path, tc.maxResults) + assert.Equal(t, tc.expected, result) + }) + } +} + +func Test_resolveGitReference(t *testing.T) { + ctx := context.Background() + owner := "owner" + repo := "repo" + mockedClient := mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetReposByOwnerByRepo, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(`{"name": "repo", "default_branch": "main"}`)) + }), + ), + mock.WithRequestMatchHandler( + mock.GetReposGitRefByOwnerByRepoByRef, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(`{"ref": "refs/heads/main", "object": {"sha": "123sha456"}}`)) + }), + ), + ) + + tests := []struct { + name string + ref string + sha string + expectedOutput *raw.ContentOpts + }{ + { + name: "sha takes precedence over ref", + ref: "refs/heads/main", + sha: "123sha456", + expectedOutput: &raw.ContentOpts{ + SHA: "123sha456", + }, + }, + { + name: "use default branch if ref and sha both empty", + ref: "", + sha: "", + expectedOutput: &raw.ContentOpts{ + Ref: "refs/heads/main", + SHA: "123sha456", + }, + }, + { + name: "get SHA from ref", + ref: "refs/heads/main", + sha: "", + expectedOutput: &raw.ContentOpts{ + Ref: "refs/heads/main", + SHA: "123sha456", + }, + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(mockedClient) + opts, err := resolveGitReference(ctx, client, owner, repo, tc.ref, tc.sha) + require.NoError(t, err) + + if tc.expectedOutput.SHA != "" { + assert.Equal(t, tc.expectedOutput.SHA, opts.SHA) + } + if tc.expectedOutput.Ref != "" { + assert.Equal(t, tc.expectedOutput.Ref, opts.Ref) + } + }) + } +} diff --git a/pkg/github/repository_resource.go b/pkg/github/repository_resource.go index 949157f55..70ca6ba65 100644 --- a/pkg/github/repository_resource.go +++ b/pkg/github/repository_resource.go @@ -9,61 +9,63 @@ import ( "mime" "net/http" "path/filepath" + "strconv" "strings" + "github.com/github/github-mcp-server/pkg/raw" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) // GetRepositoryResourceContent defines the resource template and handler for getting repository content. -func GetRepositoryResourceContent(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { +func GetRepositoryResourceContent(getClient GetClientFn, getRawClient raw.GetRawClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { return mcp.NewResourceTemplate( "repo://{owner}/{repo}/contents{/path*}", // Resource template t("RESOURCE_REPOSITORY_CONTENT_DESCRIPTION", "Repository Content"), ), - RepositoryResourceContentsHandler(getClient) + RepositoryResourceContentsHandler(getClient, getRawClient) } // GetRepositoryResourceBranchContent defines the resource template and handler for getting repository content for a branch. -func GetRepositoryResourceBranchContent(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { +func GetRepositoryResourceBranchContent(getClient GetClientFn, getRawClient raw.GetRawClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { return mcp.NewResourceTemplate( "repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*}", // Resource template t("RESOURCE_REPOSITORY_CONTENT_BRANCH_DESCRIPTION", "Repository Content for specific branch"), ), - RepositoryResourceContentsHandler(getClient) + RepositoryResourceContentsHandler(getClient, getRawClient) } // GetRepositoryResourceCommitContent defines the resource template and handler for getting repository content for a commit. -func GetRepositoryResourceCommitContent(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { +func GetRepositoryResourceCommitContent(getClient GetClientFn, getRawClient raw.GetRawClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { return mcp.NewResourceTemplate( "repo://{owner}/{repo}/sha/{sha}/contents{/path*}", // Resource template t("RESOURCE_REPOSITORY_CONTENT_COMMIT_DESCRIPTION", "Repository Content for specific commit"), ), - RepositoryResourceContentsHandler(getClient) + RepositoryResourceContentsHandler(getClient, getRawClient) } // GetRepositoryResourceTagContent defines the resource template and handler for getting repository content for a tag. -func GetRepositoryResourceTagContent(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { +func GetRepositoryResourceTagContent(getClient GetClientFn, getRawClient raw.GetRawClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { return mcp.NewResourceTemplate( "repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*}", // Resource template t("RESOURCE_REPOSITORY_CONTENT_TAG_DESCRIPTION", "Repository Content for specific tag"), ), - RepositoryResourceContentsHandler(getClient) + RepositoryResourceContentsHandler(getClient, getRawClient) } // GetRepositoryResourcePrContent defines the resource template and handler for getting repository content for a pull request. -func GetRepositoryResourcePrContent(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { +func GetRepositoryResourcePrContent(getClient GetClientFn, getRawClient raw.GetRawClientFn, t translations.TranslationHelperFunc) (mcp.ResourceTemplate, server.ResourceTemplateHandlerFunc) { return mcp.NewResourceTemplate( "repo://{owner}/{repo}/refs/pull/{prNumber}/head/contents{/path*}", // Resource template t("RESOURCE_REPOSITORY_CONTENT_PR_DESCRIPTION", "Repository Content for specific pull request"), ), - RepositoryResourceContentsHandler(getClient) + RepositoryResourceContentsHandler(getClient, getRawClient) } // RepositoryResourceContentsHandler returns a handler function for repository content requests. -func RepositoryResourceContentsHandler(getClient GetClientFn) func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) { +func RepositoryResourceContentsHandler(getClient GetClientFn, getRawClient raw.GetRawClientFn) func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) { return func(ctx context.Context, request mcp.ReadResourceRequest) ([]mcp.ResourceContents, error) { // the matcher will give []string with one element // https://github.com/mark3labs/mcp-go/pull/54 @@ -87,120 +89,104 @@ func RepositoryResourceContentsHandler(getClient GetClientFn) func(ctx context.C } opts := &github.RepositoryContentGetOptions{} + rawOpts := &raw.ContentOpts{} sha, ok := request.Params.Arguments["sha"].([]string) if ok && len(sha) > 0 { opts.Ref = sha[0] + rawOpts.SHA = sha[0] } branch, ok := request.Params.Arguments["branch"].([]string) if ok && len(branch) > 0 { opts.Ref = "refs/heads/" + branch[0] + rawOpts.Ref = "refs/heads/" + branch[0] } tag, ok := request.Params.Arguments["tag"].([]string) if ok && len(tag) > 0 { opts.Ref = "refs/tags/" + tag[0] + rawOpts.Ref = "refs/tags/" + tag[0] } prNumber, ok := request.Params.Arguments["prNumber"].([]string) if ok && len(prNumber) > 0 { - opts.Ref = "refs/pull/" + prNumber[0] + "/head" + // fetch the PR from the API to get the latest commit and use SHA + githubClient, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } + prNum, err := strconv.Atoi(prNumber[0]) + if err != nil { + return nil, fmt.Errorf("invalid pull request number: %w", err) + } + pr, _, err := githubClient.PullRequests.Get(ctx, owner, repo, prNum) + if err != nil { + return nil, fmt.Errorf("failed to get pull request: %w", err) + } + sha := pr.GetHead().GetSHA() + rawOpts.SHA = sha + opts.Ref = sha } - - client, err := getClient(ctx) - if err != nil { - return nil, fmt.Errorf("failed to get GitHub client: %w", err) + // if it's a directory + if path == "" || strings.HasSuffix(path, "/") { + return nil, fmt.Errorf("directories are not supported: %s", path) } - fileContent, directoryContent, _, err := client.Repositories.GetContents(ctx, owner, repo, path, opts) + rawClient, err := getRawClient(ctx) + if err != nil { - return nil, err + return nil, fmt.Errorf("failed to get GitHub raw content client: %w", err) } - if directoryContent != nil { - var resources []mcp.ResourceContents - for _, entry := range directoryContent { - mimeType := "text/directory" - if entry.GetType() == "file" { - // this is system dependent, and a best guess - ext := filepath.Ext(entry.GetName()) - mimeType = mime.TypeByExtension(ext) - if ext == ".md" { - mimeType = "text/markdown" - } - } - resources = append(resources, mcp.TextResourceContents{ - URI: entry.GetHTMLURL(), - MIMEType: mimeType, - Text: entry.GetName(), - }) - + resp, err := rawClient.GetRawContent(ctx, owner, repo, path, rawOpts) + defer func() { + _ = resp.Body.Close() + }() + // If the raw content is not found, we will fall back to the GitHub API (in case it is a directory) + switch { + case err != nil: + return nil, fmt.Errorf("failed to get raw content: %w", err) + case resp.StatusCode == http.StatusOK: + ext := filepath.Ext(path) + mimeType := resp.Header.Get("Content-Type") + if ext == ".md" { + mimeType = "text/markdown" + } else if mimeType == "" { + mimeType = mime.TypeByExtension(ext) } - return resources, nil - } - if fileContent != nil { - if fileContent.Content != nil { - // download the file content from fileContent.GetDownloadURL() and use the content-type header to determine the MIME type - // and return the content as a blob unless it is a text file, where you can return the content as text - req, err := http.NewRequest("GET", fileContent.GetDownloadURL(), nil) - if err != nil { - return nil, fmt.Errorf("failed to create request: %w", err) - } - - resp, err := client.Client().Do(req) - if err != nil { - return nil, fmt.Errorf("failed to send request: %w", err) - } - defer func() { _ = resp.Body.Close() }() - - if resp.StatusCode != http.StatusOK { - body, err := io.ReadAll(resp.Body) - if err != nil { - return nil, fmt.Errorf("failed to read response body: %w", err) - } - return nil, fmt.Errorf("failed to fetch file content: %s", string(body)) - } - - ext := filepath.Ext(fileContent.GetName()) - mimeType := resp.Header.Get("Content-Type") - if ext == ".md" { - mimeType = "text/markdown" - } else if mimeType == "" { - // backstop to the file extension if the content type is not set - mimeType = mime.TypeByExtension(filepath.Ext(fileContent.GetName())) - } - - // if the content is a string, return it as text - if strings.HasPrefix(mimeType, "text") { - content, err := io.ReadAll(resp.Body) - if err != nil { - return nil, fmt.Errorf("failed to parse the response body: %w", err) - } - - return []mcp.ResourceContents{ - mcp.TextResourceContents{ - URI: request.Params.URI, - MIMEType: mimeType, - Text: string(content), - }, - }, nil - } - // otherwise, read the content and encode it as base64 - decodedContent, err := io.ReadAll(resp.Body) - if err != nil { - return nil, fmt.Errorf("failed to parse the response body: %w", err) - } + content, err := io.ReadAll(resp.Body) + if err != nil { + return nil, fmt.Errorf("failed to read file content: %w", err) + } + switch { + case strings.HasPrefix(mimeType, "text"), strings.HasPrefix(mimeType, "application"): + return []mcp.ResourceContents{ + mcp.TextResourceContents{ + URI: request.Params.URI, + MIMEType: mimeType, + Text: string(content), + }, + }, nil + default: return []mcp.ResourceContents{ mcp.BlobResourceContents{ URI: request.Params.URI, MIMEType: mimeType, - Blob: base64.StdEncoding.EncodeToString(decodedContent), // Encode content as Base64 + Blob: base64.StdEncoding.EncodeToString(content), }, }, nil } + case resp.StatusCode != http.StatusNotFound: + // If we got a response but it is not 200 OK, we return an error + body, err := io.ReadAll(resp.Body) + if err != nil { + return nil, fmt.Errorf("failed to read response body: %w", err) + } + return nil, fmt.Errorf("failed to fetch raw content: %s", string(body)) + default: + // This should be unreachable because GetContents should return an error if neither file nor directory content is found. + return nil, errors.New("404 Not Found") } - - return nil, errors.New("no repository resource content found") } } diff --git a/pkg/github/repository_resource_test.go b/pkg/github/repository_resource_test.go index ffd14be32..2e3e911a9 100644 --- a/pkg/github/repository_resource_test.go +++ b/pkg/github/repository_resource_test.go @@ -3,105 +3,37 @@ package github import ( "context" "net/http" + "net/url" "testing" + "github.com/github/github-mcp-server/pkg/raw" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/migueleliasweb/go-github-mock/src/mock" "github.com/stretchr/testify/require" ) -var GetRawReposContentsByOwnerByRepoByPath mock.EndpointPattern = mock.EndpointPattern{ - Pattern: "/{owner}/{repo}/main/{path:.+}", - Method: "GET", -} - func Test_repositoryResourceContentsHandler(t *testing.T) { - mockDirContent := []*github.RepositoryContent{ - { - Type: github.Ptr("file"), - Name: github.Ptr("README.md"), - Path: github.Ptr("README.md"), - SHA: github.Ptr("abc123"), - Size: github.Ptr(42), - HTMLURL: github.Ptr("https://github.com/owner/repo/blob/main/README.md"), - DownloadURL: github.Ptr("https://raw.githubusercontent.com/owner/repo/main/README.md"), - }, - { - Type: github.Ptr("dir"), - Name: github.Ptr("src"), - Path: github.Ptr("src"), - SHA: github.Ptr("def456"), - HTMLURL: github.Ptr("https://github.com/owner/repo/tree/main/src"), - DownloadURL: github.Ptr("https://raw.githubusercontent.com/owner/repo/main/src"), - }, - } - expectedDirContent := []mcp.TextResourceContents{ - { - URI: "https://github.com/owner/repo/blob/main/README.md", - MIMEType: "text/markdown", - Text: "README.md", - }, - { - URI: "https://github.com/owner/repo/tree/main/src", - MIMEType: "text/directory", - Text: "src", - }, - } - - mockTextContent := &github.RepositoryContent{ - Type: github.Ptr("file"), - Name: github.Ptr("README.md"), - Path: github.Ptr("README.md"), - Content: github.Ptr("# Test Repository\n\nThis is a test repository."), - SHA: github.Ptr("abc123"), - Size: github.Ptr(42), - HTMLURL: github.Ptr("https://github.com/owner/repo/blob/main/README.md"), - DownloadURL: github.Ptr("https://raw.githubusercontent.com/owner/repo/main/README.md"), - } - - mockFileContent := &github.RepositoryContent{ - Type: github.Ptr("file"), - Name: github.Ptr("data.png"), - Path: github.Ptr("data.png"), - Content: github.Ptr("IyBUZXN0IFJlcG9zaXRvcnkKClRoaXMgaXMgYSB0ZXN0IHJlcG9zaXRvcnku"), // Base64 encoded "# Test Repository\n\nThis is a test repository." - SHA: github.Ptr("abc123"), - Size: github.Ptr(42), - HTMLURL: github.Ptr("https://github.com/owner/repo/blob/main/data.png"), - DownloadURL: github.Ptr("https://raw.githubusercontent.com/owner/repo/main/data.png"), - } - - expectedFileContent := []mcp.BlobResourceContents{ - { - Blob: "IyBUZXN0IFJlcG9zaXRvcnkKClRoaXMgaXMgYSB0ZXN0IHJlcG9zaXRvcnku", - MIMEType: "image/png", - URI: "", - }, - } - - expectedTextContent := []mcp.TextResourceContents{ - { - Text: "# Test Repository\n\nThis is a test repository.", - MIMEType: "text/markdown", - URI: "", - }, - } - + base, _ := url.Parse("https://raw.example.com/") tests := []struct { name string mockedClient *http.Client requestArgs map[string]any expectError string expectedResult any - expectedErrMsg string }{ { name: "missing owner", mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatch( - mock.GetReposContentsByOwnerByRepoByPath, - mockFileContent, + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "image/png") + // as this is given as a png, it will return the content as a blob + _, err := w.Write([]byte("# Test Repository\n\nThis is a test repository.")) + require.NoError(t, err) + }), ), ), requestArgs: map[string]any{}, @@ -110,9 +42,14 @@ func Test_repositoryResourceContentsHandler(t *testing.T) { { name: "missing repo", mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatch( - mock.GetReposContentsByOwnerByRepoByPath, - mockFileContent, + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoByBranchByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "image/png") + // as this is given as a png, it will return the content as a blob + _, err := w.Write([]byte("# Test Repository\n\nThis is a test repository.")) + require.NoError(t, err) + }), ), ), requestArgs: map[string]any{ @@ -123,38 +60,59 @@ func Test_repositoryResourceContentsHandler(t *testing.T) { { name: "successful blob content fetch", mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatch( - mock.GetReposContentsByOwnerByRepoByPath, - mockFileContent, - ), mock.WithRequestMatchHandler( - GetRawReposContentsByOwnerByRepoByPath, + raw.GetRawReposContentsByOwnerByRepoByPath, http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { w.Header().Set("Content-Type", "image/png") - // as this is given as a png, it will return the content as a blob _, err := w.Write([]byte("# Test Repository\n\nThis is a test repository.")) require.NoError(t, err) }), ), ), requestArgs: map[string]any{ - "owner": []string{"owner"}, - "repo": []string{"repo"}, - "path": []string{"data.png"}, - "branch": []string{"main"}, + "owner": []string{"owner"}, + "repo": []string{"repo"}, + "path": []string{"data.png"}, }, - expectedResult: expectedFileContent, + expectedResult: []mcp.BlobResourceContents{{ + Blob: "IyBUZXN0IFJlcG9zaXRvcnkKClRoaXMgaXMgYSB0ZXN0IHJlcG9zaXRvcnku", + MIMEType: "image/png", + URI: "", + }}, }, { - name: "successful text content fetch", + name: "successful text content fetch (HEAD)", mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatch( - mock.GetReposContentsByOwnerByRepoByPath, - mockTextContent, + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "text/markdown") + _, err := w.Write([]byte("# Test Repository\n\nThis is a test repository.")) + require.NoError(t, err) + }), ), - mock.WithRequestMatch( - GetRawReposContentsByOwnerByRepoByPath, - []byte("# Test Repository\n\nThis is a test repository."), + ), + requestArgs: map[string]any{ + "owner": []string{"owner"}, + "repo": []string{"repo"}, + "path": []string{"README.md"}, + }, + expectedResult: []mcp.TextResourceContents{{ + Text: "# Test Repository\n\nThis is a test repository.", + MIMEType: "text/markdown", + URI: "", + }}, + }, + { + name: "successful text content fetch (branch)", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoByBranchByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "text/markdown") + _, err := w.Write([]byte("# Test Repository\n\nThis is a test repository.")) + require.NoError(t, err) + }), ), ), requestArgs: map[string]any{ @@ -163,52 +121,91 @@ func Test_repositoryResourceContentsHandler(t *testing.T) { "path": []string{"README.md"}, "branch": []string{"main"}, }, - expectedResult: expectedTextContent, + expectedResult: []mcp.TextResourceContents{{ + Text: "# Test Repository\n\nThis is a test repository.", + MIMEType: "text/markdown", + URI: "", + }}, }, { - name: "successful directory content fetch", + name: "successful text content fetch (tag)", mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatch( - mock.GetReposContentsByOwnerByRepoByPath, - mockDirContent, + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoByTagByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "text/markdown") + _, err := w.Write([]byte("# Test Repository\n\nThis is a test repository.")) + require.NoError(t, err) + }), ), ), requestArgs: map[string]any{ "owner": []string{"owner"}, "repo": []string{"repo"}, - "path": []string{"src"}, + "path": []string{"README.md"}, + "tag": []string{"v1.0.0"}, }, - expectedResult: expectedDirContent, + expectedResult: []mcp.TextResourceContents{{ + Text: "# Test Repository\n\nThis is a test repository.", + MIMEType: "text/markdown", + URI: "", + }}, }, { - name: "no data", + name: "successful text content fetch (sha)", mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatch( - mock.GetReposContentsByOwnerByRepoByPath, + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoBySHAByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "text/markdown") + _, err := w.Write([]byte("# Test Repository\n\nThis is a test repository.")) + require.NoError(t, err) + }), ), ), requestArgs: map[string]any{ "owner": []string{"owner"}, "repo": []string{"repo"}, - "path": []string{"src"}, + "path": []string{"README.md"}, + "sha": []string{"abc123"}, }, - expectedResult: nil, - expectError: "no repository resource content found", + expectedResult: []mcp.TextResourceContents{{ + Text: "# Test Repository\n\nThis is a test repository.", + MIMEType: "text/markdown", + URI: "", + }}, }, { - name: "empty data", + name: "successful text content fetch (pr)", mockedClient: mock.NewMockedHTTPClient( - mock.WithRequestMatch( - mock.GetReposContentsByOwnerByRepoByPath, - []*github.RepositoryContent{}, + mock.WithRequestMatchHandler( + mock.GetReposPullsByOwnerByRepoByPullNumber, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "application/json") + _, err := w.Write([]byte(`{"head": {"sha": "abc123"}}`)) + require.NoError(t, err) + }), + ), + mock.WithRequestMatchHandler( + raw.GetRawReposContentsByOwnerByRepoBySHAByPath, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", "text/markdown") + _, err := w.Write([]byte("# Test Repository\n\nThis is a test repository.")) + require.NoError(t, err) + }), ), ), requestArgs: map[string]any{ - "owner": []string{"owner"}, - "repo": []string{"repo"}, - "path": []string{"src"}, + "owner": []string{"owner"}, + "repo": []string{"repo"}, + "path": []string{"README.md"}, + "prNumber": []string{"42"}, }, - expectedResult: nil, + expectedResult: []mcp.TextResourceContents{{ + Text: "# Test Repository\n\nThis is a test repository.", + MIMEType: "text/markdown", + URI: "", + }}, }, { name: "content fetch fails", @@ -234,7 +231,8 @@ func Test_repositoryResourceContentsHandler(t *testing.T) { for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { client := github.NewClient(tc.mockedClient) - handler := RepositoryResourceContentsHandler((stubGetClientFn(client))) + mockRawClient := raw.NewClient(client, base) + handler := RepositoryResourceContentsHandler((stubGetClientFn(client)), stubGetRawClientFn(mockRawClient)) request := mcp.ReadResourceRequest{ Params: struct { @@ -248,7 +246,7 @@ func Test_repositoryResourceContentsHandler(t *testing.T) { resp, err := handler(context.TODO(), request) if tc.expectError != "" { - require.ErrorContains(t, err, tc.expectedErrMsg) + require.ErrorContains(t, err, tc.expectError) return } @@ -259,25 +257,24 @@ func Test_repositoryResourceContentsHandler(t *testing.T) { } func Test_GetRepositoryResourceContent(t *testing.T) { - tmpl, _ := GetRepositoryResourceContent(nil, translations.NullTranslationHelper) + mockRawClient := raw.NewClient(github.NewClient(nil), &url.URL{}) + tmpl, _ := GetRepositoryResourceContent(nil, stubGetRawClientFn(mockRawClient), translations.NullTranslationHelper) require.Equal(t, "repo://{owner}/{repo}/contents{/path*}", tmpl.URITemplate.Raw()) } func Test_GetRepositoryResourceBranchContent(t *testing.T) { - tmpl, _ := GetRepositoryResourceBranchContent(nil, translations.NullTranslationHelper) + mockRawClient := raw.NewClient(github.NewClient(nil), &url.URL{}) + tmpl, _ := GetRepositoryResourceBranchContent(nil, stubGetRawClientFn(mockRawClient), translations.NullTranslationHelper) require.Equal(t, "repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*}", tmpl.URITemplate.Raw()) } func Test_GetRepositoryResourceCommitContent(t *testing.T) { - tmpl, _ := GetRepositoryResourceCommitContent(nil, translations.NullTranslationHelper) + mockRawClient := raw.NewClient(github.NewClient(nil), &url.URL{}) + tmpl, _ := GetRepositoryResourceCommitContent(nil, stubGetRawClientFn(mockRawClient), translations.NullTranslationHelper) require.Equal(t, "repo://{owner}/{repo}/sha/{sha}/contents{/path*}", tmpl.URITemplate.Raw()) } func Test_GetRepositoryResourceTagContent(t *testing.T) { - tmpl, _ := GetRepositoryResourceTagContent(nil, translations.NullTranslationHelper) + mockRawClient := raw.NewClient(github.NewClient(nil), &url.URL{}) + tmpl, _ := GetRepositoryResourceTagContent(nil, stubGetRawClientFn(mockRawClient), translations.NullTranslationHelper) require.Equal(t, "repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*}", tmpl.URITemplate.Raw()) } - -func Test_GetRepositoryResourcePrContent(t *testing.T) { - tmpl, _ := GetRepositoryResourcePrContent(nil, translations.NullTranslationHelper) - require.Equal(t, "repo://{owner}/{repo}/refs/pull/{prNumber}/head/contents{/path*}", tmpl.URITemplate.Raw()) -} diff --git a/pkg/github/resources.go b/pkg/github/resources.go deleted file mode 100644 index 774261e94..000000000 --- a/pkg/github/resources.go +++ /dev/null @@ -1,14 +0,0 @@ -package github - -import ( - "github.com/github/github-mcp-server/pkg/translations" - "github.com/mark3labs/mcp-go/server" -) - -func RegisterResources(s *server.MCPServer, getClient GetClientFn, t translations.TranslationHelperFunc) { - s.AddResourceTemplate(GetRepositoryResourceContent(getClient, t)) - s.AddResourceTemplate(GetRepositoryResourceBranchContent(getClient, t)) - s.AddResourceTemplate(GetRepositoryResourceCommitContent(getClient, t)) - s.AddResourceTemplate(GetRepositoryResourceTagContent(getClient, t)) - s.AddResourceTemplate(GetRepositoryResourcePrContent(getClient, t)) -} diff --git a/pkg/github/search.go b/pkg/github/search.go index ac5e2994c..04a1facc0 100644 --- a/pkg/github/search.go +++ b/pkg/github/search.go @@ -6,8 +6,9 @@ import ( "fmt" "io" + ghErrors "github.com/github/github-mcp-server/pkg/errors" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) @@ -18,7 +19,7 @@ func SearchRepositories(getClient GetClientFn, t translations.TranslationHelperF mcp.WithDescription(t("TOOL_SEARCH_REPOSITORIES_DESCRIPTION", "Search for GitHub repositories")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_SEARCH_REPOSITORIES_USER_TITLE", "Search repositories"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("query", mcp.Required(), @@ -27,7 +28,7 @@ func SearchRepositories(getClient GetClientFn, t translations.TranslationHelperF WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - query, err := requiredParam[string](request, "query") + query, err := RequiredParam[string](request, "query") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -49,7 +50,11 @@ func SearchRepositories(getClient GetClientFn, t translations.TranslationHelperF } result, resp, err := client.Search.Repositories(ctx, query, opts) if err != nil { - return nil, fmt.Errorf("failed to search repositories: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to search repositories with query '%s'", query), + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -76,7 +81,7 @@ func SearchCode(getClient GetClientFn, t translations.TranslationHelperFunc) (to mcp.WithDescription(t("TOOL_SEARCH_CODE_DESCRIPTION", "Search for code across GitHub repositories")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_SEARCH_CODE_USER_TITLE", "Search code"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("q", mcp.Required(), @@ -92,7 +97,7 @@ func SearchCode(getClient GetClientFn, t translations.TranslationHelperFunc) (to WithPagination(), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - query, err := requiredParam[string](request, "q") + query, err := RequiredParam[string](request, "q") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -125,7 +130,11 @@ func SearchCode(getClient GetClientFn, t translations.TranslationHelperFunc) (to result, resp, err := client.Search.Code(ctx, query, opts) if err != nil { - return nil, fmt.Errorf("failed to search code: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to search code with query '%s'", query), + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -146,79 +155,150 @@ func SearchCode(getClient GetClientFn, t translations.TranslationHelperFunc) (to } } -// SearchUsers creates a tool to search for GitHub users. -func SearchUsers(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { - return mcp.NewTool("search_users", - mcp.WithDescription(t("TOOL_SEARCH_USERS_DESCRIPTION", "Search for GitHub users")), - mcp.WithToolAnnotation(mcp.ToolAnnotation{ - Title: t("TOOL_SEARCH_USERS_USER_TITLE", "Search users"), - ReadOnlyHint: toBoolPtr(true), - }), - mcp.WithString("q", - mcp.Required(), - mcp.Description("Search query using GitHub users search syntax"), - ), - mcp.WithString("sort", - mcp.Description("Sort field by category"), - mcp.Enum("followers", "repositories", "joined"), - ), - mcp.WithString("order", - mcp.Description("Sort order"), - mcp.Enum("asc", "desc"), - ), - WithPagination(), - ), - func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - query, err := requiredParam[string](request, "q") - if err != nil { - return mcp.NewToolResultError(err.Error()), nil - } - sort, err := OptionalParam[string](request, "sort") - if err != nil { - return mcp.NewToolResultError(err.Error()), nil - } - order, err := OptionalParam[string](request, "order") - if err != nil { - return mcp.NewToolResultError(err.Error()), nil - } - pagination, err := OptionalPaginationParams(request) - if err != nil { - return mcp.NewToolResultError(err.Error()), nil - } +// MinimalUser is the output type for user and organization search results. +type MinimalUser struct { + Login string `json:"login"` + ID int64 `json:"id,omitempty"` + ProfileURL string `json:"profile_url,omitempty"` + AvatarURL string `json:"avatar_url,omitempty"` + Details *UserDetails `json:"details,omitempty"` // Optional field for additional user details +} - opts := &github.SearchOptions{ - Sort: sort, - Order: order, - ListOptions: github.ListOptions{ - PerPage: pagination.perPage, - Page: pagination.page, - }, - } +type MinimalSearchUsersResult struct { + TotalCount int `json:"total_count"` + IncompleteResults bool `json:"incomplete_results"` + Items []MinimalUser `json:"items"` +} - client, err := getClient(ctx) - if err != nil { - return nil, fmt.Errorf("failed to get GitHub client: %w", err) - } +func userOrOrgHandler(accountType string, getClient GetClientFn) server.ToolHandlerFunc { + return func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { + query, err := RequiredParam[string](request, "query") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + sort, err := OptionalParam[string](request, "sort") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + order, err := OptionalParam[string](request, "order") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + pagination, err := OptionalPaginationParams(request) + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + opts := &github.SearchOptions{ + Sort: sort, + Order: order, + ListOptions: github.ListOptions{ + PerPage: pagination.perPage, + Page: pagination.page, + }, + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("failed to get GitHub client: %w", err) + } - result, resp, err := client.Search.Users(ctx, query, opts) + searchQuery := "type:" + accountType + " " + query + result, resp, err := client.Search.Users(ctx, searchQuery, opts) + if err != nil { + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to search %ss with query '%s'", accountType, query), + resp, + err, + ), nil + } + defer func() { _ = resp.Body.Close() }() + + if resp.StatusCode != 200 { + body, err := io.ReadAll(resp.Body) if err != nil { - return nil, fmt.Errorf("failed to search users: %w", err) + return nil, fmt.Errorf("failed to read response body: %w", err) } - defer func() { _ = resp.Body.Close() }() + return mcp.NewToolResultError(fmt.Sprintf("failed to search %ss: %s", accountType, string(body))), nil + } - if resp.StatusCode != 200 { - body, err := io.ReadAll(resp.Body) - if err != nil { - return nil, fmt.Errorf("failed to read response body: %w", err) - } - return mcp.NewToolResultError(fmt.Sprintf("failed to search users: %s", string(body))), nil - } + minimalUsers := make([]MinimalUser, 0, len(result.Users)) - r, err := json.Marshal(result) - if err != nil { - return nil, fmt.Errorf("failed to marshal response: %w", err) + for _, user := range result.Users { + if user.Login != nil { + mu := MinimalUser{ + Login: user.GetLogin(), + ID: user.GetID(), + ProfileURL: user.GetHTMLURL(), + AvatarURL: user.GetAvatarURL(), + } + minimalUsers = append(minimalUsers, mu) } + } + minimalResp := &MinimalSearchUsersResult{ + TotalCount: result.GetTotal(), + IncompleteResults: result.GetIncompleteResults(), + Items: minimalUsers, + } + if result.Total != nil { + minimalResp.TotalCount = *result.Total + } + if result.IncompleteResults != nil { + minimalResp.IncompleteResults = *result.IncompleteResults + } - return mcp.NewToolResultText(string(r)), nil + r, err := json.Marshal(minimalResp) + if err != nil { + return nil, fmt.Errorf("failed to marshal response: %w", err) } + return mcp.NewToolResultText(string(r)), nil + } +} + +// SearchUsers creates a tool to search for GitHub users. +func SearchUsers(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("search_users", + mcp.WithDescription(t("TOOL_SEARCH_USERS_DESCRIPTION", "Search for GitHub users exclusively")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_SEARCH_USERS_USER_TITLE", "Search users"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("query", + mcp.Required(), + mcp.Description("Search query using GitHub users search syntax scoped to type:user"), + ), + mcp.WithString("sort", + mcp.Description("Sort field by category"), + mcp.Enum("followers", "repositories", "joined"), + ), + mcp.WithString("order", + mcp.Description("Sort order"), + mcp.Enum("asc", "desc"), + ), + WithPagination(), + ), userOrOrgHandler("user", getClient) +} + +// SearchOrgs creates a tool to search for GitHub organizations. +func SearchOrgs(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) { + return mcp.NewTool("search_orgs", + mcp.WithDescription(t("TOOL_SEARCH_ORGS_DESCRIPTION", "Search for GitHub organizations exclusively")), + mcp.WithToolAnnotation(mcp.ToolAnnotation{ + Title: t("TOOL_SEARCH_ORGS_USER_TITLE", "Search organizations"), + ReadOnlyHint: ToBoolPtr(true), + }), + mcp.WithString("query", + mcp.Required(), + mcp.Description("Search query using GitHub organizations search syntax scoped to type:org"), + ), + mcp.WithString("sort", + mcp.Description("Sort field by category"), + mcp.Enum("followers", "repositories", "joined"), + ), + mcp.WithString("order", + mcp.Description("Sort order"), + mcp.Enum("asc", "desc"), + ), + WithPagination(), + ), userOrOrgHandler("org", getClient) } diff --git a/pkg/github/search_test.go b/pkg/github/search_test.go index b61518e47..21f7a0ca2 100644 --- a/pkg/github/search_test.go +++ b/pkg/github/search_test.go @@ -6,8 +6,9 @@ import ( "net/http" "testing" + "github.com/github/github-mcp-server/internal/toolsnaps" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/migueleliasweb/go-github-mock/src/mock" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -17,6 +18,7 @@ func Test_SearchRepositories(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := SearchRepositories(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "search_repositories", tool.Name) assert.NotEmpty(t, tool.Description) @@ -132,12 +134,15 @@ func Test_SearchRepositories(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -164,6 +169,7 @@ func Test_SearchCode(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := SearchCode(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "search_code", tool.Name) assert.NotEmpty(t, tool.Description) @@ -283,12 +289,15 @@ func Test_SearchCode(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -315,15 +324,16 @@ func Test_SearchUsers(t *testing.T) { // Verify tool definition once mockClient := github.NewClient(nil) tool, _ := SearchUsers(stubGetClientFn(mockClient), translations.NullTranslationHelper) + require.NoError(t, toolsnaps.Test(tool.Name, tool)) assert.Equal(t, "search_users", tool.Name) assert.NotEmpty(t, tool.Description) - assert.Contains(t, tool.InputSchema.Properties, "q") + assert.Contains(t, tool.InputSchema.Properties, "query") assert.Contains(t, tool.InputSchema.Properties, "sort") assert.Contains(t, tool.InputSchema.Properties, "order") assert.Contains(t, tool.InputSchema.Properties, "perPage") assert.Contains(t, tool.InputSchema.Properties, "page") - assert.ElementsMatch(t, tool.InputSchema.Required, []string{"q"}) + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"query"}) // Setup mock search results mockSearchResult := &github.UsersSearchResult{ @@ -335,9 +345,6 @@ func Test_SearchUsers(t *testing.T) { ID: github.Ptr(int64(1001)), HTMLURL: github.Ptr("https://github.com/user1"), AvatarURL: github.Ptr("https://avatars.githubusercontent.com/u/1001"), - Type: github.Ptr("User"), - Followers: github.Ptr(100), - Following: github.Ptr(50), }, { Login: github.Ptr("user2"), @@ -345,8 +352,6 @@ func Test_SearchUsers(t *testing.T) { HTMLURL: github.Ptr("https://github.com/user2"), AvatarURL: github.Ptr("https://avatars.githubusercontent.com/u/1002"), Type: github.Ptr("User"), - Followers: github.Ptr(200), - Following: github.Ptr(75), }, }, } @@ -365,7 +370,7 @@ func Test_SearchUsers(t *testing.T) { mock.WithRequestMatchHandler( mock.GetSearchUsers, expectQueryParams(t, map[string]string{ - "q": "location:finland language:go", + "q": "type:user location:finland language:go", "sort": "followers", "order": "desc", "page": "1", @@ -376,7 +381,7 @@ func Test_SearchUsers(t *testing.T) { ), ), requestArgs: map[string]interface{}{ - "q": "location:finland language:go", + "query": "location:finland language:go", "sort": "followers", "order": "desc", "page": float64(1), @@ -391,7 +396,7 @@ func Test_SearchUsers(t *testing.T) { mock.WithRequestMatchHandler( mock.GetSearchUsers, expectQueryParams(t, map[string]string{ - "q": "location:finland language:go", + "q": "type:user location:finland language:go", "page": "1", "per_page": "30", }).andThen( @@ -400,7 +405,7 @@ func Test_SearchUsers(t *testing.T) { ), ), requestArgs: map[string]interface{}{ - "q": "location:finland language:go", + "query": "location:finland language:go", }, expectError: false, expectedResult: mockSearchResult, @@ -417,7 +422,7 @@ func Test_SearchUsers(t *testing.T) { ), ), requestArgs: map[string]interface{}{ - "q": "invalid:query", + "query": "invalid:query", }, expectError: true, expectedErrMsg: "failed to search users", @@ -438,12 +443,15 @@ func Test_SearchUsers(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error require.NotNil(t, result) @@ -451,19 +459,141 @@ func Test_SearchUsers(t *testing.T) { textContent := getTextResult(t, result) // Unmarshal and verify the result - var returnedResult github.UsersSearchResult + var returnedResult MinimalSearchUsersResult err = json.Unmarshal([]byte(textContent.Text), &returnedResult) require.NoError(t, err) - assert.Equal(t, *tc.expectedResult.Total, *returnedResult.Total) - assert.Equal(t, *tc.expectedResult.IncompleteResults, *returnedResult.IncompleteResults) - assert.Len(t, returnedResult.Users, len(tc.expectedResult.Users)) - for i, user := range returnedResult.Users { - assert.Equal(t, *tc.expectedResult.Users[i].Login, *user.Login) - assert.Equal(t, *tc.expectedResult.Users[i].ID, *user.ID) - assert.Equal(t, *tc.expectedResult.Users[i].HTMLURL, *user.HTMLURL) - assert.Equal(t, *tc.expectedResult.Users[i].AvatarURL, *user.AvatarURL) - assert.Equal(t, *tc.expectedResult.Users[i].Type, *user.Type) - assert.Equal(t, *tc.expectedResult.Users[i].Followers, *user.Followers) + assert.Equal(t, *tc.expectedResult.Total, returnedResult.TotalCount) + assert.Equal(t, *tc.expectedResult.IncompleteResults, returnedResult.IncompleteResults) + assert.Len(t, returnedResult.Items, len(tc.expectedResult.Users)) + for i, user := range returnedResult.Items { + assert.Equal(t, *tc.expectedResult.Users[i].Login, user.Login) + assert.Equal(t, *tc.expectedResult.Users[i].ID, user.ID) + assert.Equal(t, *tc.expectedResult.Users[i].HTMLURL, user.ProfileURL) + assert.Equal(t, *tc.expectedResult.Users[i].AvatarURL, user.AvatarURL) + } + }) + } +} + +func Test_SearchOrgs(t *testing.T) { + // Verify tool definition once + mockClient := github.NewClient(nil) + tool, _ := SearchOrgs(stubGetClientFn(mockClient), translations.NullTranslationHelper) + + assert.Equal(t, "search_orgs", tool.Name) + assert.NotEmpty(t, tool.Description) + assert.Contains(t, tool.InputSchema.Properties, "query") + assert.Contains(t, tool.InputSchema.Properties, "sort") + assert.Contains(t, tool.InputSchema.Properties, "order") + assert.Contains(t, tool.InputSchema.Properties, "perPage") + assert.Contains(t, tool.InputSchema.Properties, "page") + assert.ElementsMatch(t, tool.InputSchema.Required, []string{"query"}) + + // Setup mock search results + mockSearchResult := &github.UsersSearchResult{ + Total: github.Ptr(int(2)), + IncompleteResults: github.Ptr(false), + Users: []*github.User{ + { + Login: github.Ptr("org-1"), + ID: github.Ptr(int64(111)), + HTMLURL: github.Ptr("https://github.com/org-1"), + AvatarURL: github.Ptr("https://avatars.githubusercontent.com/u/111?v=4"), + }, + { + Login: github.Ptr("org-2"), + ID: github.Ptr(int64(222)), + HTMLURL: github.Ptr("https://github.com/org-2"), + AvatarURL: github.Ptr("https://avatars.githubusercontent.com/u/222?v=4"), + }, + }, + } + + tests := []struct { + name string + mockedClient *http.Client + requestArgs map[string]interface{} + expectError bool + expectedResult *github.UsersSearchResult + expectedErrMsg string + }{ + { + name: "successful org search", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchUsers, + expectQueryParams(t, map[string]string{ + "q": "type:org github", + "page": "1", + "per_page": "30", + }).andThen( + mockResponse(t, http.StatusOK, mockSearchResult), + ), + ), + ), + requestArgs: map[string]interface{}{ + "query": "github", + }, + expectError: false, + expectedResult: mockSearchResult, + }, + { + name: "org search fails", + mockedClient: mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + mock.GetSearchUsers, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.WriteHeader(http.StatusBadRequest) + _, _ = w.Write([]byte(`{"message": "Validation Failed"}`)) + }), + ), + ), + requestArgs: map[string]interface{}{ + "query": "invalid:query", + }, + expectError: true, + expectedErrMsg: "failed to search orgs", + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + // Setup client with mock + client := github.NewClient(tc.mockedClient) + _, handler := SearchOrgs(stubGetClientFn(client), translations.NullTranslationHelper) + + // Create call request + request := createMCPRequest(tc.requestArgs) + + // Call handler + result, err := handler(context.Background(), request) + + // Verify results + if tc.expectError { + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) + return + } + + require.NoError(t, err) + require.NotNil(t, result) + + textContent := getTextResult(t, result) + + // Unmarshal and verify the result + var returnedResult MinimalSearchUsersResult + err = json.Unmarshal([]byte(textContent.Text), &returnedResult) + require.NoError(t, err) + assert.Equal(t, *tc.expectedResult.Total, returnedResult.TotalCount) + assert.Equal(t, *tc.expectedResult.IncompleteResults, returnedResult.IncompleteResults) + assert.Len(t, returnedResult.Items, len(tc.expectedResult.Users)) + for i, org := range returnedResult.Items { + assert.Equal(t, *tc.expectedResult.Users[i].Login, org.Login) + assert.Equal(t, *tc.expectedResult.Users[i].ID, org.ID) + assert.Equal(t, *tc.expectedResult.Users[i].HTMLURL, org.ProfileURL) + assert.Equal(t, *tc.expectedResult.Users[i].AvatarURL, org.AvatarURL) } }) } diff --git a/pkg/github/search_utils.go b/pkg/github/search_utils.go new file mode 100644 index 000000000..5dd48040e --- /dev/null +++ b/pkg/github/search_utils.go @@ -0,0 +1,88 @@ +package github + +import ( + "context" + "encoding/json" + "fmt" + "io" + "net/http" + + "github.com/google/go-github/v73/github" + "github.com/mark3labs/mcp-go/mcp" +) + +func searchHandler( + ctx context.Context, + getClient GetClientFn, + request mcp.CallToolRequest, + searchType string, + errorPrefix string, +) (*mcp.CallToolResult, error) { + query, err := RequiredParam[string](request, "query") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + query = fmt.Sprintf("is:%s %s", searchType, query) + + owner, err := OptionalParam[string](request, "owner") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + repo, err := OptionalParam[string](request, "repo") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + if owner != "" && repo != "" { + query = fmt.Sprintf("repo:%s/%s %s", owner, repo, query) + } + + sort, err := OptionalParam[string](request, "sort") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + order, err := OptionalParam[string](request, "order") + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + pagination, err := OptionalPaginationParams(request) + if err != nil { + return mcp.NewToolResultError(err.Error()), nil + } + + opts := &github.SearchOptions{ + // Default to "created" if no sort is provided, as it's a common use case. + Sort: sort, + Order: order, + ListOptions: github.ListOptions{ + Page: pagination.page, + PerPage: pagination.perPage, + }, + } + + client, err := getClient(ctx) + if err != nil { + return nil, fmt.Errorf("%s: failed to get GitHub client: %w", errorPrefix, err) + } + result, resp, err := client.Search.Issues(ctx, query, opts) + if err != nil { + return nil, fmt.Errorf("%s: %w", errorPrefix, err) + } + defer func() { _ = resp.Body.Close() }() + + if resp.StatusCode != http.StatusOK { + body, err := io.ReadAll(resp.Body) + if err != nil { + return nil, fmt.Errorf("%s: failed to read response body: %w", errorPrefix, err) + } + return mcp.NewToolResultError(fmt.Sprintf("%s: %s", errorPrefix, string(body))), nil + } + + r, err := json.Marshal(result) + if err != nil { + return nil, fmt.Errorf("%s: failed to marshal response: %w", errorPrefix, err) + } + + return mcp.NewToolResultText(string(r)), nil +} diff --git a/pkg/github/secret_scanning.go b/pkg/github/secret_scanning.go index 847fcfc6d..dc199b4e6 100644 --- a/pkg/github/secret_scanning.go +++ b/pkg/github/secret_scanning.go @@ -7,8 +7,9 @@ import ( "io" "net/http" + ghErrors "github.com/github/github-mcp-server/pkg/errors" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) @@ -19,7 +20,7 @@ func GetSecretScanningAlert(getClient GetClientFn, t translations.TranslationHel mcp.WithDescription(t("TOOL_GET_SECRET_SCANNING_ALERT_DESCRIPTION", "Get details of a specific secret scanning alert in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_GET_SECRET_SCANNING_ALERT_USER_TITLE", "Get secret scanning alert"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -35,11 +36,11 @@ func GetSecretScanningAlert(getClient GetClientFn, t translations.TranslationHel ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -55,7 +56,11 @@ func GetSecretScanningAlert(getClient GetClientFn, t translations.TranslationHel alert, resp, err := client.SecretScanning.GetAlert(ctx, owner, repo, int64(alertNumber)) if err != nil { - return nil, fmt.Errorf("failed to get alert: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to get alert with number '%d'", alertNumber), + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() @@ -82,7 +87,7 @@ func ListSecretScanningAlerts(getClient GetClientFn, t translations.TranslationH mcp.WithDescription(t("TOOL_LIST_SECRET_SCANNING_ALERTS_DESCRIPTION", "List secret scanning alerts in a GitHub repository.")), mcp.WithToolAnnotation(mcp.ToolAnnotation{ Title: t("TOOL_LIST_SECRET_SCANNING_ALERTS_USER_TITLE", "List secret scanning alerts"), - ReadOnlyHint: toBoolPtr(true), + ReadOnlyHint: ToBoolPtr(true), }), mcp.WithString("owner", mcp.Required(), @@ -105,11 +110,11 @@ func ListSecretScanningAlerts(getClient GetClientFn, t translations.TranslationH ), ), func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) { - owner, err := requiredParam[string](request, "owner") + owner, err := RequiredParam[string](request, "owner") if err != nil { return mcp.NewToolResultError(err.Error()), nil } - repo, err := requiredParam[string](request, "repo") + repo, err := RequiredParam[string](request, "repo") if err != nil { return mcp.NewToolResultError(err.Error()), nil } @@ -132,7 +137,11 @@ func ListSecretScanningAlerts(getClient GetClientFn, t translations.TranslationH } alerts, resp, err := client.SecretScanning.ListAlertsForRepo(ctx, owner, repo, &github.SecretScanningAlertListOptions{State: state, SecretType: secretType, Resolution: resolution}) if err != nil { - return nil, fmt.Errorf("failed to list alerts: %w", err) + return ghErrors.NewGitHubAPIErrorResponse(ctx, + fmt.Sprintf("failed to list alerts for repository '%s/%s'", owner, repo), + resp, + err, + ), nil } defer func() { _ = resp.Body.Close() }() diff --git a/pkg/github/secret_scanning_test.go b/pkg/github/secret_scanning_test.go index d32cbca94..96b281830 100644 --- a/pkg/github/secret_scanning_test.go +++ b/pkg/github/secret_scanning_test.go @@ -7,7 +7,7 @@ import ( "testing" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/migueleliasweb/go-github-mock/src/mock" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -90,12 +90,15 @@ func Test_GetSecretScanningAlert(t *testing.T) { // Verify results if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) // Parse the result and get the text content if no error textContent := getTextResult(t, result) @@ -217,12 +220,15 @@ func Test_ListSecretScanningAlerts(t *testing.T) { result, err := handler(context.Background(), request) if tc.expectError { - require.Error(t, err) - assert.Contains(t, err.Error(), tc.expectedErrMsg) + require.NoError(t, err) + require.True(t, result.IsError) + errorContent := getErrorResult(t, result) + assert.Contains(t, errorContent.Text, tc.expectedErrMsg) return } require.NoError(t, err) + require.False(t, result.IsError) textContent := getTextResult(t, result) diff --git a/pkg/github/server.go b/pkg/github/server.go index e4c241716..ea476e3ac 100644 --- a/pkg/github/server.go +++ b/pkg/github/server.go @@ -1,10 +1,11 @@ package github import ( + "encoding/json" "errors" "fmt" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/mcp" "github.com/mark3labs/mcp-go/server" ) @@ -33,7 +34,7 @@ func NewServer(version string, opts ...server.ServerOption) *server.MCPServer { // It returns the value, a boolean indicating if the parameter was present, and an error if the type is wrong. func OptionalParamOK[T any](r mcp.CallToolRequest, p string) (value T, ok bool, err error) { // Check if the parameter is present in the request - val, exists := r.Params.Arguments[p] + val, exists := r.GetArguments()[p] if !exists { // Not present, return zero value, false, no error return @@ -59,30 +60,30 @@ func isAcceptedError(err error) bool { return errors.As(err, &acceptedError) } -// requiredParam is a helper function that can be used to fetch a requested parameter from the request. +// RequiredParam is a helper function that can be used to fetch a requested parameter from the request. // It does the following checks: // 1. Checks if the parameter is present in the request. // 2. Checks if the parameter is of the expected type. // 3. Checks if the parameter is not empty, i.e: non-zero value -func requiredParam[T comparable](r mcp.CallToolRequest, p string) (T, error) { +func RequiredParam[T comparable](r mcp.CallToolRequest, p string) (T, error) { var zero T // Check if the parameter is present in the request - if _, ok := r.Params.Arguments[p]; !ok { + if _, ok := r.GetArguments()[p]; !ok { return zero, fmt.Errorf("missing required parameter: %s", p) } // Check if the parameter is of the expected type - if _, ok := r.Params.Arguments[p].(T); !ok { + val, ok := r.GetArguments()[p].(T) + if !ok { return zero, fmt.Errorf("parameter %s is not of type %T", p, zero) } - if r.Params.Arguments[p].(T) == zero { + if val == zero { return zero, fmt.Errorf("missing required parameter: %s", p) - } - return r.Params.Arguments[p].(T), nil + return val, nil } // RequiredInt is a helper function that can be used to fetch a requested parameter from the request. @@ -91,7 +92,7 @@ func requiredParam[T comparable](r mcp.CallToolRequest, p string) (T, error) { // 2. Checks if the parameter is of the expected type. // 3. Checks if the parameter is not empty, i.e: non-zero value func RequiredInt(r mcp.CallToolRequest, p string) (int, error) { - v, err := requiredParam[float64](r, p) + v, err := RequiredParam[float64](r, p) if err != nil { return 0, err } @@ -106,16 +107,16 @@ func OptionalParam[T any](r mcp.CallToolRequest, p string) (T, error) { var zero T // Check if the parameter is present in the request - if _, ok := r.Params.Arguments[p]; !ok { + if _, ok := r.GetArguments()[p]; !ok { return zero, nil } // Check if the parameter is of the expected type - if _, ok := r.Params.Arguments[p].(T); !ok { - return zero, fmt.Errorf("parameter %s is not of type %T, is %T", p, zero, r.Params.Arguments[p]) + if _, ok := r.GetArguments()[p].(T); !ok { + return zero, fmt.Errorf("parameter %s is not of type %T, is %T", p, zero, r.GetArguments()[p]) } - return r.Params.Arguments[p].(T), nil + return r.GetArguments()[p].(T), nil } // OptionalIntParam is a helper function that can be used to fetch a requested parameter from the request. @@ -149,11 +150,11 @@ func OptionalIntParamWithDefault(r mcp.CallToolRequest, p string, d int) (int, e // 2. If it is present, iterates the elements and checks each is a string func OptionalStringArrayParam(r mcp.CallToolRequest, p string) ([]string, error) { // Check if the parameter is present in the request - if _, ok := r.Params.Arguments[p]; !ok { + if _, ok := r.GetArguments()[p]; !ok { return []string{}, nil } - switch v := r.Params.Arguments[p].(type) { + switch v := r.GetArguments()[p].(type) { case nil: return []string{}, nil case []string: @@ -169,12 +170,14 @@ func OptionalStringArrayParam(r mcp.CallToolRequest, p string) ([]string, error) } return strSlice, nil default: - return []string{}, fmt.Errorf("parameter %s could not be coerced to []string, is %T", p, r.Params.Arguments[p]) + return []string{}, fmt.Errorf("parameter %s could not be coerced to []string, is %T", p, r.GetArguments()[p]) } } // WithPagination returns a ToolOption that adds "page" and "perPage" parameters to the tool. -// The "page" parameter is optional, min 1. The "perPage" parameter is optional, min 1, max 100. +// The "page" parameter is optional, min 1. +// The "perPage" parameter is optional, min 1, max 100. If unset, defaults to 30. +// https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api func WithPagination() mcp.ToolOption { return func(tool *mcp.Tool) { mcp.WithNumber("page", @@ -214,3 +217,12 @@ func OptionalPaginationParams(r mcp.CallToolRequest) (PaginationParams, error) { perPage: perPage, }, nil } + +func MarshalledTextResult(v any) *mcp.CallToolResult { + data, err := json.Marshal(v) + if err != nil { + return mcp.NewToolResultErrorFromErr("failed to marshal text result to json", err) + } + + return mcp.NewToolResultText(string(data)) +} diff --git a/pkg/github/server_test.go b/pkg/github/server_test.go index 955377990..6353f254d 100644 --- a/pkg/github/server_test.go +++ b/pkg/github/server_test.go @@ -2,10 +2,14 @@ package github import ( "context" + "encoding/json" + "errors" "fmt" + "net/http" "testing" - "github.com/google/go-github/v69/github" + "github.com/github/github-mcp-server/pkg/raw" + "github.com/google/go-github/v73/github" "github.com/shurcooL/githubv4" "github.com/stretchr/testify/assert" ) @@ -16,12 +20,45 @@ func stubGetClientFn(client *github.Client) GetClientFn { } } +func stubGetClientFromHTTPFn(client *http.Client) GetClientFn { + return func(_ context.Context) (*github.Client, error) { + return github.NewClient(client), nil + } +} + +func stubGetClientFnErr(err string) GetClientFn { + return func(_ context.Context) (*github.Client, error) { + return nil, errors.New(err) + } +} + func stubGetGQLClientFn(client *githubv4.Client) GetGQLClientFn { return func(_ context.Context) (*githubv4.Client, error) { return client, nil } } +func stubGetRawClientFn(client *raw.Client) raw.GetRawClientFn { + return func(_ context.Context) (*raw.Client, error) { + return client, nil + } +} + +func badRequestHandler(msg string) http.HandlerFunc { + return func(w http.ResponseWriter, _ *http.Request) { + structuredErrorResponse := github.ErrorResponse{ + Message: msg, + } + + b, err := json.Marshal(structuredErrorResponse) + if err != nil { + http.Error(w, "failed to marshal error response", http.StatusInternalServerError) + } + + http.Error(w, string(b), http.StatusBadRequest) + } +} + func Test_IsAcceptedError(t *testing.T) { tests := []struct { name string @@ -99,7 +136,7 @@ func Test_RequiredStringParam(t *testing.T) { for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { request := createMCPRequest(tc.params) - result, err := requiredParam[string](request, tc.paramName) + result, err := RequiredParam[string](request, tc.paramName) if tc.expectError { assert.Error(t, err) diff --git a/pkg/github/tools.go b/pkg/github/tools.go index 9c1ab34af..bd349171d 100644 --- a/pkg/github/tools.go +++ b/pkg/github/tools.go @@ -3,9 +3,10 @@ package github import ( "context" + "github.com/github/github-mcp-server/pkg/raw" "github.com/github/github-mcp-server/pkg/toolsets" "github.com/github/github-mcp-server/pkg/translations" - "github.com/google/go-github/v69/github" + "github.com/google/go-github/v73/github" "github.com/mark3labs/mcp-go/server" "github.com/shurcooL/githubv4" ) @@ -15,8 +16,7 @@ type GetGQLClientFn func(context.Context) (*githubv4.Client, error) var DefaultTools = []string{"all"} -func InitToolsets(passedToolsets []string, readOnly bool, getClient GetClientFn, getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (*toolsets.ToolsetGroup, error) { - // Create a new toolset group +func DefaultToolsetGroup(readOnly bool, getClient GetClientFn, getGQLClient GetGQLClientFn, getRawClient raw.GetRawClientFn, t translations.TranslationHelperFunc) *toolsets.ToolsetGroup { tsg := toolsets.NewToolsetGroup(readOnly) // Define all available features with their default state (disabled) @@ -24,7 +24,7 @@ func InitToolsets(passedToolsets []string, readOnly bool, getClient GetClientFn, repos := toolsets.NewToolset("repos", "GitHub Repository related tools"). AddReadTools( toolsets.NewServerTool(SearchRepositories(getClient, t)), - toolsets.NewServerTool(GetFileContents(getClient, t)), + toolsets.NewServerTool(GetFileContents(getClient, getRawClient, t)), toolsets.NewServerTool(ListCommits(getClient, t)), toolsets.NewServerTool(SearchCode(getClient, t)), toolsets.NewServerTool(GetCommit(getClient, t)), @@ -39,6 +39,13 @@ func InitToolsets(passedToolsets []string, readOnly bool, getClient GetClientFn, toolsets.NewServerTool(CreateBranch(getClient, t)), toolsets.NewServerTool(PushFiles(getClient, t)), toolsets.NewServerTool(DeleteFile(getClient, t)), + ). + AddResourceTemplates( + toolsets.NewServerResourceTemplate(GetRepositoryResourceContent(getClient, getRawClient, t)), + toolsets.NewServerResourceTemplate(GetRepositoryResourceBranchContent(getClient, getRawClient, t)), + toolsets.NewServerResourceTemplate(GetRepositoryResourceCommitContent(getClient, getRawClient, t)), + toolsets.NewServerResourceTemplate(GetRepositoryResourceTagContent(getClient, getRawClient, t)), + toolsets.NewServerResourceTemplate(GetRepositoryResourcePrContent(getClient, getRawClient, t)), ) issues := toolsets.NewToolset("issues", "GitHub Issues related tools"). AddReadTools( @@ -52,16 +59,21 @@ func InitToolsets(passedToolsets []string, readOnly bool, getClient GetClientFn, toolsets.NewServerTool(AddIssueComment(getClient, t)), toolsets.NewServerTool(UpdateIssue(getClient, t)), toolsets.NewServerTool(AssignCopilotToIssue(getGQLClient, t)), - ) + ).AddPrompts(toolsets.NewServerPrompt(AssignCodingAgentPrompt(t))) users := toolsets.NewToolset("users", "GitHub User related tools"). AddReadTools( toolsets.NewServerTool(SearchUsers(getClient, t)), ) + orgs := toolsets.NewToolset("orgs", "GitHub Organization related tools"). + AddReadTools( + toolsets.NewServerTool(SearchOrgs(getClient, t)), + ) pullRequests := toolsets.NewToolset("pull_requests", "GitHub Pull Request related tools"). AddReadTools( toolsets.NewServerTool(GetPullRequest(getClient, t)), toolsets.NewServerTool(ListPullRequests(getClient, t)), toolsets.NewServerTool(GetPullRequestFiles(getClient, t)), + toolsets.NewServerTool(SearchPullRequests(getClient, t)), toolsets.NewServerTool(GetPullRequestStatus(getClient, t)), toolsets.NewServerTool(GetPullRequestComments(getClient, t)), toolsets.NewServerTool(GetPullRequestReviews(getClient, t)), @@ -77,7 +89,7 @@ func InitToolsets(passedToolsets []string, readOnly bool, getClient GetClientFn, // Reviews toolsets.NewServerTool(CreateAndSubmitPullRequestReview(getGQLClient, t)), toolsets.NewServerTool(CreatePendingPullRequestReview(getGQLClient, t)), - toolsets.NewServerTool(AddPullRequestReviewCommentToPendingReview(getGQLClient, t)), + toolsets.NewServerTool(AddCommentToPendingReview(getGQLClient, t)), toolsets.NewServerTool(SubmitPendingPullRequestReview(getGQLClient, t)), toolsets.NewServerTool(DeletePendingPullRequestReview(getGQLClient, t)), ) @@ -91,6 +103,11 @@ func InitToolsets(passedToolsets []string, readOnly bool, getClient GetClientFn, toolsets.NewServerTool(GetSecretScanningAlert(getClient, t)), toolsets.NewServerTool(ListSecretScanningAlerts(getClient, t)), ) + dependabot := toolsets.NewToolset("dependabot", "Dependabot tools"). + AddReadTools( + toolsets.NewServerTool(GetDependabotAlert(getClient, t)), + toolsets.NewServerTool(ListDependabotAlerts(getClient, t)), + ) notifications := toolsets.NewToolset("notifications", "GitHub Notifications related tools"). AddReadTools( @@ -104,35 +121,58 @@ func InitToolsets(passedToolsets []string, readOnly bool, getClient GetClientFn, toolsets.NewServerTool(ManageRepositoryNotificationSubscription(getClient, t)), ) + discussions := toolsets.NewToolset("discussions", "GitHub Discussions related tools"). + AddReadTools( + toolsets.NewServerTool(ListDiscussions(getGQLClient, t)), + toolsets.NewServerTool(GetDiscussion(getGQLClient, t)), + toolsets.NewServerTool(GetDiscussionComments(getGQLClient, t)), + toolsets.NewServerTool(ListDiscussionCategories(getGQLClient, t)), + ) + + actions := toolsets.NewToolset("actions", "GitHub Actions workflows and CI/CD operations"). + AddReadTools( + toolsets.NewServerTool(ListWorkflows(getClient, t)), + toolsets.NewServerTool(ListWorkflowRuns(getClient, t)), + toolsets.NewServerTool(GetWorkflowRun(getClient, t)), + toolsets.NewServerTool(GetWorkflowRunLogs(getClient, t)), + toolsets.NewServerTool(ListWorkflowJobs(getClient, t)), + toolsets.NewServerTool(GetJobLogs(getClient, t)), + toolsets.NewServerTool(ListWorkflowRunArtifacts(getClient, t)), + toolsets.NewServerTool(DownloadWorkflowRunArtifact(getClient, t)), + toolsets.NewServerTool(GetWorkflowRunUsage(getClient, t)), + ). + AddWriteTools( + toolsets.NewServerTool(RunWorkflow(getClient, t)), + toolsets.NewServerTool(RerunWorkflowRun(getClient, t)), + toolsets.NewServerTool(RerunFailedJobs(getClient, t)), + toolsets.NewServerTool(CancelWorkflowRun(getClient, t)), + toolsets.NewServerTool(DeleteWorkflowRunLogs(getClient, t)), + ) + // Keep experiments alive so the system doesn't error out when it's always enabled experiments := toolsets.NewToolset("experiments", "Experimental features that are not considered stable yet") + contextTools := toolsets.NewToolset("context", "Tools that provide context about the current user and GitHub context you are operating in"). + AddReadTools( + toolsets.NewServerTool(GetMe(getClient, t)), + ) + // Add toolsets to the group + tsg.AddToolset(contextTools) tsg.AddToolset(repos) tsg.AddToolset(issues) + tsg.AddToolset(orgs) tsg.AddToolset(users) tsg.AddToolset(pullRequests) + tsg.AddToolset(actions) tsg.AddToolset(codeSecurity) tsg.AddToolset(secretProtection) + tsg.AddToolset(dependabot) tsg.AddToolset(notifications) tsg.AddToolset(experiments) - // Enable the requested features + tsg.AddToolset(discussions) - if err := tsg.EnableToolsets(passedToolsets); err != nil { - return nil, err - } - - return tsg, nil -} - -func InitContextToolset(getClient GetClientFn, t translations.TranslationHelperFunc) *toolsets.Toolset { - // Create a new context toolset - contextTools := toolsets.NewToolset("context", "Tools that provide context about the current user and GitHub context you are operating in"). - AddReadTools( - toolsets.NewServerTool(GetMe(getClient, t)), - ) - contextTools.Enabled = true - return contextTools + return tsg } // InitDynamicToolset creates a dynamic toolset that can be used to enable other toolsets, and so requires the server and toolset group as arguments @@ -150,6 +190,16 @@ func InitDynamicToolset(s *server.MCPServer, tsg *toolsets.ToolsetGroup, t trans return dynamicToolSelection } -func toBoolPtr(b bool) *bool { +// ToBoolPtr converts a bool to a *bool pointer. +func ToBoolPtr(b bool) *bool { return &b } + +// ToStringPtr converts a string to a *string pointer. +// Returns nil if the string is empty. +func ToStringPtr(s string) *string { + if s == "" { + return nil + } + return &s +} diff --git a/pkg/raw/raw.go b/pkg/raw/raw.go new file mode 100644 index 000000000..af669c905 --- /dev/null +++ b/pkg/raw/raw.go @@ -0,0 +1,73 @@ +// Package raw provides a client for interacting with the GitHub raw file API +package raw + +import ( + "context" + "net/http" + "net/url" + + gogithub "github.com/google/go-github/v73/github" +) + +// GetRawClientFn is a function type that returns a RawClient instance. +type GetRawClientFn func(context.Context) (*Client, error) + +// Client is a client for interacting with the GitHub raw content API. +type Client struct { + url *url.URL + client *gogithub.Client +} + +// NewClient creates a new instance of the raw API Client with the provided GitHub client and provided URL. +func NewClient(client *gogithub.Client, rawURL *url.URL) *Client { + client = gogithub.NewClient(client.Client()) + client.BaseURL = rawURL + return &Client{client: client, url: rawURL} +} + +func (c *Client) newRequest(ctx context.Context, method string, urlStr string, body interface{}, opts ...gogithub.RequestOption) (*http.Request, error) { + req, err := c.client.NewRequest(method, urlStr, body, opts...) + if err != nil { + return nil, err + } + req = req.WithContext(ctx) + return req, nil +} + +func (c *Client) refURL(owner, repo, ref, path string) string { + if ref == "" { + return c.url.JoinPath(owner, repo, "HEAD", path).String() + } + return c.url.JoinPath(owner, repo, ref, path).String() +} + +func (c *Client) URLFromOpts(opts *ContentOpts, owner, repo, path string) string { + if opts == nil { + opts = &ContentOpts{} + } + if opts.SHA != "" { + return c.commitURL(owner, repo, opts.SHA, path) + } + return c.refURL(owner, repo, opts.Ref, path) +} + +// BlobURL returns the URL for a blob in the raw content API. +func (c *Client) commitURL(owner, repo, sha, path string) string { + return c.url.JoinPath(owner, repo, sha, path).String() +} + +type ContentOpts struct { + Ref string + SHA string +} + +// GetRawContent fetches the raw content of a file from a GitHub repository. +func (c *Client) GetRawContent(ctx context.Context, owner, repo, path string, opts *ContentOpts) (*http.Response, error) { + url := c.URLFromOpts(opts, owner, repo, path) + req, err := c.newRequest(ctx, "GET", url, nil) + if err != nil { + return nil, err + } + + return c.client.Client().Do(req) +} diff --git a/pkg/raw/raw_mock.go b/pkg/raw/raw_mock.go new file mode 100644 index 000000000..30c7759d3 --- /dev/null +++ b/pkg/raw/raw_mock.go @@ -0,0 +1,20 @@ +package raw + +import "github.com/migueleliasweb/go-github-mock/src/mock" + +var GetRawReposContentsByOwnerByRepoByPath mock.EndpointPattern = mock.EndpointPattern{ + Pattern: "/{owner}/{repo}/HEAD/{path:.*}", + Method: "GET", +} +var GetRawReposContentsByOwnerByRepoByBranchByPath mock.EndpointPattern = mock.EndpointPattern{ + Pattern: "/{owner}/{repo}/refs/heads/{branch}/{path:.*}", + Method: "GET", +} +var GetRawReposContentsByOwnerByRepoByTagByPath mock.EndpointPattern = mock.EndpointPattern{ + Pattern: "/{owner}/{repo}/refs/tags/{tag}/{path:.*}", + Method: "GET", +} +var GetRawReposContentsByOwnerByRepoBySHAByPath mock.EndpointPattern = mock.EndpointPattern{ + Pattern: "/{owner}/{repo}/{sha}/{path:.*}", + Method: "GET", +} diff --git a/pkg/raw/raw_test.go b/pkg/raw/raw_test.go new file mode 100644 index 000000000..18a48130d --- /dev/null +++ b/pkg/raw/raw_test.go @@ -0,0 +1,150 @@ +package raw + +import ( + "context" + "net/http" + "net/url" + "testing" + + "github.com/google/go-github/v73/github" + "github.com/migueleliasweb/go-github-mock/src/mock" + "github.com/stretchr/testify/require" +) + +func TestGetRawContent(t *testing.T) { + base, _ := url.Parse("https://raw.example.com/") + + tests := []struct { + name string + pattern mock.EndpointPattern + opts *ContentOpts + owner, repo, path string + statusCode int + contentType string + body string + expectError string + }{ + { + name: "HEAD fetch success", + pattern: GetRawReposContentsByOwnerByRepoByPath, + opts: nil, + owner: "octocat", repo: "hello", path: "README.md", + statusCode: 200, + contentType: "text/plain", + body: "# Test file", + }, + { + name: "branch fetch success", + pattern: GetRawReposContentsByOwnerByRepoByBranchByPath, + opts: &ContentOpts{Ref: "refs/heads/main"}, + owner: "octocat", repo: "hello", path: "README.md", + statusCode: 200, + contentType: "text/plain", + body: "# Test file", + }, + { + name: "tag fetch success", + pattern: GetRawReposContentsByOwnerByRepoByTagByPath, + opts: &ContentOpts{Ref: "refs/tags/v1.0.0"}, + owner: "octocat", repo: "hello", path: "README.md", + statusCode: 200, + contentType: "text/plain", + body: "# Test file", + }, + { + name: "sha fetch success", + pattern: GetRawReposContentsByOwnerByRepoBySHAByPath, + opts: &ContentOpts{SHA: "abc123"}, + owner: "octocat", repo: "hello", path: "README.md", + statusCode: 200, + contentType: "text/plain", + body: "# Test file", + }, + { + name: "not found", + pattern: GetRawReposContentsByOwnerByRepoByPath, + opts: nil, + owner: "octocat", repo: "hello", path: "notfound.txt", + statusCode: 404, + contentType: "application/json", + body: `{"message": "Not Found"}`, + }, + } + + for _, tc := range tests { + t.Run(tc.name, func(t *testing.T) { + mockedClient := mock.NewMockedHTTPClient( + mock.WithRequestMatchHandler( + tc.pattern, + http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) { + w.Header().Set("Content-Type", tc.contentType) + w.WriteHeader(tc.statusCode) + _, err := w.Write([]byte(tc.body)) + require.NoError(t, err) + }), + ), + ) + ghClient := github.NewClient(mockedClient) + client := NewClient(ghClient, base) + resp, err := client.GetRawContent(context.Background(), tc.owner, tc.repo, tc.path, tc.opts) + defer func() { + _ = resp.Body.Close() + }() + if tc.expectError != "" { + require.Error(t, err) + return + } + require.NoError(t, err) + require.Equal(t, tc.statusCode, resp.StatusCode) + }) + } +} + +func TestUrlFromOpts(t *testing.T) { + base, _ := url.Parse("https://raw.example.com/") + ghClient := github.NewClient(nil) + client := NewClient(ghClient, base) + + tests := []struct { + name string + opts *ContentOpts + owner string + repo string + path string + want string + }{ + { + name: "no opts (HEAD)", + opts: nil, + owner: "octocat", repo: "hello", path: "README.md", + want: "https://raw.example.com/octocat/hello/HEAD/README.md", + }, + { + name: "ref branch", + opts: &ContentOpts{Ref: "refs/heads/main"}, + owner: "octocat", repo: "hello", path: "README.md", + want: "https://raw.example.com/octocat/hello/refs/heads/main/README.md", + }, + { + name: "ref tag", + opts: &ContentOpts{Ref: "refs/tags/v1.0.0"}, + owner: "octocat", repo: "hello", path: "README.md", + want: "https://raw.example.com/octocat/hello/refs/tags/v1.0.0/README.md", + }, + { + name: "sha", + opts: &ContentOpts{SHA: "abc123"}, + owner: "octocat", repo: "hello", path: "README.md", + want: "https://raw.example.com/octocat/hello/abc123/README.md", + }, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + got := client.URLFromOpts(tt.opts, tt.owner, tt.repo, tt.path) + if got != tt.want { + t.Errorf("UrlFromOpts() = %q, want %q", got, tt.want) + } + }) + } +} diff --git a/pkg/toolsets/toolsets.go b/pkg/toolsets/toolsets.go index 7400119c8..5d503b742 100644 --- a/pkg/toolsets/toolsets.go +++ b/pkg/toolsets/toolsets.go @@ -7,10 +7,59 @@ import ( "github.com/mark3labs/mcp-go/server" ) +type ToolsetDoesNotExistError struct { + Name string +} + +func (e *ToolsetDoesNotExistError) Error() string { + return fmt.Sprintf("toolset %s does not exist", e.Name) +} + +func (e *ToolsetDoesNotExistError) Is(target error) bool { + if target == nil { + return false + } + if _, ok := target.(*ToolsetDoesNotExistError); ok { + return true + } + return false +} + +func NewToolsetDoesNotExistError(name string) *ToolsetDoesNotExistError { + return &ToolsetDoesNotExistError{Name: name} +} + func NewServerTool(tool mcp.Tool, handler server.ToolHandlerFunc) server.ServerTool { return server.ServerTool{Tool: tool, Handler: handler} } +func NewServerResourceTemplate(resourceTemplate mcp.ResourceTemplate, handler server.ResourceTemplateHandlerFunc) ServerResourceTemplate { + return ServerResourceTemplate{ + resourceTemplate: resourceTemplate, + handler: handler, + } +} + +func NewServerPrompt(prompt mcp.Prompt, handler server.PromptHandlerFunc) ServerPrompt { + return ServerPrompt{ + Prompt: prompt, + Handler: handler, + } +} + +// ServerResourceTemplate represents a resource template that can be registered with the MCP server. +type ServerResourceTemplate struct { + resourceTemplate mcp.ResourceTemplate + handler server.ResourceTemplateHandlerFunc +} + +// ServerPrompt represents a prompt that can be registered with the MCP server. +type ServerPrompt struct { + Prompt mcp.Prompt + Handler server.PromptHandlerFunc +} + +// Toolset represents a collection of MCP functionality that can be enabled or disabled as a group. type Toolset struct { Name string Description string @@ -18,6 +67,11 @@ type Toolset struct { readOnly bool writeTools []server.ServerTool readTools []server.ServerTool + // resources are not tools, but the community seems to be moving towards namespaces as a broader concept + // and in order to have multiple servers running concurrently, we want to avoid overlapping resources too. + resourceTemplates []ServerResourceTemplate + // prompts are also not tools but are namespaced similarly + prompts []ServerPrompt } func (t *Toolset) GetActiveTools() []server.ServerTool { @@ -51,6 +105,45 @@ func (t *Toolset) RegisterTools(s *server.MCPServer) { } } +func (t *Toolset) AddResourceTemplates(templates ...ServerResourceTemplate) *Toolset { + t.resourceTemplates = append(t.resourceTemplates, templates...) + return t +} + +func (t *Toolset) AddPrompts(prompts ...ServerPrompt) *Toolset { + t.prompts = append(t.prompts, prompts...) + return t +} + +func (t *Toolset) GetActiveResourceTemplates() []ServerResourceTemplate { + if !t.Enabled { + return nil + } + return t.resourceTemplates +} + +func (t *Toolset) GetAvailableResourceTemplates() []ServerResourceTemplate { + return t.resourceTemplates +} + +func (t *Toolset) RegisterResourcesTemplates(s *server.MCPServer) { + if !t.Enabled { + return + } + for _, resource := range t.resourceTemplates { + s.AddResourceTemplate(resource.resourceTemplate, resource.handler) + } +} + +func (t *Toolset) RegisterPrompts(s *server.MCPServer) { + if !t.Enabled { + return + } + for _, prompt := range t.prompts { + s.AddPrompt(prompt.Prompt, prompt.Handler) + } +} + func (t *Toolset) SetReadOnly() { // Set the toolset to read-only t.readOnly = true @@ -150,15 +243,25 @@ func (tg *ToolsetGroup) EnableToolsets(names []string) error { func (tg *ToolsetGroup) EnableToolset(name string) error { toolset, exists := tg.Toolsets[name] if !exists { - return fmt.Errorf("toolset %s does not exist", name) + return NewToolsetDoesNotExistError(name) } toolset.Enabled = true tg.Toolsets[name] = toolset return nil } -func (tg *ToolsetGroup) RegisterTools(s *server.MCPServer) { +func (tg *ToolsetGroup) RegisterAll(s *server.MCPServer) { for _, toolset := range tg.Toolsets { toolset.RegisterTools(s) + toolset.RegisterResourcesTemplates(s) + toolset.RegisterPrompts(s) + } +} + +func (tg *ToolsetGroup) GetToolset(name string) (*Toolset, error) { + toolset, exists := tg.Toolsets[name] + if !exists { + return nil, NewToolsetDoesNotExistError(name) } + return toolset, nil } diff --git a/pkg/toolsets/toolsets_test.go b/pkg/toolsets/toolsets_test.go index 7ece1df1e..d74c94bbb 100644 --- a/pkg/toolsets/toolsets_test.go +++ b/pkg/toolsets/toolsets_test.go @@ -1,17 +1,12 @@ package toolsets import ( + "errors" "testing" ) -func TestNewToolsetGroup(t *testing.T) { +func TestNewToolsetGroupIsEmptyWithoutEverythingOn(t *testing.T) { tsg := NewToolsetGroup(false) - if tsg == nil { - t.Fatal("Expected NewToolsetGroup to return a non-nil pointer") - } - if tsg.Toolsets == nil { - t.Fatal("Expected Toolsets map to be initialized") - } if len(tsg.Toolsets) != 0 { t.Fatalf("Expected Toolsets map to be empty, got %d items", len(tsg.Toolsets)) } @@ -157,6 +152,9 @@ func TestEnableToolsets(t *testing.T) { if err == nil { t.Error("Expected error when enabling list with non-existent toolset") } + if !errors.Is(err, NewToolsetDoesNotExistError("non-existent")) { + t.Errorf("Expected ToolsetDoesNotExistError when enabling non-existent toolset, got: %v", err) + } // Test with empty list err = tsg.EnableToolsets([]string{}) @@ -213,7 +211,7 @@ func TestEnableEverything(t *testing.T) { func TestIsEnabledWithEverythingOn(t *testing.T) { tsg := NewToolsetGroup(false) - // Enable "everything" + // Enable "all" err := tsg.EnableToolsets([]string{"all"}) if err != nil { t.Errorf("Expected no error when enabling 'all', got: %v", err) @@ -228,3 +226,27 @@ func TestIsEnabledWithEverythingOn(t *testing.T) { t.Error("Expected IsEnabled to return true for any toolset when everythingOn is true") } } + +func TestToolsetGroup_GetToolset(t *testing.T) { + tsg := NewToolsetGroup(false) + toolset := NewToolset("my-toolset", "desc") + tsg.AddToolset(toolset) + + // Should find the toolset + got, err := tsg.GetToolset("my-toolset") + if err != nil { + t.Fatalf("expected no error, got %v", err) + } + if got != toolset { + t.Errorf("expected to get the same toolset instance") + } + + // Should not find a non-existent toolset + _, err = tsg.GetToolset("does-not-exist") + if err == nil { + t.Error("expected error for missing toolset, got nil") + } + if !errors.Is(err, NewToolsetDoesNotExistError("does-not-exist")) { + t.Errorf("expected error to be ToolsetDoesNotExistError, got %v", err) + } +} diff --git a/script/generate-docs b/script/generate-docs new file mode 100755 index 000000000..a2a7255d7 --- /dev/null +++ b/script/generate-docs @@ -0,0 +1,5 @@ +#!/bin/bash + +# This script generates documentation for the GitHub MCP server. +# It needs to be run after tool updates to ensure the latest changes are reflected in the documentation. +go run ./cmd/github-mcp-server generate-docs \ No newline at end of file diff --git a/script/get-discussions b/script/get-discussions new file mode 100755 index 000000000..3e68abf24 --- /dev/null +++ b/script/get-discussions @@ -0,0 +1,5 @@ +#!/bin/bash + +# echo '{"jsonrpc":"2.0","id":3,"params":{"name":"list_discussions","arguments": {"owner": "github", "repo": "securitylab", "first": 10, "since": "2025-04-01T00:00:00Z"}},"method":"tools/call"}' | go run cmd/github-mcp-server/main.go stdio | jq . +echo '{"jsonrpc":"2.0","id":3,"params":{"name":"list_discussions","arguments": {"owner": "github", "repo": "securitylab", "first": 10, "since": "2025-04-01T00:00:00Z", "sort": "CREATED_AT", "direction": "DESC"}},"method":"tools/call"}' | go run cmd/github-mcp-server/main.go stdio | jq . + diff --git a/script/lint b/script/lint new file mode 100755 index 000000000..e6ea9da89 --- /dev/null +++ b/script/lint @@ -0,0 +1,14 @@ +set -eu + +# first run go fmt +gofmt -s -w . + +BINDIR="$(git rev-parse --show-toplevel)"/bin +BINARY=$BINDIR/golangci-lint +GOLANGCI_LINT_VERSION=v2.2.1 + +if [ ! -f "$BINARY" ]; then + curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s "$GOLANGCI_LINT_VERSION" +fi + +$BINARY run \ No newline at end of file diff --git a/script/tag-release b/script/tag-release new file mode 100755 index 000000000..fd94167c3 --- /dev/null +++ b/script/tag-release @@ -0,0 +1,151 @@ +#!/bin/bash + +# Exit immediately if a command exits with a non-zero status. +set -e + +# Initialize variables +TAG="" +DRY_RUN=false + +# Parse arguments +for arg in "$@"; do + case $arg in + --dry-run) + DRY_RUN=true + ;; + *) + # The first non-flag argument is the tag + if [[ ! $arg == --* ]]; then + if [ -z "$TAG" ]; then + TAG=$arg + fi + fi + ;; + esac +done + +if [ "$DRY_RUN" = true ]; then + echo "DRY RUN: No changes will be pushed to the remote repository." + echo +fi + +# 1. Validate input +if [ -z "$TAG" ]; then + echo "Error: No tag specified." + echo "Usage: ./script/tag-release vX.Y.Z [--dry-run]" + exit 1 +fi + +# Regular expression for semantic versioning (vX.Y.Z or vX.Y.Z-suffix) +if [[ ! $TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-.*)?$ ]]; then + echo "Error: Tag must be in format vX.Y.Z or vX.Y.Z-suffix (e.g., v1.0.0 or v1.0.0-rc1)" + exit 1 +fi + +# 2. Check current branch +CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD) +if [ "$CURRENT_BRANCH" != "main" ]; then + echo "Error: You must be on the 'main' branch to create a release." + echo "Current branch is '$CURRENT_BRANCH'." + exit 1 +fi + +# 3. Fetch latest from origin +echo "Fetching latest changes from origin..." +git fetch origin main + +# 4. Check if the working directory is clean +if ! git diff-index --quiet HEAD --; then + echo "Error: Working directory is not clean. Please commit or stash your changes." + exit 1 +fi + +# 5. Check if main is up-to-date with origin/main +LOCAL_SHA=$(git rev-parse @) +REMOTE_SHA=$(git rev-parse @{u}) + +if [ "$LOCAL_SHA" != "$REMOTE_SHA" ]; then + echo "Error: Your local 'main' branch is not up-to-date with 'origin/main'. Please pull the latest changes." + exit 1 +fi +echo "✅ Local 'main' branch is up-to-date with 'origin/main'." + +# 6. Check if tag already exists +if git tag -l | grep -q "^${TAG}$"; then + echo "Error: Tag ${TAG} already exists locally." + exit 1 +fi +if git ls-remote --tags origin | grep -q "refs/tags/${TAG}$"; then + echo "Error: Tag ${TAG} already exists on remote 'origin'." + exit 1 +fi + +# 7. Confirm release with user +echo +LATEST_TAG=$(git tag --sort=-version:refname | head -n 1) +if [ -n "$LATEST_TAG" ]; then + echo "Current latest release: $LATEST_TAG" +fi +echo "Proposed new release: $TAG" +echo +read -p "Do you want to proceed with the release? (y/n) " -n 1 -r +echo # Move to a new line +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "Release cancelled." + exit 1 +fi +echo + +# 8. Create the new release tag +if [ "$DRY_RUN" = true ]; then + echo "DRY RUN: Skipping creation of tag $TAG." +else + echo "Creating new release tag: $TAG" + git tag -a "$TAG" -m "Release $TAG" +fi + +# 9. Push the new tag to the remote repository +if [ "$DRY_RUN" = true ]; then + echo "DRY RUN: Skipping push of tag $TAG to origin." +else + echo "Pushing tag $TAG to origin..." + git push origin "$TAG" +fi + +# 10. Update and push the 'latest-release' tag +if [ "$DRY_RUN" = true ]; then + echo "DRY RUN: Skipping update and push of 'latest-release' tag." +else + echo "Updating 'latest-release' tag to point to $TAG..." + git tag -f latest-release "$TAG" + echo "Pushing 'latest-release' tag to origin..." + git push origin latest-release --force +fi + +if [ "$DRY_RUN" = true ]; then + echo "✅ DRY RUN complete. No tags were created or pushed." +else + echo "✅ Successfully tagged and pushed release $TAG." + echo "✅ 'latest-release' tag has been updated." +fi + +# 11. Post-release instructions +REPO_URL=$(git remote get-url origin) +REPO_SLUG=$(echo "$REPO_URL" | sed -e 's/.*github.com[:\/]//' -e 's/\.git$//') + +cat << EOF + +## 🎉 Release $TAG has been initiated! + +### Next steps: +1. 📋 Check https://github.com/$REPO_SLUG/releases and wait for the draft release to show up (after the goreleaser workflow completes) +2. ✏️ Edit the new release, delete the existing notes and click the auto-generate button GitHub provides +3. ✨ Add a section at the top calling out the main features +4. 🚀 Publish the release +5. 📢 Post message in #gh-mcp-releases channel in Slack and then share to the other mcp channels + +### Resources: +- 📦 Draft Release: https://github.com/$REPO_SLUG/releases/tag/$TAG + +The release process is now ready for your review and completion! +EOF diff --git a/script/test b/script/test new file mode 100755 index 000000000..7f0dd0c20 --- /dev/null +++ b/script/test @@ -0,0 +1,3 @@ +set -eu + +go test -race ./... \ No newline at end of file diff --git a/third-party-licenses.darwin.md b/third-party-licenses.darwin.md index cdb2af5b5..6a9f895cb 100644 --- a/third-party-licenses.darwin.md +++ b/third-party-licenses.darwin.md @@ -9,11 +9,19 @@ Some packages may only be included on certain architectures or operating systems - [github.com/fsnotify/fsnotify](https://pkg.go.dev/github.com/fsnotify/fsnotify) ([BSD-3-Clause](https://github.com/fsnotify/fsnotify/blob/v1.8.0/LICENSE)) - [github.com/github/github-mcp-server](https://pkg.go.dev/github.com/github/github-mcp-server) ([MIT](https://github.com/github/github-mcp-server/blob/HEAD/LICENSE)) - - [github.com/go-viper/mapstructure/v2](https://pkg.go.dev/github.com/go-viper/mapstructure/v2) ([MIT](https://github.com/go-viper/mapstructure/blob/v2.2.1/LICENSE)) - - [github.com/google/go-github/v69/github](https://pkg.go.dev/github.com/google/go-github/v69/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v69.2.0/LICENSE)) + - [github.com/go-openapi/jsonpointer](https://pkg.go.dev/github.com/go-openapi/jsonpointer) ([Apache-2.0](https://github.com/go-openapi/jsonpointer/blob/v0.19.5/LICENSE)) + - [github.com/go-openapi/swag](https://pkg.go.dev/github.com/go-openapi/swag) ([Apache-2.0](https://github.com/go-openapi/swag/blob/v0.21.1/LICENSE)) + - [github.com/go-viper/mapstructure/v2](https://pkg.go.dev/github.com/go-viper/mapstructure/v2) ([MIT](https://github.com/go-viper/mapstructure/blob/v2.3.0/LICENSE)) + - [github.com/google/go-github/v71/github](https://pkg.go.dev/github.com/google/go-github/v71/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v71.0.0/LICENSE)) + - [github.com/google/go-github/v73/github](https://pkg.go.dev/github.com/google/go-github/v73/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v73.0.0/LICENSE)) - [github.com/google/go-querystring/query](https://pkg.go.dev/github.com/google/go-querystring/query) ([BSD-3-Clause](https://github.com/google/go-querystring/blob/v1.1.0/LICENSE)) - [github.com/google/uuid](https://pkg.go.dev/github.com/google/uuid) ([BSD-3-Clause](https://github.com/google/uuid/blob/v1.6.0/LICENSE)) - - [github.com/mark3labs/mcp-go](https://pkg.go.dev/github.com/mark3labs/mcp-go) ([MIT](https://github.com/mark3labs/mcp-go/blob/v0.28.0/LICENSE)) + - [github.com/gorilla/mux](https://pkg.go.dev/github.com/gorilla/mux) ([BSD-3-Clause](https://github.com/gorilla/mux/blob/v1.8.0/LICENSE)) + - [github.com/josephburnett/jd/v2](https://pkg.go.dev/github.com/josephburnett/jd/v2) ([MIT](https://github.com/josephburnett/jd/blob/v1.9.2/LICENSE)) + - [github.com/josharian/intern](https://pkg.go.dev/github.com/josharian/intern) ([MIT](https://github.com/josharian/intern/blob/v1.0.0/license.md)) + - [github.com/mailru/easyjson](https://pkg.go.dev/github.com/mailru/easyjson) ([MIT](https://github.com/mailru/easyjson/blob/v0.7.7/LICENSE)) + - [github.com/mark3labs/mcp-go](https://pkg.go.dev/github.com/mark3labs/mcp-go) ([MIT](https://github.com/mark3labs/mcp-go/blob/v0.32.0/LICENSE)) + - [github.com/migueleliasweb/go-github-mock/src/mock](https://pkg.go.dev/github.com/migueleliasweb/go-github-mock/src/mock) ([MIT](https://github.com/migueleliasweb/go-github-mock/blob/v1.3.0/LICENSE)) - [github.com/pelletier/go-toml/v2](https://pkg.go.dev/github.com/pelletier/go-toml/v2) ([MIT](https://github.com/pelletier/go-toml/blob/v2.2.3/LICENSE)) - [github.com/sagikazarmark/locafero](https://pkg.go.dev/github.com/sagikazarmark/locafero) ([MIT](https://github.com/sagikazarmark/locafero/blob/v0.9.0/LICENSE)) - [github.com/shurcooL/githubv4](https://pkg.go.dev/github.com/shurcooL/githubv4) ([MIT](https://github.com/shurcooL/githubv4/blob/48295856cce7/LICENSE)) @@ -27,8 +35,12 @@ Some packages may only be included on certain architectures or operating systems - [github.com/spf13/viper](https://pkg.go.dev/github.com/spf13/viper) ([MIT](https://github.com/spf13/viper/blob/v1.20.1/LICENSE)) - [github.com/subosito/gotenv](https://pkg.go.dev/github.com/subosito/gotenv) ([MIT](https://github.com/subosito/gotenv/blob/v1.6.0/LICENSE)) - [github.com/yosida95/uritemplate/v3](https://pkg.go.dev/github.com/yosida95/uritemplate/v3) ([BSD-3-Clause](https://github.com/yosida95/uritemplate/blob/v3.0.2/LICENSE)) + - [github.com/yudai/golcs](https://pkg.go.dev/github.com/yudai/golcs) ([MIT](https://github.com/yudai/golcs/blob/ecda9a501e82/LICENSE)) + - [golang.org/x/exp](https://pkg.go.dev/golang.org/x/exp) ([BSD-3-Clause](https://cs.opensource.google/go/x/exp/+/8a7402ab:LICENSE)) - [golang.org/x/sys/unix](https://pkg.go.dev/golang.org/x/sys/unix) ([BSD-3-Clause](https://cs.opensource.google/go/x/sys/+/v0.31.0:LICENSE)) - [golang.org/x/text](https://pkg.go.dev/golang.org/x/text) ([BSD-3-Clause](https://cs.opensource.google/go/x/text/+/v0.23.0:LICENSE)) + - [golang.org/x/time/rate](https://pkg.go.dev/golang.org/x/time/rate) ([BSD-3-Clause](https://cs.opensource.google/go/x/time/+/v0.5.0:LICENSE)) + - [gopkg.in/yaml.v2](https://pkg.go.dev/gopkg.in/yaml.v2) ([Apache-2.0](https://github.com/go-yaml/yaml/blob/v2.4.0/LICENSE)) - [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) ([MIT](https://github.com/go-yaml/yaml/blob/v3.0.1/LICENSE)) [github/github-mcp-server]: https://github.com/github/github-mcp-server diff --git a/third-party-licenses.linux.md b/third-party-licenses.linux.md index cdb2af5b5..6a9f895cb 100644 --- a/third-party-licenses.linux.md +++ b/third-party-licenses.linux.md @@ -9,11 +9,19 @@ Some packages may only be included on certain architectures or operating systems - [github.com/fsnotify/fsnotify](https://pkg.go.dev/github.com/fsnotify/fsnotify) ([BSD-3-Clause](https://github.com/fsnotify/fsnotify/blob/v1.8.0/LICENSE)) - [github.com/github/github-mcp-server](https://pkg.go.dev/github.com/github/github-mcp-server) ([MIT](https://github.com/github/github-mcp-server/blob/HEAD/LICENSE)) - - [github.com/go-viper/mapstructure/v2](https://pkg.go.dev/github.com/go-viper/mapstructure/v2) ([MIT](https://github.com/go-viper/mapstructure/blob/v2.2.1/LICENSE)) - - [github.com/google/go-github/v69/github](https://pkg.go.dev/github.com/google/go-github/v69/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v69.2.0/LICENSE)) + - [github.com/go-openapi/jsonpointer](https://pkg.go.dev/github.com/go-openapi/jsonpointer) ([Apache-2.0](https://github.com/go-openapi/jsonpointer/blob/v0.19.5/LICENSE)) + - [github.com/go-openapi/swag](https://pkg.go.dev/github.com/go-openapi/swag) ([Apache-2.0](https://github.com/go-openapi/swag/blob/v0.21.1/LICENSE)) + - [github.com/go-viper/mapstructure/v2](https://pkg.go.dev/github.com/go-viper/mapstructure/v2) ([MIT](https://github.com/go-viper/mapstructure/blob/v2.3.0/LICENSE)) + - [github.com/google/go-github/v71/github](https://pkg.go.dev/github.com/google/go-github/v71/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v71.0.0/LICENSE)) + - [github.com/google/go-github/v73/github](https://pkg.go.dev/github.com/google/go-github/v73/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v73.0.0/LICENSE)) - [github.com/google/go-querystring/query](https://pkg.go.dev/github.com/google/go-querystring/query) ([BSD-3-Clause](https://github.com/google/go-querystring/blob/v1.1.0/LICENSE)) - [github.com/google/uuid](https://pkg.go.dev/github.com/google/uuid) ([BSD-3-Clause](https://github.com/google/uuid/blob/v1.6.0/LICENSE)) - - [github.com/mark3labs/mcp-go](https://pkg.go.dev/github.com/mark3labs/mcp-go) ([MIT](https://github.com/mark3labs/mcp-go/blob/v0.28.0/LICENSE)) + - [github.com/gorilla/mux](https://pkg.go.dev/github.com/gorilla/mux) ([BSD-3-Clause](https://github.com/gorilla/mux/blob/v1.8.0/LICENSE)) + - [github.com/josephburnett/jd/v2](https://pkg.go.dev/github.com/josephburnett/jd/v2) ([MIT](https://github.com/josephburnett/jd/blob/v1.9.2/LICENSE)) + - [github.com/josharian/intern](https://pkg.go.dev/github.com/josharian/intern) ([MIT](https://github.com/josharian/intern/blob/v1.0.0/license.md)) + - [github.com/mailru/easyjson](https://pkg.go.dev/github.com/mailru/easyjson) ([MIT](https://github.com/mailru/easyjson/blob/v0.7.7/LICENSE)) + - [github.com/mark3labs/mcp-go](https://pkg.go.dev/github.com/mark3labs/mcp-go) ([MIT](https://github.com/mark3labs/mcp-go/blob/v0.32.0/LICENSE)) + - [github.com/migueleliasweb/go-github-mock/src/mock](https://pkg.go.dev/github.com/migueleliasweb/go-github-mock/src/mock) ([MIT](https://github.com/migueleliasweb/go-github-mock/blob/v1.3.0/LICENSE)) - [github.com/pelletier/go-toml/v2](https://pkg.go.dev/github.com/pelletier/go-toml/v2) ([MIT](https://github.com/pelletier/go-toml/blob/v2.2.3/LICENSE)) - [github.com/sagikazarmark/locafero](https://pkg.go.dev/github.com/sagikazarmark/locafero) ([MIT](https://github.com/sagikazarmark/locafero/blob/v0.9.0/LICENSE)) - [github.com/shurcooL/githubv4](https://pkg.go.dev/github.com/shurcooL/githubv4) ([MIT](https://github.com/shurcooL/githubv4/blob/48295856cce7/LICENSE)) @@ -27,8 +35,12 @@ Some packages may only be included on certain architectures or operating systems - [github.com/spf13/viper](https://pkg.go.dev/github.com/spf13/viper) ([MIT](https://github.com/spf13/viper/blob/v1.20.1/LICENSE)) - [github.com/subosito/gotenv](https://pkg.go.dev/github.com/subosito/gotenv) ([MIT](https://github.com/subosito/gotenv/blob/v1.6.0/LICENSE)) - [github.com/yosida95/uritemplate/v3](https://pkg.go.dev/github.com/yosida95/uritemplate/v3) ([BSD-3-Clause](https://github.com/yosida95/uritemplate/blob/v3.0.2/LICENSE)) + - [github.com/yudai/golcs](https://pkg.go.dev/github.com/yudai/golcs) ([MIT](https://github.com/yudai/golcs/blob/ecda9a501e82/LICENSE)) + - [golang.org/x/exp](https://pkg.go.dev/golang.org/x/exp) ([BSD-3-Clause](https://cs.opensource.google/go/x/exp/+/8a7402ab:LICENSE)) - [golang.org/x/sys/unix](https://pkg.go.dev/golang.org/x/sys/unix) ([BSD-3-Clause](https://cs.opensource.google/go/x/sys/+/v0.31.0:LICENSE)) - [golang.org/x/text](https://pkg.go.dev/golang.org/x/text) ([BSD-3-Clause](https://cs.opensource.google/go/x/text/+/v0.23.0:LICENSE)) + - [golang.org/x/time/rate](https://pkg.go.dev/golang.org/x/time/rate) ([BSD-3-Clause](https://cs.opensource.google/go/x/time/+/v0.5.0:LICENSE)) + - [gopkg.in/yaml.v2](https://pkg.go.dev/gopkg.in/yaml.v2) ([Apache-2.0](https://github.com/go-yaml/yaml/blob/v2.4.0/LICENSE)) - [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) ([MIT](https://github.com/go-yaml/yaml/blob/v3.0.1/LICENSE)) [github/github-mcp-server]: https://github.com/github/github-mcp-server diff --git a/third-party-licenses.windows.md b/third-party-licenses.windows.md index 74d13898c..505c2d83e 100644 --- a/third-party-licenses.windows.md +++ b/third-party-licenses.windows.md @@ -9,12 +9,20 @@ Some packages may only be included on certain architectures or operating systems - [github.com/fsnotify/fsnotify](https://pkg.go.dev/github.com/fsnotify/fsnotify) ([BSD-3-Clause](https://github.com/fsnotify/fsnotify/blob/v1.8.0/LICENSE)) - [github.com/github/github-mcp-server](https://pkg.go.dev/github.com/github/github-mcp-server) ([MIT](https://github.com/github/github-mcp-server/blob/HEAD/LICENSE)) - - [github.com/go-viper/mapstructure/v2](https://pkg.go.dev/github.com/go-viper/mapstructure/v2) ([MIT](https://github.com/go-viper/mapstructure/blob/v2.2.1/LICENSE)) - - [github.com/google/go-github/v69/github](https://pkg.go.dev/github.com/google/go-github/v69/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v69.2.0/LICENSE)) + - [github.com/go-openapi/jsonpointer](https://pkg.go.dev/github.com/go-openapi/jsonpointer) ([Apache-2.0](https://github.com/go-openapi/jsonpointer/blob/v0.19.5/LICENSE)) + - [github.com/go-openapi/swag](https://pkg.go.dev/github.com/go-openapi/swag) ([Apache-2.0](https://github.com/go-openapi/swag/blob/v0.21.1/LICENSE)) + - [github.com/go-viper/mapstructure/v2](https://pkg.go.dev/github.com/go-viper/mapstructure/v2) ([MIT](https://github.com/go-viper/mapstructure/blob/v2.3.0/LICENSE)) + - [github.com/google/go-github/v71/github](https://pkg.go.dev/github.com/google/go-github/v71/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v71.0.0/LICENSE)) + - [github.com/google/go-github/v73/github](https://pkg.go.dev/github.com/google/go-github/v73/github) ([BSD-3-Clause](https://github.com/google/go-github/blob/v73.0.0/LICENSE)) - [github.com/google/go-querystring/query](https://pkg.go.dev/github.com/google/go-querystring/query) ([BSD-3-Clause](https://github.com/google/go-querystring/blob/v1.1.0/LICENSE)) - [github.com/google/uuid](https://pkg.go.dev/github.com/google/uuid) ([BSD-3-Clause](https://github.com/google/uuid/blob/v1.6.0/LICENSE)) + - [github.com/gorilla/mux](https://pkg.go.dev/github.com/gorilla/mux) ([BSD-3-Clause](https://github.com/gorilla/mux/blob/v1.8.0/LICENSE)) - [github.com/inconshreveable/mousetrap](https://pkg.go.dev/github.com/inconshreveable/mousetrap) ([Apache-2.0](https://github.com/inconshreveable/mousetrap/blob/v1.1.0/LICENSE)) - - [github.com/mark3labs/mcp-go](https://pkg.go.dev/github.com/mark3labs/mcp-go) ([MIT](https://github.com/mark3labs/mcp-go/blob/v0.28.0/LICENSE)) + - [github.com/josephburnett/jd/v2](https://pkg.go.dev/github.com/josephburnett/jd/v2) ([MIT](https://github.com/josephburnett/jd/blob/v1.9.2/LICENSE)) + - [github.com/josharian/intern](https://pkg.go.dev/github.com/josharian/intern) ([MIT](https://github.com/josharian/intern/blob/v1.0.0/license.md)) + - [github.com/mailru/easyjson](https://pkg.go.dev/github.com/mailru/easyjson) ([MIT](https://github.com/mailru/easyjson/blob/v0.7.7/LICENSE)) + - [github.com/mark3labs/mcp-go](https://pkg.go.dev/github.com/mark3labs/mcp-go) ([MIT](https://github.com/mark3labs/mcp-go/blob/v0.32.0/LICENSE)) + - [github.com/migueleliasweb/go-github-mock/src/mock](https://pkg.go.dev/github.com/migueleliasweb/go-github-mock/src/mock) ([MIT](https://github.com/migueleliasweb/go-github-mock/blob/v1.3.0/LICENSE)) - [github.com/pelletier/go-toml/v2](https://pkg.go.dev/github.com/pelletier/go-toml/v2) ([MIT](https://github.com/pelletier/go-toml/blob/v2.2.3/LICENSE)) - [github.com/sagikazarmark/locafero](https://pkg.go.dev/github.com/sagikazarmark/locafero) ([MIT](https://github.com/sagikazarmark/locafero/blob/v0.9.0/LICENSE)) - [github.com/shurcooL/githubv4](https://pkg.go.dev/github.com/shurcooL/githubv4) ([MIT](https://github.com/shurcooL/githubv4/blob/48295856cce7/LICENSE)) @@ -28,8 +36,12 @@ Some packages may only be included on certain architectures or operating systems - [github.com/spf13/viper](https://pkg.go.dev/github.com/spf13/viper) ([MIT](https://github.com/spf13/viper/blob/v1.20.1/LICENSE)) - [github.com/subosito/gotenv](https://pkg.go.dev/github.com/subosito/gotenv) ([MIT](https://github.com/subosito/gotenv/blob/v1.6.0/LICENSE)) - [github.com/yosida95/uritemplate/v3](https://pkg.go.dev/github.com/yosida95/uritemplate/v3) ([BSD-3-Clause](https://github.com/yosida95/uritemplate/blob/v3.0.2/LICENSE)) + - [github.com/yudai/golcs](https://pkg.go.dev/github.com/yudai/golcs) ([MIT](https://github.com/yudai/golcs/blob/ecda9a501e82/LICENSE)) + - [golang.org/x/exp](https://pkg.go.dev/golang.org/x/exp) ([BSD-3-Clause](https://cs.opensource.google/go/x/exp/+/8a7402ab:LICENSE)) - [golang.org/x/sys/windows](https://pkg.go.dev/golang.org/x/sys/windows) ([BSD-3-Clause](https://cs.opensource.google/go/x/sys/+/v0.31.0:LICENSE)) - [golang.org/x/text](https://pkg.go.dev/golang.org/x/text) ([BSD-3-Clause](https://cs.opensource.google/go/x/text/+/v0.23.0:LICENSE)) + - [golang.org/x/time/rate](https://pkg.go.dev/golang.org/x/time/rate) ([BSD-3-Clause](https://cs.opensource.google/go/x/time/+/v0.5.0:LICENSE)) + - [gopkg.in/yaml.v2](https://pkg.go.dev/gopkg.in/yaml.v2) ([Apache-2.0](https://github.com/go-yaml/yaml/blob/v2.4.0/LICENSE)) - [gopkg.in/yaml.v3](https://pkg.go.dev/gopkg.in/yaml.v3) ([MIT](https://github.com/go-yaml/yaml/blob/v3.0.1/LICENSE)) [github/github-mcp-server]: https://github.com/github/github-mcp-server diff --git a/third-party/github.com/go-openapi/jsonpointer/LICENSE b/third-party/github.com/go-openapi/jsonpointer/LICENSE new file mode 100644 index 000000000..d64569567 --- /dev/null +++ b/third-party/github.com/go-openapi/jsonpointer/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/third-party/github.com/go-openapi/swag/LICENSE b/third-party/github.com/go-openapi/swag/LICENSE new file mode 100644 index 000000000..d64569567 --- /dev/null +++ b/third-party/github.com/go-openapi/swag/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/third-party/github.com/google/go-github/v69/github/LICENSE b/third-party/github.com/google/go-github/v71/github/LICENSE similarity index 100% rename from third-party/github.com/google/go-github/v69/github/LICENSE rename to third-party/github.com/google/go-github/v71/github/LICENSE diff --git a/third-party/github.com/google/go-github/v73/github/LICENSE b/third-party/github.com/google/go-github/v73/github/LICENSE new file mode 100644 index 000000000..28b6486f0 --- /dev/null +++ b/third-party/github.com/google/go-github/v73/github/LICENSE @@ -0,0 +1,27 @@ +Copyright (c) 2013 The go-github AUTHORS. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + * Neither the name of Google Inc. nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/third-party/github.com/gorilla/mux/LICENSE b/third-party/github.com/gorilla/mux/LICENSE new file mode 100644 index 000000000..6903df638 --- /dev/null +++ b/third-party/github.com/gorilla/mux/LICENSE @@ -0,0 +1,27 @@ +Copyright (c) 2012-2018 The Gorilla Authors. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + * Neither the name of Google Inc. nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/third-party/github.com/josephburnett/jd/v2/LICENSE b/third-party/github.com/josephburnett/jd/v2/LICENSE new file mode 100644 index 000000000..8e11d69d5 --- /dev/null +++ b/third-party/github.com/josephburnett/jd/v2/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2016 Joseph Burnett + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/third-party/github.com/josharian/intern/license.md b/third-party/github.com/josharian/intern/license.md new file mode 100644 index 000000000..353d3055f --- /dev/null +++ b/third-party/github.com/josharian/intern/license.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2019 Josh Bleecher Snyder + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/third-party/github.com/mailru/easyjson/LICENSE b/third-party/github.com/mailru/easyjson/LICENSE new file mode 100644 index 000000000..fbff658f7 --- /dev/null +++ b/third-party/github.com/mailru/easyjson/LICENSE @@ -0,0 +1,7 @@ +Copyright (c) 2016 Mail.Ru Group + +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/third-party/github.com/migueleliasweb/go-github-mock/src/mock/LICENSE b/third-party/github.com/migueleliasweb/go-github-mock/src/mock/LICENSE new file mode 100644 index 000000000..86d42717d --- /dev/null +++ b/third-party/github.com/migueleliasweb/go-github-mock/src/mock/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2021 Miguel Elias dos Santos + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/third-party/github.com/yudai/golcs/LICENSE b/third-party/github.com/yudai/golcs/LICENSE new file mode 100644 index 000000000..ab7d2e0fb --- /dev/null +++ b/third-party/github.com/yudai/golcs/LICENSE @@ -0,0 +1,21 @@ +The MIT License (MIT) + +Copyright (c) 2015 Iwasaki Yudai + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in +all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN +THE SOFTWARE. diff --git a/third-party/golang.org/x/exp/LICENSE b/third-party/golang.org/x/exp/LICENSE new file mode 100644 index 000000000..2a7cf70da --- /dev/null +++ b/third-party/golang.org/x/exp/LICENSE @@ -0,0 +1,27 @@ +Copyright 2009 The Go Authors. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + * Neither the name of Google LLC nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/third-party/golang.org/x/time/rate/LICENSE b/third-party/golang.org/x/time/rate/LICENSE new file mode 100644 index 000000000..6a66aea5e --- /dev/null +++ b/third-party/golang.org/x/time/rate/LICENSE @@ -0,0 +1,27 @@ +Copyright (c) 2009 The Go Authors. All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + * Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above +copyright notice, this list of conditions and the following disclaimer +in the documentation and/or other materials provided with the +distribution. + * Neither the name of Google Inc. nor the names of its +contributors may be used to endorse or promote products derived from +this software without specific prior written permission. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, +SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT +LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/third-party/gopkg.in/yaml.v2/LICENSE b/third-party/gopkg.in/yaml.v2/LICENSE new file mode 100644 index 000000000..8dada3eda --- /dev/null +++ b/third-party/gopkg.in/yaml.v2/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "{}" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright {yyyy} {name of copyright owner} + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/third-party/gopkg.in/yaml.v2/NOTICE b/third-party/gopkg.in/yaml.v2/NOTICE new file mode 100644 index 000000000..866d74a7a --- /dev/null +++ b/third-party/gopkg.in/yaml.v2/NOTICE @@ -0,0 +1,13 @@ +Copyright 2011-2016 Canonical Ltd. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy