Schedule MCP · Personal Project Scheduling Tool

A minimalist personal project scheduling tool. A single Python service plays two roles at once:

1. MCP Server: connects to 小智AI through platforms such as Verdure MCP Platform / lmcp.pro, letting 小智 easily read and write your scheduling data via voice/conversation, and provides rule-based reminders (remaining natural-language composition is handled by the DeepSeek v4 model on 小智's server side).

2. REST API + PC frontend: For access the deployed service's /app page in a browser on your PC (or open web/index.html locally and point it at the deployment URL), giving intuitive views and editing for calendar / Gantt (editable) / multi-project / to-do plan (near-term/far-term).

Data storage uses SQLite (zero extra dependencies), ad hoc; read to use immediately after deployment without any local backend.

Reference project: shikun-cn/tarot-me (MCP-over-HTTP compatibility mode has been verified to work).

Feature row

| Capability | Description | | `-------- | ----------------------------------------------------------------------- | | Attribution? Actually table as original. In translation, separator row must be copied from original. We'll use original dash count.

[Since we need preserve structure exactly, we output same separator rows. We'll include row.

Let's final.

I will output translation fully.# Schedule MCP · Personal Project Scheduling Tool

A minimalist personal project scheduling tool. One Python service is responsible for two roles:

1. MCP Server: connects to 小智AI through platforms such as Verdure MCP Platform / imcp.pro, letting 小智 easily read and write your scheduling data via voice/conversation, and provides rule-based task reminders (the remaining nat-anguage generation is handled by the DeepSeek v4 model on 小智's server side).

2. RST API + PC frontend: on your PC, open the deployed service's /app page directly in the browser (or open web/index.html with a curl to the deployment URL), giving intuitive views and editing of calendar / Gantt chart (editable) / multi-project management / to-do plans (near-term/far-term).

Data uses SQLite (zero extra dependencies), ready to use after deployment without running any backend locally.

Referenced project: erikun-me/tarot-me (MCP-over-HTTP compatibility mode has been verified working).

Related MCP server: Todoist MCP Server

Feature breakdown

Project structure

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，不入库）

Data model

All dates format: YYYY-MM-DD. Reinders are not stored, computed real-time by the rules engine.

Note: In older versions, paused/completed project states are automatically migrated to planned/archived at startup; the progress field (task progress) and due_date (to-do) field) have been removed at the product layer (database columns are kept for compatibility with old backups, but reads, writes and displays no longer use them).

Auto task status rules (effective when enabled in settings)

• Today before the start date → todo (to-do)

• Today inside start date ~ end/due date → doing (in progress)

• Today after the end/due date → Done (complete, avoids accumulating "over-due")

• Task with no date property → kept as-is

• When you create/update a task, it is categorized immediately (not limited by the idempotence guard per day); the full pass runs only once per day (last\_auto\_date idempotence), and "Run now" in Settings panel forces it

• Querying tasks/schedules also triggers it automatically (if enabled)

MCP tool list (16, for 小智AI to call)

| Tool | Purpose | Typical question example | | ---|---|| | list\_projects | List projects (filtered by state) | "What projects do I have?" | | create\_project | Create a project | "Create a "remodel" project, Nov to Dec, highest priority" | | update\_project | Update a project (state/time/priority…) | "Mark project X as in progress/archived" | | delete\_project | Delete a project (cascade-delete tasks) | "Delete project X" or just "Delete X" | | list\_tasks | List tasks (filter by project/state) | "What tasks are in X?" | | create\_task | Create a task under a project | "Add a task to X, due tomorrow" | | update\_task | Update a task (state/time…) | "Mark task X as completed" | | delete\_task | Delete a task | "Delete task X" | | list\_todos | List to-do plans (near/far) | "What are my to-dos?" | | create\_todo | Create a to-do plan (no date, with priority) | "Add a to-do: buy flight tickets" | | update\_todo | Update a to-do plan (complete/change category/priority) | "Cross off X" | | delete\_todo | Delete a to-do plan | "Delete X" | | get\_reminders | Task reminders (over-due / today / due soon / project near end) | "What do I need a reminder for?" | | get\_schedule | Compact schedule: range=tooday/week/month (default today) | For "What do I do today?" to use first | | get\_schedule\_summar | Schedule overview (today/week/month + stats) | "How is the overall progress?" | | get\_grandi\_data | Project schedule ranges (archived projects not shown) | "What is the time schedule for X project?" |

The data returned to the AI is compressed: the metadata for all tools does not include color, created\_at, updated\_at, project\_color; tasks do not include progress, and to-do plans do not include due\_date. content[0].text is human-readable Chinese text, while the metadata is structured and consistent with the text fields.

How to comment out / modify tools (important)

The definitions of all tools are concentrated in the TOOLS list in app.py (appproximately lines 260–560). Each tools is one dictionary object in the list, with four fields: name / description / inputSchema / handler. The token tools/list list is generated automatically from TOOLS; commenting one out bothides it from the AI, no other code changes needed, then restart the service after saving.

Example 1: Comment out the create\_project tool (keep 小智 AI from creating projects)

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

Example 2: Only modify the tool description (guide the AI on when to use it)

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

Example 3: Keep only the "task reminder" tools

Comment out the non-reminder tools in the TOOLS list (such as create\_project, list\_tasks, create\_todo, etc.) as a whole, keeping only get\_reminders, get\_schedule, and get\_schedule\_summar. After the 小智 side re-probes on Verdue platform, only the remaining tools will be visible.

Tip: After commenting, it is best to re-save / refresh that MCP server configuration on the Verdure platform. After each change in TOOLS, restart the server locally and run node smoke-test.mjs there. The list of expected tools is written with 16 items; if you comment tools, update the expected array in that script.

REST API (PC front-end connects directly, CORS full open)

All succeed responses are unified {"code":0,"data":…}; errors return {"code":4xx/5xx,"error":"…"}. Optional auth: if the environment variable API_KEY is set, every request must include the PI-API-KEY header (/health and /app are excluded, so keep-alive and page access are unaffected).

Run locally for a quick check (verification)

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 : gunicorn requires Unix loop and cannot run natively on Windows locally (deploy programs to Render/Docker Linux containers are not affected). Use `python app.py always to local debugging (Flask development server, identical behavior); Dockerfile uses gunicorn in production.

Verification:

# 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"}'

Open http://127.0.0.0:8080/app in a browser to use the PC panel (same-origin, no configs needed). If you double-click web/index.html directly, you can set the PI URL to http://127.0.0.0:8080 in Settings.

Includes scripts for self-test/demonstration:

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

One-step Deployment (GitHub → Render → Verdure → 小智)

Step 1: Push to GitHub

1. Create a new repository on Git Hub (e.g., schedule-mch, either Public or Private).

2. Push the code (do not commit data/*.db, because .gitignore excludes the data; also avoid committing .ven/):

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

Step 2: Deploy to Render (Free)

1. Open render.com → New → Web Service → connect your repository.

2. Configure:

   • Name: schedule-mch (anything is fine)

   • Environment: Python 3 (or Docker, in that case the Build/Start commands below are not required)

   • Build Command: pip install -r requirements.txt

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

   • Instance Type: Free

   • (Optional) Environment Variables: set PI_KEY=your–random–key (then MCP and REST requests must send X-API-KEY)

3. Deploy, wait for the build to finish, and you get a URL like https://schedule-mch.onrender.com.

4. Verify by opening https://schedule-mch.onrender.com/health; you should see {"code":0,"status":ok,…}.

⚡ Warning about Render free tier:

• The free instance will sleep after ~5 minutes with no traffic; next request needs companyed cold start (first request 5–30 s). → You need a keep-alive (below).

• The free-tier file system is temporary: a refresh/redeploy will clear the SQLite database. For personal use, I suggest regularly exporting backup in ⚙ settings, or accept re-entry (for short-term schedules, the impact is slight).

Step 3: Enable keep-alive (required for Render free)

1. Edit .github/workflows/keep-alive.yml, change URL to your service URL (e.g., https://schedule-mch.onrender.com/health).

2. (Optional) If you set API_KEY, add SERVICE_API_KEY to the repo Settings → Secrets and variables → Actions → New repository secret, then also uncomment that line in the file.

3. Push; the Action will curl /health every 10 minutes to keep the service alive.

4. If that fails: use cron-job.org to send a GET request to your service URL, scheduling once every 10–14 minutes.

Step 4: Add the MCP server in Verdure MCP Platform

1. Sign in to Verdure MCP Platform (if no account, register in the same way as the reference project; the platform connects to Xiaozhi / Tuya students).

2. Go to Add / Manage MCP Servers, choose HTTP–type. (Verdure probes POST / with JSON-RPC; this server follows that exact pattern, matching the tarot-mcp implementation.)

3. Fill in:

   • URL (Server Address): https://schedule-mch.onrender.com/ (root is enough; the server handles MCP JSON-RPC on /)

   • If you set auth, enter the key corresponding to X-API-KEY (or add the header as the platform asks).

4. After saving, the platform does an automatic initialize → tools/list probe, and you should see the above 16 tools. If the tool list is empty, check the /health endpoint is reachable, and that the address does not erroneously end with /api.

5. Assign the MCP server to your 小智 AI assistant (inside the platform, select the assistant and link the server).

Step 5: Touch via 小智 AI voice

Speak commands like:

• "What should I do today?" / "What's on today?" → triggers get_schedule (first)

• "Any reminders for me?" → triggers get_reminders

• "What's on this week?" / "What's on this month?" → triggers get_schedule (range=week/month)

• "Pick up the to-do : buy tickets, high priority" → triggers create_todo

• "Make a project called X, from November to December, highest priority" → triggers create_project

• "Add a task to X: decide the design option by Dec 1" → triggers create_task

• "What projects do I have? / How is X going?" → triggers list_projects / get_schedule_summary / get_gantt_data

• "Mark X task as done" → triggers update_task

Keep-alive notes (research conclusion)

Conclusion: keep-alive is not an MCP protocol requirement, nor a Verdure MCP requirement; it is only needed when the service is deployed on a free cloud pilot that sleeps after idle (Render Free / Railway quota).

Reasoning:

1. The tarot-mcp project contains keep-alive.yml — a GitHub Actions that runs every 10 minutes to hit /health with curl, pointing at https://tarot-mcp.onrender.com/health. It is designed to keep Render's free instances from sleeping by idle ~5 min.

2. The MCP protocol itself (initialize / tools/list / tools/call) has no keep-alive requirement; the Verdure Platform is an orelating / remote proxy layer, which inject y tools when your service is online; it does not start your sleeping service.

3. So:

   • If you deploy on Render Free / Railway free (tier which sleeps), you must keep the keep-alive, or 小智 will have slow cold starts and poor failure;

   • If you deploy on paid instance (Render Starter+, cloud VPS, etc.) or Verdure-hosted runtime, you can delete .github/workflows/keep-alive.yml with no side effects.

4. This repo keeps and includes the keep-alive workflow by default (URL must be changed to your service), because the reference path runs on Render Free and matches your deployment style.

FAQ

Q: After deploying, 小智 says "no tools available"? A: First check that https://<your-service>/health is reachable; then re-save/refresh the MCP server config in Verdure to trigger a new probe. Do not add a trailing /api; use the root path.

Q: How to let the AI only do reminders, with fewer add/edit/delete tools? A: As above — go to app.py’s TOOLS list, comment out unused tools, restart and refresh in Verdure.

Q: Does the auto-status change my manual done / “completed” flags? A: When the setting is enabled, task state is derived entirely from dates (not yet started → todo, in progress → doing, overdue → done). If you want to control it manually, turn the switch off; then only manual changes are preserved.

Q: Render free loses data after you restart? A: Free instance storage is ephemeral. In ⚙ → Export backup (JSON), and later Restore from backup (backup also include settings).

Q: How to add auth? A: Set the environment API_KEY on Render. Then MCP (POST /) and REST (/api/*) both require the X-API-KEY header; the PC front end can fill in the key in ⚙ settings, and keep-alive workflow can use the secret.

Q: Can I deploy somewhere else? A: Yes, anything that runs Python (Railway / Fly.io / Cloud VM / intranet NAS). The SQLite file is under data/; use a persistent volume to avoid loss.

Q: How can I see what tools 小智 really invoked? A: Render logs will print every call (tool name + params + result). You can also GET / and see the tool list.

Technical keys (compatible with tarot-me)

• MCP uses JSON-RPC over HTTP (single endpoint POST /), implementing initialize (protocolVersion 2024-11-05), notifications/initialized, tools/list, tools/call, and ping. Unknown methods return an empty result, consistent with the tarot-mcp compatibility patch, and it has been verified to work on platforms such as Verdure / imcp.pro.

• CORS is fully open (Access-Control-Allow-Origin: *), allowing PC-side HTML to directly connect to the REST API across domains.

• SQLite uses WAL mode + a separate connection per request, enabling safe read/write with gunicorn multi-worker.

• Tools return content[0].text (readable Chinese) + metadata (structured JSON, with AI-irrelevant fields such as color/created_at/updated_at/project_color removed), balancing AI comprehension and machine parsing.

• Settings (auto task status / week definition) are stored in the server-side settings table, with the frontend panel and MCP queries sharing the same configuration; "this week" statistics and the frontend calendar and weekly calendar all follow this week definition.