MCP Server Github Repo

🚀 MCP GitHub 倉庫服務器

MCP GitHub 倉庫服務器基於模型上下文協議（MCP），可讓AI助手便捷地瀏覽與讀取指定GitHub倉庫內的文件，實現對倉庫內容的高效訪問。

🚀 快速開始

配置環境變量

服務器運行依賴以下環境變量，請按需配置：

GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name
GITHUB_BRANCH=branch_name  # 可選

安裝依賴

npm install

構建服務器

npm run build

開發模式

若需自動重建開發，可執行：

npm run watch

與Claude Desktop集成

在Claude Desktop中使用時，需添加服務器配置：

配置位置

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server-github-repo": {
      "command": "/path/to/mcp-server-github-repo/build/index.js"
    }
  }
}

✨ 主要特性

資源訪問

• 靈活文件訪問：可通過URI訪問倉庫中的任意文件。
• 內容導航：支持列出倉庫內容並導航目錄。
• 分支特定訪問：支持分支特定的文件訪問。
• 純文本輸出：文件內容以純文本格式提供。

資源URI規範

• 基本URL格式：https://api.github.com/repos/{owner}/{repo}/contents/{path}
• 類型支持：支持文件和目錄，文件使用 text/plain MIME類型，目錄使用 application/x-directory MIME類型。

📦 安裝指南

與Claude Desktop一起使用時，按上述配置位置添加服務器配置即可完成安裝。

💻 使用示例

基礎用法

通過基本URL格式訪問倉庫資源，例如訪問特定文件：

https://api.github.com/repos/owner/repo/contents/path/to/file.txt

高級用法

若要訪問特定分支的文件，可在URL中指定分支：

https://api.github.com/repos/owner/repo/contents/path/to/file.txt?ref=branch_name

📚 詳細文檔

API 實現

服務器實現了三個主要MCP端點：

1. ListResources - 列出倉庫中的文件和目錄
2. ReadResource - 獲取特定文件的內容

認證機制

服務器使用GitHub個人訪問令牌進行認證，請確保您的令牌具有適當的權限以訪問倉庫內容。

錯誤處理

服務器包含以下錯誤處理機制：

• 環境變量缺失
• GitHub API錯誤
• 無效路徑（例如嘗試將目錄讀取為文件）
• 認證失敗

調試方法

由於MCP服務器通過stdio通信，調試可能具有挑戰性。可使用MCP Inspector進行調試：

npm run inspector

這將提供一個訪問瀏覽器中的調試工具的URL。

🔧 技術細節

服務器藉助GitHub API實現對倉庫資源的訪問，通過環境變量配置倉庫信息和認證令牌。在處理請求時，根據不同的MCP端點和資源URI，調用相應的GitHub API接口獲取資源，並對返回結果進行處理和格式化。同時，服務器包含完善的錯誤處理機制，以應對各種可能的異常情況。

📄 許可證

本項目採用MIT許可證。

演示

⚠️ 重要提示

請保持GitHub個人訪問令牌的安全，考慮使用權限最小的令牌，並注意倉庫大小限制，以免影響訪問大型倉庫。

💡 使用建議

在開發過程中，可使用 npm run watch 命令進行帶自動重建的開發，提高開發效率。調試時，使用MCP Inspector可更方便地進行問題排查。