GitHub MCP Server (Go) 使用说明

项目简介

本项目 'github-mcp-server-go' 是一个基于 Model Context Protocol (MCP) 协议的服务器端实现，使用 Go 语言开发。它旨在为 AI 助手等 MCP 客户端提供访问和操作 GitHub API 的能力，例如搜索仓库、创建仓库、管理分支、操作文件、管理 Issue 等。通过本服务，AI 助手可以安全、可控地与 GitHub 进行交互，实现代码仓库管理、项目协作等功能。

主要功能点

仓库操作: 搜索仓库、创建仓库、Fork 仓库。
分支管理: 创建分支。
文件操作: 获取文件内容、创建或更新文件、批量推送文件。
Issue 管理: 创建 Issue、获取 Issue 详情、列出 Issue、更新 Issue、添加 Issue 评论。
代码/Issue/用户搜索: 搜索代码、搜索 Issue 和 Pull Request、搜索用户。
提交记录: 获取分支的提交记录。
多种身份验证方式: 支持环境变量和 HTTP Header 两种方式配置 GitHub Personal Access Token。
Stdio 传输协议: 默认使用 Stdio 作为 MCP 通信协议。

安装步骤

安装 Go 环境: 确保您的机器上已安装 Go 1.21 或更高版本。

获取项目代码: 使用 'go get' 命令下载项目到您的 Go 工作区：

go get github.com/metoro-io/github-mcp-server-go

配置 GitHub Personal Access Token:
- 环境变量方式 (推荐): 设置名为 'GITHUB_PERSONAL_ACCESS_TOKEN' 的环境变量，值为您的 GitHub Personal Access Token。
```
export GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token
```
- HTTP Header 方式: MCP 客户端可以在发送请求时，在 HTTP Header 中包含 'Authorization' 字段来传递 Token。

运行服务器: 在项目根目录下，执行以下命令启动 MCP 服务器：

go run main.go

或者，您也可以先构建可执行文件再运行：

go build -o github-mcp-server
./github-mcp-server

服务器配置 (MCP 客户端配置)

MCP 客户端需要配置以下信息才能连接到 GitHub MCP Server：

{
  "serverName": "github-mcp-server",
  "transport": "stdio",
  "command": "github-mcp-server",  // 或者 "go run main.go" 如果您直接运行 main.go
  "args": []                      // 启动参数，本项目无需额外参数
}

配置参数说明:

'serverName': 服务器名称，可以自定义，用于在 MCP 客户端中标识该服务器。
'transport': 传输协议，本项目使用 'stdio'。
'command': 启动服务器的命令。如果已构建可执行文件，则填写可执行文件名 '"github-mcp-server"'；如果直接运行 'main.go' 文件，则填写 '"go run main.go"'。
'args': 启动命令的参数列表。本项目服务器启动无需额外命令行参数，所以为空数组 '[]'。 GitHub Personal Access Token 通过环境变量 'GITHUB_PERSONAL_ACCESS_TOKEN' 或 HTTP Header 传递，无需在此处配置。

基本使用方法

启动 MCP 客户端: 配置您的 MCP 客户端，使其能够连接到上面配置的 GitHub MCP Server。
调用工具: 在 MCP 客户端中，您可以调用服务器提供的各种工具 (Tools) 来执行 GitHub 操作。可用的工具名称及其描述如下：
- 'search_repositories': 搜索 GitHub 仓库
- 'create_repository': 在您的 GitHub 账户下创建新的仓库
- 'fork_repository': Fork 一个 GitHub 仓库到您的账户或指定的组织
- 'create_branch': 在 GitHub 仓库中创建新的分支
- 'get_file_contents': 获取 GitHub 仓库中文件或目录的内容
- 'create_or_update_file': 在 GitHub 仓库中创建或更新单个文件
- 'push_files': 在单个提交中将多个文件推送到 GitHub 仓库
- 'create_issue': 在 GitHub 仓库中创建新的 Issue
- 'get_issue': 获取 GitHub 仓库中特定 Issue 的详细信息
- 'list_issues': 列出 GitHub 仓库中的 Issue，支持过滤选项
- 'update_issue': 更新 GitHub 仓库中已存在的 Issue
- 'add_issue_comment': 为 GitHub 仓库中已存在的 Issue 添加评论
- 'list_commits': 获取 GitHub 仓库分支的提交记录列表
- 'search_code': 在 GitHub 仓库中搜索代码
- 'search_issues': 在 GitHub 仓库中搜索 Issue 和 Pull Request
- 'search_users': 搜索 GitHub 用户
参数传递: 根据您要使用的工具，MCP 客户端需要按照工具的参数定义，以 JSON 格式传递参数给 MCP 服务器。具体的参数定义请参考项目代码或 MCP 客户端的文档。

示例: 使用 'search_repositories' 工具搜索仓库 (假设 MCP 客户端已配置并连接到服务器)

MCP 客户端发送类似以下的 JSON-RPC 请求 (具体格式取决于 MCP 客户端的实现):

{
  "method": "call_tool",
  "params": {
    "tool_name": "search_repositories",
    "tool_args": {
      "query": "topic:mcp language:go"
    }
  }
}

服务器会执行 'search_repositories' 工具，并返回搜索结果给 MCP 客户端。

注意事项

确保您配置的 GitHub Personal Access Token 具有执行所需 GitHub API 操作的权限。
本服务器默认使用 Stdio 传输协议，适用于本地或命令行环境下的 MCP 客户端。
本项目仅实现了 MCP 协议的工具 (Tools) 功能，资源 (Resources) 和 Prompt 模板 (Prompts) 功能可能需要根据 MCP 客户端的需求进行扩展。

关键词