Schedule MCP · 個人プロジェクトスケジュール管理ツール

ミニマル設計の個人プロジェクトスケジュール管理ツール。1つの Python サービスが同時に2つの役割を担います。

1. MCP Server：Verdure MCP Platform / imcp.pro などのプラットフォームを通じて小智 AI に接続し、小智が音声・対話でスケジュールデータを手軽に読み書きできるようにします。また、ルールに基づいた用事のリマインダーを提供します（残りの自然な文言組み立ては小智サーバー側の DeepSeek v4 モデル任せです）。

2. REST API + PC フロントエンド：PC ブラウザからデプロイしたサービスの /app ページに直接アクセス（またローカルで web/index.html を開きデプロイ先アドレスを指定）することで、カレンダー / ・カート図表（編集可能）/ 多方プロジェクト管理 / TODO リスト（近日・後日）を直感的に表示・編集できます。

データ保存は SQLite（追加に依存し）で、デプロイすればすぐ利用でき、ローカルで後客端末を動かす必要はありません。

参考プロジェクト：shiikun-cn/tarot-mcp（MCP-over-HTTP 互換モードで動作確認済み）。

機能一覧

Related MCP server: Todoist MCP Server

プロジェクト構築

schedule-mcp/
├── app.py                     # Flask 主服务：MCP JSON-RPC 兼容层 + REST API + 前端托管
├── db.py                      # SQLite 数据层 + 设置 + 自动任务状态 + 提醒规则引擎 + 备份/恢复
├── requirements.txt           # 仅 Flask + gunicorn（SQLite 用标准库）
├── Dockerfile                 # 容器镜像（gunicorn 生产启动，PORT 环境变量）
├── .gitignore
├── .github/workflows/
│   └── keep-alive.yml         # 服务保活（Render 免费版必须，详见下文说明）
├── web/
│   └── index.html             # PC 端前端（单文件，无外部依赖）
├── smoke-test.mjs             # 端到端冒烟测试（35 项断言）
├── seed-demo.mjs              # 演示数据播种（日期相对今天）
└── data/                      # SQLite 数据库文件（data/schedule.db，不入库）

データモデル

すべての日付形式は YYYY-MM-DD。リマインダーはDBに保存されず、ルールエンジンがリアルタイム算出します。

注意：旧バージョンの paused/completed プロジェクト状態は、起動時に planned/archived へ自動移行します。progress（タスク進捗）と due_date（TODO の期限日）は製品レイヤーから削除されています（データベースの列は旧バックアップ互換のために残していますが、読み書き・表示では使用しません）。

自動タスク状態のルール（設定で有効化すると適用）

• 今日が開始日より前 → todo（未着手）

• 今日が開始日 ～ 終了日・期限日の間 → doing（進行中）

• 今日が終了日・期限日より後 → done（完了。*期限切れ**の蓄積を回避）

• タスクに日付属性が無い → 状態を保持

• 新規作成・更新時に即時分類（同日の突発制限を受けません）。一括実行は同じ日に1回だけ実行（last_auto_date で突きすると）、設定パネルの「今すぐ実行」で強制できます

• タスク・スケジュールの照会時にも自動的に起動（有効時）

MCP ツール一覧（16個・小智 AI による呼び出し）

AI に返すデータは省略されています：全ツールの metadata に color、created_at、updated_at、project_color は含まれません。タスクには progress、TODO には due_date は含まれません。content[0].text は中文で読みやすいテキスト、metadata は構造化データで、両者のフィールドは一致します。

ツールをコメントアウト / 削除する方法（重要）

ツールには（** app.py 内の TOOLS リストにまとめて定義されています**（約260～560列目）。1つのツールはリスト内の1つのオブジェクトで、name / description / inputSchema / handler の4つのフィールドを持ちます。tools/list は TOOLS から自動生成されるので、コメントアウト、AI から非表示になる、変更する、その他のコードを変更する必要はありません。保存后、サーバーを再起動してちょうど有効になります。

例 1：create_project ツールをコメントor（小智にプロジェクト作成させない）

