使用说明

项目简介

本项目 'MCP-Github-Oauth' 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型 (LLM) 应用提供访问 GitHub 数据的能力。通过此 MCP 服务器，LLM 可以安全、便捷地获取用户的 GitHub 仓库信息和个人资料，从而扩展 LLM 在软件开发、知识管理等领域的应用场景。

主要功能点

GitHub OAuth 授权: 支持用户通过 GitHub OAuth 流程授权应用访问其 GitHub 账户。
获取 Access Token: 通过授权码交换获取 GitHub API 的 Access Token，用于后续 API 请求的身份验证。
获取用户仓库列表: 允许 LLM 获取已授权用户的 GitHub 仓库列表，包括仓库名称、URL 和编程语言等信息。
获取用户个人资料: 允许 LLM 获取已授权用户的 GitHub 个人资料，包括用户名、姓名、邮箱、公开仓库数量、关注者、关注列表以及个人主页 URL 等信息。

安装步骤

安装 uv: 根据您的操作系统，运行以下命令安装 'uv' 包管理器 (如果已安装 uv，请跳过此步骤)。

# MacOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后，请重启您的终端，确保 'uv' 命令可以被识别。

克隆仓库: 使用 'git clone' 命令将 'MCP-Github-Oauth' 仓库克隆到本地。

git clone https://github.com/Nikhil-Patil-RI/MCP-Github-Oauth.git
cd MCP-Github-Oauth

创建并激活虚拟环境: 使用 'uv' 创建并激活 Python 虚拟环境。

uv venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate  # Windows

安装依赖: 使用 'uv pip install' 安装项目依赖。
```
uv pip install -r requirements.txt
```
仓库中没有 requirements.txt 文件，但根据代码逻辑和 'fastmcp' 的依赖，可能需要手动创建 requirements.txt 文件，并添加 'fastmcp', 'httpx', 'python-dotenv' 等依赖。 实际上，根据 'uv run server.py' 的命令，可能不需要 requirements.txt，uv 可以自动处理。
配置环境变量:
- 在项目根目录下创建 '.env' 文件。
- 在 '.env' 文件中配置 GitHub OAuth 应用的 'CLIENT_ID' 和 'CLIENT_SECRET'。
```
CLIENT_ID=YOUR_GITHUB_CLIENT_ID
CLIENT_SECRET=YOUR_GITHUB_CLIENT_SECRET
```
  请替换 'YOUR_GITHUB_CLIENT_ID' 和 'YOUR_GITHUB_CLIENT_SECRET' 为您在 GitHub 开发者设置中创建的 OAuth App 的 Client ID 和 Client Secret。 Redirect URI 需要设置为 'http://localhost:8080/callback'。

服务器配置

要将此 MCP 服务器配置到 MCP 客户端（例如 Claude 桌面应用），您需要提供服务器的启动命令和参数。以下是配置信息（JSON 格式），请根据您的实际环境调整路径：

{
  "mcpServers": {
    "Github-Oauth": {
      "command": "uv",  // 启动命令，这里使用 uv 包管理器
      "args": [
        "--directory",  // 指定工作目录
        "/path/to/MCP-Github-Oauth/src/github_oauth", // 替换为您的 github_oauth 目录的绝对路径
        "run",          // uv 的 run 命令，用于运行 Python 脚本
        "server.py"     // 服务器脚本名称
      ]
    }
  }
}

配置参数说明:

'"Github-Oauth"': 服务器名称，您可以自定义。
'"command": "uv"': 指定用于启动服务器的命令为 'uv' 包管理器。确保您的 MCP 客户端环境可以访问到 'uv' 命令。如果 'uv' 不在全局 PATH 中，您可能需要提供 'uv' 的完整路径。
'"args"': 启动参数列表。
- '"--directory"': 指定服务器的工作目录为 '/path/to/MCP-Github-Oauth/src/github_oauth'。请务必将 '/path/to/MCP-Github-Oauth' 替换为您本地仓库的实际绝对路径。
- '"run"': 'uv run' 命令指示 uv 运行后面的 Python 脚本。
- '"server.py"': 指定要运行的 Python 服务器脚本为 'server.py'。

Claude 桌面应用配置示例:

您可以按照 README.md 中的指引，修改 Claude 桌面应用的配置文件 'claude_desktop_config.json'，将上述 JSON 配置添加到 'mcpServers' 字段中。

Windows: 'code $env:AppData\Claude\claude_desktop_config.json'
Mac/Linux: 'code ~/Library/Application\ Support/Claude/claude_desktop_config.json'

基本使用方法

启动 MCP 服务器: 在克隆仓库的根目录下，激活虚拟环境后，运行服务器脚本。
```
uv run src/github_oauth/server.py
```
或者，如果您已经配置好 'claude_desktop_config.json'，Claude 桌面应用在启动时会自动启动配置的 MCP 服务器。
在 LLM 客户端中使用工具:
- 连接到 MCP 服务器后，LLM 客户端应该能够发现并调用以下工具 (Tools):
  - 'authorize_github': 获取 GitHub 授权 URL，用户需要访问此 URL 完成授权。
  - 'get_access_token_from_code': 使用授权码交换 Access Token。在用户完成 GitHub 授权后，需要将授权码提供给 LLM，由 LLM 调用此工具获取 Access Token。
  - 'get_user_repositories': 获取已授权用户的 GitHub 仓库列表。
  - 'get_user_profile': 获取已授权用户的 GitHub 个人资料。
授权流程:
- LLM 调用 'authorize_github' 工具，获取授权 URL 并呈现给用户。
- 用户访问授权 URL，完成 GitHub OAuth 授权。
- GitHub 会将用户重定向到 'http://localhost:8080/callback'，并在 URL 中包含授权码 (code)。
- 用户需要将此授权码复制并提供给 LLM。
- LLM 调用 'get_access_token_from_code' 工具，并将授权码作为参数传递，以获取 Access Token。
- 成功获取 Access Token 后，LLM 就可以调用 'get_user_repositories' 和 'get_user_profile' 等工具来访问用户的 GitHub 数据了。

注意: 此 MCP 服务器使用标准输入输出 (stdio) 作为传输协议。确保您的 MCP 客户端支持 stdio 协议的 MCP 服务器。

关键词