Schedule MCP · 개인 프로젝트 일정 관리 도구

미니멀한 스타일의 개인 프로젝트 일정 관리 도구입니다. 하나의 Python 서비스가 두 가지 역할을 동시에 수행합니다:

1. MCP Server: Verdure MCP Platform / imcp.pro 등의 플랫폼을 통해 小智 AI에 연결하여, 小智가 음성/대화로 일정 데이터를 쉽게 읽고 쓸 수 있게 하며, 규칙 기반으로 일정 알림을 제공합니다(나머지 자연어 처리는 小智 서버의 DeepSeek v4 모델이 담당).

2. REST API + PC 프런트엔드: 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에 color, created_at, updated_at, project_color가 포함되지 않습니다; 작업에는 progress, 할 일 계획에는 due_date가 포함되지 않습니다. content[0].text는 읽기 쉬운 중국어 텍스트이고, content[0].metadata는 구조화된 데이터로 두 필드 내용이 일치합니다.

도구 주석 처리 / 수정 방법(중요)

도구의 app.py에 모인 정의는 TOOLS 목록(약 260-560행)에 있으며, 각각의 도구는 목록 중 하나의 정의에 해당하며 name/description/inputSchema/handler 4개 필드를 포함합니다. 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를 수정할 때마다 로컬에서 서비스를 중지하고 node smoke-test.mjs로 실행 목록이 예상대로 변경되었는지 확인할 수 있습니다(정보 수 있는 숫자가 16개이므로, 도구를 주석 처리한 경우 스크립트의 expected 배열도 함께 수정하세요).

REST API(PC 프로 추가, 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/Docker의 Linux 컨테이너에서는 제한되지 않습니다만). **로컬 개발은 항상 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을 직접 접속하면 will need to set http://127.0.0.1:8080 in ⚙ 설정입니다.

동봉 자체 테스트/데모 스크립트:

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

데이터 초기화: data/schedule.db를 삭제하고 서버를 재시작하면 됩니다(기본적으로 .gitignore는 데이터베이스 파일을 제외합니다).

배포 단계(GitHub → Render → Verdure → 小智 AI)

Step 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

Server가 아님 / 정확한 페이즈: Render 총 - 클래스마 :

1. render.com 열기 → New → Web Service → GitHub 저장소를 연결합니다.

2. 설정:

   • Name: schedule-mcp(임의 값)

   • Environment: Python 3(또는 Docker. Docker를 선택하면 아래의 Build/Start Command에 필요 없음)

   • 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

   • (선택) Environment Variables: API_KEY=임의의 키 값(설정하면 MCP/REST 모든 요청에 X-API-KEY 필요)

3. Deploy를 클릭하고 빌드가 완료될 때까지 기다립니다. 서비스 주소: https://schedule-mcp.onrender.com

4. 확인: 브라우저에서 https://schedule-mcp.onrender.com/health 방문 시 are you blind {"code":0,"status":"ok",...,...}가 반환되어야 합니다.

⚠️ Render 무료 버전 참고:

