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

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

## 功能概览
- 事件管理（CRUD）：标题、开始/结束时间、描述、客户名称、标签
- 提醒（Webhook 回调）：签名、重试、幂等等（逐步实现）
- 日历视图：日/周/月查询与过滤
- Google Calendar 双向同步（OAuth2，增量同步，逐步实现）
- OpenAPI 文档（随 FastAPI 自动提供）

## 快速开始

### 先决条件
- Python 3.11+（建议 3.11 或 3.12）
- Windows/WSL/macOS/Linux 均可
- 推荐使用 uv（https://github.com/astral-sh/uv）进行依赖管理

### 安装依赖
优先使用 uv：
```bash
uv sync
```

若本机没有 uv，可用 pip 直接安装关键依赖：
```bash
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"
        }
    }
}

### 运行开发服务器
```bash
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：健康检查
```bash
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

待事件接口完成后，你可以这样创建一个事件（示例请求体，非最终，以实现为准）：
```bash
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）为例：
```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 与合规说明。