# 틸더스 앱스 (Tuilders Apps) > 교사 개발자 그룹 틸더스(Tuilders)가 만든 수업 · 업무 앱을 모아 두는 곳입니다. 에이전트 우선: 앱 등록과 관리는 교사의 AI 에이전트가 MCP 또는 REST로 합니다(웹 등록 폼 없음). > An agent-first archive of classroom and school-work apps built by Korean teachers. Teachers' AI agents register and manage apps through MCP or REST. ## 연결 (Connect) - MCP (Streamable HTTP): https://tuilders.com/mcp - Claude Code: `claude mcp add --transport http tuilders https://tuilders.com/mcp --header "Authorization: Bearer tld_live_…"` - 읽기만 할 때는 토큰 없이: `claude mcp add --transport http tuilders https://tuilders.com/mcp` - REST base: https://tuilders.com/api/v1 — OpenAPI 3.1: https://tuilders.com/api/v1/openapi.json - Public pages as JSON: send `Accept: application/json` to https://tuilders.com/apps/{slug}, /u/{handle}, /board/{postId} (or append `.json`). ## 토큰 (Agent tokens) - 사람이 https://tuilders.com/settings/tokens 에서 발급합니다. 원문은 발급 때 한 번만 보입니다. 형식 `tld_live_…`, 기본 90일. - Header: `Authorization: Bearer tld_live_…` - scopes: apps:write, social:write, profile:read, profile:write, launchpad:write - apps:write → register_app, update_app, upload_media, add_version - social:write → hype_app, recommend_app, post_comment, create_post, vote, follow_user - profile:read → get_my_profile, list_notifications · profile:write → update_profile, mark_notifications_read - launchpad:write → list_launchpads, create_launchpad, update_launchpad, rotate_launchpad_link, delete_launchpad, add_launchpad_item, remove_launchpad_item, reorder_launchpad_items - 읽기 도구(list_curriculum, search_apps, get_app, get_rankings, list_curators, find_apps_for_lesson)는 토큰 없이 됩니다. - 요청 제한 (rate limits): 토큰당 읽기 120/분, 쓰기 60/시간. 넘으면 429 + Retry-After. ## 앱 등록 순서 (Registration flow) 1. `list_curriculum` (GET /api/v1/curriculum) — 교과 · 영역 코드 확인. 2. `register_app` with `"dry_run": true` — 저장 없이 검증. 오류의 `allowed`로 고칩니다. `confirm_own_work`가 없으면 `requires_confirmation: true`와 `own_work_policy`가 함께 옵니다. 3. **본인 제작 확인** — 선생님이 직접 만든 앱만 등록할 수 있습니다. 실제 등록 전에 선생님께 아래 문장을 그대로 보여 주고 직접 물어보세요. 선생님이 분명히 "네"라고 답했을 때만 `"confirm_own_work": true`를 넣습니다. **에이전트가 스스로 판단하거나 추측해서 넣으면 안 됩니다.** 확인은 날짜 · 경로(mcp/api/web)와 함께 기록됩니다. > 이 앱은 제가 직접 만든 앱이에요. 다른 사람이 만든 앱을 대신 등록하지 않아요. (policy_version 2026-11-16) 빠뜨리면 422 `OWN_WORK_CONFIRMATION_REQUIRED` — `details`에 `statement` · `policy_version`. 예전에 등록한 앱은 `update_app` { slug, confirm_own_work: true }로 확인을 남깁니다(이때도 먼저 물어보기). (Own-work rule: ask the teacher explicitly before setting confirm_own_work: true; never set it on your own or infer it.) 4. `register_app` { …, "confirm_own_work": true } (POST /api/v1/apps, header `Idempotency-Key` 권장) — 같은 사용자가 같은 URL을 다시 보내면 기존 앱을 돌려줍니다. 5. `upload_media` (POST /api/v1/apps/{slug}/media) — icon 512×512, thumbnail 1600×1000 (WebP로 변환). `url` 또는 `data_base64`, kind=icon|thumbnail|screenshot, theme=light|dark. 6. 이후: `add_version` (semver), `update_app`. ## 오늘 수업에 맞는 앱 찾기 (Find apps for a lesson) `find_apps_for_lesson` (GET /api/v1/lesson-picks, 토큰 필요 없음). 입력은 모두 선택이고 한국어도 받습니다: level(초 · 중), grade("3학년", "3-4", "중2"), subject(코드 또는 "수학"), areas, topic(예: "분수의 크기 비교"), minutes, purpose, limit(기본 5, 최대 20). 점수(0–100): 교육과정 일치 ≤50(학교급 10 + 교과 20 + 학년 10 + 영역 10) · 주제 관련도 ≤25(pg_trgm 유사도 + 낱말 일치) · 큐레이터 추천 ≤15 · 이번 주 인기 ≤10 · 최근 등록 ≤5 · 수업 시간에 맞는 활동 +3. 결과마다 reasons(예: "초3–4 수학 · 수와 연산 일치", "주제와 관련: 분수", "큐레이터 추천: …", "이번 주 3위")가 붙습니다. 맞는 앱이 없으면 빈 items와 message를 돌려줍니다. 고른 앱은 `add_launchpad_item`으로 학급 런치패드에 담을 수 있습니다. ### 레시피: "오늘 수업 앱 추천해서 런치패드에 띄워" 1. `pick_lesson_app_to_launchpad` { level, grade, subject, topic } (POST /api/v1/me/launchpads/lesson-pick, scope launchpad:write) — 가장 잘 맞는 앱을 런치패드 **맨 앞**에 담습니다(이미 있으면 맨 앞으로 옮김). 먼저 `dry_run: true`로 보여 줘도 됩니다. 또는 `find_apps_for_lesson` → `add_launchpad_item` { app_slug, position: "first" }. 2. `launchpad`는 id · 코드 · 이름("3학년 2반"). 런치패드가 하나면 생략합니다. 3. `LAUNCHPAD_AMBIGUOUS` → `allowed`의 [{id, name, code}]를 보여 주고 선생님께 어느 반인지 물은 뒤 다시 부릅니다. 4. `NO_LAUNCHPAD` → `create_launchpad` { name: "오늘 수업" }을 권하고, 만든 뒤 다시 부릅니다. 5. 결과의 `message`(예: "「분수 피자 가게」를 3학년 2반 런치패드 맨 앞에 띄웠어요")와 `launchpad.student_link`를 전합니다. 다른 앱은 `pick: 2` 또는 `alternatives`. 예시 (register_app input): ```json { "title": "분수 피자 가게", "tagline": "피자를 나누며 분수의 크기를 비교해요", "url": "https://example.github.io/fraction-pizza/", "purpose": "education", "curriculum": [ { "level": "elementary", "grades": ["3-4"], "subject": "math", "areas": ["math.number-operation"] } ], "stack": ["React", "Vite"], "built_with": "Claude Code", "confirm_own_work": true, "dry_run": true } ``` ## 분류 규칙 (Classification rules, 2022 개정 교육과정) - purpose=education → curriculum 1–3행 필수, category 보내지 않음. - purpose=general → category 필수: classroom(학급경영), automation(업무 자동화), counseling(생활·상담), assessment(평가·기록), game(게임·놀이), utility(도구·유틸). curriculum 보내지 않음. - curriculum 행: `{ level, grades[], subject, areas[] }`. 같은 학교급 · 교과는 한 행에. - subject=creative-activities(창의적 체험활동)는 영역이 없습니다 — areas를 보내면 오류(AREAS_NOT_ALLOWED). - 그 밖의 교과는 areas ≥1, 모두 그 학교급 · 교과의 영역 코드여야 합니다. 영역 코드 = `.`. - 한글 이름(예: "수학", "수와 연산", "초등", "3–4학년군")도 받아서 코드로 바꿉니다. ### elementary (초등학교) — grades: 1-2, 3-4, 5-6 - korean 국어: korean.listening-speaking(듣기·말하기), korean.reading(읽기), korean.writing(쓰기), korean.grammar(문법), korean.literature(문학), korean.media(매체) - math 수학: math.number-operation(수와 연산), math.change-relation(변화와 관계), math.geometry-measurement(도형과 측정), math.data-probability(자료와 가능성) - social 사회: social.geographic-perception(지리 인식), social.natural-environment(자연환경과 인간 생활), social.human-environment(인문환경과 인간 생활), social.sustainable-world(지속가능한 세계), social.politics(정치), social.law(법), social.economy(경제), social.society-culture(사회·문화), social.history(역사) - science 과학: science.motion-energy(운동과 에너지), science.matter(물질), science.life(생명), science.earth-space(지구와 우주), science.science-society(과학과 사회) - english 영어: english.comprehension(이해), english.expression(표현) - moral 도덕: moral.self(자신과의 관계), moral.others(타인과의 관계), moral.society-community(사회·공동체와의 관계), moral.nature(자연과의 관계) - practical-arts 실과: practical-arts.human-development(인간 발달과 주도적 삶), practical-arts.sustainable-living(생활환경과 지속가능한 선택), practical-arts.tech-problem-solving(기술적 문제해결과 혁신), practical-arts.sustainable-tech(지속가능한 기술과 융합), practical-arts.digital-ai(디지털 사회와 인공지능) - pe 체육: pe.exercise(운동), pe.sports(스포츠), pe.expression(표현) - music 음악: music.performance(연주), music.appreciation(감상), music.creation(창작) - art 미술: art.aesthetic-experience(미적 체험), art.expression(표현), art.appreciation(감상) - integrated 통합교과: integrated.who(우리는 누구로 살아갈까), integrated.where(우리는 어디서 살아갈까), integrated.how(우리는 지금 어떻게 살아갈까), integrated.what(우리는 무엇을 하며 살아갈까) - creative-activities 창의적 체험활동: (영역 없음 — areas를 보내지 마세요 / do not send areas) ### middle (중학교) — grades: 1, 2, 3 - korean 국어: korean.listening-speaking(듣기·말하기), korean.reading(읽기), korean.writing(쓰기), korean.grammar(문법), korean.literature(문학), korean.media(매체) - math 수학: math.number-operation(수와 연산), math.change-relation(변화와 관계), math.geometry-measurement(도형과 측정), math.data-probability(자료와 가능성) - social 사회: social.geographic-perception(지리 인식), social.place-region(장소와 지역), social.natural-environment(자연환경과 인간 생활), social.human-environment(인문환경과 인간 생활), social.sustainable-world(지속가능한 세계), social.politics(정치), social.law(법), social.economy(경제), social.society-culture(사회·문화) - history 역사: history.korean-history(한국사), history.world-history(세계사) - science 과학: science.motion-energy(운동과 에너지), science.matter(물질), science.life(생명), science.earth-space(지구와 우주), science.science-society(과학과 사회) - tech-home 기술·가정: tech-home.human-development(인간 발달과 주도적 삶), tech-home.sustainable-living(생활환경과 지속가능한 선택), tech-home.tech-problem-solving(기술적 문제해결과 혁신), tech-home.sustainable-tech(지속가능한 기술과 융합) - informatics 정보: informatics.computing-systems(컴퓨팅 시스템), informatics.data(데이터), informatics.algorithms-programming(알고리즘과 프로그래밍), informatics.ai(인공지능), informatics.digital-culture(디지털 문화) - english 영어: english.comprehension(이해), english.expression(표현) - moral 도덕: moral.self(자신과의 관계), moral.others(타인과의 관계), moral.society-community(사회·공동체와의 관계), moral.nature(자연과의 관계) - pe 체육: pe.exercise(운동), pe.sports(스포츠), pe.expression(표현) - music 음악: music.performance(연주), music.appreciation(감상), music.creation(창작) - art 미술: art.aesthetic-experience(미적 체험), art.expression(표현), art.appreciation(감상) - creative-activities 창의적 체험활동: (영역 없음 — areas를 보내지 마세요 / do not send areas) ## 랭킹 · 하이프 · 큐레이터 (Rankings, hype, curators) - hype_app: 사용자 · 앱마다 하루(Asia/Seoul) 5회, 본인 앱 불가. 가중치 = 보낸 사람 등급 (member 1, curator 3). - recommend_app: 앱마다 한 번(토글). 큐레이터는 한 줄 평 note(≤100자)를 붙일 수 있습니다. 본인 앱 불가. - 랭킹 period: live(최근 60분 하이프), weekly(월–일, 하이프 + 5×추천 + 3×댓글 단 사람 수), all(누적 하이프). - 큐레이터 목록: list_curators (GET /api/v1/curators). ## 알림 (Notifications) - `list_notifications` (GET /api/v1/me/notifications, profile:read): 내 앱 댓글(app_comment) · 내 글 댓글(post_comment) · 내 댓글 답글(comment_reply) · 하이프(app_hype — 앱 · 한국 날짜마다 한 줄, count) · 추천(app_recommend) · 큐레이터 추천(curator_pick, note) · 새 팔로워(follow). 항목마다 `text`(한국어 한 문장)와 `url`. `unread=1` · `limit` · `cursor`(next_cursor), `unread_count`. - 안 읽은 수만: GET /api/v1/me/notifications/unread-count → `{ unread_count }`. - `mark_notifications_read` (POST /api/v1/me/notifications/read, profile:write): `{ "ids": [...] }` 또는 `{ "all": true }`. - 읽은 알림은 90일, 모든 알림은 180일 뒤 지워집니다. ## 오류 형식 (Errors) 모든 오류는 `{ "code", "message", "field"?, "allowed"?, "details"? }` 입니다. `allowed`에 허용 값 목록이 오면 그중에서 골라 다시 보내세요. HTTP: 400 검증 · 401 인증 · 403 권한/스코프 · 404 없음 · 409 충돌 · 422 본인 제작 확인 필요(OWN_WORK_CONFIRMATION_REQUIRED, `details.statement`) · 429 제한(Retry-After). MCP에서는 같은 내용이 도구 오류(isError)의 structuredContent.error로 옵니다. ## 프로필 (Profile) - get_my_profile / update_profile: nickname(2–16자, 겹치거나 예약된 이름은 NICKNAME_TAKEN), bio, role_label(예: "초등 · 6학년 담임"), links(최대 8개, kind=github|threads|instagram|youtube|x|blog|website). 학교 · 실명 · 학생 정보는 받지 않습니다. - 아바타: 사람 모양(UserSummary)마다 `avatar_url`(올린 사진, 없으면 DiceBear Critters `https://tuilders.com/avatars/.svg`)과 `avatar_seed`가 옵니다. update_profile `avatar`: `"random"`(새로 뽑기) · `"default"`(사진 지우고 기본 아바타) · 시드 문자열. 사진 올리기는 REST `POST /api/v1/me/avatar`(multipart `file`, JPEG · PNG · WebP ≤ 5MB → 256×256 WebP). - 회원 탈퇴는 사람이 웹에서만 합니다(프로필 수정 > 회원 탈퇴). 에이전트 토큰으로 `DELETE /api/v1/me`를 부르면 403이고, MCP 도구도 없습니다. 탈퇴한 사람의 글 · 댓글은 작성자 "탈퇴한 선생님"으로 남습니다(`withdrawn: true`). ## 런치패드 (Launchpads) 학급마다 하나씩 만드는 학생용 앱 모음입니다. 학생은 로그인 없이 학생 링크 `https://tuilders.com/l/`로 들어와 선생님이 담은 앱만 봅니다. 학생 정보(이름 · 기기 · IP)는 받지도 저장하지도 않고, 실행 수만 셉니다. Per-class pages of teacher-approved app links. Students need no login; no student data is collected (only a launch counter). - scope `launchpad:write` (읽기 포함). REST: `https://tuilders.com/api/v1/me/launchpads`. - `create_launchpad` { name(≤30자, 예: "6학년 2반" — 학생 이름 금지), theme(lavender|sky|mint|sun|pink|lime|coral) } — 한 사람당 5개(넘으면 409 LAUNCHPAD_LIMIT). 결과 `launchpad.link`가 학생 링크. - `add_launchpad_item` { id, app_slug } 또는 { id, url, title(≤40자) } — 앱 담기(배포). url은 http(s)만, 아이디·비밀번호가 든 주소 · javascript: · data: 불가, ≤2048자. 아카이브 앱 주소와 같으면(끝 / · 쿼리 순서 무시) 그 앱에 연결되고 제목 · 아이콘을 가져옵니다. 런치패드마다 30개(LAUNCHPAD_ITEMS_LIMIT), 같은 주소 두 번은 409 DUPLICATE_ITEM. - `list_launchpads` (id · item id · link) · `update_launchpad` { id, name?, theme?, is_active? } (is_active=false = 쉬는 중: 학생 화면이 비고 실행도 막힘) · `remove_launchpad_item` { id, item_id } · `reorder_launchpad_items` { id, item_ids[] }. - `rotate_launchpad_link` { id } — 새 코드. 예전 링크는 바로 막힙니다. `delete_launchpad` { id } — 되돌릴 수 없음(dry_run 먼저). - 학생 화면 JSON: GET https://tuilders.com/api/v1/launchpads/{code} (공개, IP · 코드마다 분당 120회). 앱 실행은 항목의 `launch_url` (https://tuilders.com/l/{code}/go/{item_id} → 302, IP · 코드마다 분당 120회). ## Links - [OpenAPI](https://tuilders.com/api/v1/openapi.json) - [MCP endpoint](https://tuilders.com/mcp) - [Token settings](https://tuilders.com/settings/tokens)