关键词

GitHub GraphQL APIAI Agent 工具开发者服务数据查询服务外部功能调用

项目简介

这是一个基于 Model Context Protocol (MCP) 实现的服务器端应用。它的核心功能是作为LLM客户端（如AI助手）与 GitHub GraphQL API 之间的桥梁。通过这个服务器，AI可以调用一个特定的工具，向GitHub发起任何有效的GraphQL查询或mutation请求，获取仓库、用户信息、代码等数据，甚至执行某些操作（如创建Issue），极大地扩展了AI在GitHub生态中的能力。

主要功能点

  • 强大的GitHub访问能力： 提供一个统一的工具接口，允许AI直接执行GitHub GraphQL API支持的任何查询或修改操作。
  • 灵活的数据获取： AI可以根据需要构造特定的GraphQL查询，精确获取所需数据，避免过度抓取，提高效率。
  • 支持变量： 支持在GraphQL查询中使用变量，使得操作更加灵活和参数化。
  • 错误处理和报告： 服务器会处理GitHub API的响应，包括错误信息，并返回给AI，便于AI理解和应对问题。
  • 集成能力： 设计为可被任何支持MCP协议的LLM客户端集成和调用。

安装步骤

  1. 克隆仓库： 将项目的代码克隆到本地计算机上的一个目录。 
    git clone https://github.com/QuentinCody/github-graphql-mcp-server.git
cd github-graphql-mcp-server
  2. 创建并激活虚拟环境： 推荐使用Python虚拟环境隔离项目依赖。 
    # 在 macOS/Linux 上
python3 -m venv .venv
source .venv/bin/activate

# 在 Windows 上
python -m venv .venv
.venv\Scripts\activate
  3. 安装依赖： 安装运行服务器所需的Python库。 
    pip install -r requirements.txt
  4. 获取GitHub Personal Access Token (PAT)： 你需要一个GitHub PAT来认证API请求。请确保该Token具有执行所需操作（如读取仓库信息、创建Issue）的权限。参考GitHub官方文档创建PAT。

服务器配置（供MCP客户端使用）

MCP客户端（如特定的AI应用）需要知道如何启动并连接到这个服务器。通常，这通过在客户端的配置文件中指定服务器的启动命令、参数和环境变量来实现。

你需要告诉你的MCP客户端：

  1. 服务器名称 (server name): 这个服务器的唯一标识符，例如 'github-graphql'。
  2. 启动命令 (command): 运行服务器脚本的Python解释器的绝对路径。推荐使用你在安装步骤中创建的虚拟环境中的Python路径（例如，'/path/to/your/repository/.venv/bin/python' 或 'C:\path\to\your\repository.venv\Scripts\python.exe'）。
  3. 启动参数 (args): 传递给Python解释器的参数。第一个参数应该是服务器脚本文件的绝对路径（例如，'/path/to/your/repository/github_graphql_mcp_server.py'）。
  4. 环境变量 (env): 设置名为 'GITHUB_TOKEN' 的环境变量，其值就是你获取的GitHub Personal Access Token。这是服务器用来认证GitHub API请求的关键信息。

配置示例（请根据你的实际路径和Token填写）：

  • 'server name': 'github-graphql'
  • 'command': 指向虚拟环境中的 'python' 或 'python.exe' 的绝对路径。
  • 'args': 包含服务器脚本文件 'github_graphql_mcp_server.py' 的绝对路径。
  • 'env': 设置 'GITHUB_TOKEN' 环境变量为你的 GitHub PAT。

基本使用方法

服务器通过标准输入/输出（stdio）与MCP客户端通信。一旦你的MCP客户端配置并启动了这个服务器，客户端就能发现并调用服务器提供的工具。

这个服务器暴露了一个名为 'github_execute_graphql' 的工具。AI客户端可以通过MCP协议调用这个工具，并向其提供两个参数：

  1. 'query' (字符串): 你想要执行的完整GitHub GraphQL查询或mutation语句。
  2. 'variables' (字典, 可选): 如果你的查询使用了变量，需要提供一个JSON对象或Python字典，其中包含变量名和对应的值。

服务器接收到调用请求后，会使用你的GitHub Token向GitHub GraphQL API发起HTTP请求，然后将GitHub API返回的完整的JSON响应（包含数据和任何错误信息）封装并通过MCP协议返回给客户端。AI客户端可以解析这个JSON响应来获取所需的数据或处理错误。

例如，如果AI想要获取一个仓库的信息，它可能会调用 'github_execute_graphql' 工具，其中 'query' 参数是类似 'query GetRepo($owner: String!, $name: String!) { repository(owner: $owner, name: $name) { name description url } }' 的字符串，而 'variables' 参数是 '{ "owner": "octocat", "name": "Hello-World" }' 这样的字典。服务器执行后会将GitHub的响应（包含仓库名称、描述、URL等）返回给AI。

确保你的GitHub Token拥有执行相应GraphQL操作所需的权限。

信息

分类

开发者工具

访问项目