Merge branch 'main' into read-only

Author: SamMorrowDrums

.github/workflows/docker-publish.yml

@@ -0,0 +1,98 @@
+name: Docker
+
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+on:
+  schedule:
+    - cron: '27 0 * * *'
+  push:
+    branches: [ "main" ]
+    # Publish semver tags as releases.
+    tags: [ 'v*.*.*' ]
+  pull_request:
+    branches: [ "main" ]
+
+env:
+  # Use docker.io for Docker Hub if empty
+  REGISTRY: ghcr.io
+  # github.repository as <account>/<repo>
+  IMAGE_NAME: ${{ github.repository }}
+
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+      # This is used to complete the identity challenge
+      # with sigstore/fulcio when running outside of PRs.
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Install the cosign tool except on PR
+      # https://github.com/sigstore/cosign-installer
+      - name: Install cosign
+        if: github.event_name != 'pull_request'
+        uses: sigstore/cosign-installer@59acb6260d9c0ba8f4a2f9d9b48431a222b68e20 #v3.5.0
+        with:
+          cosign-release: 'v2.2.4'
+
+      # Set up BuildKit Docker container builder to be able to build
+      # multi-platform images and export cache
+      # https://github.com/docker/setup-buildx-action
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@f95db51fddba0c2d1ec667646a06c2ce06100226 # v3.0.0
+
+      # Login against a Docker registry except on PR
+      # https://github.com/docker/login-action
+      - name: Log into registry ${{ env.REGISTRY }}
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@343f7c4344506bcbf9b4de18042ae17996df046d # v3.0.0
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      # Extract metadata (tags, labels) for Docker
+      # https://github.com/docker/metadata-action
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@96383f45573cb7f253c731d3b3ab81c87ef81934 # v5.0.0
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+
+      # Build and push Docker image with Buildx (don't push on PR)
+      # https://github.com/docker/build-push-action
+      - name: Build and push Docker image
+        id: build-and-push
+        uses: docker/build-push-action@0565240e2d4ab88bba5387d719585280857ece09 # v5.0.0
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      # Sign the resulting Docker image digest except on PRs.
+      # This will only write to the public Rekor transparency log when the Docker
+      # repository is public to avoid leaking data.  If you would like to publish
+      # transparency data even for private images, pass --force to cosign below.
+      # https://github.com/sigstore/cosign
+      - name: Sign the published Docker image
+        if: ${{ github.event_name != 'pull_request' }}
+        env:
+          # https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-an-intermediate-environment-variable
+          TAGS: ${{ steps.meta.outputs.tags }}
+          DIGEST: ${{ steps.build-and-push.outputs.digest }}
+        # This step uses the identity token to provision an ephemeral certificate
+        # against the sigstore community Fulcio instance.
+        run: echo "${TAGS}" | xargs -I {} cosign sign --yes {}@${DIGEST}

README.md

@@ -22,13 +22,34 @@ and set it as the GITHUB_PERSONAL_ACCESS_TOKEN environment variable.
   - `repo`: Repository name (string, required)
   - `issue_number`: Issue number (number, required)
 
+- **create_issue** - Create a new issue in a GitHub repository
+
+  - `owner`: Repository owner (string, required)
+  - `repo`: Repository name (string, required)
+  - `title`: Issue title (string, required)
+  - `body`: Issue body content (string, optional)
+  - `assignees`: Comma-separated list of usernames to assign to this issue (string, optional)
+  - `labels`: Comma-separated list of labels to apply to this issue (string, optional)
+
 - **add_issue_comment** - Add a comment to an issue
 
   - `owner`: Repository owner (string, required)
   - `repo`: Repository name (string, required)
   - `issue_number`: Issue number (number, required)
   - `body`: Comment text (string, required)
 
