Forgejo MCP

🚀 Gitea/Forgejo MCP Server

這是一個 模型上下文協議（Model Context Protocol，MCP） 服務器，可讓你通過 Claude、Gemini 和 Copilot 等 AI 助手來管理 Gitea/Forgejo 代碼倉庫。藉助它，AI 能成為你的代碼倉庫管理助手。

🚀 快速開始

為何使用 Forgejo MCP 服務器？

如果你有以下需求：

• 智能進度跟蹤：讓 AI 幫你跟蹤項目進度並分析瓶頸。
• 自動問題分類：根據問題內容自動添加標籤並設置里程碑。
• 優先級排序：讓 AI 分析問題內容，幫助你對任務進行優先級排序。
• 代碼審查輔助：在拉取請求（Pull Request）中獲取 AI 的建議和見解。
• 項目文檔整理：自動整理 Wiki 文檔和發佈說明。

那麼這個工具就是為你量身打造的！

✨ 主要特性

問題管理

• 創建、編輯和查看問題。
• 添加、移除和替換標籤。
• 管理問題評論和附件。
• 設置問題依賴關係。

項目組織

• 管理標籤（創建、編輯、刪除）。
• 管理里程碑（創建、編輯、刪除）。
• 倉庫搜索和列表展示。

版本發佈管理

• 管理版本發佈。
• 管理發佈附件。

其他特性

• 查看拉取請求。
• 管理 Wiki 頁面。
• 查看 Forgejo/Gitea Actions 任務。

📦 安裝指南

方法一：使用 Docker（推薦）

如果你使用的是 STDIO 模式，可以直接跳到使用說明部分。 如果你使用的是 SSE/可流式 HTTP 模式，在配置 MCP 客戶端之前，你應該先將 forgejo-mcp 作為服務器運行。

docker run -p 8080:8080 -e FORGEJOMCP_TOKEN="my-forgejo-api-token" ronmi/forgejo-mcp http --address :8080 --server https://git.example.com

方法二：從源代碼安裝

go install github.com/raohwork/forgejo-mcp@latest

方法三：下載預編譯二進制文件

從 發佈頁面 下載適合你操作系統的版本。

💻 使用示例

基礎用法

本工具提供兩種主要操作模式：用於本地集成的 stdio 模式和用於遠程訪問的 http 模式。 在實際設置 MCP 客戶端之前，你需要在 Forgejo/Gitea 服務器上創建一個訪問令牌。

1. 登錄到你的 Forgejo/Gitea 實例。
2. 轉到設置 → 應用程序 → 訪問令牌。
3. 點擊生成新令牌。
4. 選擇適當的權限範圍（建議至少選擇 repository 和 issue 的寫入權限）。
5. 複製生成的令牌。

💡 使用建議

為了安全起見，考慮使用環境變量而不是直接在配置中使用令牌：

export FORGEJOMCP_SERVER="https://your-forgejo-instance.com"
export FORGEJOMCP_TOKEN="your_access_token"

STDIO 模式（用於本地客戶端）

這是與 Claude Desktop 或 Gemini CLI 等本地 AI 助手客戶端集成的推薦模式。它使用標準輸入/輸出來進行直接通信。

使用 Docker：

{
  "mcpServers": {
    "forgejo": {
      "command": "docker",
      "args": [
        "--rm",
        "ronmi/forgejo-mcp",
        "stdio",
        "--server", "https://your-forgejo-instance.com",
        "--token", "your_access_token"
      ]
    }
  }
}

從源代碼或預構建二進制文件安裝：

{
  "mcpServers": {
    "forgejo": {
      "command": "/path/to/forgejo-mcp",
      "args": [
        "stdio",
        "--server", "https://your-forgejo-instance.com",
        "--token", "your_access_token"
      ]
    }
  }
}

你可能需要查看安全建議部分以獲取最佳實踐。

HTTP 服務器模式（用於遠程訪問）

此模式啟動一個 Web 服務器，允許遠程客戶端通過 HTTP 連接。它非常適合基於 Web 的服務或為多個用戶設置中央網關。 運行以下命令啟動服務器：

# 使用本地二進制文件
/path/to/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com

# 使用 Docker
docker run -p 8080:8080 -d --rm ronmi/forgejo-mcp http --address :8080 --server https://your-forgejo-instance.com

服務器支持兩種操作模式：

• 單用戶模式：如果你在啟動時提供了 --token（或環境變量 FORGEJOMCP_TOKEN），所有操作都將使用該令牌。

  forgejo-mcp http --address :8080 --server https://git.example.com --token your_token
  

• 多用戶模式：如果未提供令牌，服務器要求客戶端在每個請求中發送 Authorization: Bearer <token> 頭，從而安全地為多個用戶提供服務。

客戶端配置

對於支持通過 HTTP 連接到遠程 MCP 服務器的客戶端，你可以添加如下配置。此示例展示瞭如何連接到以多用戶模式運行的服務器：

{
  "mcpServers": {
    "forgejo-remote": {
      "type": "sse",
      "url": "http://localhost:8080/sse",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}

或者 http 類型（對於可流式 HTTP，在 URL 中使用不同的路徑）

{
  "mcpServers": {
    "forgejo-remote": {
      "type": "http",
      "url": "http://localhost:8080/",
      "headers": {
        "Authorization": "Bearer your_token"
      }
    }
  }
}

如果你連接的是以單用戶模式運行的服務器，可以省略 headers 字段。

高級用法

配置完成後，你可以在 AI 助手中使用自然語言來管理你的代碼倉庫：

"Show me critical bug reports of this repo on my gitea server"

"According to our discussion above, create a detailed issue about this bug, then leave a comment on the issue to describe how we will fix it."

"Give me a report about current milestone. Recent progression in particular."

"Analyze recent pull requests and tell me which ones need priority review"

🔧 安全建議

1. 使用環境變量：設置 FORGEJOMCP_SERVER 和 FORGEJOMCP_TOKEN，然後從配置中移除 --server 和 --token。
2. 限制令牌權限：僅授予必要的權限範圍。
3. 定期輪換令牌：定期更新訪問令牌。

🤝 支持與貢獻

• 報告 Bug：GitHub Issues
• 代碼貢獻：歡迎提交拉取請求！

📄 許可證

本項目採用 Mozilla 公共許可證 2.0 進行許可。

讓 AI 成為你的代碼倉庫管理夥伴！ 🚀