# app.py 中 TOOLS 列表里，把整个对象包进注释：
    # {
    #     "name": "create_project",
    #     "description": "新建一个项目。…",
    #     "inputSchema": {…},
    #     "handler": tool_create_project,
    # },

例 2：ツールの説明だけを変更（AI にいつ使うのを伝える）

    {
        "name": "get_reminders",
        "description": "获取事务提醒…。建议每天早上询问用户时优先调用。",
        # ↑ 只改 description 字符串即可
        …
    },

例 3：タスク関連ツールだけを残す

TOOLS の中の非リマインダー系（例：create_project、list_tasks、create_todo）など）ごとコメントアウトし、get_reminders、get_schedule、get_schedule_summary を残します。小智側で Verdure に再開発検出すると、残った下のツールのみ見えます。

ヒント：変更後は Verdure でMCP サーバーの設定を保存/リロードして再発行を促してください。TOOLS を変更したら、ローカルで再起動して node smoke-test.mjs でツールー内容が予期通りになっているか確認することをおすすめします（アサーションは16個に設定済みなので、コメントアウトしたらスクリプトの expected 配列も合わせて変更）。

REST API（PC フロントエンドから直接接続、CORS を全面CORS）

共通レスポンスは {"code":0,"data":…}。エラは {"code":4xx/5xx,"error":"…"}。認証は任意で、環境変数 API_KEY を設定すると、全リクエストに X-API-KEY ヘッダーが必要になります（/health と /app を除く、keep-alive とページ性の維持のため）。

ローカルで試す（動作確認）

cd schedule-mcp
python -m venv .venv
# Windows: .venv\Scripts\activate     macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
python app.py        # 默认监听 0.0.0.0:8080，可用环境变量 PORT 修改

💡 gunicorn は Linux のみ：gunicorn は Unix の fcntl に依存するので、Windows ではローカル実行できません（Render/Dinux コンテナへのデプロイでは影響ありません）。ローカルデバッグは必ず python app.py（Flask 開発サーバー、機能は同じ）。本番は Dockerfile で gunicorn を使用します。

確認手順：

# 1) 健康检查
curl http://127.0.0.1:8080/health

# 2) MCP 握手
curl -X POST http://127.0.0.1:8080/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'

# 3) 列出工具（应 16 个）
curl -X POST http://127.0.0.1:8080/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'

# 4) 今日日程（新工具）
curl -X POST http://127.0.0.1:8080/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_schedule","arguments":{"range":"today"}}}'

# 5) 事务提醒
curl -X POST http://127.0.0.1:8080/ -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_reminders","arguments":{}}}'

# 6) 设置：星期定义 / 自动任务状态
curl http://127.0.0.1:8080/api/settings
curl -X PUT http://127.0.0.1:8080/api/settings -H "Content-Type: application/json" \
  -d '{"week_start":"sun","auto_task_status":"1"}'

ブラウザで http://127.0.0.1:8080/app を開くと PC パネルが使えます（同じオリジンからの直接接続で設定不要）。直接 web/index.html をダブルで開く場合は、⚙ 設定で API アドレスを http://127.0.0.1:8080 に設定します。

同梱される自己テスト / デモスクリプト：

node smoke-test.mjs            # 端到端冒烟测试（35 项断言，含自动状态/设置/字段精简）
node seed-demo.mjs             # 播种演示数据（一个项目+4任务+4待办，日期相对今天）

データリセット：data/schedule.db を削除して再起動します（リポジトリのデフォルトの gitignore で DB ファイルは除外済み）。

デプロイ手順（GitHub → Render → Verdure → 小智 AI）

第1章：GitHub にアップロード

1. GitHub でリポジトリを作成（schedule-mcp など、Private/Public どちらでも可）。

