nthu-complaints-mcp 1.6.0

FastMCP server for NTHU Complaints System

NTHU Complaints System - FastMCP Server

一個專為 NTHU 申訴系統設計的 FastMCP 伺服器，提供完整的申訴管理功能。

🚀 功能特點

🔐 用戶認證

• 登入/登出: 安全的用戶會話管理
• 會話驗證: 自動會話過期和驗證
• 權限控制: 基於角色的存取控制

📝 申訴管理

• 提交申訴: 支援匿名和實名申訴
• 查看摘要: 獲取所有申訴的概覽
• 詳細查看: 查看特定申訴的完整資訊
• 狀態追蹤: 即時更新申訴處理狀態

🛠 系統監控

• 伺服器狀態: 監控伺服器和資料庫連線
• 會話管理: 追蹤活躍用戶會話

📦 安裝方式

使用 UVX (推薦)

# 直接執行，無需手動安裝
uvx nthu-complaints-mcp

使用 UV

# 安裝到全域環境
uv tool install nthu-complaints-mcp

# 執行
nthu-complaints-mcp

使用 Pip

# 從本地安裝
pip install .

# 或從 PyPI 安裝 (如果已發布)
pip install nthu-complaints-mcp

# 執行
nthu-complaints-mcp

⚙️ 設置

1. Firebase 配置

在執行前，需要設置 Firebase 服務帳戶金鑰：

1. 從 Firebase Console 下載服務帳戶金鑰
2. 將檔案放置在以下任一位置：
   • ./firebase-service-account.json (當前目錄)
   • ~/.nthu-complaints/firebase-service-account.json (用戶目錄)
   • /etc/nthu-complaints/firebase-service-account.json (系統目錄)

2. 環境變數 (可選)

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/firebase-service-account.json"

🔧 開發設置

本地開發

# 克隆倉庫
git clone <repository-url>
cd nthu-complaints-mcp

# 使用 UV 設置開發環境
uv venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 安裝依賴
uv pip install -e ".[dev]"

# 執行伺服器
python -m nthu_complaints_mcp.server

測試

# 執行測試
pytest

# 執行測試並顯示覆蓋率
pytest --cov=nthu_complaints_mcp

代碼品質

# 格式化代碼
black src/
isort src/

# 類型檢查
mypy src/

📚 API 參考

可用工具

工具名稱	描述	參數
mcp_login_user	用戶登入	email, password
mcp_logout_user	用戶登出	session_token
mcp_check_session_status	檢查會話狀態	session_token
mcp_submit_complaint	提交申訴	session_token, title, description, category, department, priority, anonymous, contact_info
mcp_get_user_complaints_summary	獲取申訴摘要	session_token
mcp_get_complaint_details	獲取申訴詳情	session_token, case_number
mcp_server_status	獲取伺服器狀態	無

使用範例

1. 登入用戶

result = mcp_login_user("[e-mail]", "password123")
if result["success"]:
    session_token = result["session_token"]
    print(f"登入成功: {result['user']['display_name']}")

2. 提交申訴

complaint = mcp_submit_complaint(
    session_token=session_token,
    title="圖書館設備問題",
    description="圖書館的電腦無法正常使用，影響學習效率",
    category="設施設備",
    department="圖書館",
    priority="medium",
    anonymous=False,
    contact_info={"phone": "0912345678", "preferred_contact": "email"}
)

if complaint["success"]:
    print(f"申訴已提交，案件編號: {complaint['case_number']}")

3. 查看申訴摘要

summary = mcp_get_user_complaints_summary(session_token)
if summary["success"]:
    print(f"總共有 {summary['total_count']} 個申訴")
    for complaint in summary["complaints"]:
        print(f"- {complaint['case_number']}: {complaint['title']} ({complaint['status']})")

4. 查看申訴詳情

details = mcp_get_complaint_details(session_token, "NTHU20241219120000")
if details["success"]:
    complaint = details["complaint"]
    print(f"標題: {complaint['title']}")
    print(f"狀態: {complaint['status']}")
    print(f"描述: {complaint['description']}")

🏗 架構

模組結構

src/nthu_complaints_mcp/
├── __init__.py          # 套件初始化
├── config.py            # 配置管理
├── firebase_client.py   # Firebase 客戶端
├── session_manager.py   # 會話管理
├── tools.py            # MCP 工具實現
└── server.py           # 主伺服器

資料流

1. 認證: 用戶通過 mcp_login_user 登入，獲得會話令牌
2. 授權: 每個操作都需要有效的會話令牌
3. 資料存取: 通過 Firebase Firestore 進行資料持久化
4. 會話管理: 自動處理會話過期和清理

🔒 安全性

• 會話管理: 使用 UUID 作為會話令牌，自動過期機制
• 權限控制: 用戶只能查看自己的申訴 (管理員除外)
• 資料驗證: 所有輸入都經過驗證和清理
• Firebase 安全規則: 配合 Firestore 安全規則進行多層保護

🐛 故障排除

常見問題

Firebase 初始化失敗

解決方案:
1. 檢查 firebase-service-account.json 是否存在
2. 確認 JSON 格式正確
3. 驗證 Firebase 專案設置

用戶登入失敗

解決方案:
1. 確認 Firebase Authentication 已啟用
2. 檢查用戶是否存在於 Firestore 'users' 集合
3. 驗證用戶權限設置

權限被拒絕

解決方案:
1. 檢查 Firestore 安全規則
2. 確認服務帳戶權限
3. 驗證用戶角色設置

日誌和調試

# 啟用詳細日誌
export PYTHONPATH=.
python -m nthu_complaints_mcp.server --log-level DEBUG

📄 許可證

MIT License - 詳見 LICENSE 檔案

🤝 貢獻

歡迎提交 Issue 和 Pull Request！

開發流程

1. Fork 專案
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 開啟 Pull Request

📞 支援

• Issues: GitHub Issues
• 文件: FastMCP 官方文件
• Firebase: Firebase 官方文件

---

注意: 這是一個開發版本，建議在生產環境中使用前進行充分測試。