# 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 安裝狀態追蹤