AI导哈

GitLab代码搜索服务器

一个基于TypeScript和Node.js的服务器项目，用于在GitLab中搜索代码并提供MCP连接模式支持。

  • by dq042000
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 dq042000/gitlab-mcp-server

使用说明

gitlab-mcp-server

簡短說明

  • 用途：此專案是一個以 TypeScript 撰寫的 Node.js 伺服器範例，主要入口為 src/index.ts。
  • 專案類型：TypeScript + Node.js

專案結構

開始（本地開發）

建議步驟（以常見設定為例，實際以 package.json 為準）：

  1. 安裝相依套件
npm install
  1. 本地建置（TypeScript → JavaScript）
npm run build
# 或: npx tsc -p tsconfig.json
  1. 啟動伺服器
npm start
# 或直接執行編譯後的檔案，例如: node dist/index.js

開發流程（開發時可用）

  • 使用 ts-node 或 nodemon + ts-node 來熱重載：
npm run dev

MCP 連線模式與常見錯誤

  • 伺服器同時支援兩種模式：
    • Stateful：客戶端帶 mcp-session-id，伺服器維護 session。
    • Stateless：客戶端未帶 mcp-session-id，伺服器會以無 session 模式處理請求。
  • 若遇到 Request failed with status code 400，通常代表請求不是 initialize 且 session 無效。
  • 若遇到 Session not found，請讓客戶端重新 initialize（重新連線）。

環境變數設定

  • GITLAB_API：GitLab API Base URL（例如 https://gitlab.example.com/api/v4）
  • GITLAB_GROUP_TOKEN：GitLab Token（建議至少有 read_api）
  • PLATFORM_GROUP_ID：選填
    • 有填：只查詢該群組（含子群組）底下專案
    • 未填：查詢 token 可存取的專案（membership=true）
  • PORT：伺服器埠號（選填）
  • URL：伺服器對外位址

search_code（無 Elasticsearch）調校建議

  • 可用 mode 控制掃描策略：
    • fast：較快（掃描範圍較小）
    • balanced：預設（速度與完整度平衡）
    • deep：較完整（掃描範圍較大）
    • hybrid：先 fast 再 deep 補抓（建議查漏時使用）
  • 強烈建議指定 projectId（專案 ID 或 group/project 路徑）：
    • 會優先使用 GitLab projects/:id/search，速度通常明顯快於群組或全域搜尋
    • fallback 內容掃描也只會掃該專案，避免掃到整個可存取範圍
  • 若 未指定 projectId 且未傳入 maxProjects：
    • 系統會自動套用 maxProjects=10 保護值，降低慢查詢風險
    • 回應會提示目前為未指定專案的受限搜尋
  • 可選參數：
    • projectId：指定單一專案（建議優先使用）
    • maxProjects：最多掃描專案數
    • maxFilesPerProject：每個專案最多讀取檔案數
    • maxResults：最多回傳結果數
  • 多關鍵字請用 | 分隔，例如：臺銀|台銀|繳費|virtual_account|bank_code

範例：

{
  "query": "PaymentService|virtual_account",
  "projectId": "platform/tc-gaizan",
  "mode": "fast",
  "maxResults": 50
}

GitLab Token 權限建議（GITLAB_GROUP_TOKEN）

  • 建議類型：
    • 有設定 PLATFORM_GROUP_ID：Group Access Token
    • 未設定 PLATFORM_GROUP_ID：建議 Personal Access Token
  • 最小 Scope：read_api
  • 建議角色：至少 Reporter（可讀取可存取範圍內專案與 repository 內容）
  • 不需要開啟：write_repository、read_registry、write_registry

說明：本專案目前僅使用 GitLab 讀取型 API（GET/HEAD），包含：

  • 列出可存取專案（群組範圍或 membership 範圍）
  • 搜尋程式碼
  • 讀取檔案內容
  • 讀取分支與目錄樹

因此以 read_api 為最小且安全的預設即可；若你的 GitLab 環境策略較嚴格導致 403，再視需要升級為 api。

Token 安全檢查清單

  • 不要把 token 寫進版本控制（避免提交 .env）
  • 使用部署環境變數或 Secret 管理服務保存 token
  • 以最小權限原則設定 scope（優先 read_api）
  • 設定到期日並定期輪替 token
  • 若懷疑外洩，立即 revoke 與重發 token

相依與建議工具

  • Node.js (v16+ 建議)
  • TypeScript
  • 建議安裝 VS Code 的 TypeScript/Node 開發相關外掛

貢獻指南

  1. Fork 專案並建立 branch
  2. 撰寫或修改 src/ 下的程式
  3. 送出 PR 並描述變更重點

授權

此專案未指定授權（請視需求加入 LICENSE 檔）。

聯絡

若有問題或需求，請在 repository 中開 issue。

相关 MCP