Mytaskly MCP

🚀 MyTaskly MCP 服務器

MyTaskly MCP 服務器是為 MyTaskly 打造的 模型上下文協議（MCP）服務器，具備 OAuth 2.1 JWT 認證 功能，並能與 FastAPI 後端 實現無縫集成。

✨ 主要特性

🔐 企業級認證

• OAuth 2.1 JWT：遵循 MCP 2025 標準（RFC 8707）的安全令牌認證方式。
• 多用戶支持：通過 JWT 令牌驗證，單個部署即可服務所有用戶。
• 受眾聲明驗證：防止令牌在不同服務間重複使用。

🚀 高性能集成

• HTTP API 網關：與 FastAPI 後端通信，無需直接訪問數據庫。
• 無狀態架構：無需會話管理，具備完全可擴展性。
• 連接池：優化後的 HTTP 客戶端，實現高吞吐量。

📱 移動優先設計

• React Native 優化：返回的數據格式適配原生移動組件。
• 語音友好響應：包含用於聊天應用 TTS 的語音摘要。
• 預格式化 UI 數據：包含表情符號、顏色和格式化日期，可直接顯示。

🛠️ 可用的 MCP 工具（共 20 個）

MCP 服務器提供 20 個工具，分為 5 個類別，用於全面的任務管理。

📋 任務工具（8 個）

示例響應 - get_tasks:

{
  "type": "task_list",
  "tasks": [
    {
      "id": 123,
      "title": "Pizza",
      "endTimeFormatted": "Venerdì 15 dicembre, 18:00",
      "category": "Cibo",
      "categoryColor": "#EF4444",
      "priority": "Alta",
      "priorityEmoji": "⚡",
      "status": "Pending",
      "actions": {
        "canEdit": true,
        "canDelete": true,
        "canComplete": true
      }
    }
  ],
  "summary": {
    "total": 10,
    "pending": 5,
    "completed": 3,
    "high_priority": 2
  },
  "voice_summary": "Hai 10 task, di cui 2 ad alta priorità. 5 sono in sospeso e 3 completati."
}

📂 分類工具（4 個）

示例響應 - get_my_categories:

{
  "categories": [
    {
      "category_id": 1,
      "name": "Lavoro",
      "description": "Task di lavoro",
      "is_shared": true,
      "owner_id": 1,
      "permission_level": "READ_WRITE"
    }
  ],
  "total": 5,
  "owned": 3,
  "shared_with_me": 2
}

📝 筆記工具（4 個）

示例響應 - create_note:

{
  "note_id": 456,
  "title": "Comprare il latte",
  "color": "#FFEB3B",
  "position_x": 100.5,
  "position_y": 250.0,
  "created_at": "2025-01-15T10:30:00Z",
  "message": "✅ Nota creata con successo"
}

🔧 元工具（3 個）

⚕️ 系統工具（1 個）

示例響應 - health_check:

{
  "mcp_server": "healthy",
  "fastapi_server": "healthy",
  "fastapi_url": "http://localhost:8080",
  "timestamp": "2025-01-15T10:30:00Z",
  "version": "2.0.0"
}

🚀 快速開始

使用選項

你有 兩種方式 來使用 MyTaskly MCP 服務器：

選項 1：使用官方公共服務器（推薦）

使用 官方 MyTaskly MCP 服務器（即將推出），無需進行任何設置！

# 配置你的 MCP 客戶端連接到：
# https://mcp.mytasklyapp.com （URL 即將發佈）

優點：

• ✅ 無需安裝或配置
• ✅ 始終保持最新功能
• ✅ 由 MyTaskly 團隊管理和監控
• ✅ 可直接與 MyTaskly 移動應用配合使用

選項 2：自行搭建（高級用戶）

運行你自己的本地 MCP 服務器實例。

前提條件：

• Python 3.11+（建議使用虛擬環境）
• 本地運行的 MyTaskly FastAPI 服務器（詳見 MyTaskly-server）
• 與你的 FastAPI 服務器配置匹配的 JWT 密鑰
• 配置為使用自定義服務器的 修改後的 MyTaskly 應用

快速開始（5 分鐘）：

git clone https://github.com/Gabry848/MyTaskly-mcp.git
cd MyTaskly-mcp
python -m venv venv && pip install -r requirements.txt
cp .env.example .env && python main.py

⚠️ 重要提示： 自行搭建時，你還必須：

1. 運行本地的 MyTaskly-server 實例。
2. 修改 MyTaskly 移動應用，使其指向你的自定義服務器 URL。

自行搭建設置指南

1. 克隆並安裝

# 克隆倉庫
git clone https://github.com/Gabry848/MyTaskly-mcp.git
cd MyTaskly-mcp

# 創建虛擬環境
python -m venv venv

# 激活虛擬環境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# 安裝依賴
pip install -r requirements.txt

2. 配置環境變量

在根目錄下創建 .env 文件：

# ============ FASTAPI 後端 ============
FASTAPI_BASE_URL=http://localhost:8080
FASTAPI_API_KEY=your_api_key_here

# ============ JWT 配置 ============
# 關鍵：必須與 FastAPI 服務器配置匹配！
JWT_SECRET_KEY=your_jwt_secret_key_here
JWT_ALGORITHM=HS256
MCP_AUDIENCE=mytaskly-mcp

# ============ 服務器配置 ============
MCP_SERVER_NAME=MyTaskly-MCP
MCP_SERVER_VERSION=2.0.0
LOG_LEVEL=INFO

⚠️ 關鍵提示： JWT_SECRET_KEY 必須與你的 FastAPI 服務器的 SECRET_KEY 環境變量匹配！

3. 啟動 MCP 服務器

python main.py

服務器將以 標準輸入輸出模式 啟動，並顯示可用工具。配置你的 MCP 客戶端連接到該服務器。

🔐 認證與安全

OAuth 2.1 流程

MCP 服務器使用遵循 OAuth 2.1 和 RFC 8707 標準的 JWT 令牌：

┌─────────────────┐
│  移動客戶端  │
│  (React Native) │
└────────┬────────┘
         │ 1. 登錄請求
         ▼
┌─────────────────┐
│  FastAPI 服務器 │  2. 驗證憑據
│  (認證服務器)  │  3. 生成帶有 MCP 受眾聲明的 JWT
└────────┬────────┘
         │ 4. 返回 JWT 令牌
         ▼
┌─────────────────┐
│  移動客戶端  │  5. 安全存儲令牌
└────────┬────────┘
         │ 6. 使用授權頭調用 MCP 工具
         ▼
┌─────────────────┐
│   MCP 服務器    │  7. 驗證 JWT 簽名
│ (本項目)  │  8. 驗證受眾聲明
│                 │  9. 從令牌中提取用戶 ID
└────────┬────────┘
         │ 10. 使用用戶 ID 向 FastAPI 發送 HTTP 請求
         ▼
┌─────────────────┐
│  FastAPI 服務器 │  11. 返回特定用戶的數據
│ (資源 API)  │
└────────┬────────┘
         │ 12. 格式化數據以適配移動 UI
         ▼
┌─────────────────┐
│   MCP 服務器    │  13. 返回格式化響應
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  移動客戶端  │  14. 渲染 UI / 播放 TTS
└─────────────────┘

JWT 令牌結構

JWT 必須包含以下聲明（遵循 RFC 7519 和 RFC 8707）：

{
  "sub": "123",                              // 用戶 ID（必需）
  "aud": "mcp://mytaskly-mcp-server",       // 受眾（必需，RFC 8707）
  "iss": "https://api.mytasklyapp.com",     // 頒發者（可選）
  "exp": 1735689600,                         // 過期時間戳（必需）
  "iat": 1735686000,                         // 頒發時間戳（必需）
  "scope": "tasks:read tasks:write notes:write" // 權限範圍（可選）
}

安全特性：

獲取 JWT 令牌

