Schedule MCP · инструмент управления личным расписанием проектов

Минималистичный инструмент управления личным расписанием проектов. Один Python-сервис выполняет две роли одновременно:

1. MCP Server: подключается к 小智 AI через такие платформы, как Verdure MCP Platform / imcp.pro, позволяя 小智 легко читать и записывать ваши данные расписания голосом/в диалоге, а также выдавать напоминания о делах на основе правил (остальную организацию естественного языка берёт на себя модель DeepSeek v4 на стороне сервера 小智).

2. REST API + PC-фронтенд: в браузере с компьютера вы открываете страницу /app развёрнутого сервиса (или локально открываете web/index.html и указываете адрес развёртывания) — здесь доступны наглядный просмотр и редактирование календаря / диаграммы Ганта (с редактированием) / многопроектного управления / плановых задач (ближние/дальние).

Для хранения данных используется 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. Напоминания не сохраняются в базе данных, а вычисляются правилом-движком в реальном времени.

Примечание: статусы проектов старых версий paused/completed при запуске автоматически мигрируют в planned/archived; поля progress (прогресс задачи) и due_date (срок планового дела) удалены на уровне продукта (столбцы в базе сохранены для совместимости со старыми резервными копиями, в чтении, записи и отображении больше не используются).

Правила автоматического статуса задач (вступают в силу после включения в настройках)

• Если сегодня раньше даты начала → todo (не начато)

• Если сегодня в интервале между датой начала и сроком окончания → doing (в работе)

• Если сегодня позже даты окончания / крайнего срока → done (выполнено, чтобы не накапливалось «просрочено»)

• Если у задачи нет никаких свойств дат → сохраняется исходный статус

• Мгновенная классификация при создании/обновлении задачи (не ограничена идемпотентностью текущего дня); полный запуск выполняется не более одного раза в день (идемпотентность last_auto_date), кнопка «Выполнить сейчас» в панели настроек принудительно запускает обработку

• Автоматически срабатывает также при каждом запросе задач/расписания (если функция включена)

Список MCP-инструментов (16 шт., вызываются 小智 AI)

Данные, возвращаемые в AI, уже сокращены: у всех инструментов в metadata delivery not color, created_at, updated_at, project_color; задачи не содержат progress, компа-планные дела не содержание due_date. свойство content[0].text — это легко читаемый китайский текст, metadata — структурированные данные, наборы полей совпадают.

Как закомментировать / изменить инструменты (важно)

Все определения инструментов сосредоточены в списке TOOLS в app.py (примерно строки 260-560). Один инструмент — это один объект в фигурных скобках, включающий четыре поля: name / description / input / handler. Список tools/list автоматически генерируется из TOOLS; закомментировали — и инструмент становится скрытым от AI, остальной код менять не нужно. После сохранения перезапустите сервис — изменения вступят в силу.

Пример 1: закомментировать инструмент create_project (не давать 小智 создавать проекты)

# 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 можно сначала перезапустить локальный сервис и с помощью НОДА убедиться, что список smoke-test.mjs соответствует ожиданиям (в проверки захардкожено 16 — иначе изменить этот скрипт, обновив массив expected).

REST API (PC-фронтенд подключается напрямую, CORS открыт полностью)

Все ответы единообразно возвращают {"code":0,"data":…}; errors return {"code":4xx/5xx,"error":"…"}. Optional authentication: after setting the environment variable API_KEY all requests must include X-API-KEY header (except /health and /app, to keep keep-alive and page access unaffected).

Быстрый локальный запуск (проверка)

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 depends on Unix fcntl, cannot directly run on Windows (deployment in Linux containers Render/Docker unaffected). Local debug always uses python app.py (Flask dev server, intended), in production in Dockerfile uses 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-панель (antidirect connection, no configuration needed). If you opened web/index.html directly, set API address to http://127.0.0.1:8080 in the ⚙ settings.

Прилагаются автоматические и демонстрации:

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

Сброс данных: удалите data/schedule.db и restart service (DB files by default are gitignored).

Шаги развёртывания (GitHub → Render → Verdure → 小智AI)

Шаг 1: загрузите GitHub

1. Создайте репозиторий на GitHub (например, schedule-mcp, Private or Public — mutual compatible).

