Freelancer's Focus Calendar (MCP 服务) — 自由职业者日程管理

一个面向自由职业者的轻量级日程/待办管理服务：事件 CRUD、Webhook 提醒、日/周/月视图、Google Calendar 双向同步（逐步实现）。提供清晰的 API 以及 MCP 集成（以工具形式暴露）。

功能概览

• 事件管理（CRUD）：标题、开始/结束时间、描述、客户名称、标签

• 提醒（Webhook 回调）：签名、重试、幂等等（逐步实现）

• 日历视图：日/周/月查询与过滤

• Google Calendar 双向同步（OAuth2，增量同步，逐步实现）

• OpenAPI 文档（随 FastAPI 自动提供）

Related MCP server: gcal-mcp

快速开始

先决条件

• Python 3.11+（建议 3.11 或 3.12）

• Windows/WSL/macOS/Linux 均可

• 推荐使用 uv（https://github.com/astral-sh/uv）进行依赖管理

安装依赖

优先使用 uv：

uv sync

若本机没有 uv，可用 pip 直接安装关键依赖：

python -m pip install -U pip
pip install fastapi "uvicorn[standard]" sqlmodel apscheduler httpx python-dotenv \
  google-api-python-client google-auth-httplib2 google-auth-oauthlib "mcp[cli]"

MCP配置

{ "mcpServers":{ "mcp-calendar-focus": { "disabled": false, "timeout": 60, "type": "sse", "url": "http://127.0.0.1:8000/sse" } } }

运行开发服务器

uv run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# 或（未安装 uv）
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

启动后：

• 健康检查: http://127.0.0.1:8000/healthz

• OpenAPI 文档: http://127.0.0.1:8000/docs

环境变量与配置

在项目根目录创建 .env（开发示例）：

API_KEY=DEV-KEY-CHANGE-ME
TZ=Asia/Shanghai
DATABASE_URL=sqlite:///./data.db

# Google OAuth（待接入阶段使用）
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://127.0.0.1:8000/auth/google/callback

# Webhook 签名密钥（可注册多个 webhook 时每条记录自带 secret）
WEBHOOK_DEFAULT_SECRET=change-me

说明：

• API_KEY：比赛阶段可采用简单的 Header 认证（X-API-Key），后续可扩展为多租户/用户体系。

• TZ：服务内部的用户默认时区（可后续按用户维度存储）。

• DATABASE_URL：MVP 使用 SQLite，后续可切换 Postgres。

简单示例

当前已实现接口：

• 健康检查（healthz）

示例 1：健康检查

curl -s http://127.0.0.1:8000/healthz
# {"status":"ok"}

示例 2： “创建一个8月16日10点到11点，标题为 Design Review，客户 ACME，标签 design/review 的事件，并返回事件ID” “列出8月16日当天 ACME 的事件” “给我 2025-08-16 的日视图，时区 Asia/Shanghai”

即将提供（实现中，参考 PRD 的字段约定）：

• 创建事件：POST /events

• 查询事件：GET /events?start=&end=&tags=&client_name=&q=

• 更新事件：PATCH /events/:id

• 删除事件：DELETE /events/:id

• 日历视图：GET /calendar?date=&view=day|week|month

• Webhook 注册/管理：POST /webhooks, DELETE /webhooks/:id

• Google OAuth：GET /auth/google/start, GET /auth/google/callback

• 同步：POST /sync/google/pull, POST /sync/google/push

待事件接口完成后，你可以这样创建一个事件（示例请求体，非最终，以实现为准）：

curl -X POST http://127.0.0.1:8000/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: DEV-KEY-CHANGE-ME" \
  -d '{
    "title": "Design Review",
    "start_time": "2025-08-16T10:00:00+08:00",
    "end_time": "2025-08-16T11:00:00+08:00",
    "description": "Review with client",
    "client_name": "ACME",
    "tags": ["design","review"]
  }'

Webhook 调试建议

• 开发期可使用 https://webhook.site 或 ngrok/cloudflared 将本地端口暴露到公网。

• 回调请求将包含签名头 X-Signature（HMAC-SHA256(body, secret)）；接收端需校验后返回 2xx。

• 失败会按指数退避重试（如 1m / 5m / 15m / 1h，达到上限停止）。

Google OAuth 配置要点（后续阶段）

1. 前往 Google Cloud Console 创建 OAuth 同意屏幕与 OAuth Client（Web）。

2. 回调 URI 设为：http://127.0.0.1:8000/auth/google/callback（或你的部署域名）。

3. 将生成的 CLIENT_ID、CLIENT_SECRET 填入 .env。

4. 首版采用轮询增量同步（syncToken），后续可支持 Push Notifications（watch channels）。

MCP 集成配置（示例）

当前项目将提供一个 MCP Server（stdio）用于把日程能力暴露为「工具」，便于在 AI 客户端中直接调用。MCP 入口将在后续文件（例如 servers/calendar_mcp.py）中实现，以下为未来可用的客户端配置示例。

以 Claude Desktop（settings.json）为例：

{
  "mcpServers": {
    "freelancer-calendar": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "servers/calendar_mcp.py"
      ],
      "env": {
        "CALENDAR_API_BASE": "http://127.0.0.1:8000",
        "API_KEY": "DEV-KEY-CHANGE-ME"
      }
    }
  }
}

MCP 侧将暴露的典型工具（规划中）：

• create_event(title, start_time, end_time?, description?, client_name?, tags?)

• list_events(start, end, filters?)

• get_calendar(date, view, filters?)

• register_webhook(url, secret?, filters?)

• sync_google(direction?) // pull, push

说明：

• 以上为“配置示例”，帮助你在完成 MCP 入口后快速集成到 Claude Desktop 或其他支持 MCP 的客户端。

• 你也可以使用 mcp[cli] 自带的客户端进行本地调试。

路线图（与 docs/tasks.md 同步）

• 阶段一：项目初始化（进行中）

• 阶段二：事件管理（CRUD）

• 阶段三：日/周/月视图

• 阶段四：Webhook 提醒

• 阶段五：Google Calendar 双向同步

• 阶段六：安全与文档

• 阶段七：演示与样例

许可

本仓库用于比赛演示，若用于生产请补充 License 与合规说明。