MyTaskly MCP服务器

![Python](https://www.python.org/) ![MCP](https://modelcontextprotocol.io/) ![FastAPI](https://fastapi.tiangolo.com/) ![License](LICENSE)

______________________________________________________________________

📋 主要特点

🔐 企业级身份验证

OAuth 2.1 JWT -遵循MCP 2025标准（RFC 8707）的基于令牌的身份验证
苏格兰和南方能源公司运输 -基于HTTP部署的服务器发送事件（铁路就绪）
基于上下文的身份验证 -从SSE请求标头中自动提取的令牌

🚀 高性能集成

HTTP API网关 -与FastAPI后端通信，无直接数据库访问
无状态架构 -无会话管理，完全可扩展
连接池 -优化异步HTTP客户端（httpx）

📱 移动优先设计

React原生优化 - show_* 工具返回为本机移动组件格式化的数据
语音友好响应 -包括 voice_summary 用于聊天应用程序中的TTS
双模式工具 - get_* 对于内部数据处理， show_* 触发UI更新

______________________________________________________________________

🛠️ 可用的MCP工具（18个活动）

MCP服务器提供 18个活动工具 分为3类。所有工具都需要通过SSE授权标头进行JWT身份验证。

工具遵循双重模式： get_* 返回用于模型推理的原始数据， show_* 触发移动应用程序中的UI渲染。

📋 任务工具（8）

工具	说明
`get_tasks`	使用过滤器获取任务——供内部模型使用（原始数据）
`add_task`	使用智能类别查找创建新任务
`update_task`	更新现有任务的一个或多个字段
`complete_task`	将任务标记为已完成的快捷方式
`get_task_stats`	按状态、优先级和类别获取汇总统计信息
`get_overdue_tasks`	获取所有过期的待处理任务
`get_upcoming_tasks`	获取未来N天内到期的任务
`show_tasks_to_user`	在移动应用UI中显示任务列表

示例响应-- get_tasks:

{
  "tasks": [
    {
      "task_id": 123,
      "title": "Pizza",
      "description": "Ordinare pizza margherita",
      "end_time": "2025-12-15T18:00:00",
      "start_time": null,
      "priority": "Alta",
      "status": "In sospeso",
      "category_id": 5,
      "duration_minutes": 30
    }
  ],
  "total": 10
}

示例响应-- add_task （成功）：

{
  "success": true,
  "task_id": 124,
  "category_used": "Cibo"
}

示例响应-- add_task （未找到类别）：

{
  "success": false,
  "message": "Categoria 'Cibo' non trovata.",
  "category_suggestions": ["Alimentari", "Cucina"],
  "action_required": "ask_user_to_create_category"
}

示例响应-- get_task_stats:

{
  "success": true,
  "by_status": {
    "In sospeso": 5,
    "Completato": 3,
    "Annullato": 1
  },
  "by_priority": {
    "Alta": 2,
    "Media": 4,
    "Bassa": 3
  },
  "by_category": { "5": 4, "3": 2 },
  "total": 9
}

示例响应-- get_overdue_tasks:

{
  "tasks": [
    {
      "task_id": 10,
      "title": "Consegnare report",
      "priority": "Alta",
      "status": "In sospeso",
      "end_time": "2025-12-01T09:00:00",
      "days_overdue": 14
    }
  ],
  "total": 1
}

示例响应-- show_tasks_to_user:

{
  "type": "task_list",
  "success": true,
  "filters_applied": {
    "priority": "Alta",
    "status": "In sospeso"
  }
}

______________________________________________________________________

📂 分类工具（5）

工具	说明
`get_my_categories`	获取所有用户类别——供内部模型使用（原始数据）
`create_category`	创建新类别
`update_category`	更新现有类别的名称或描述
`show_categories_to_user`	在移动应用UI中显示类别列表
`show_category_details`	在移动应用UI中显示单个类别的详细信息

示例响应-- get_my_categories:

{
  "categories": [
    {
      "category_id": 1,
      "name": "Lavoro",
      "description": "Task di lavoro"
    },
    {
      "category_id": 2,
      "name": "Casa",
      "description": "Faccende domestiche"
    }
  ],
  "total": 2
}

示例响应-- create_category:

{
  "success": true,
  "type": "category_created",
  "category_id": 3
}

示例响应-- show_categories_to_user:

{
  "type": "category_list",
  "success": true
}

______________________________________________________________________

📝 笔记工具（5）

工具	说明
`get_notes`	获取所有用户注释——供内部模型使用（原始数据）
`create_note`	创建新的便利贴样式注释
`update_note`	更新注释的文本、位置或颜色
`delete_note`	删除注释（不可逆）
`show_notes_to_user`	在移动应用UI中显示便签板

可用钞票颜色： #FFEB3B （黄色）， #FF9800 （橙色）， #4CAF50 （绿色）， #2196F3 （蓝色）， #E91E63 （粉红色）， #9C27B0 （紫色）

示例响应-- get_notes:

{
  "notes": [
    {
      "note_id": 456,
      "title": "Comprare il latte",
      "color": "#FFEB3B",
      "position_x": "100",
      "position_y": "250",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 3
}

示例响应-- create_note:

{
  "success": true,
  "type": "note_created",
  "note_id": 456
}

示例响应-- show_notes_to_user:

{
  "type": "note_list",
  "success": true
}

______________________________________________________________________

⚕️ 非活动工具（2--已评论）

工具	说明
`add_multiple_tasks`	一次性批量创建多个任务
`health_check`	检查服务器运行状况和连接（无需身份验证）

这些工具在 src/tools/ 但未注册。不作任何承诺 src/core/server.py 以启用。

______________________________________________________________________

🚀 入门指南

使用选项

你有 两种方式 要使用MyTaskly MCP服务器：

选项1：使用官方公共服务器（推荐）

使用 官方MyTaskly MCP服务器 （即将推出）-无需设置！

# Configure your MCP client to connect to:
# https://mcp.mytasklyapp.com (URL will be published soon)

优点：

✅ 无需安装或配置
✅ 始终保持最新功能
✅ 由MyTaskly团队管理和监控
✅ 与MyTaskly移动应用程序开箱即用

______________________________________________________________________

选项2：自主机（高级用户）

运行您自己的本地MCP服务器实例。

先决条件：

Python 3.11+ （建议使用虚拟环境）
MyTaskly快速API服务器 在本地运行（请参见 MyTaskly服务器)
JWT密钥 匹配您的FastAPI服务器配置

快速入门（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.克隆和安装

# Clone the repository
git clone https://github.com/Gabry848/MyTaskly-mcp.git
cd MyTaskly-mcp

# Create virtual environment
python -m venv venv

# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

2.配置环境变量

创建 .env 根目录中的文件：

# ============ FASTAPI BACKEND ============
FASTAPI_BASE_URL=http://localhost:8080
FASTAPI_API_KEY=your_api_key_here

# ============ JWT CONFIGURATION ============
# CRITICAL: Must match FastAPI server configuration!
JWT_SECRET_KEY=your_jwt_secret_key_here
JWT_ALGORITHM=HS256
MCP_AUDIENCE=mcp://mytaskly-mcp-server

# ============ SERVER CONFIGURATION ============
MCP_SERVER_NAME=MyTaskly MCP Server
MCP_SERVER_VERSION=0.1.1
LOG_LEVEL=INFO

# ============ DEPLOYMENT ============
HOST=0.0.0.0
PORT=8000

⚠️ 关键： JWT_SECRET_KEY 必须与您的FastAPI服务器匹配 SECRET_KEY 环境变量！

3.启动MCP服务器

python main.py

服务器启动于 SSE（服务器发送事件）模式 上 http://0.0.0.0:8000。配置您的MCP客户端以连接到此URL。

______________________________________________________________________

🔐 身份验证和安全

OAuth 2.1流程

MCP服务器使用符合OAuth 2.1和RFC 8707标准的JWT令牌。令牌自动从SSE提取 Authorization header——工具接收 ctx: Context 参数，不是显式的 authorization 弦。

┌─────────────────┐
│  Mobile Client  │
│  (React Native) │
└────────┬────────┘
         │ 1. Login request
         ▼
┌─────────────────┐
│  FastAPI Server │  2. Validates credentials
│  (Auth Server)  │  3. Generates JWT with MCP audience claim
└────────┬────────┘
         │ 4. Returns JWT token
         ▼
┌─────────────────┐
│  Mobile Client  │  5. Stores token securely
└────────┬────────┘
         │ 6. Calls MCP tools via SSE with Authorization header
         ▼
┌─────────────────┐
│   MCP Server    │  7. Extracts token from SSE context
│ (This project)  │  8. Validates JWT signature + audience
│                 │  9. Extracts user_id from "sub" claim
└────────┬────────┘
         │ 10. Makes HTTP request to FastAPI with user_id
         ▼
┌─────────────────┐
│  FastAPI Server │  11. Returns user-specific data
│ (Resource API)  │
└────────┬────────┘
         │ 12. Formats data for mobile UI
         ▼
┌─────────────────┐
│   MCP Server    │  13. Returns formatted response
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Mobile Client  │  14. Renders UI / plays TTS
└─────────────────┘

JWT令牌结构

JWT必须包含这些声明（遵循RFC 7519和RFC 8707）：

{
  "sub": "123",                              // User ID (required)
  "aud": "mcp://mytaskly-mcp-server",       // Audience (required, RFC 8707)
  "iss": "https://api.mytasklyapp.com",     // Issuer (optional)
  "exp": 1735689600,                         // Expiration timestamp (required)
  "iat": 1735686000,                         // Issued at timestamp (required)
  "scope": "tasks:read tasks:write notes:write" // Scopes (optional)
}

安全功能：

功能	实现
签名验证	HS256共享密钥
观众声明	防止跨服务的令牌重用（RFC 8707）
过期检查	自动令牌失效
用户隔离	每个请求都适用于经过身份验证的用户

获取JWT代币

选项1：来自FastAPI（生产）

将此端点添加到您的FastAPI服务器：

@router.post("/auth/mcp-token")
async def get_mcp_token(current_user: User = Depends(get_current_user)):
    """Generate JWT token for MCP server access."""
    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

# Generate test token for user_id=1
token = create_test_token(user_id=1, expires_minutes=30)
print(f"Test Token: {token}")

______________________________________________________________________

🧪 测试与开发

生成测试令牌

python -c "from src.auth import create_test_token; print(create_test_token(1))"

使用cURL进行手动测试

# Export token to environment variable
export MCP_TOKEN="your_token_here"

# Test get_tasks (SSE endpoint)
curl -X POST http://localhost:8000/mcp/get_tasks \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json"

# Test add_task
curl -X POST http://localhost:8000/mcp/add_task \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Comprare latte", "category_name": "Casa", "priority": "Bassa"}'

自动化测试套件

# Run all unit tests
python -m pytest tests/ -v

# Run specific test file
python -m pytest tests/test_auth.py -v

# Run with coverage report
python -m pytest tests/ --cov=src --cov-report=html

______________________________________________________________________

🔒 安全最佳实践

始终使用https 生产中
确保JWT_SECRET_KEY的安全 -永远不要使用git
使用短期代币 （15-30分钟）
实现令牌刷新 在你的客户
验证受众声明 （RFC 8707）-防止令牌重用
记录身份验证失败 用于监控

______________________________________________________________________

🏗️ 建筑与项目结构

系统架构

┌─────────────────────────────────────────────────────────────┐
│                    MyTaskly Ecosystem                        │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│   ┌─────────────────┐                                       │
│   │  Mobile Client  │  1. User authentication               │
│   │ (React Native)  │  2. Receives JWT token                │
│   └────────┬────────┘  3. Calls MCP tools via SSE          │
│            │                                                  │
│            ▼                                                  │
│   ┌─────────────────┐                                       │
│   │   MCP Server    │  4. Validates JWT (OAuth 2.1)        │
│   │ (This project)  │  5. Extracts user_id from token       │
│   └────────┬────────┘  6. Formats data for mobile UI        │
│            │                                                  │
│            ▼                                                  │
│   ┌─────────────────┐                                       │
│   │  FastAPI Server │  7. Handles business logic            │
│   │ (MyTaskly-API)  │  8. Manages database operations       │
│   └────────┬────────┘  9. Returns raw data                  │
│            │                                                  │
│            ▼                                                  │
│   ┌─────────────────┐                                       │
│   │   PostgreSQL    │  10. Persistent storage               │
│   │    Database     │  11. Triggers & notifications         │
│   └─────────────────┘                                       │
│                                                               │
└─────────────────────────────────────────────────────────────┘

项目结构

MyTaskly-mcp/
├── src/
│   ├── core/                      # Core MCP server
│   │   ├── __init__.py
│   │   └── server.py             # FastMCP instance, log_tool decorator & tool registration
│   │
│   ├── client/                    # HTTP client layer
│   │   ├── __init__.py
│   │   ├── base.py               # BaseClient with async HTTP methods + JWT token generation
│   │   ├── categories.py         # CategoryClient
│   │   ├── tasks.py              # TaskClient (with status/priority normalization)
│   │   ├── notes.py              # NoteClient
│   │   └── health.py             # HealthClient
│   │
│   ├── tools/                     # MCP tool definitions
│   │   ├── __init__.py
│   │   ├── categories.py         # 5 category tools
│   │   ├── tasks.py              # 8 task tools
│   │   ├── notes.py              # 5 note tools
│   │   ├── meta.py               # add_multiple_tasks (inactive)
│   │   └── health.py             # health_check (inactive)
│   │
│   ├── formatters/                # Response formatters for React Native
│   │   ├── __init__.py
│   │   └── tasks.py              # format_tasks_for_ui, format_categories_for_ui, format_notes_for_ui
│   │
│   ├── auth.py                    # JWT authentication (extract, verify, create_test_token)
│   ├── config.py                  # Pydantic settings (loaded from .env)
│   └── http_server.py            # HTTP server wrapper
│
├── tests/                         # Test suite
├── main.py                        # Entry point — runs FastMCP in SSE mode
├── pyproject.toml                 # Project configuration
├── requirements.txt               # Python dependencies
├── ARCHITECTURE.md                # Detailed architecture documentation
└── README.md                      # This file

层架构

图层	文件	责任
核心层	`src/core/`	FastMCP实例， `log_tool` 工具注册装饰师
工具层	`src/tools/`	MCP工具定义——身份验证、业务逻辑、响应整形
客户端层	`src/client/`	与FastAPI后端异步HTTP通信
格式化程序层	`src/formatters/`	将API响应转换为React Nativeready结构

关键组件

组件	技术	目的
MCP 服务器	FastMCP+SSE	请求处理、工具编排、铁路部署
JWT身份验证	PyJWT（HS256）	通过SSE上下文标头进行令牌验证
HTTP客户端	httpx（异步）	FastAPI后端通信
数据格式化程序	自定义格式化程序	带有语音摘要的移动优化响应结构

📚 有关详细的架构信息，请参阅建筑.md

______________________________________________________________________

🛠️ 开发指南

添加新的MCP工具

遵循分层架构模式：

1.添加HTTP客户端方法

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

2.添加MCP工具

# src/tools/tasks.py
from fastmcp import Context
from src.auth import authenticate_from_context

async def new_tool(ctx: Context, params...) -> Dict[str, Any]:
    """Tool documentation here."""
    user_id = await authenticate_from_context(ctx)
    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()(log_tool(new_tool))

更多详细信息，请参阅建筑.md

代码质量

# Format code with Black
black src/ tests/

# Lint with Ruff
ruff check src/ tests/

# Type checking with mypy
mypy src/

# Run tests with coverage
pytest tests/ --cov=src --cov-report=html

常见开发任务

任务	命令
运行服务器	`python main.py`
生成测试令牌	`python -c "from src.auth import create_test_token; print(create_test_token(1))"`
运行测试	`pytest tests/ -v`
检查覆盖范围	`pytest tests/ --cov=src`
格式代码	`black src/ tests/`
安装依赖项	`pip install -r requirements.txt`

______________________________________________________________________

📚 资源及相关项目

MyTaskly生态系统

Mytaskly移动应用程序 -React原生前端
MyTaskly服务器 -FastAPI后端
MyTaskly MCP （本项目）-模型上下文协议服务器

文档

______________________________________________________________________

🤝 贡献

我们欢迎捐款！该项目是MyTaskly生态系统的一部分。

如何做出贡献

分叉存储库
创建要素分支: git checkout -b feature/my-feature
进行更改 带有明确的提交信息
添加测试 对于新功能
确保测试通过: pytest tests/ -v
格式代码: black src/ tests/
提交拉取请求

开发工作流程

# 1. Clone your fork
git clone https://github.com/YOUR_USERNAME/MyTaskly-mcp.git
cd MyTaskly-mcp

# 2. Create feature branch
git checkout -b feature/my-feature

# 3. Make changes and test
pytest tests/ -v

# 4. Commit with descriptive message
git commit -m "feat: add new MCP tool for task statistics"

# 5. Push and create PR
git push origin feature/my-feature

______________________________________________________________________

📄 许可证

该项目根据 MIT许可证 -看看许可证文件以获取详细信息。

MIT许可证允许您：

✅ 商业用途
✅ 修改
✅ 分发
✅ 专用

______________________________________________________________________

📞 支持与反馈

问题:
讨论:
电子邮件: support@mytasklyapp.com

______________________________________________________________________

制作❤️ 通过 Gabry848 作为 MyTaskly 项目

欣赏主演！ ⭐

⬆ 返回页首

My Taskly MCP

快速接入

详细介绍

MyTaskly MCP服务器

📋 主要特点

🔐 企业级身份验证

🚀 高性能集成

📱 移动优先设计

🛠️ 可用的MCP工具（18个活动）

📋 任务工具（8）

📂 分类工具（5）

📝 笔记工具（5）

⚕️ 非活动工具（2--已评论）

🚀 入门指南

使用选项

选项1：使用官方公共服务器（推荐）

选项2：自主机（高级用户）

自助主机设置指南

1.克隆和安装

2.配置环境变量

3.启动MCP服务器

🔐 身份验证和安全

OAuth 2.1流程

JWT令牌结构

获取JWT代币

🧪 测试与开发

生成测试令牌

使用cURL进行手动测试

自动化测试套件

🔒 安全最佳实践

🏗️ 建筑与项目结构

系统架构

项目结构

层架构

关键组件

🛠️ 开发指南

添加新的MCP工具

1.添加HTTP客户端方法

2.添加MCP工具

3.注册工具

代码质量

常见开发任务

📚 资源及相关项目

MyTaskly生态系统

文档

🤝 贡献

如何做出贡献

开发工作流程

📄 许可证

📞 支持与反馈

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP