使用说明

项目简介

本项目是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为大型语言模型（LLM）应用提供访问和操作 GitHub 资源的标准化接口。它允许LLM通过预定义的工具集与GitHub进行交互，实现代码库管理、文件操作、Issue和Pull Request管理、以及代码和用户搜索等功能。

主要功能点

自动化分支管理：在创建或更新文件时，如果分支不存在则自动创建。
全面的错误处理：提供清晰的错误信息，方便问题排查。
保留Git历史：所有操作都维护完整的Git历史记录。
批量操作：支持单文件和多文件批量操作，提高效率。
高级搜索：支持代码、Issue/PR 和用户搜索，满足多样化信息检索需求。
丰富的工具集: 提供20多个工具，涵盖了GitHub API的常用功能，例如：
- 文件操作：创建、更新、获取文件内容、推送文件
- 代码库操作：创建代码库、Fork代码库、搜索代码库
- 分支管理：创建分支、列出提交
- Issue管理：创建、更新、列出、搜索Issue，添加评论
- Pull Request管理：创建、获取、列出、搜索Pull Request，创建/获取评论和Review，合并PR，获取PR文件列表和状态

安装步骤

前提条件：确保已安装 Node.js 和 npm (或 yarn)。如果使用 Docker，请确保已安装 Docker。
获取代码：从 GitHub 克隆仓库代码到本地。
安装依赖：在仓库根目录下，运行 'npm install' 或 'yarn install' 安装项目依赖。

服务器配置

MCP客户端需要配置 MCP 服务器的启动命令 (command) 及其参数 (args) 才能与MCP服务器建立连接。以下是 Claude Desktop 的 'claude_desktop_config.json' 配置文件示例，用于配置本 GitHub MCP 服务器。请根据您的实际使用环境选择 Docker 或 NPX 方式配置，并替换 '<YOUR_TOKEN>' 为您自己的 GitHub Personal Access Token。

重要提示：您需要先创建 GitHub Personal Access Token，并赋予 'repo' 权限 (或 'public_repo' 权限，如果仅操作公开仓库)。

配置示例 1: 使用 Docker 运行

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITHUB_PERSONAL_ACCESS_TOKEN",
        "mcp/github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

'command': 指定运行的命令为 'docker'。
'args': Docker 命令行参数，包括：
- 'run': 运行一个新的容器。
- '-i': 保持标准输入 (STDIN) 打开，即使没有连接。
- '--rm': 容器退出时自动删除容器。
- '-e GITHUB_PERSONAL_ACCESS_TOKEN': 设置环境变量 'GITHUB_PERSONAL_ACCESS_TOKEN'，用于传递 GitHub Personal Access Token。
- 'mcp/github': Docker 镜像名称，假设您已按照仓库 'README.md' 中的 Docker build 命令构建了名为 'mcp/github' 的镜像。
'env': 环境变量配置，'GITHUB_PERSONAL_ACCESS_TOKEN' 的值需要替换为您的实际 Token。

配置示例 2: 使用 NPX 运行

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

'command': 指定运行的命令为 'npx'。
'args': NPX 命令行参数，包括：
- '-y': 自动确认安装软件包。
- '@modelcontextprotocol/server-github': 要运行的 npm 包，这里假设您已将项目发布为 '@modelcontextprotocol/server-github' (根据 'README.md'，实际可能需要您手动构建 Docker 镜像或使用 'npm link' 等方式)。
'env': 环境变量配置，'GITHUB_PERSONAL_ACCESS_TOKEN' 的值需要替换为您的实际 Token。

基本使用方法

启动服务器：
- Docker: 确保 Docker 已经启动，并根据上述配置在 MCP 客户端中配置 Docker 运行方式。
- NPX: 确保 Node.js 环境配置正确，并根据上述配置在 MCP 客户端中配置 NPX 运行方式。
在 MCP 客户端中使用：
- 在支持 MCP 协议的 LLM 客户端 (如 Claude Desktop) 中配置并连接到本 GitHub MCP 服务器。
- 通过自然语言指令，指示 LLM 调用 GitHub 相关工具，例如：
  - "创建一个名为 'my-new-repo' 的公开代码库。"
  - "在 'owner/repo' 代码库的 'main' 分支下，创建一个名为 'test.txt'，内容为 'Hello, GitHub MCP Server!' 的文件。"
  - "搜索 GitHub 上关于 '自然语言处理' 的代码库。"
  - "列出 'owner/repo' 代码库中所有打开的 Issue。"
- LLM 将根据指令调用相应的工具，并将 GitHub API 返回的结果以自然语言形式呈现给用户。

请注意，本服务器仅作为 MCP 服务器提供 GitHub API 的工具接口，实际的功能调用和结果展示依赖于 MCP 客户端和 LLM 的能力。

关键词