2. コードをプッシュします（data/*.db を含めない。.gitignore で除外済み。また .venv/ も含めないこと推奨）：

cd schedule-mcp
git init
git add .
git commit -m "feat: schedule-mcp 个人排程 MCP 服务"
git branch -M main
git remote add origin https://github.com/<你的用户名>/schedule-mcp.git
git push -u origin main

第2章：Render にデプロイ（無料）

1. render.com を開く→ New → Web Service → 自分の GitHub リポジトリを接続。

2. 設定：

   • Name：schedule-mcp（任意）

   • Environment：Python 3（or Docker。Docker を選んだ場合は以下の Build/Start は不要）

   • Build Command：pip install -r requirements.txt

   • Start Command：gunicorn -w 2 -b 0.0.0.0:${PORT:-8080} app:app --timeout 30

   • InstanceType：Free

   • （任意）Environment Variables：API_KEY=あなたのランダムキー（設定すると MCP/REST リクエストに X-API-KEY が必要）

3. Deploy するとビルドが完了します。サービス URL は https://schedule-mcp.onrender.com になります。

4. ブラウザで https://schedule-mcp.onrender.com/health を開き、{"code":0,"status":"ok" …} を確認。

⚠️ Render 無料版の注意：

• 無料インスタンスは約15分間トラフィックがないとスリープします。次のリクエストはコールドスタートで最初は遅くなります50秒）→ 必ず keep-alive を有効にしてください（下記）。

• 無料版のファイルシステムは一時です：再デプロイ / 再起動時に SQLite データが初期化されます。個人利用では ⚙ 設定で「バックアップ出力」を定期的におこない、または再構築後に再入力する場合が過度です。

第3章：keep-alive を有効化（Render 無料版は必須）

1. .github/workflows/keep-alive.yml を編集し、URL を自分のサービスURLに変更（例：https://schedule-mcp.onrender.com/health）。

2. （任意）API_KEY を設定している場合は、GitHub の Settings → Secrets and variables → Actions → New repository secret から SERVICE_API_KEY を追加し、workflow で該当行を有効にします。

3. 変更を push。Actions が10分ごとに /health に ping して、サービスをアクティブに保ちます。

4. 特に workflow の keep-alive が機能しない場合は、cron-job.org などの cron サービスから GET リクエストを10～14分間隔で送信します。

第4講：Verdure MCP Platform に MCP サーバーを追加

1. Verdure MCP Platform にログインします（アカウントがない場合は、参照先と同じ方法で登録してください。プラットフォームは小智 / トゥヤなどのアシスタントエンドポイントと接続されます）。

2. 「MCP サーバーを追加 / 管理」ページで HTTP タイプを選択（Verdure は POST / の JSON-RPC を探索します。本サービスはこれを実装しており、tarot-mcp とまったく一致しています）。

3. 記入：

   • サービス URL：https://schedule-mcp.onrender.com/（ルートだけを指定。/ で MCP JSON-RPC を処理）

   • 認証を設定している場合は X-API-KEY に対応するヘッダーを入力

4. 保存後にプラットフォームが自動的に initialize と tools/list を実行し、上記の16ツールが表示されます。ツールが空の場合は、/health がアクセス可能か、最後に /api など余分なパスが付いていないか確認してください。

5. 追加した MCP サーバーを小智 AI のアシスタントにバインドします（プラットフォームでアシスタント → サーバーを関連付ける）。

第5ステップ：小智 AI の音声動作確認

小智に次のような指示をして、読み書きをテストします：

• 「今日は何をする？」/「今日の予定は？」 → get_schedule（優先）

• 「何かリマインドして」 → get_reminders

• 「今週はどう？」/「今月はどう？」 → get_schedule(range=week/month)

• 「購入航空券をTODOに追加、高優先度」 → create_todo

• 「家のリフォームというプロジェクトを新規追加、11月1日から12月31日まで、最高優先度」 → create_project

• 「リフォームプロジェクトにタスクを追加：設計・ソリューションの結果、12月1日締切」 → create_task

• 「どのプロジェクトがある？プロジェクトの進捗はどう」 → list_projects / list_tasks / get_gannt

• 「〇〇タスクを完了に」 → update_task

keep-alive の説明（研究結果）

結論：keep-alive は、MCP プロトコルの要件ではありません。Verdure MCP Platform の要件でもありません。 ただ、トラフィックがないとスリープする無料ホスティング（Render Free / Railway 無料枠など）にデプロイしている場合のみ必須です。

考慮:

1. 参考プロジェクト tarot-mcp の keep-alive.yml は、GitHub Actions のスケジュールタスク。10分ごとに curl で /health を GET しており、URL は https://tarot-mcp.onrender.com/health。これは Render 無料インスタンスが約15分無応答でスリープする対策です。

2. MCP プロトコル自体（initialize / tools/list / tools/call）に keep-alive の要件はありません。Verdure プラットフォームは「接続 + リモート注入」の中間層で、あなたのサービスの起動を代わりに行うわけではありません。あくまでオンライン状態のときにツールを小智に注入します。

3. つまり：

   • スリープするホスティング（Render Free / Railway 無料枠）→ keep-alive を残す（スリープする: 呼び出し時にコールドスタートが遅い・タイムアウトになるため）

   • 有料常駐インスタンス（Render Starter+、クラウドサーバー等）や Verdure のマネージドホスティングで → .github/workflows/keep-alive.yml を削除しても良い（直接影響はありません）

4. このプロジェクトはデフォルトで keep-alive.yml を保持・適応しています（URL を自分のサービストに書き換える必要がある） — が、参考プロジェクトは Render フリー版で動いており、このデプロロイー方法と同様だからです。

よくある質問

Q：デプロイ後、小智が「利用できるツールがない」と言う A：まず https://<あなたの>.com/health がアクセス可能かを確認してください。Verdure プラットフォーム上でサーバーの設定を保存/再読込みして再発見させましょう。注意：アドレはルート（/）を相手、/API などを追加しない」。

Q：AI に答エマイ感を中心で、マスタ形式のツールを少なくするには？ A：上記「ツールをコメントアウト / 対応」で説明した通り、app.py の TOOLSリストで不要なツールをコメントアウトし、再起動後に *Verdure で再読込み。

Q：自動タスク状態で手動での「完了」が変更されます？ A：有効にすると、タスク状態は日付から自動導出します（未開始→待办、進行中→進行中、期限切れ→完了）。手動で制御したい場合は設定のスイッチをオフして、その後は手動変更のみ有効です。

Q：Renderの無料版を再起動するとデータが消えまし? A：無料インスタンスの filesystem は一時的です。⚙ 設定 → バックアプ出力 で定期的にJSON保存し、次回は「バックアプから復元」でインポートします（バックアプは設定含）。他プロバイダーの利用：

Q：API 認をどう追加する？ A：Renderの環環境変数に API_KEY=xxx を設定します。これでMCP（時) もREST(/api/) も X-API-KEY ヘッダーが必須になります。Frontendの ⚙ 設定に Keyを入力し、KEEP-aliveの workflow には secret設定します。

Q：他の場所にデプロイしてもよいですか？ A：はい。Python が起動する任意のホステことができます（Railway / Fly.io / お名 VPS / 内网NAS など）。SQLite は data/ にあり、永続ボリと組み合わせるとデータを失いません。

Q：小智が実際に呼んだツールを確認するには？ A：Render のログ（Logs）に tools/call のパラメータ・結果が毎回出力されます。また / の GET リスポンスのツールリストでツール一覧を確認できます。

実装上の要点（tarot-mcp との応換性維持）

• MCP は JSON-RPC over HTTP（単一エンドポイント POST /）を使用し、initialize（protocolVersion 2024-11-05）、notifications/initialized、tools/list、tools/call、ping を実装します。未知のメソッドには空の結果を返し、tarot-mcp 互換パッチと一致しています。Verdure / imcp.pro 系プラットフォームで動作確認済みです。

• CORS は全開放（Access-Control-Allow-Origin: *）。PC 側の HTML からはクロスドメインで REST API に直接接続できます。

• SQLite は WAL モード + リクエストごとに独立した接続を使用し、gunicorn マルチワーカーと組み合わせて安全な読み書きを実現します。

• ツールは content[0].text（中国語で読みやすい）+ metadata（構造化 JSON。color/created_at/updated_at/project_color など AI に無関係なフィールドは除外済み）を返し、AI の理解と機械解析を両立します。

• 設定（自動タスク状態 / 曜日定義）はサーバー側の settings テーブルに保存され、フロントエンドパネルと MCP クエリが同じ設定を共有します。「本周」の集計はフロントエンドのカレンダー・週間カレンダーとすべてこの曜日定義に従います。