選項 1：從 FastAPI 獲取（生產環境）

你需要在 FastAPI 服務器中添加以下端點：

# src/app/api/routes/auth.py

@router.post("/auth/mcp-token")
async def get_mcp_token(current_user: User = Depends(get_current_user)):
    """為 MCP 服務器訪問生成 JWT 令牌。"""
    payload = {
        "sub": str(current_user.user_id),
        "aud": "mcp://mytaskly-mcp-server",
        "iss": "https://api.mytasklyapp.com",
        "exp": datetime.utcnow() + timedelta(minutes=30),
        "iat": datetime.utcnow(),
        "scope": "tasks:read tasks:write categories:read notes:read notes:write"
    }
    token = jwt.encode(payload, settings.JWT_SECRET_KEY, algorithm="HS256")
    return {"mcp_token": token, "expires_in": 1800}

選項 2：生成測試令牌（開發環境）

from src.auth import create_test_token

# 為用戶 ID 為 1 的用戶生成測試令牌
token = create_test_token(user_id=1, expires_minutes=30)
print(f"測試令牌: {token}")

🧪 測試與開發

使用 Python 進行手動測試

import asyncio
from src.auth import create_test_token
from src.server import get_tasks, get_categories, create_note

async def test_mcp_tools():
    """使用生成的令牌測試所有 MCP 工具。"""

    # 為用戶 ID 為 1 的用戶生成測試令牌（30 分鐘後過期）
    token = create_test_token(user_id=1, expires_minutes=30)
    auth_header = f"Bearer {token}"

    print("🔑 為用戶 ID 為 1 的用戶生成了測試令牌\n")

    # 測試 1: 獲取任務
    print("1️⃣ 測試 get_tasks...")
    tasks = await get_tasks(authorization=auth_header)
    print(f"   ✅ 檢索到 {tasks['summary']['total']} 個任務")
    print(f"   📊 摘要: {tasks['summary']}")
    print(f"   🎤 語音: {tasks['voice_summary']}\n")

    # 測試 2: 獲取分類
    print("2️⃣ 測試 get_categories...")
    categories = await get_categories(authorization=auth_header)
    print(f"   ✅ 檢索到 {categories['total']} 個分類")
    print(f"   📂 擁有的: {categories.get('owned', 0)}")
    print(f"   🤝 共享的: {categories.get('shared_with_me', 0)}\n")

    # 測試 3: 創建筆記
    print("3️⃣ 測試 create_note...")
    note = await create_note(
        authorization=auth_header,
        title="Test note from MCP",
        color="#4CAF50",
        position_x=100.0,
        position_y=200.0
    )
    print(f"   ✅ 創建了筆記 #{note['note_id']}")
    print(f"   📝 標題: {note['title']}")
    print(f"   🎨 顏色: {note['color']}\n")

    print("✅ 所有測試均成功完成！")

# 運行測試
if __name__ == "__main__":
    asyncio.run(test_mcp_tools())

使用 cURL 進行測試

# 1. 生成測試 JWT 令牌
python -c "from src.auth import create_test_token; print(create_test_token(1))"

# 2. 將令牌導出到環境變量（替換為實際令牌）
export MCP_TOKEN="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

# 3. 測試 get_tasks
curl -X POST http://localhost:8000/mcp/get_tasks \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json"

# 4. 測試 get_categories
curl -X POST http://localhost:8000/mcp/get_categories \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json"

# 5. 測試 create_note
curl -X POST http://localhost:8000/mcp/create_note \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting notes",
    "color": "#FF5722",
    "position_x": 150.5,
    "position_y": 300.0
  }'

# 6. 測試 health_check（無需認證）
curl -X GET http://localhost:8000/mcp/health_check

自動化測試套件

# 運行所有單元測試
python -m pytest tests/ -v

# 運行特定測試文件
python -m pytest tests/test_auth.py -v

# 運行並生成覆蓋率報告
python -m pytest tests/ --cov=src --cov-report=html

# 運行並輸出結果
python -m pytest tests/ -v -s