• 무료 인스턴스는 약 15분간 트래픽이 없으면 휴면 상태가 되며, 다음 요청은 콜드 스타트(첫 요청은 약 5~30초 소요)가 발생합니다. **따라서`(keep-alive) 필수.

• 무료 버전 파일 시스템은 일시적입니다: 재배포/재시작 시 SQLite 데이터가 지워집니다. 개인용으로는 ⚙ 설정에서 정기적으로 "백업"을 백업하거나, 다시 구성한 후 다시 입력하는 것을 허용합니다(일상 단기 일정에 큰 문제 없음).

Step 3: keep-alive 동작 · Render 무료 버전은 필수

1. .github/workflows/keep-alive.yml을 편집하여 URL을 자신의 서비스 주소로 변경합니다(예: https://schedule-mcp.onrender.com/health).

2. (선택) API_KEY를 설정한 경우, GitHub 저장소의 Settings → Secrets and variables → Actions → New repository secret에 SERVICE_API_KEY를 추가하고, workflow에서 해당 행을 활성화합니다.

3. 수정 사항을 푸시합니다. Actions는 10분마다 /health를 get 해주기 때문에 서버가 깨어 있을 수 있습니다.

4. (특수한 경우 workflow가 실패하지 않도록) 혹시모르니 보조 cron-job 등으로 서비스 주소에 GET 요청을 보낼 수 있습니다. 주기는 10~14분마다 1회로 설정합니다.

Step 4: Verdure MCP Platform에서 MCP 서버 추가

1. Verdure MCP Platform에 로그인합니다(계정이 없으면 참고 프로젝트와 동일한 방식으로 등록하시기 바랍니다. 플랫폼은 小智 / Tok 등 타인조에게 연결).

2. "추가 / MCP 서버 관리"로 이동 → HTTP 타입을 선택합니다(Verdure는 POST /의 JSON-RPC를 감지하며, 서비스는 이 프로토콜과 완전히 동일하게 동작합니다).

3. 입력:

   • 서비스 주소(URL): https://schedule-mcp.onrender.com/(루트 폴더를 사용합니다. 루트 /에서 MCP JSON-RPC 요청을 받습니다)

   • 인증을 설정한 경우 X-API-KEY에 해당하는 키를 입력합니다(또는 플랫폼에 지정된 헤더에 넣습니다)

4. 저장 후 플랫폼이 자동으로 initialize + tools/list를 실행하고, 위의 16가지 도구가 표시되어야 합니다. 도구 목록이 비어 있으면 서비스 /health에 접근 가능한지, 주서 주 남의 /api 경로를 잘못 붙였는지 확인하세요.

5. 추가된 MCP 서버를 보유 및 페이로 폰 자체에 연결합니다(플랫폼에서 답변을 선택 → 해당 서버 연결).

Step 5: 小智 AI 음성 확인

小智에게 아래 유사한 지시를 보내어 읽기/쓰기를 테스트해 보세요:

• "今天要做什么?"/"今天有什么安排?" → get_schedule 실습(우선)

• "有什么需要提醒我的关卡?" → get_reminders 호출

• "这周有什么安排?"/"这个月有什么安排?" → get_schedule(range=today/now) 호출

• "记个待办计划：买机票，高优先级" → create_todo 호출

• "새 프로젝트 만들기, 11월부터 12월까지, 1순위" → create_project 호출

• "프로젝트에 '디자인 안 확정' 작업 추가, 마감 12월 1일" → create_task 호출

• "我有哪些项目？XX项目进度怎么样" → list_projects / list_tasks / get_gantt_data 호출

• "XX 작업 완료로 표시" → 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분간 무요청 시 잠드는 문제를 위한 keep-alive입니다.

2. MCP 자신의 프로토콜(initialize/tools/call)에는 keep-alive 요구가 없습니다. Verdure Platform은** 对接 + 원격 설치** 의 관리입니다. 즉 "어플이 Online 상태일 때"에 도구를 小智에게 보여주는 데요, 遼ko에서 잠자는 외부 서비스를 시작해 주지 않습니다.

3. 따라서:

   • Render 무료 / Railway 무료등의 자동 절전 지연에 께 있다면 → keep-alive는 필수입니다(그렇지 않으면 小智가 도구를 호출 시 콜드 스타트나 timeout이 자주 발생해 사용에oustic 합격함)

   • 유료 상주 인스턴스(Render Start+, 클라우드 서버 등) 또는 Verdure 자체 호스팅 기능을 → .github/workflows/keep-alive.yml를 삭제해도 무해.

4. 이 프로젝트는 기본적으로keep-alive.yml을 포함, 적응합니다(URL을 자신의 서버 주소로 반꺼줘야 함). 참고 경로가 Render 무료 버전을 사용하므로 이곳에서도同じ 방식 적용.

자주 묻는 질문

Q: 배포되고 나서 小智가 "사용 가능한 도구 없음"이라고 A: 먼저 서비스의 https://<your-domain>/health가 접속할 수 있는지 확인합니다. 그 다음 Verdure 플랫폼에서 MCP 서버 설정을 새롭게 저장/새로고침하여 재탐지를 실행합니다. 주 기: 주소에 루트 경로 /(기본값)를 사용하며, /api 등 경로를 붙이지 마세요.

Q: AI가 알림 기능만 쓰고, 수정/생성 도구는 줄이려면? A: 위의 "도구 주석 처리/수정 방법"에서 TOOLS 목록의 주석을 처리할 시/치지 않기를 원하는 도구를 빼면 됩니다. 주석 처리 후server 재시작 및 Verdure에서 다시 조회하면 됩니다.

Q: 자동 작업 상태가 제가 수동으로 설정한 "완료" 상태를 바꿀까요? A: 기능이 켜져있으면 작업 상태는 날짜 규칙에 따라 완전히 다시 정해집니다(날짜 미지 → 할 일, 진행 중 → 진행 중, 기한 지난 → 완료). 수동으로 조절하고 싶으면 설정에서 이 옵션을 끄시면 됩니다. 해당 기능은 비활성화되면 자동 분류가 멈추고 수동으로 유지됩니다.

Q: Render 무료 버전에서 재시작하면 데이터가 사라지나요? A: 무료 인스턴스의 파일 시스템은 일시적입니다. 설정에 있는 데이터 백업을 웹에서 정기적으로 실행하여 JSON 파일로 저장하고, 재배포 후 해당 파일을 복원하면 방금 전 상태를 그대로 재생할 수 있습니다.

Q: API 인증 키를 설정할 수 있나요? A: Render에서 환경 변수 API_KEY를 추가합니다. 이 설정이 있으면 MCP(POST /)와 REST(/api/*) 모두 X-API-KEY 헤더가 필요하며, 프런트엔드는 ⚙ 설정에서 그 키를 입력할 수 있습니다. keep-alive workflow가 사용할 수 있도록 GitHub Secrets에 조건적으로 추가할 수 있습니다.

Q: 타 플랫폼에 배포할 수 있나요? A: 가능합니다. 모든 리눅스/Windows 서버(예: Railway, Fly.io, 클라우드VM, 内 NAS등)에서 실행됩니다. SQLite 데이터은 data/ 폴더에 저장되므로, (있으면) 데이터를 볼륨에 마운트할 수 있는 클러스터 환경을 권장합니다.

Q: 小智가 어떤 도구를 호출했는지 어떻게 확인하나요? A: Render의 Logs(로그)에 각 tools/call 호출과 함께 매개변수와 결과가 출력됩니다. 또한 / 엔드포인트의 GET 응답에서 목록을 확인할 수 있습니다.

주요 기술 참고 사항(lykby MCP와 호환성 일치)

(there is no more content after that marker)

• 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(color/created_at/updated_at/project_color 등 AI와 무관한 필드를 제거한 구조화 JSON)를 반환하여 AI 이해와 기계 파싱을 모두 고려합니다.

• 설정(자동 작업 상태 / 요일 정의)은 서버의 settings 테이블에 저장되며, 프런트엔드 패널과 MCP 조회가 동일한 설정을 공유합니다. "이번 주" 통계와 프런트엔드 캘린더, 주간 캘린더 모두 이 요일 정의를 따릅니다.