Schedule MCP · Herramienta de gestión de planificación de proyectos personales

Una herramienta de gestión de planificación de proyectos personales de estilo minimalista. Un mismo servicio Python desempeña dos funciones a la vez:

1. Servidor MCP: Se conecta a 小智 AI a través de plataformas como Verdure MCP Platform / imcp.pro, para que 小智 pueda leer y escribir fácilmente tus datos de planificación mediante voz o conversación, y ofrecer recordatorios basados en reglas (la organización del lenguaje natural restante queda a cargo del modelo DeepSeek v4 en el servidor de 小智).

2. API REST + interfaz para PC: el navegador del PC puede acceder directamente a la página /app del servicio desplegado (o abrir localmente web/index.html apuntando a la dirección de despliegue), para consultar y editar de forma visual el calendario, el diagrama de Gantt (editable), la gestión de múltiples proyectos y los planes de tareas pendientes (próximos o futuros).

El almacenamiento de datos usa SQLite (cero dependencias extra); tras el despliegue funciona de inmediato, sin necesidad de ejecutar ningún backend en local.

Proyecto de referencia: shiikun-cn/tarot-mcp (se ha verificado que el modo de compatibilidad MCP-over-HTTP funciona).

Resumen de funcionalidades

Related MCP server: Todoist MCP Server

Estructura del proyecto

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

Modelo de datos

Todos los formatos de fecha: YYYY-MM-DD. Los recordatorios no se guardan en la base de datos, los datos el motor de reglas en tiempo real.

Nota: en versiones antiguas, los estados paused/completed de los proyectos se migran automáticamente a planned/archived al inicio; los campos progress (progreso de la tarea) y duehed (deadline de tareas pendientes) ya se han eliminado de la capa de producto (las columnas en la base se conservan por compatibilidad con copias antiguas, pero ya no se usan ni se muestran).

Reglas del estado automático de tareas (se aplical si se abre en ajustes)

• Hoy es anterior a la fecha de inicio → todo (pendiente)

• Hoy está entre la fecha de inicio y la de fin/límite → doing (en curso)

• Hoy es posterior a la fecha de fin/límite → done (completada, para no acumular "vencidas")

• Si la tarea no tiene ningún atributo de fecha → mantiene su estado original

• Al crear/actualizar una tarea, la clasifica al momento (no se aplica la deducción del día); la ejecución completa solo se hace una vez al mismo día (deduplicación con last_auto_date), y el "Ejecutar" del panel de ajustes la fuerza.

• También se activa automáticamente cada vez que se consultan tareas o calendario (si está habilitado)

Lista de herramientas MCP (16, para que las llame 小智 AI)

Los datos que se devuelven a la IA están resumeados: en el metadata de todas las herramientas no se incluyen color, created_at, updated_at ni project_color; en tareas no se incluye progress, y en pendientes no se incluye due_date. content[0].text es texto legible en chino, y metadata contiene los datos estructurados; campos coincidentes entre ambos.

Cómo comentar/modificar herramientas (importante)

La definición de todos los herramientas está centrada en la lista TOOLS de app.py (approx., lines 260-560). Cada herramienta corresponde a un objeto grande de la lista y contiene los siguientes campos: name / description / inputSchema / handler. El listado de tools/list se genera automáticamente desde TOOLS. Al comentarla, la ocultas para la IA, no necesitas modificar otro código; tras Guardar, hay que reiniciar el servicio.

Ejemplo 1: cómo dejar el utilizado la herramienta create_project (para que no pueda crear proyectos con 小智)

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

Ejemplo 2: qui solo modificar la description de la herramienta (para indicar a la IA por qué usarla)

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

Ejemplo 3: dejar solo de "recordatorio de tareas"

Como en la lista TOOLS se comentan todas las que no son de recordatorio (por ejemplo create_project, list_tasks, create_todo, etc.) y se dejan únicamente get_reminders, get_schedule y get_schedule_summary. El lado de 小智 en la reevaluación de Verdere solo verá las herramientas restantes.

Tip: después de comentar, es recomiendo volver a guardar/refrescar la configuración del servidor MCP en Verdure para que se convierta en el re-detect. Después de cada cambio en TOOLS, puedes reiniciar el servicio en local y usar node smoke-test.mjs para confirmar que el cambio de lista es el esperado (en el assertion hay 16 fijos; si no comentas herramientas, cambia también el array expected de ese script).

REST API (frontend PC se conecta directamente, CORS abierto)

La respuesta normalizada es {"code":0,"data":…}; en caso de error es {"code":4xx/5xx,"error":"…"}. Autenticación opcional: si se define la variable de entorno API_KEY, todas peticiones deben llevar el header X-API-KEY en las solicitudes (excepto /health y /app, para que el keep-alive y la página web no se vean afectados).

Ejecución local rápida (verificación)

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 修改

