Mcp Github Advanced Search

GitHub 高级搜索 MCP 服务（G.A.S.）

一个功能强大的模型上下文协议（MCP）服务，可让大模型执行高级 GitHub 代码搜索，并具备智能筛选和内容检索能力，针对 DeepSeek 集成进行了优化。

🔍 概述

GitHub 高级搜索（G.A.S.）MCP 服务为大模型提供了复杂的 GitHub 搜索能力，突破标准 API 的限制。它使用 Playwright 进行网页自动化，可在整个 GitHub 生态系统中深入发现代码、分析模式并检索内容。此版本增强了对 DeepSeek 模型的支持，可提供量身定制的搜索结果和结构化 JSON 输出。

演示

使用 vscode + cline + openrouter:deepseek/deepseek-r1-0528:free 进行测试

演示视频链接

示例 1

# step1: init gas
gas_entrypoint

# step2: feed model
gas_search_code
file_name: clinerules

# step3: make your wish
You are now have better knowledge of `clinerules`
please keep the current file format and deep level
enhance the `<file-path-to-clinerules>`

主要功能

• 🔍 高级 GitHub 搜索：按关键词、文件名和复杂筛选条件搜索
• 📁 内容检索：自动获取并返回文件内容
• 🤖 大模型集成：与 Claude、GPT 及其他兼容 MCP 的大模型无缝集成
• 🔄 分页支持：通过智能分页处理大量结果
• 🌐 网页自动化：使用 Playwright 实现可靠的 GitHub 交互
• 📊 结构化结果：返回包含仓库链接、文件链接和内容的有序 JSON 数据
• ⚡ 高性能：异步操作，并发下载文件
• 🔐 身份验证支持：支持使用 GitHub 登录来访问私有仓库
• 🤖 DeepSeek 集成：针对 DeepSeek 模型进行了优化，可提供量身定制的搜索结果和结构化 JSON 输出

🏗️ 架构

graph TB
    subgraph "MCP Client (LLM)"
        A[Claude/GPT/Other LLM]
    end

    subgraph "MCP Server (G.A.S.)"
        B[MCP Server]
        C[Search Engine]
        D[Playwright Browser]
        E[Content Fetcher]
        F[Result Processor]
    end

    subgraph "GitHub"
        G[GitHub Search]
        H[Repository Files]
        I[Raw Content]
    end

    A -->|MCP Protocol| B
    B --> C
    C --> D
    D -->|Web Automation| G
    G -->|Search Results| D
    D --> E
    E -->|HTTP Requests| I
    I -->|File Content| E
    E --> F
    F -->|Structured Data| B
    B -->|JSON Response| A

    classDef client fill:#e1f5fe,stroke:#01579b,color:#01579b
    classDef server fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef github fill:#f3e5f5,stroke:#4a148c,color:#4a148c

    class A client
    class B,C,D,E,F server
    class G,H,I github

🔄 搜索工作流

sequenceDiagram
    participant LLM as LLM Client
    participant MCP as MCP Server
    participant PW as Playwright Browser
    participant GH as GitHub Search
    participant API as GitHub Raw API

    LLM->>MCP: gas_search_code(keyword, file_name)
    MCP->>PW: Launch browser session
    PW->>GH: Navigate to search URL
    GH-->>PW: Search results page
    PW->>PW: Extract repository & file links

    loop For each page
        PW->>GH: Navigate to page N
        GH-->>PW: Results for page N
        PW->>PW: Extract links from page
    end

    MCP->>API: Fetch file contents (async)
    API-->>MCP: Raw file content
    MCP->>MCP: Structure response data
    MCP-->>LLM: JSON with repositories, files & content

    alt More results available
        LLM->>MCP: get_remaining_result(start_id)
        MCP-->>LLM: Next batch of results
    end

🚀 快速开始

前提条件

• Python 3.10 或更高版本
• Node.js（用于 Playwright 浏览器自动化）
• GitHub 账号（建议使用，以获得最佳功能体验）

安装

1. 安装软件包：

   pip install mcp-server-git-gas
   

2. 安装 Playwright 浏览器：

   playwright install chromium
   

3. 💀未经测试 配置 MCP 客户端（例如 claude desktop）：

   添加到你的 claude_desktop_config.json：

   # not tested !!!
   {
     "mcpServers": {
       "github-advanced-search": {
         "command": "mcp-server-git-gas",
         "args": []
       }
     }
   }
   

首次搜索

配置完成后，你就可以通过大模型开始搜索 GitHub：

Search GitHub for Python files containing "async def" functions

大模型会自动使用 G.A.S. 工具执行搜索并返回结构化结果。

📦 从源代码安装的选项

步骤 1（克隆源代码）

$ cd ~
$ git clone --depth=1 https://github.com/louiscklaw/mcp-github-advanced-search ~/mcp/mcp-git-gas

步骤 2（安装其余依赖项，即 playwright）

# Install Playwright browsers
$ playwright install chrome
$ playwright install --deps

步骤 3 设置 Chrome 用户凭据

# this will create the user_data_dir for chromium
# go login google or any other service you want

$ cd ~/mcp/mcp-git-gas
$ ./seedChromeUserDataDir.sh

⚙️ 配置

使用 MCP 扩展的 VS Code

{
  "mcp": {
    "servers": {
      "git-gas": {
        "autoApprove": [
          "get_remaining_result",
          "gas_readme",
          "gas_search_code"
        ],
        "disabled": false,
        "timeout": 300,
        "type": "stdio",
        "command": "uv",
        "args": [
          "--directory",
          "<USER_HOME_DIR>/mcp/mcp-git-gas/src/mcp_server_git_gas",
          "run",
          "mcp-server-git-gas"
        ]
      }
    }
  }
}