💻 使用示例

與 React Native 集成

get_tasks 工具返回的數據經過優化，適用於 React Native 組件：

import { FlatList, View, Text } from 'react-native';

async function fetchTasks() {
  // 從你的認證系統獲取 JWT 令牌
  const token = await getAuthToken();

  // 調用 MCP 服務器
  const response = await mcpClient.call('get_tasks', {
    authorization: `Bearer ${token}`
  });

  return response;
}

function TasksList() {
  const [data, setData] = useState(null);

  useEffect(() => {
    fetchTasks().then(setData);
  }, []);

  if (!data) return <Loading />;

  return (
    <View>
      {/* 語音摘要，提高可訪問性 */}
      <Text accessible>{data.voice_summary}</Text>

      {/* 渲染任務列表 */}
      <FlatList
        data={data.tasks}
        renderItem={({ item }) => (
          <TaskCard
            title={item.title}
            date={item.endTimeFormatted}
            category={item.category}
            categoryColor={item.categoryColor}
            priority={item.priorityEmoji}
          />
        )}
      />
    </View>
  );
}

與語音聊天集成

響應中包含用於 TTS 的 voice_summary：

# 在你的聊天機器人服務中
response = await mcp_client.call('get_tasks', {
    'authorization': f'Bearer {user_jwt}'
})

# 用於可視化顯示
ui_data = response['tasks']

# 用於語音輸出
tts_text = response['voice_summary']
# "Hai 10 task, di cui 2 ad alta priorità. 5 sono in sospeso e 3 completati."

🔒 安全最佳實踐

1. 生產環境始終使用 HTTPS。
2. 確保 JWT_SECRET_KEY 安全：切勿將其提交到 Git。
3. 使用短期令牌（15 - 30 分鐘）。
4. 在客戶端實現令牌刷新機制。
5. 驗證受眾聲明（RFC 8707）：防止令牌重複使用。
6. 記錄認證失敗信息 以便監控。

🏗️ 架構與項目結構

系統架構

┌─────────────────────────────────────────────────────────────┐
│                    MyTaskly 生態系統                        │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│   ┌─────────────────┐                                       │
│   │  移動客戶端  │  1. 用戶認證               │
│   │ (React Native)  │  2. 接收 JWT 令牌                │
│   └────────┬────────┘  3. 調用 MCP 工具                   │
│            │                                                  │
│            ▼                                                  │
│   ┌─────────────────┐                                       │
│   │   MCP 服務器    │  4. 驗證 JWT（OAuth 2.1）        │
│   │ (本項目)  │  5. 從令牌中提取用戶 ID       │
│   └────────┬────────┘  6. 格式化數據以適配移動 UI        │
│            │                                                  │
│            ▼                                                  │
│   ┌─────────────────┐                                       │
│   │  FastAPI 服務器 │  7. 處理業務邏輯            │
│   │ (MyTaskly-API)  │  8. 管理數據庫操作       │
│   └────────┬────────┘  9. 返回原始數據                  │
│            │                                                  │
│            ▼                                                  │
│   ┌─────────────────┐                                       │
│   │   PostgreSQL    │  10. 持久化存儲               │
│   │    數據庫     │  11. 觸發器和通知         │
│   └─────────────────┘                                       │
│                                                               │
└─────────────────────────────────────────────────────────────┘

項目結構