Sugerencia: gunicorn solo disponible en Linux (requiere fcntl de UNIX; no se puede ejecutar directamente en Windows local, pero no afecta a la implementación en Render/Docker de Linux). Para debug en local usa siempre python app.py (servidor de desarrollo Flask; el comportamiento es el mismo), en producción el Dockerfile usa gunicorn.

Verificación:

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

Abre en el navegador http://127.0.0.1:8080/app para usar el panel de PC (same origin, no necesita configuración); si abres el web/index.html mediante doble clic, debes poner la dirección API como http://127.0.0.1:8080 en los ajustes (⚙).

Scripts de autoverificación para el asistente:

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

Restablecer datos: reestablecer los datos borrando data/schedule.db y volver a.. reiniciar el servicio (the default repository already includes ignore for database files).

Pasos de desplegable (GitHub → Render→ elipse→ 小智)

Paso 1: Subir a GitHub

1. Crea un repositorio en GitHub (ej schedule-mcp, tanto Private como Public).

2. Sumbén el código (pero no it comidas data/*.db; el .gitignore lo excluye. Además se recomienda no subir .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

Paso 2: Desplegar en Render (gratis)

1. Abre render.com → New → Web Service → conecta tu repositorio de GitHub.

2. Configuración:

   • Name: schedule-mcp (arbitrario)

   • Environment: Python 3 (o Docker (si elegis Docker no necesentes los siguientes 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

   • Instance Type: Free

   • (optional) Environment Variables: API_KEY=tu_clave_aleatoria (si lo pones, todas las peticiones de MCP/REST deben llevar X-API-KEY)

3. Despliega y espera que complet la compilación. Obtendrás de dirección: https://schedule-mcp.onrender.com.

4. Verificar: abre https://schedule-mcp.onrender.com/health para ver {"code":0,"status":"ok",…}.

⚠️ Notas sobre la versión gratuita de Render:

• La instancia gratuita se encuentra si no recibe tráfico durante unos 15 minutos; la próxima ejecución solicita un arranque en frío (la primera tarda unos 5-30 segundos). → es obligar de keep no recuperado (ver abajo).

• En la versión gratuita el filesystem es temporal: al reimplementar o reiniciar se pierden los datos SQLite. Para protección personal, se recomienda exportar la copia de seguridad en los ajustes ⚙ cada tiempo, o aceptar over la reconfiguración tras un reinicio (para la planificación a corto plazo del diario, dilo no muy gran impacto).

Paso 3: Activar el keep-alive (obligado para la versión gratuita de Render)

1. Modificaá .github/workflows/keep-alive.yml y cambia la URL a tu dirección de servicio (por ejemplo https://schedule-mcp.onrender.com/health).

2. (Opcional) Si has asignado API_KEY, en tu repo de GitHub Settings → Secrets and variables → Actions → New repository secret agrega SERVICE_API_KEY y activa esa línea del workflow.

3. Haz push de los cambios. Actions hará ping cada 10 minutos a /health, mantendrás el servicio activo.

4. Si el workbook no funciona: usa cron-job.org para enviar peticiones GET a la dirección. Pon el intervalo de 10-14 min.

Paso 4: Añadir el servidor MCP en Verdure MCP Platform

1. Conecta a Verdure MCP de platform (si no tienes cuenta, regístrate de la misma forma que la que en el proyecto de referencia; la plataforma se connecta a asistan como ten pequeño / Shadow Tuya, etc.).

2. En la página "Añadir / Gestión de servidores MCP", selecciona el tipo HTTP (Verdure sondea POST / como JSON-RPC, este servicio ya lo hace así, tal como tarot-mcp).

3. Rellena:

   • Service URL: https://schedule-mcp.onrender.com/ (with root o directly; the service handles the MCP JSON-RPC in /)

   • Si has configurado API_KEY, poner la clave correspondiente a (o según el header que pida la plataforma)

4. Tras guardar, la plataforma automáticamente realizará initialize + tools/list para detectar las 16 herramientas. Si list aparece vacía, comprueba que you /health esté disponible y que no has añadido al final de la ruta una /api.

5. Asocia el servidor MCP agregado a tu asistente 小智 AI (elegir el → añadir ese server).

Paso 5: Verificación por voz con 小智 AI

Prueba a pedir a 小智 frases como:

• "¿Qué me vas a contar hoy?" / "¿Qué tengo hoy?" -> active get_schedule

• "¿Qué vale acerdar?" → get_reminders

• "¿Qué plan hay esta semana?" / "¿Qué hay que hacer para este mes?" → get_schedule(range=week/month)

• "Anota un pendiente: comprar el billete de avión, prioridad alta" → create_todo

• "Crea un proyecto llamado renovación, del 16 de abril al 24 de mayo, máxima prioridad" → create_project

• "Añadir una tarea al proyecto de renovación: definir el diseño, con entrega del 1 de diciembre final de December" → create_task

• "¿Qué proyectos tengo? qué proyección de proyecto de la MT" → list_projects / list_tasks / get_gantt_data

• "Marca la tareas de XX como completes" → update_task

Notas sobre keep-alive (conclusiones)

Con: keep-alive no es que el protocolo ni se pedido ni una plat a la plataforma; solo es estrictamente necesario cuando el servicio está desplegado en plataformas free que se duerman (por ejemplo Render Free / Railway).

fundamento:

1. En el proyecto de referencia tarot-mcp, el keepalon-enable es una tarea programada de Github Actions que cada 10 min hace curl a /health (apuntando a https://tarot-mcp.onrender.com/health) para mantener activo el planificación y evit de que el instance de Render (that sleep after ~15 min inactivity).

2. El protocolo MCP (initialize / tools/list / tools/call) no tiene ningún tempo requer; Verdure es una capa de gestión para "cercar con la remote" inyect. provisions en la minor mientras, pero no arranca los servicios externos en reposo.

3. Por lo tanto:

   • Si está en Render Free / Railway free etc que duermen → es obligacio. (director no quedarán tiempo out o tardan).

   • Si está en el sector de pago sin dormir (Render Starter+, nube server etc) o de interior hosting garantizado de Verdure → se puede quitar el workflow, sin ningún negativo.

4. Este proyecto mantiene y adapta keep-alive.yml por defecto (hay que cambiar la URL), porque la via de referencia usa Render Free e igual que tú loalternative.

Preguntas frecuentes

P: ¿Después del desple, 小智 dice no hay "tools" disponible? R:** Primero verifica que https://<tu-servicio>/health es accesible, y queda en el unión nueva protección o actualizado del y serve). Recuerda que la dirección debe ser / (root), no le añadas /api.

¿Cómo hacer que la IA solo recordatorios, y usar menos herramientas de crear /edes? R:** Mira el "Cómo comen tar herramientes" antes o ** en app.py lista TOOLS puedescomentar las que no necesits; después reiniciate de nuevo y re-deté en Verdure.

P: ¿Estado auto tareas reemplaza lo que yo hà marcado manualmente como completo? R:** Cuando se activa, el estado tá completo suivió determina de fechas(si no anima-ra:pena ; en progress→en progress ; ultvence→ completda). Si quieres controlar manual, desactivar el interrupt figures de la configuración; al desactivarlo solo se mantienen los cambios manual.

P: En Render free, los se pierden al reinici? R**: En la version gratuita el arch de arch son temporales. En el panel Configuración → Exportar backup guardar la copia periódico; tras reiniciar puedes "Restaurar desde copia" para importarla. La copia incluye todos los ajustes.

P: ¿Cómo habilitar API-Key auth? R:** Dado eliedad SI * en . recipientes en volumen**: añad API_KEY=xxx; a partir de entes, en el **MCP (POST /)** y en **REST /api/*** se exige el header X-API-KEY`. El frontend de PC lo configuras en ⚙ Ajustes, y en el workflow de keep-alive usa un secret.

P: ¿Se puede desplegar en otro lugar? R:** Se puede, cualquier hosting que ejecute Python ue entonces (Railway / Fly.io / nube / NAS en entorno local). El archivode SQLite está en data/; montar un volumen persistention evita la pérdida de datos.

P: ¿Cómo veo qué tools ha llamado 小智? R:** En logs de Render (Logos) se imprimen los parámetros y el resultado de cada tools/call; también puedes ver la list deherramientassing in la respuesta de GET a /.

Puntos técnicos (compatibilidad con tarot-mcp)

• MCP utiliza JSON-RPC over HTTP (un único endpoint POST /), e implementa initialize (protocolVersion 2024-11-05), notifications/initialized, tools/list, tools/call y ping; para métodos desconocidos devuelve un resultado vacío, de acuerdo con el parche de compatibilidad de tarot-mcp, y se ha verificado que funciona en plataformas como Verdure / imcp.pro.

• CORS totalmente abierto (Access-Control-Allow-Origin: *); el HTML del PC puede conectarse directamente a la REST API en cross-origin.

• SQLite utiliza modo WAL + conexión independiente por solicitud, lo que, junto con gunicorn con múltiples workers, permite lecturas y escrituras seguras.

• Las herramientas devuelven content[0].text (legible en chino) + metadata (JSON estructurado, con los campos irrelevantes para la IA, como color/created_at/updated_at/project_color, ya excluidos), con el objetivo de equilibrar la comprensión de la IA y el análisis automatizado.

• Los ajustes (estado de tareas automáticas / definición de semana) se almacenan en la tabla settings del servidor; el panel del frontend y las consultas MCP comparten la misma configuración; las estadísticas de "esta semana" y el calendario / vista semanal del frontend siguen por completo esa definición de semana.