# TimelyGPT MCP Hub

> NestJS 11 백엔드(Hub)와 Next.js 15 시범 프론트(Web)로 구성된, Korean public API + 생산성(Gmail/Calendar)을 25개 MCP 도구로 묶은 허브. 백엔드는 통째 이식, 프론트는 컴포넌트 단위 부분 이식. 이 파일은 AI 에이전트용 네비게이션 인덱스 — 더 깊은 전체 컨텍스트는 [llms-full.txt](/llms-full.txt) 참조.

## 핵심 정보

- 언어: TypeScript 5.8 (Node ≥24.14)
- 백엔드: NestJS 11 + Prisma 6 (Postgres 18) + BullMQ + Redis 7 + Zod v4
- 프론트(시범): Next.js 15 + React 19 + Tailwind 4
- 프로토콜: MCP (Model Context Protocol) over StreamableHTTP, JSON-RPC 2.0
- 패키지 매니저: pnpm 10.32.1 (lockfile 필수, npm/yarn 금지)
- 컨벤션: V3 — per-tool 4-set (`dto/ + .service.ts + .controller.ts + .module.ts`), `@McpTool` 데코레이터 자동 등록

## 이식 우선순위 (높음 → 낮음)

- [핸드오프 가이드 (한국어, 인간용)](/specs/HANDOFF.md): 5분 안에 이식 단위 파악. 환경변수·quickstart·FAQ 포함.
- [PRD (Source of truth)](/specs/PRD.md): 제품 요구사항 (immutable to agents).
- [LEARNINGS.md (append-only 학습 누적)](/LEARNINGS.md): 과거 실패·해결 패턴.
- [전체 인덱스 (llms-full.txt)](/llms-full.txt): 모든 파일 경로 + 한 줄 설명 + 이식 레시피.

## 백엔드 핵심 코드

- [Tool 등록 데코레이터](/src/modules/mcp/decorators/mcp-tool.decorator.ts): `@McpTool({name, description, inputSchema, ...})` 한 줄로 도구 등록.
- [Tool Registry](/src/modules/mcp/tool-registry.service.ts): 부팅 시 자동 발견, `list()` 시 hints 메타 포함.
- [MCP JSON-RPC 컨트롤러](/src/modules/mcp/mcp.controller.ts): `tools/list`, `tools/call` 처리. friendly error 포함.
- [전역 에러 필터](/src/common/filters/all-exceptions.filter.ts): 응답에 `friendly: {category, title, message, retry}` 강제 부착.
- [Error code 카탈로그](/src/common/errors.ts): 17개 표준 코드.
- [Friendly 메시지 (i18n)](/src/common/i18n/error-messages.ts): **0-dep pure TS**. ErrorCode → category(external/user/system) + 한국어 title/message + retry policy.
- [Input hint 레지스트리](/src/common/input-hints/registry.ts): 19 atomic 도구의 모든 입력 필드를 14개 HintType으로 분류.
- [Hint type 정의](/src/common/input-hints/types.ts): location-lat-lon-pair, lawd-cd, sido-name, date-yyyymm 등.
- [참조 데이터 컨트롤러](/src/common/reference/reference.controller.ts): `/reference/lawd-codes`, `/reference/sido` 공개 엔드포인트 (1일 캐시).
- [Solar Pro 클라이언트](/src/common/solar/solar.client.ts): Upstage Solar 자연어 요약, non-streaming.

## 도구 (25개)

- [Weather (6)](/src/modules/tools/weather/): short/ultra-now/ultra-forecast/mid-land/mid-ta/mid-summary (기상청 KMA).
- [Air Quality (4)](/src/modules/tools/air-quality/): sido/forecast/station/week (한국환경공단 AirKorea).
- [Apartment](/src/modules/tools/apartment-rent/): rent + trade 검색 (국토부 실거래가).
- [기타 atomic 9개](/src/modules/tools/): arxiv, semantic-scholar, kosis, library, korean-dict, exchange, assembly.
- [Composite (6)](/src/modules/tools/composite/): paper-research-global, daily-briefing, **morning-briefing**, **unanswered-reminder**, paper-research-korea(stub), composite-stubs(4).

## 스케줄러 + 알림

- [Scheduler Service](/src/modules/scheduler/scheduler.service.ts): cron CRUD + BullMQ Repeatable 동기화.
- [Scheduler Worker](/src/modules/scheduler/scheduler.worker.ts): 발화 시 도구 호출 → Solar 자연어 요약 → 알림 dispatch.
- [Scheduler 도구 4개](/src/modules/scheduler/scheduler-tools.service.ts): schedule_create/list/update/delete (자연어 등록용).
- [Notification 포매터](/src/modules/scheduler/notification-formatter.service.ts): toolResult → 사람이 읽는 한 단락.
- [Delivery 어댑터](/src/modules/scheduler/delivery/): PUSH (DB), Slack/Email/KakaoTalk 핸들러는 후속.

## Composio L1 (OAuth 외부 통합)

- [Composio Service](/src/modules/composio/composio.service.ts): SDK 래퍼. 5종 toolkit (gmail/googlecalendar/slack/notion/github).
- [Tool Bridge](/src/modules/composio/composio-tool-bridge.service.ts): 부팅 시 Composio 카탈로그를 ToolRegistry에 동적 등록.
- [한국어 description override](/src/modules/composio/composio-tool-overrides.ts): 7개 슬러그 자연어 강화.

## 프론트 부분 이식 대상 (6 컴포넌트 + 2 에러)

- [LocationPicker](/apps/web/components/inputs/LocationPicker.tsx): "서울 강남" 자연어 → lat/lon/lawdCd 자동 채움.
- [LawdCodePicker](/apps/web/components/inputs/LawdCodePicker.tsx): 250개 법정동 코드 fuzzy search.
- [SidoSelector](/apps/web/components/inputs/SidoSelector.tsx): 17개 시도.
- [DateSelector](/apps/web/components/inputs/DateSelector.tsx): yyyymm/yyyymmdd/iso/datetime 4종 자동 변환.
- [EnumSelector](/apps/web/components/inputs/EnumSelector.tsx): labeled-enum.
- [SmartArgField](/apps/web/components/inputs/SmartArgField.tsx): hint 메타 기반 라우터.
- [Location presets](/apps/web/components/inputs/location-presets.ts): 41개 한국 도시 시드 데이터.
- [ErrorChip](/apps/web/components/errors/ErrorChip.tsx): 3분류 색칠.
- [FriendlyErrorBanner](/apps/web/components/errors/FriendlyErrorBanner.tsx): 카테고리 + 메시지 + retry + raw 토글.

## 데이터 모델

- [Prisma schema](/prisma/schema.prisma): User, OAuthToken, Schedule, ScheduleRun, UsageLog, ToolConfig, Conversation, Message, Notification.

## 컨벤션·운영

- [CLAUDE.md (프로젝트 컨벤션)](/CLAUDE.md): pnpm 강제, conventional commits, V3 컨벤션, Karpathy 가이드라인.
- [Husky pre-commit hooks](/.husky/): lint-staged + commitlint.

## Optional

- [시연 영상 v3](/apps/web/public/report/demo/scheduler/): 7 시나리오, 자연어 등록 → 실제 발화 → 알림함 표시까지.
- [Composio 컨트롤러](/src/modules/composio/composio.controller.ts): OAuth connect 링크 발급 REST.