feat: Initial v0.9 release with API Key authentication
## v0.9.20260325_144654 ### Features - API Key Authentication System - Job Worker System - V2 Backup Versioning ### Bug Fixes - get_processor_results_by_job column mapping Co-authored-by: OpenCode
This commit is contained in:
accusys
@@ -0,0 +1,393 @@
|
||||
# Gitea MCP Server 安裝指南 (本地部署)
|
||||
|
||||
| 項目 | 內容 |
|
||||
|------|------|
|
||||
| 建立者 | OpenCode |
|
||||
| 建立時間 | 2026-03-24 |
|
||||
| 文件版本 | V1.0 |
|
||||
|
||||
---
|
||||
|
||||
## 版本歷史
|
||||
|
||||
| 版本 | 日期 | 目的 | 操作人 | 工具/模型 |
|
||||
|------|------|------|--------|-----------|
|
||||
| V1.0 | 2026-03-24 | 創建文件 | OpenCode | OpenCode / big-pickle |
|
||||
|
||||
---
|
||||
|
||||
## 概述
|
||||
|
||||
本文檔說明如何在 macOS 上安裝 Gitea MCP Server，配置為透過 OpenCode MCP 整合存取 Gitea API。
|
||||
|
||||
Gitea MCP Server 是一個 MCP (Model Context Protocol) 伺服器，提供對 Gitea API 的完整存取能力，包括 repos、issues、pull requests、workflows 等資源管理。
|
||||
|
||||
---
|
||||
|
||||
## 當前狀態
|
||||
|
||||
| 項目 | 狀態 |
|
||||
|------|------|
|
||||
| Gitea MCP Server | ✅ 已安裝 |
|
||||
| 安裝方式 | Homebrew (`gitea-mcp-server`) |
|
||||
| Plist | /Library/LaunchDaemons/com.momentry.gitea-mcp-server.plist |
|
||||
| 執行身份 | accusys |
|
||||
| 監聽端口 | 8787 |
|
||||
| Gitea 主機 | http://localhost:3000 |
|
||||
| Launchd 狀態 | ✅ 已註冊 |
|
||||
| RunAtLoad | ✅ 已設定 |
|
||||
| KeepAlive | ✅ 已設定 |
|
||||
|
||||
---
|
||||
|
||||
## 前置條件
|
||||
|
||||
- Gitea 服務已運行（端口 3000）
|
||||
- Homebrew 已安裝
|
||||
- 管理員權限
|
||||
|
||||
---
|
||||
|
||||
## 安裝步驟
|
||||
|
||||
### Step 1: 安裝 Gitea MCP Server
|
||||
|
||||
```bash
|
||||
brew install gitea-mcp-server
|
||||
```
|
||||
|
||||
**驗證**:
|
||||
|
||||
```bash
|
||||
which gitea-mcp-server
|
||||
# /opt/homebrew/bin/gitea-mcp-server
|
||||
|
||||
/opt/homebrew/bin/gitea-mcp-server --help
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: 創建日誌目錄
|
||||
|
||||
```bash
|
||||
mkdir -p /Users/accusys/momentry/log
|
||||
|
||||
touch /Users/accusys/momentry/log/gitea-mcp-server.log
|
||||
touch /Users/accusys/momentry/log/gitea-mcp-server.error.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: 獲取 Gitea API Token
|
||||
|
||||
#### 步驟 3.1: 登入 Gitea
|
||||
|
||||
1. 開啟瀏覽器，訪問 http://localhost:3000
|
||||
2. 使用管理員帳號登入
|
||||
|
||||
#### 步驟 3.2: 生成 Personal Access Token
|
||||
|
||||
1. 點擊右上角頭像 → **Settings**
|
||||
2. 左側選單選擇 **Applications**
|
||||
3. 在 **Access Tokens** 區塊：
|
||||
- **Token Name**: `opencode-mcp`
|
||||
- **Expiration**: 選擇過期時間（如 365 days）
|
||||
- **Scopes**: 勾選需要的權限
|
||||
- `repo` - 倉庫操作
|
||||
- `read:user` - 讀取用戶資訊
|
||||
- `read:org` - 讀取組織資訊
|
||||
4. 點擊 **Generate Token**
|
||||
5. **立即複製** 生成的 Token
|
||||
|
||||
#### 步驟 3.3: 驗證 Token
|
||||
|
||||
```bash
|
||||
curl -H "Authorization: token <YOUR_TOKEN>" http://localhost:3000/api/v1/user
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4: 創建 Plist 檔案
|
||||
|
||||
```bash
|
||||
sudo tee /Library/LaunchDaemons/com.momentry.gitea-mcp-server.plist << 'EOF'
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
|
||||
<plist version="1.0">
|
||||
<dict>
|
||||
<key>Label</key>
|
||||
<string>com.momentry.gitea-mcp-server</string>
|
||||
<key>UserName</key>
|
||||
<string>accusys</string>
|
||||
<key>ProgramArguments</key>
|
||||
<array>
|
||||
<string>/opt/homebrew/bin/gitea-mcp-server</string>
|
||||
<string>-transport</string>
|
||||
<string>http</string>
|
||||
<string>-port</string>
|
||||
<string>8787</string>
|
||||
<string>-host</string>
|
||||
<string>http://localhost:3000</string>
|
||||
<string>-token</string>
|
||||
<string><GITEA_TOKEN></string>
|
||||
</array>
|
||||
<key>RunAtLoad</key>
|
||||
<true/>
|
||||
<key>KeepAlive</key>
|
||||
<true/>
|
||||
<key>StandardOutPath</key>
|
||||
<string>/Users/accusys/momentry/log/gitea-mcp-server.log</string>
|
||||
<key>StandardErrorPath</key>
|
||||
<string>/Users/accusys/momentry/log/gitea-mcp-server.error.log</string>
|
||||
</dict>
|
||||
</plist>
|
||||
EOF
|
||||
```
|
||||
|
||||
**注意**: 將 `<GITEA_TOKEN>` 替換為實際的 Token 值。
|
||||
|
||||
---
|
||||
|
||||
### Step 5: 設定權限
|
||||
|
||||
```bash
|
||||
sudo chown root:wheel /Library/LaunchDaemons/com.momentry.gitea-mcp-server.plist
|
||||
sudo chmod 644 /Library/LaunchDaemons/com.momentry.gitea-mcp-server.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 6: 載入服務
|
||||
|
||||
```bash
|
||||
sudo launchctl bootstrap system /Library/LaunchDaemons/com.momentry.gitea-mcp-server.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 7: 驗證服務
|
||||
|
||||
```bash
|
||||
# 檢查服務狀態
|
||||
sudo launchctl list | grep gitea-mcp-server
|
||||
|
||||
# 檢查進程
|
||||
ps aux | grep gitea-mcp-server | grep -v grep
|
||||
|
||||
# 測試端點
|
||||
curl -s http://localhost:8787/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 8: 整合 OpenCode MCP
|
||||
|
||||
#### 步驟 8.1: 更新 OpenCode 配置
|
||||
|
||||
編輯 `~/.config/opencode/opencode.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://opencode.ai/config.json",
|
||||
"mcp": {
|
||||
"gitea": {
|
||||
"type": "local",
|
||||
"enabled": true,
|
||||
"command": [
|
||||
"/opt/homebrew/bin/gitea-mcp-server",
|
||||
"-token", "<GITEA_TOKEN>",
|
||||
"-host", "http://localhost:3000"
|
||||
]
|
||||
},
|
||||
"n8n": {
|
||||
"type": "local",
|
||||
"enabled": true,
|
||||
"command": ["/opt/homebrew/bin/mcp-n8n"],
|
||||
"environment": {
|
||||
"N8N_BASE_URL": "http://localhost:5678",
|
||||
"N8N_API_KEY": "<N8N_API_KEY>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### 步驟 8.2: 重啟 OpenCode
|
||||
|
||||
```bash
|
||||
# 停止現有 OpenCode
|
||||
pkill -f opencode
|
||||
|
||||
# 重新啟動
|
||||
opencode
|
||||
```
|
||||
|
||||
#### 步驟 8.3: 驗證 MCP 連接
|
||||
|
||||
在 OpenCode 中執行：
|
||||
|
||||
```
|
||||
/mcps
|
||||
```
|
||||
|
||||
確認 gitea 顯示為 `connected`。
|
||||
|
||||
---
|
||||
|
||||
## Plist 參數說明
|
||||
|
||||
| 參數 | 說明 | 值 |
|
||||
|------|------|-----|
|
||||
| `-transport` | 傳輸類型 | `http` |
|
||||
| `-port` | HTTP 監聽端口 | `8787` |
|
||||
| `-host` | Gitea 主機 URL | `http://localhost:3000` |
|
||||
| `-token` | Gitea API Token | 見 Step 3 |
|
||||
|
||||
---
|
||||
|
||||
## 管理指令
|
||||
|
||||
### 啟動服務
|
||||
|
||||
```bash
|
||||
sudo launchctl bootstrap system /Library/LaunchDaemons/com.momentry.gitea-mcp-server.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 停止服務
|
||||
|
||||
```bash
|
||||
sudo launchctl bootout system/com.momentry.gitea-mcp-server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 重啟服務
|
||||
|
||||
```bash
|
||||
sudo launchctl bootout system/com.momentry.gitea-mcp-server
|
||||
sudo launchctl bootstrap system /Library/LaunchDaemons/com.momentry.gitea-mcp-server.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 查看日誌
|
||||
|
||||
```bash
|
||||
# 即時查看日誌
|
||||
tail -f /Users/accusys/momentry/log/gitea-mcp-server.log
|
||||
|
||||
# 錯誤日誌
|
||||
tail -f /Users/accusys/momentry/log/gitea-mcp-server.error.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 卸載步驟
|
||||
|
||||
### Step 1: 停止服務
|
||||
|
||||
```bash
|
||||
sudo launchctl bootout system/com.momentry.gitea-mcp-server
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: 移除 Plist
|
||||
|
||||
```bash
|
||||
sudo rm /Library/LaunchDaemons/com.momentry.gitea-mcp-server.plist
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 3: 從 OpenCode 配置移除
|
||||
|
||||
編輯 `~/.config/opencode/opencode.json`，移除 `mcp.gitea` 區塊。
|
||||
|
||||
---
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 服務無法啟動
|
||||
|
||||
1. 檢查 Token 是否正確
|
||||
2. 檢查 Gitea 是否運行：`curl -s http://localhost:3000/`
|
||||
3. 檢查日誌：`/Users/accusys/momentry/log/gitea-mcp-server.error.log`
|
||||
|
||||
---
|
||||
|
||||
### Token 無效
|
||||
|
||||
1. 確認 Token 未過期
|
||||
2. 確認 Token 有足夠的權限
|
||||
3. 重新生成 Token
|
||||
|
||||
---
|
||||
|
||||
### 端口被佔用
|
||||
|
||||
```bash
|
||||
# 檢查端口占用
|
||||
lsof -i :8787
|
||||
|
||||
# 修改 plist 中的端口後重新載入
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### OpenCode MCP 未顯示
|
||||
|
||||
1. 確認 OpenCode 已重啟
|
||||
2. 檢查 `~/.config/opencode/opencode.json` 格式正確
|
||||
3. 確認 gitea-mcp-server 程序正在運行
|
||||
|
||||
---
|
||||
|
||||
## 檔案位置
|
||||
|
||||
| 類型 | 路徑 | 說明 |
|
||||
|------|------|------|
|
||||
| Plist | /Library/LaunchDaemons/com.momentry.gitea-mcp-server.plist | Launchd 服務配置 |
|
||||
| 日誌 | /Users/accusys/momentry/log/gitea-mcp-server.log | 標準輸出日誌 |
|
||||
| 錯誤日誌 | /Users/accusys/momentry/log/gitea-mcp-server.error.log | 錯誤日誌 |
|
||||
| OpenCode 配置 | ~/.config/opencode/opencode.json | MCP 設定檔 |
|
||||
| Gitea | http://localhost:3000 | Gitea Web UI |
|
||||
|
||||
---
|
||||
|
||||
## 常用指令
|
||||
|
||||
```bash
|
||||
# 驗證服務狀態
|
||||
sudo launchctl list | grep gitea-mcp-server
|
||||
|
||||
# 查看服務 PID
|
||||
ps aux | grep gitea-mcp-server | grep -v grep
|
||||
|
||||
# 測試端點
|
||||
curl -s http://localhost:8787/
|
||||
|
||||
# 驗證 Gitea 連接
|
||||
curl -H "Authorization: token <TOKEN>" http://localhost:3000/api/v1/user
|
||||
|
||||
# 查看即時日誌
|
||||
tail -f /Users/accusys/momentry/log/gitea-mcp-server.log
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 版本資訊
|
||||
|
||||
- 版本: 1.0
|
||||
- 安裝日期: 2026-03-24
|
||||
- 文件更新: 2026-03-24
|
||||
|
||||
---
|
||||
|
||||
## 相關文件
|
||||
|
||||
- [OpenCode MCP 整合](./N8N_MCP_SETUP.md) - n8n MCP 設定說明
|
||||
- [服務總覽](./SERVICES.md) - 所有服務狀態總覽
|
||||
- [待解決問題](./PENDING_ISSUES.md) - MCP 安裝狀態追蹤
|
||||
Reference in New Issue
Block a user