Metadata-Version: 2.4
Name: nthu-complaints-mcp
Version: 1.0.0
Summary: FastMCP server for NTHU Complaints System
Project-URL: Homepage, https://github.com/nthu-complaints-system/mcp-server
Project-URL: Repository, https://github.com/nthu-complaints-system/mcp-server.git
Project-URL: Issues, https://github.com/nthu-complaints-system/mcp-server/issues
Author: NTHU Complaints System Team
License: MIT
License-File: LICENSE
Keywords: complaints,fastmcp,mcp,nthu
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Requires-Dist: fastmcp>=0.2.0
Requires-Dist: firebase-admin>=6.0.0
Requires-Dist: google-cloud-firestore>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: black>=22.0.0; extra == 'dev'
Requires-Dist: isort>=5.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# NTHU Complaints System - FastMCP Server

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

## 🚀 功能特點

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

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

### 🛠 系統監控
- **伺服器狀態**: 監控伺服器和資料庫連線
- **會話管理**: 追蹤活躍用戶會話

## 📦 安裝方式

### 使用 UVX (推薦)

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

### 使用 UV

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

# 執行
nthu-complaints-mcp
```

### 使用 Pip

```bash
# 從本地安裝
pip install .

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

# 執行
nthu-complaints-mcp
```

## ⚙️ 設置

### 1. Firebase 配置

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

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

### 2. 環境變數 (可選)

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

## 🔧 開發設置

### 本地開發

```bash
# 克隆倉庫
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
```

### 測試

```bash
# 執行測試
pytest

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

### 代碼品質

```bash
# 格式化代碼
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. 登入用戶

```python
result = mcp_login_user("user@example.com", "password123")
if result["success"]:
    session_token = result["session_token"]
    print(f"登入成功: {result['user']['display_name']}")
```

#### 2. 提交申訴

```python
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. 查看申訴摘要

```python
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. 查看申訴詳情

```python
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. 驗證用戶角色設置
```

### 日誌和調試

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

## 📄 許可證

MIT License - 詳見 [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](https://github.com/nthu-complaints-system/mcp-server/issues)
- **文件**: [FastMCP 官方文件](https://github.com/jlowin/fastmcp)
- **Firebase**: [Firebase 官方文件](https://firebase.google.com/docs)

---

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