+- **list_issues** - List and filter repository issues
+
+  - `owner`: Repository owner (string, required)
+  - `repo`: Repository name (string, required)
+  - `state`: Filter by state ('open', 'closed', 'all') (string, optional)
+  - `labels`: Comma-separated list of 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)
+  - `per_page`: Results per page (number, optional)
+
 - **search_issues** - Search for issues and pull requests
   - `query`: Search query (string, required)
   - `sort`: Sort field (string, optional)
@@ -267,6 +288,36 @@ GitHub MCP Server running on stdio
 
 ```
 
+## i18n / Overriding descriptions
+
+The descriptions of the tools can be overridden by creating a github-mcp-server.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.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"
+```
+
 ## Testing on VS Code Insiders
 
 First of all, install `github-mcp-server` with:
@@ -313,16 +364,14 @@ Lots of things!
 Missing tools:
 
 - push_files (files array)
-- create_issue (assignees and labels arrays)
 - list_issues (labels array)
 - update_issue (labels and assignees arrays)
 - create_pull_request_review (comments array)
 
 Testing
 
-- Unit tests
 - Integration tests
-- Blackbox testing: ideally comparing output to Anthromorphic's server to make sure that this is a fully compatible drop-in replacement.
+- Blackbox testing: ideally comparing output to Anthropic's server to make sure that this is a fully compatible drop-in replacement.
 
 And some other stuff:
 

cmd/github-mcp-server/main.go