2. Загрузите код (не data/*.db в gitignore; also recommended not to add .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: deploy Render (free)

1. Open render.com → New → Web Service → connect your GitHub repo.

2. Configure:

   • Name: см. services

   • Environment: Python 3 (or Docker; if you choose Docker, Build/Start below не org need you)

   • 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: API_KEY=你的随机密钥 (if set, all MCP/REST requests must carry X-API-KEY)

3. Deploy and wait for the build to finish. Получите адрес сервиса: https://schedule-mcp.onrender.com.

4. Check: open https://schedule-mcp.onrender.com/health in browser, should return {"code":0,"status":"ok",…}.

⚠️ Особенности бесплатной вернии Render:

Free instance approximately 15 minutes without traffic → sleep; next request requires cold start (first request about 5-30 seconds) **. → keep-alive must be enabled.

• The file system in the free version is temporary: after redeploy/again restart SQLite data will be cleared. For personal self-use what follows is「export backup」regularly in ⚙ settings, либо accept that after rebuild ты заново вводить данные (небольшое влияние на короткосрочное планирование).

Шаг 3: enable keep-alive (обязательно для бесплатной версии Render)

1. Open .github/workflows/keep-alive.yml, change URL in https://schedule-mcp.onrender.com/health.

2. (Optional) If API_KEY is set, add system secret SERVICE_API_KEY in GitHub repo Settings → Secrets and variables → Actions → New repo.

3. Push the change. Actions will ping /health every 10 minutes? The service stays active.

4. If workflow keep-alive not works: use cron-job.org send GET to the service. Set frequency every 10-14 minutes.

Шаг 4: добавьте MCP-сервер на Verdure MCP Platform

1. Login to Verdure MCP Platform (if no account, register in the same account as the reference project; the platform connects endpoints and assistants like 小智 / Tuya).

2. In the page «Add / Manage MCP Servers», select HTTP (Verdure detect JSON-RPC via POST /, this service already implements in the same way as tarot-mcp).

3. Fill:

   • Service address (URL): https://schedule-mcp.onrender.com/ (the root path enough; the service handles MCP JSON-RPC on /)

   • If authentication is configured, set the key corresponding to X-API-KEY (or fill header as platform requests).

4. After saving, the platform automatically runs initialize + tools/list, should see 16 tools above. If tool list is empty, check if /health available and check that the end of URL accidentally doesn't have /api.

5. Bind the added MCP server to your 小智 AI assistant (choose the assistant, associate with that server).

Шаг 5: голосовая проверка 小智 AI

• Ask 小智 similar instructions to verify read/write:

• "Что делать сегодня?" / "Today's schedule?" → triggers get_schedule (priority)

• "What do I need to remind?" → triggers get_reminders

• "Какие планы на этой неделе? / в месяце?" → triggers get_schedule(range=week/month)

• "Запиши плановое дело: покупай билеты на самолет, высокий приоритет" → create_todo

• "Создай проект «Ремонт», с ноября по декабрь, высокий приоритет" → create_project

• "Добавь задачу в проект «Ремонт»: выбор проекта, до 1 декабря" → create_task

• "Какие у меня есть проекток? Как общий прогресс проекта X?" → list_projects / list_tasks / get_gantt_data

• "Отметь задачу X" → update_task

Пояснение про keep-alive (выводы по исследованиям)

Вывод: keep-alive — не требование MCP-против, nor Verdure MCP Platform; it applies only for free temporary deployments like if service is deployed on free hard (Render Free / Railway free quota) and goes to sleep when there under no traffic.

Логические основания:

1. In the reference project tarot-m», the keep-alive.ymlis a **GitHub Actions** cron job, every 10 minutes viacurlrequests/health; it points tohttps://tarot-mcp.onrender.com/health` — это так, для Render free instance has ~15 no traffic sleep protection.

2. The MCP protocol itself (initialize / tools/list / tools/call) has any requirements; Verdure platform is a management level, which is, «integration + remote injection», it is responsible for injecting tools into 小易 when your service is online, but it does not start your sleep host for you.

3. Therefore:

   • deployment of Render Free / Railway free quota and other sleeping platforms → keep-alives must be retained (otherwise you will see cold start slow or timeout when 小智 calls the tool, the taste is bad);

   • deployment to paid persistent instances (Render Starter+, cloud server, etc.) or Verdure hosted (if the platform supports this) → you can remove .github/workflows/keep-alive.yml, no side effects.

4. This project keeps and adapts the keep-alive.yml (URL should be changed to service address), because the reference chain uses Render free version, and your deployment method matches.

FAQ

Q: After deployment 小智 says "no available tools"? A: First check that https://<你的服务>/health is accessible; then on the Verdure page save/refresh the server config trigger. Note address root path (/), not /api.

Q: How to make AI only do official reminders, fewer tools? A: We described in "How to edit / modify tools" — comment on all in app.py TOOLS list, not needed other tools; after commenting, restart and re-engine with Verdure.

Q: Auto status will change my manual completion? A: The status is completely derived from date. If you want manual control, turn off that switch in settings; changes after disabling affect manual modifications.

Q: data after restart lost? A: Free instance file system temporary. In settings → Export Backup / JSON save; restore data on next reboot (backups contain configuration).

Q: How add API auth? A: In Render env variable API_KEY=xxx. Then MCP (POST /) and REST ( /api/*) require header X-API-KEY; front-end also fills Key in ⚙ settings, secret service for keep-alive.

Q: Can deploy elsewhere?

A: Yes, any hosting that runs Python (Railway / Fly.io / cloud server / NAS local network). SQLite file in data/, if mounted persistent volume no data loss.

Q: How to check which 小智 tools have invoked? A: Render logs (Logs) print all tools/call calls and results; you can also see the tool list in root / GET response.

Technical points (compatibility with 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: *), поэтому HTML-клиент на ПК может напрямую обращаться к REST API с любого origin.

• SQLite использует режим WAL + отдельное подключение на каждый запрос, что обеспечивает безопасное чтение/запись при нескольких воркерах gunicorn.

• Инструменты возвращают content[0].text (читаемый текст на китайском) + metadata (структурированный JSON, из которого исключены нерелевантные для AI поля, такие как color/created_at/updated_at/project_color), что учитывает и понимание AI, и машинный разбор.

• Настройки (статус автоматических задач / определение недели) хранятся на сервере в таблице settings; панель интерфейса и MCP-запросы используют одну и ту же конфигурацию. Статистика за «текущую неделю» в frontend-календаре и недельном календаре также полностью следует этому определению недели.