MCP 服务器

freelancer-focus-calendar

An MCP server for freelancers to manage events and tasks with CRUD, calendar views, webhook reminders, and Google Calendar sync.

README

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：

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 配置要点（后续阶段）

前往 Google Cloud Console 创建 OAuth 同意屏幕与 OAuth Client（Web）。
回调 URI 设为：http://127.0.0.1:8000/auth/google/callback（或你的部署域名）。
将生成的 CLIENT_ID、CLIENT_SECRET 填入 .env。
首版采用轮询增量同步（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"
      }
    }
  }
}