@@ -11,6 +11,7 @@ import (
 
 	"github.com/github/github-mcp-server/pkg/github"
 	iolog "github.com/github/github-mcp-server/pkg/log"
+	"github.com/github/github-mcp-server/pkg/translations"
 	gogithub "github.com/google/go-github/v69/github"
 	"github.com/mark3labs/mcp-go/server"
 	log "github.com/sirupsen/logrus"
@@ -37,7 +38,7 @@ var (
 				stdlog.Fatal("Failed to initialize logger:", err)
 			}
 			logCommands := viper.GetBool("enable-command-logging")
-			if err := runStdioServer(readOnly, logger, logCommands); err != nil {
+			if err := runStdioServer(readOnly, logger, logCommands, viper.GetBool("export-translations")); err != nil {
 				stdlog.Fatal("failed to run stdio server:", err)
 			}
 		},
@@ -51,11 +52,13 @@ func init() {
 	rootCmd.PersistentFlags().Bool("read-only", false, "Restrict the server to read-only operations")
 	rootCmd.PersistentFlags().String("log-file", "", "Path to log file")
 	rootCmd.PersistentFlags().Bool("enable-command-logging", false, "When enabled, the server will log all command requests and responses to the log file")
+	rootCmd.PersistentFlags().Bool("export-translations", false, "Save translations to a JSON file")
 
 	// Bind flag to viper
 	viper.BindPFlag("read-only", rootCmd.PersistentFlags().Lookup("read-only"))
 	viper.BindPFlag("log-file", rootCmd.PersistentFlags().Lookup("log-file"))
 	viper.BindPFlag("enable-command-logging", rootCmd.PersistentFlags().Lookup("enable-command-logging"))
+	viper.BindPFlag("export-translations", rootCmd.PersistentFlags().Lookup("export-translations"))
 
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)
@@ -84,7 +87,7 @@ func initLogger(outPath string) (*log.Logger, error) {
 	return logger, nil
 }
 
-func runStdioServer(readOnly bool, logger *log.Logger, logCommands bool) error {
+func runStdioServer(readOnly bool, logger *log.Logger, logCommands bool, exportTranslations bool) error {
 	// Create app context
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
 	defer stop()
@@ -96,13 +99,20 @@ func runStdioServer(readOnly bool, logger *log.Logger, logCommands bool) error {
 	}
 	ghClient := gogithub.NewClient(nil).WithAuthToken(token)
 
-	// Create
-	ghServer := github.NewServer(ghClient, readOnly)
+	t, dumpTranslations := translations.TranslationHelper()
+
+	// Create server
+	ghServer := github.NewServer(ghClient, readOnly, t)
 	stdioServer := server.NewStdioServer(ghServer)
 
 	stdLogger := stdlog.New(logger.Writer(), "stdioserver", 0)
 	stdioServer.SetErrorLogger(stdLogger)
 
+	if exportTranslations {
+		// Once server is initialized, all translations are loaded
+		dumpTranslations()
+	}
+
 	// Start listening for messages
 	errC := make(chan error, 1)
 	go func() {

pkg/github/code_scanning.go

@@ -7,14 +7,15 @@ import (
 	"io"
 	"net/http"
 
+	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/google/go-github/v69/github"
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
 )
 
-func getCodeScanningAlert(client *github.Client) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func getCodeScanningAlert(client *github.Client, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("get_code_scanning_alert",
-			mcp.WithDescription("Get details of a specific code scanning alert in a GitHub repository."),
+			mcp.WithDescription(t("TOOL_GET_CODE_SCANNING_ALERT_DESCRIPTION", "Get details of a specific code scanning alert in a GitHub repository.")),
 			mcp.WithString("owner",
 				mcp.Required(),
 				mcp.Description("The owner of the repository."),
@@ -56,9 +57,9 @@ func getCodeScanningAlert(client *github.Client) (tool mcp.Tool, handler server.
 		}
 }
 
-func listCodeScanningAlerts(client *github.Client) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func listCodeScanningAlerts(client *github.Client, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_code_scanning_alerts",
-			mcp.WithDescription("List code scanning alerts in a GitHub repository."),
+			mcp.WithDescription(t("TOOL_LIST_CODE_SCANNING_ALERTS_DESCRIPTION", "List code scanning alerts in a GitHub repository.")),
 			mcp.WithString("owner",
 				mcp.Required(),
 				mcp.Description("The owner of the repository."),

pkg/github/code_scanning_test.go

@@ -6,6 +6,7 @@ import (
 	"net/http"
 	"testing"
 
+	"github.com/github/github-mcp-server/pkg/translations"
 	"github.com/google/go-github/v69/github"
 	"github.com/migueleliasweb/go-github-mock/src/mock"
 	"github.com/stretchr/testify/assert"
@@ -15,7 +16,7 @@ import (
 func Test_GetCodeScanningAlert(t *testing.T) {
 	// Verify tool definition once
 	mockClient := github.NewClient(nil)
-	tool, _ := getCodeScanningAlert(mockClient)
+	tool, _ := getCodeScanningAlert(mockClient, translations.NullTranslationHelper)
 
 	assert.Equal(t, "get_code_scanning_alert", tool.Name)
 	assert.NotEmpty(t, tool.Description)
@@ -81,7 +82,7 @@ func Test_GetCodeScanningAlert(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			// Setup client with mock
 			client := github.NewClient(tc.mockedClient)
-			_, handler := getCodeScanningAlert(client)
+			_, handler := getCodeScanningAlert(client, translations.NullTranslationHelper)
 
 			// Create call request
 			request := createMCPRequest(tc.requestArgs)
@@ -117,7 +118,7 @@ func Test_GetCodeScanningAlert(t *testing.T) {
 func Test_ListCodeScanningAlerts(t *testing.T) {
 	// Verify tool definition once
 	mockClient := github.NewClient(nil)
-	tool, _ := listCodeScanningAlerts(mockClient)
+	tool, _ := listCodeScanningAlerts(mockClient, translations.NullTranslationHelper)
 
 	assert.Equal(t, "list_code_scanning_alerts", tool.Name)
 	assert.NotEmpty(t, tool.Description)
@@ -194,7 +195,7 @@ func Test_ListCodeScanningAlerts(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			// Setup client with mock
 			client := github.NewClient(tc.mockedClient)
-			_, handler := listCodeScanningAlerts(client)
+			_, handler := listCodeScanningAlerts(client, translations.NullTranslationHelper)
 
 			// Create call request
 			request := createMCPRequest(tc.requestArgs)