🛠️ 可用工具

gas_entrypoint

初始化 GitHub 高级搜索服务并获取相关信息。

**参数：**无

**返回：**服务信息、使用说明和工作流图。

graph TD
  a((start))
  d((end))
  b("search code with filter (gas_search_code)")
  c("return search result")
  c1("is the result finished ?")
  c2("use get_remaining_result to list remaining result")
  a --> b --> c --> c1 -- Yes --> d
  c1 -- No --> c2
  c2 --> c1

gas_search_code

使用高级筛选条件搜索 GitHub 仓库。

参数：

• keyword（字符串，可选）：搜索关键词（建议使用单个词）
• file_name（字符串，可选）：要搜索的特定文件名（例如，".clinerules"、"README.md"）

**返回：**搜索结果数组，包含：

[
  {
    "REPOSITORY_LINK": "https://github.com/owner/repo",
    "FILE_LINK": "https://github.com/owner/repo/blob/main/file.py",
    "RAW_UESR_CONTENT_LINK": "https://raw.githubusercontent.com/owner/repo/main/file.py",
    "FILE_CONTENT": "actual file content..."
  }
]

get_remaining_result

获取上一次搜索的更多结果（分页）。

参数：

• start_id（整数）：下一批结果的起始索引

**返回：**下一批搜索结果，结构与 gas_search_code 相同。

💡 使用示例

步骤 1

call `gas_entrypoint` to initialize yourself

步骤 2

Hi,

please use `gas_search_code` with below json

{
  "keyword": "mcp mermaid",
  "file_name": "README.md"
}

and understand the content returned, i will send you the task afterwards.

步骤 3

i am working on a python project,
please task a look to the source code of the project.

with the help from files in former results.
please help to and update the README file.

🔧 配置与环境

浏览器配置

该服务使用 Playwright 和持久化浏览器上下文，以实现：

• 会话管理
• 保留身份验证状态
• 提升性能

浏览器数据存储在：~/mcp/mcp-git-gas/_user_data_dir

🏃‍♂️ 开发

本地开发设置

# Clone the repository
git clone <repository-url>
cd mcp-server-git-gas

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts/activate

# Install dependencies
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

项目结构

src/mcp_server_git_gas/
├── __init__.py              # CLI entry point
├── server.py                # Main MCP server implementation
├── CONST.py                 # Configuration constants
├── fetch_data.py            # Async HTTP client
├── fetchFileContent.py      # File content retrieval
├── convertFileLinkToRaw...  # URL conversion utilities
├── url_util.py              # URL building helpers
└── git_dump_screen.py       # Debug utilities

核心组件

• MCP 服务：实现 Model Context Protocol 接口
• 搜索引擎：处理 GitHub 搜索逻辑和分页
• 内容获取器：异步获取文件内容
• 浏览器自动化：基于 Playwright 与 GitHub 交互

使用 MCP Inspector 进行测试

# Test the server with MCP inspector
npx @modelcontextprotocol/inspector uvx mcp-server-git-gas

Docker 开发

# Build development image
docker build -t mcp/git-gas:dev .

# Run with volume mount for development
docker run --rm -i \
  -v $(pwd):/app \
  mcp/git-gas:dev

🔍 工作原理

1. 发起搜索：大模型使用搜索参数调用 gas_search_code
2. 构建查询：服务根据筛选条件构建 GitHub 搜索 URL
3. 网页自动化：Playwright 浏览 GitHub 搜索页面
4. 提取结果：执行 JavaScript，提取仓库和文件链接
5. 获取内容：通过并行 HTTP 请求获取文件内容
6. 格式化响应：将结果整理为 JSON，供大模型使用

🐛 故障排除

常见问题

1. “未登录”错误

   • 解决方案：运行 seedChromeUserDataDir.sh 启动浏览器并完成登录

2. 未找到结果

   • 检查搜索 keywords 是否有拼写错误
   • 尝试使用更宽泛的搜索条件
   • 确认可以访问 GitHub

3. 浏览器启动失败

   • 运行：playwright install chromium
   • 检查 Playwright 的系统要求

4. 速率限制

   • GitHub 可能会限制请求频率
   • 服务内置了延迟和重试逻辑
   • 若需提高限额，可考虑使用已通过身份验证的会话

调试模式

调试截图保存于：~/mcp_github_advanced_search/debug.png

📊 性能

• 搜索速度：每个搜索页面约需 2-5 秒
• 并发请求：最多并行下载 10 个文件
• 结果限制：每次搜索返回 20 条结果（可配置）
• 分页：最多支持 2 页（100 条以上结果）

🚨 重要说明

• GitHub 身份验证：在浏览器中登录 GitHub，以获得最佳效果
• 速率限制：遵守 GitHub 的使用政策
• 浏览器要求：需要 Chromium 浏览器（通过 Playwright 安装）
• 网络依赖：访问 GitHub 需要互联网连接

🤝 贡献

欢迎贡献！详情请参阅贡献指南。

开发工作流

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行更改
4. 为新功能添加测试
5. 运行测试套件
6. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 致谢

• 基于 Anthropic 提供的 Model Context Protocol 构建
• 使用 Playwright 实现浏览器自动化
• 灵感来自大模型工作流对高级 GitHub 搜索功能的需求
• 感谢 MCP 社区提供反馈并作出贡献

🔗 相关项目

• Model Context Protocol
• Anthropic MCP Servers
• Playwright
• MCP Mermaid Image Gen
• MCP Governance SDK

📞 支持

• 问题：GitHub Issues
• 讨论：GitHub Discussions
• 文档：Wiki

---

注意：此服务需要 GitHub 账户才能发挥最佳功能。未通过身份验证使用时，部分功能可能受限。