GitLab GraphQL MCP 服务器

关键词

GitLabGraphQL APILLM插件资源访问工具

使用说明

项目简介

'GitLab GraphQL MCP 服务器' 是一个基于 Model Context Protocol (MCP) 框架开发的后端服务，旨在为大型语言模型 (LLM) 提供访问 GitLab 实例的能力。通过此服务，LLM 可以安全地查询 GitLab 资源，例如项目、用户、合并请求等，并利用缓存机制提高效率。该服务器作为一个 MCP 插件，可以方便地集成到支持 MCP 协议的 LLM 客户端，例如 Claude。

主要功能点

  • GitLab GraphQL API 集成: 无缝对接 GitLab GraphQL API，支持强大的数据查询能力。
  • 项目数据掩码: 根据项目可见性自动处理敏感数据，提供多种掩码模式（简单模式和内容模式）以保护私有项目信息。
  • 智能 URL 处理: 自动识别并保留 GitLab 域名 URL，同时对非 GitLab 敏感 URL 进行掩码处理。
  • 高效缓存管理: 缓存项目可见性状态，减少不必要的 API 请求，提升性能。
  • 灵活查询支持: 支持查询各种 GitLab 资源，包括项目、用户、群组、合并请求等。
  • 资源访问: 提供 'file://' 协议的资源访问，允许 LLM 引用之前检索到的 GitLab 数据，增强对话连贯性。

安装步骤

  1. 安装依赖: 确保已安装 Node.js 和 npm，然后克隆仓库到本地并进入项目目录，运行命令安装项目依赖： 
    npm install
  2. 构建项目: 运行命令构建项目，将 TypeScript 代码编译为 JavaScript 代码： 
    npm run build
  3. 启动服务: 配置好环境变量后，运行命令启动 MCP 服务器： 
    npm run start

服务器配置

MCP 服务器需要配置以下环境变量才能正常连接到 GitLab 实例：

  • 'GITLAB_API_URL': GitLab 实例的 API 地址。例如：'https://your-gitlab-instance.com'。请替换为您的 GitLab 实例地址。
  • 'GITLAB_TOKEN': GitLab 访问令牌。需要具有访问 GitLab API 的权限。请在 GitLab 中生成个人访问令牌并替换此处。
  • 'GITLAB_MASK_MODE': 掩码模式，可选值 'simple' 或 'content'。
    • 'simple': (默认) 私有项目仅返回 id, name, webUrl 和 visibility 字段，其他信息完全隐藏。
    • 'content': 私有项目返回所有字段，但敏感内容（如路径、描述、用户名等）会被 "***" 掩码。

为了让 MCP 客户端（如 Claude）连接到此服务器，您需要在客户端的配置文件中添加服务器配置信息。以 Claude Desktop Client 为例，配置信息如下 (请根据您的MCP客户端实际要求进行配置)：

{
  "mcpServers": {
    "@zephyr-mcp/gitlab-gql": {  // server name：服务器名称，用于在客户端中标识和引用
      "command": "npx",         // command： 启动服务器的命令，这里使用 npx 运行 @zephyr-mcp/gitlab-gql 包
      "args": ["-y", "@zephyr-mcp/gitlab-gql"] // args： 启动命令的参数，'-y' 表示自动确认执行包，'@zephyr-mcp/gitlab-gql' 是 package.json 中配置的启动入口
      // 注意： 实际部署时，如果将服务发布到 npm，可以直接使用包名作为 server name 和 args。
      // 如果是本地开发或直接运行，可能需要调整 command 和 args 以指向正确的启动脚本。
    }
  }
}

配置说明（重要）:

  • 'server name' (服务器名称): '"@zephyr-mcp/gitlab-gql"' 是为此 MCP 服务器定义的名字，客户端会通过这个名字来识别和调用它。您可以自定义名称，但需要与客户端配置保持一致。
  • 'command' (启动命令): '"npx"' 表示使用 'npx' 命令来执行后续的包。'npx' 是 npm 包管理器自带的工具，用于方便地运行本地或远程的 npm 包。
  • 'args' (启动参数): '["-y", "@zephyr-mcp/gitlab-gql"]' 是传递给 'npx' 命令的参数。
    • '"-y"': 是 'npx' 的参数，表示 "yes"，用于自动确认执行 npm 包，避免在启动时出现交互式提示。
    • '"@zephyr-mcp/gitlab-gql"': 指定要 'npx' 运行的 npm 包名称。 由于 'package.json' 中配置了 'bin' 字段，指向了服务器的入口文件 ('src/index.ts')，'npx' 可以找到并执行服务器代码。

请根据您的 MCP 客户端的具体配置要求，调整上述 JSON 配置。 关键是确保 'command' 和 'args' 能正确启动 'GitLab GraphQL MCP 服务器'。

基本使用方法

  1. 启动 MCP 服务器: 按照上述安装步骤和服务器配置启动 'GitLab GraphQL MCP 服务器'。
  2. 配置 MCP 客户端: 在支持 MCP 协议的 LLM 客户端 (例如 Claude) 中，根据客户端的指引配置 MCP 服务器连接。通常需要提供服务器名称 (例如 '"@zephyr-mcp/gitlab-gql"') 和启动命令 (如上面 'claude_desktop_config.json' 中的配置)。
  3. 在 LLM 中使用: 配置完成后，LLM 应该能够通过 MCP 协议与 'GitLab GraphQL MCP 服务器' 通信。您可以指示 LLM 使用 'gitlab_gql' 工具执行 GraphQL 查询，或者使用 'file' 资源访问缓存的 GitLab 数据。

工具调用示例 (在 LLM 客户端中指示模型执行 Tool Call):

  • 搜索项目: 让 LLM 调用 'gitlab_gql' 工具，并提供如下参数： 
    {
  "tool_call": {
    "name": "gitlab_gql",
    "arguments": {
      "query": "{projects(search: \\"project name\\") { nodes { id name webUrl visibility } }}",
      "queryType": "projects"
    }
  }
}
  • 获取特定项目: 
    {
  "tool_call": {
    "name": "gitlab_gql",
    "arguments": {
      "query": "{project(fullPath: \\"namespace/project\\") { id name webUrl visibility }}",
      "queryType": "project",
      "projectPath": "namespace/project"
    }
  }
}
  • 访问缓存文件: 让 LLM 使用 'file' 资源读取缓存文件内容： 
    resource:///file:///.cache/gitlab-projects-cache.json
    或使用更灵活的路径： 
    resource:///file:///{cwd}/.cache/gitlab-projects-cache.json

请参考仓库的 'README.md' 和代码注释，了解更多工具和资源的详细使用方法和参数说明。

服务器信息

访问项目