MyTaskly-mcp/
├── src/
│   ├── core/                      # 核心 MCP 服務器
│   │   ├── __init__.py
│   │   └── server.py             # FastMCP 實例和工具註冊
│   │
│   ├── client/                    # HTTP 客戶端層
│   │   ├── __init__.py
│   │   ├── base.py               # 帶有認證的基礎 HTTP 客戶端
│   │   ├── categories.py         # 分類 API 端點
│   │   ├── tasks.py              # 任務 API 端點
│   │   ├── notes.py              # 筆記 API 端點
│   │   └── health.py             # 健康檢查端點
│   │
│   ├── tools/                     # MCP 工具（業務邏輯）
│   │   ├── __init__.py
│   │   ├── categories.py         # 分類工具（4 個方法）
│   │   ├── tasks.py              # 任務工具（8 個方法）
│   │   ├── notes.py              # 筆記工具（4 個方法）
│   │   ├── meta.py               # 元工具（3 個方法）
│   │   └── health.py             # 健康檢查工具（1 個方法）
│   │
│   ├── formatters/                # 響應格式化器
│   │   ├── __init__.py
│   │   └── tasks.py              # 為 React Native UI 格式化任務數據
│   │
│   ├── auth.py                    # JWT 認證
│   ├── config.py                  # 配置設置
│   └── http_server.py            # 可選的 HTTP 服務器包裝器
│
├── tests/                         # 測試套件
├── main.py                        # 主入口點
├── pyproject.toml                 # 項目配置
├── requirements.txt               # Python 依賴項
├── ARCHITECTURE.md                # 詳細架構文檔
└── README.md                      # 本文件

分層架構

關鍵組件

📚 如需詳細架構信息，請參閱 ARCHITECTURE.md

🛠️ 開發指南

添加新的 MCP 工具

遵循分層架構模式：

1. 添加 HTTP 客戶端方法

# src/client/tasks.py
async def new_operation(self, user_id: int, params...) -> Dict[str, Any]:
    """調用新的 FastAPI 端點。"""
    token = await self._get_user_token(user_id)
    return await self._post("/new-endpoint", token, json={...})

2. 添加 MCP 工具

# src/tools/tasks.py
async def new_tool(authorization: str, params...) -> Dict[str, Any]:
    """工具文檔說明。"""
    user_id = verify_jwt_token(authorization)
    result = await task_client.new_operation(user_id, params)
    return format_response(result)

3. 註冊工具

# src/core/server.py
from src.tools.tasks import new_tool
mcp.tool()(new_tool)

4. 更新 main.py 橫幅

在 print_banner() 中添加新工具到列表。

更多詳細信息，請參閱 ARCHITECTURE.md

代碼質量

# 使用 Black 格式化代碼
black src/ tests/

# 使用 Ruff 進行代碼檢查
ruff check src/ tests/

# 使用 mypy 進行類型檢查
mypy src/

# 運行測試並生成覆蓋率報告
pytest tests/ --cov=src --cov-report=html

常見開發任務

📚 資源與相關項目

MyTaskly 生態系統

• MyTaskly 移動應用：React Native 前端
• MyTaskly 服務器：FastAPI 後端
• MyTaskly MCP（本項目）：模型上下文協議服務器

文檔

• 模型上下文協議規範
• RFC 8707 - OAuth 2.0 資源指示符
• RFC 7519 - JSON Web 令牌（JWT）
• FastAPI 官方文檔

🤝 貢獻指南

我們歡迎貢獻！本項目是 MyTaskly 生態系統的一部分。

如何貢獻

1. ** Fork 倉庫**
2. 創建功能分支：git checkout -b feature/my-feature
3. 進行更改，並使用清晰的提交信息
4. 為新功能添加測試
5. 確保測試通過：pytest tests/ -v
6. 格式化代碼：black src/ tests/
7. 提交拉取請求

開發工作流

# 1. 克隆你的 Fork
git clone https://github.com/YOUR_USERNAME/MyTaskly-mcp.git
cd MyTaskly-mcp

# 2. 創建功能分支
git checkout -b feature/my-feature

# 3. 進行更改並測試
pytest tests/ -v

# 4. 提交帶有描述性信息的更改
git commit -m "feat: add new MCP tool for task statistics"

# 5. 推送並創建 PR
git push origin feature/my-feature

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

MIT 許可證允許你：

• ✅ 商業使用
• ✅ 修改
• ✅ 分發
• ✅ 個人使用

📞 支持與反饋

• 問題反饋：GitHub Issues
• 討論交流：GitHub Discussions
• 郵件支持：support@mytasklyapp.com