신규 기능 외부 연동 가이드 — 유튜브 채널 전사 · 블로그 게시 (261117 릴리스)
| 항목 | 내용 |
|---|---|
| 대상 독자 | 외부 연동 세션 (예: 건설도면프로젝트) — MCP 클라이언트로 두 기능을 소비하는 개발자 |
| 릴리스 | stable-261117 승격 반영 (§3.5.4 M4 승격·사용자 승인 bf562ea1a — 2026-11-17) |
| 기능 1 | 유튜브 채널 전사 — ai-ready MCP 확장: youtube_list_channel_videos·youtube_get_video_transcript (배치 3종은 prod 레버 off — §4.4 "문의 필요") |
| 기능 2 | 블로그 게시 — 별도 MCP blog_publish_mcp :8770: aiready_blog_create_draft·aiready_blog_publish(confirm=true 필수)·aiready_blog_status |
| 기준 문서 | 1_type_regrex/docs/aiready_mcp/261117_유튜브채널전사_AIReadyMCP확장_상세설계서.md · 261117_블로그게시_별도MCP_상세설계서.md |
| 참조 코드 | 1_type_regrex/ai_ready_mcp/server/tools/youtube_transcript.py · ai_ready/src/format_parsers/youtube_channel_fetch.py · f1_orchest/blog_publish_mcp/(server/tools/blog.py·server/service/publish_service.py·server/core/errors.py) |
| 파일럿 실측 | 1_type_regrex/docs/aiready_mcp/261117_유튜브전사_파일럿실측/T7T8T9_파일럿판정_261117.md + t7_results.json·t8_videos.json |
| 표기 규칙 | [실측]=파일·실행으로 확인된 값(근거 file:line) · [계약]=설계서·docstring 확정 계약 · 시크릿은 원문 미기재(위치·환경변수명만 — CREDENTIALS.md SSOT) · 파일경로는 리포 루트(f1_orchest/) 기준 |
1. 개요·엔드포인트·MCP 클라이언트 연결
1.1 기능·엔드포인트 요약
| 기능 | 서버 | 엔드포인트 | 도구 | 인증 |
|---|---|---|---|---|
| 유튜브 채널 전사 | ai-ready MCP (기존 서버에 additive 확장) | prod http://192.168.50.88:8766/mcp · dev http://127.0.0.1:8765/mcp [실측·CREDENTIALS.md "MCP 서비스" 표] | 2종 (+배치 3종 prod 미노출) | Bearer 토큰 (§2) |
| 블로그 게시 | blog_publish_mcp (독립 서버·ai-ready와 별계·무접촉) | http://192.168.50.88:8770/mcp — 포트 8770 [실측·blog_publish_mcp/docker-compose.blog.yml ports] | 3종 | v1 내부망 네트워크 경계 신뢰 (§2.3) |
- 유튜브 도구는 기존 ai-ready MCP에 additive 확장된 도구 — 별도 연결 없이 기존 MCP 연결에서 그대로 호출 [계약·설계서 §1 "신규 MCP 서버 아님"].
- 블로그 도구는 별도 서버 — ai-ready(:8765/:8766)와 프로세스·코드·볼륨·자격 전부 분리 [계약·블로그 설계서 §3-1].
- prod 노출 실측(승격 스모크 B): prod tools/list 64종 + youtube 2종 노출, 배치 3종 미노출 / dev 67종(배치 포함) [실측·SESSION_LOG 261117 승격 스모크].
1.2 MCP 클라이언트 연결 (Streamable HTTP)
두 서버 모두 FastMCP 기반 Streamable HTTP. JSON-RPC POST로 initialize → notifications/initialized → tools/list → tools/call 순서로 호출하며, 응답 헤더 mcp-session-id를 이후 요청에 유지한다. 파일럿에서 동일 방식으로 실측 [실측·docs/aiready_mcp/261117_유튜브전사_파일럿실측/mcp_client.py].
import json, urllib.request
BASE = "http://192.168.50.88:8766/mcp" # prod (dev: http://127.0.0.1:8765/mcp)
TOKEN = "<MCP 토큰 — CREDENTIALS.md 참조, 평문 커밋 금지>" # §2
HEADERS = {"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"Authorization": f"Bearer {TOKEN}"}
session_id = None
def call(method, params=None):
global session_id
body = {"jsonrpc": "2.0", "id": next_id(), "method": method}
if params is not None:
body["params"] = params
h = dict(HEADERS)
if session_id:
h["mcp-session-id"] = session_id
req = urllib.request.Request(BASE, data=json.dumps(body).encode(), headers=h, method="POST")
with urllib.request.urlopen(req, timeout=300) as r:
sid = r.headers.get("mcp-session-id")
if sid and not session_id:
session_id = sid
# SSE(data: ...) 또는 plain JSON 모두 수용 — data: 라인 우선 파싱
return parse_sse_or_json(r.read())
call("initialize", {"protocolVersion": "2024-11-05", "capabilities": {},
"clientInfo": {"name": "my-client", "version": "1.0"}})
call("notifications/initialized")
블로그 MCP 연결: BASE를 http://192.168.50.88:8770/mcp로 교체. 토큰 헤더는 v1 불요(§2.3) — 다만 헤더를 보내도 무해. 로컬 개발용 stdio도 지원: python -m server.main --transport stdio (기본 http :8770) [실측·blog_publish_mcp/server/main.py docstring].
1.3 tools/list 예시
요청: {"jsonrpc": "2.0", "id": 1001, "method": "tools/list"}
prod 응답에서 신규 도구 확인 (이름만 발췌 — 전체는 스키마 포함):
{ "jsonrpc": "2.0", "id": 1001,
"result": { "tools": [
{ "name": "youtube_list_channel_videos", "description": "List all videos of a YouTube channel ...", "inputSchema": { ... } },
{ "name": "youtube_get_video_transcript", "description": "Get the transcript of a YouTube video from its processed case ...", "inputSchema": { ... } },
...
] } }
[실측] 파일럿: tools/list 64종 중 youtube 2종 노출 확인(배치 3종 off — 계약 일치) / 승격 후 prod 64종+youtube 2종·dev 67종(배치 3종 포함). 블로그 서버 tools/list는 aiready_blog_create_draft·aiready_blog_publish·aiready_blog_status 3종 [실측·blog_publish_mcp/server/tools/blog.py:39-41].
1.4 tools/call 응답 형태
도구 반환 dict는 표준 result.structuredContent(또는 result.content[0].text의 JSON 본문)로 취득한다. 이 문서의 "예시 응답"은 도구 반환 dict 기준이며, 실측 원문은 t7_results.json·파일럿 판정문에 보존되어 있다.
2. 인증 — 런타임 크레덴셜 (CREDENTIALS.md SSOT·평문 금지)
2.1 ai-ready MCP (유튜브 도구)
| 항목 | 계약 |
|---|---|
| 방식 | HTTP Authorization: Bearer <토큰> — 발급 토큰은 mcp_api_tokens 테이블(sha256 해시 저장·tier free/paid) [실측·CREDENTIALS.md "DB" 표] |
| 토큰 SSOT | 1_type_regrex/docs/aiready_mcp/CREDENTIALS.md "발급 토큰(활성)" 표만이 평문 토큰의 단일 장소 — 타 문서·커밋·로그에 평문 기재 금지. 파일럿도 "토큰: unlimited-261019 (CREDENTIALS.md SSOT)" 방식으로 참조만 기록 [실측·파일럿 판정문 헤더] |
| 과금 | 도구별 포인트 정액(TOOL_COSTS) — 유튜브 전사는 케이스 산출물 재가공이므로 읽기 성격이나, 케이스 생성(create_case_from_url, 3P)에 전사 취득 원가(다운로드+ASR)가 과금된다. 전사·목록 도구 자체 과금은 운영 협의 항목 [계약·설계서 §10 "과금·정책 연동 [제안 — 운영 협의]"] |
| 소유권 스코프 | 토큰별 데이터 루트 격리 — 생성한 케이스·전사는 자기 데이터 루트에서만 조회 |
2.2 시크릿 취급 원칙 (양 서버 공통)
- 크레덴셜은 런타임 env 주입만 — 평문을 compose·설정 파일·문서·코드에 저장 금지 [계약·블로그 설계서 §7 G-B1].
- 블로그 외부 API 자격(확정 시): env 키 접두
BLOG_TOKEN_*— 기동 시 존재 확인, 부재 시 어댑터가target_unavailable반환(조용한 폴백 금지) [실측·blog_publish_mcp/server/core/config.py:has_credential]. - 로그·감사·도구 응답에 토큰 미포함 — 마스킹 필터(
mask_secret: 앞 3자리만 노출) 내장 [실측·config.pymask_secret·redact_env_text]. - 평문 잔존 게이트:
tests/test_blog_mcp.py::test_ac3_no_plaintext_credentials— 이미지 컨텍스트·설정 파일 전수 grepBLOG_TOKEN_실값 0건을 CI로 강제 [계약·블로그 설계서 §9 AC-3].
2.3 블로그 MCP (v1 인증 모델)
v1은 네트워크 경계 신뢰(LAN 바인딩 192.168.50.88·내부망) — 토큰 게이트는 없으며 차기 확장 여지만 명시 [계약·블로그 설계서 §7 G-B7]. 내부망 밖 노출 금지. 외부 게시 API(ExternalApiAdapter)는 NA — 실연동 0 [실측·server/adapters/external_api.py NA 스텁].
3. 도구별 스펙 (파라미터·반환·예시)
각 도구 예시의 응답값 중 파일럿 실측 유래 값은 [실측] 태그로 출처를 표기한다.
3.1 youtube_list_channel_videos — 채널 영상 목록
| 항목 | 명세 [계약·youtube_transcript.py:70-127 + 설계서 §4.1] | |||
|---|---|---|---|---|
| 파라미터 | channel_url: str (채널 URL 또는 @handle·channelId — youtube.com 도메인만. /c/ 경로는 invalid_channel 거부 [실측·파일럿 판정문]) · limit: int = 50 (1~200 클램프) · page_token: str = "" (불투명 커서) · fill_dates: bool = False (빈 published_at 상세조회 채움 — 영상당 1회·스로틀 적용·YT_DATE_FILL_MAX 상한 기본 50 [실측·youtube_channel_fetch.py:92]) | |||
| 반환 | `{videos: [{video_id, title, published_at(YYYY-MM-DD, 빈값 가능), duration_s, url}], next_page_token: str | null, total: int(근사), cached: bool, fetched_at, published_at_empty: int, published_at_note?: str, dates_filled?: int, dates_failures?: {video_id: reason}}` | ||
| 캐시 | 서버측 TTL 캐시 YT_CHANNEL_CACHE_TTL_S 기본 21600(6h) — 캐시 히트 페이지당 ~0.01s [실측·파일럿 T8] | |||
| 실패 | `{"error", "reason": rate_limited | cache_expired | invalid_channel | ..., "retry_after_s"?, "hint"?}` — 조용한 성공 금지 |
요청 예시:
{ "name": "youtube_list_channel_videos",
"arguments": { "channel_url": "https://www.youtube.com/@OpenSearchProject/videos", "limit": 200 } }
응답 예시 (video 항목 — [실측·t8_videos.json 첫/말 항목]):
{ "videos": [
{ "video_id": "vzlnRt_6TWA", "title": "See Every Span, Find the Failure | OpenSearch 3.9 Highlights",
"published_at": "", "duration_s": 275, "url": "https://www.youtube.com/watch?v=vzlnRt_6TWA" },
...
{ "video_id": "Ppnwp12PyKo", "title": "OpenSearch Community Meeting - June 13th, 2022",
"published_at": "", "duration_s": 2883, "url": "https://www.youtube.com/watch?v=Ppnwp12PyKo" } ],
"next_page_token": "<불투명 커서 문자열 — 마지막 페이지에서 null>",
"total": 711, "cached": true,
"published_at_empty": 200,
"published_at_note": "업로드일 미확보 N건 — 사유: flat-playlist 메타데이터에 업로드일 미포함 (fill_dates=true로 상세 조회 채움 가능, YT_DATE_FILL_MAX 상한)" }
- 페이징:
next_page_token을 다음 호출의page_token으로 전달 — 마지막 페이지에서 null 소멸 [실측·파일럿 T8: 4페이지 200+200+200+111 순회 후 소멸·합계 711 unique 711]. 캐시 만료 시reason=cache_expired+hint: "page_token 없이 재호출". - 제목 파싱 711/711=100% (lockupViewModel — yt-dlp 위임, 커스텀 파서 0) · duration_s 711/711 > 0 [실측·T8].
published_at은 flat-playlist 메타 한계로 기본 공란 →fill_dates=true로 상세조회 채움. dev 실측: 50편 fill 50/50=100% 충전, 134.6s 소요 [실측·SESSION_LOG 261117 잔여 3건 완결].
3.2 youtube_get_video_transcript — 영상 전사
| 항목 | 명세 [계약·youtube_transcript.py:131-218 + 설계서 §4.2] |
|---|---|
| 파라미터 | video_id: str = "" (11자 패턴 [A-Za-z0-9_-]{11} — case_stem 미지정 시 필수) · case_stem: str = "" (직접 지정 — 우선) · lang: str = "" (기대 언어 — 감지 언어와 불일치 시 lang_mismatch 경고, 거부 아님) |
| 반환 (성공) | {case_stem, transcript: {segments: [{start_s, timestamp, text}], plain_text, segment_count, spoken_span_s}, video: {...}, lang_detected, lang_requested, duration_consistent: bool, source: {case_stem, pipeline, md_path}, acquired_at(ISO8601), engine, usage_note, duplicates?: [stems], lang_mismatch?: true, lang_note?: str} |
| 반환 (부재) | {transcript: null, reason: <enum §4.3>, video_id?, case_stem?, hint} — 빈 200 금지 [계약·P6] |
| 중요 | 전사 신규 취득(다운로드·ASR)을 수행하지 않는다 — 기존 video 케이스 산출 MD의 ## 영상_발화 축만 읽음. 케이스가 없으면 no_case 안내 |
요청 예시 (video_id 자동해석 — 261117 폴백 체인 수정 후):
{ "name": "youtube_get_video_transcript", "arguments": { "video_id": "tzmnr3mTibg" } }
응답 예시 ([실측·t7_results.json — 값 원문 인용]):
{ "case_stem": "tzmnr3mTibg_261117_1309_3144",
"transcript": { "segments": [{ "start_s": 0.0, "timestamp": "00:00", "text": "..." }, "..."],
"plain_text": "<전문>", "segment_count": 22, "spoken_span_s": 77.524 },
"video": { "video_id": "tzmnr3mTibg", "title": "...", "duration_s": 80, "...": "..." },
"lang_detected": "en", "lang_requested": "",
"duration_consistent": true,
"source": { "case_stem": "tzmnr3mTibg_261117_1309_3144",
"pipeline": "create_case_from_url→video_to_mark(ASR)",
"md_path": "/data/users/<uid>/markdown/tzmnr3mTibg_261117_1309_3144.md" },
"acquired_at": "2026-11-17T04:10:23+00:00",
"engine": "video_to_mark + ASR(faster_whisper_local)",
"usage_note": "내부 학습자료 용도 한정 — 외부 재게시 시 채널·라이선스 표기 필요" }
파일럿 3편 전체 실측 [실측·T7 + t7_results.json]:
| video_id | 길이 | 세그먼트 | 발화커버 | 문자 | lang | duration_consistent |
|---|---|---|---|---|---|---|
| tzmnr3mTibg | 80s | 22 | 96.9% (77.5s) | 1,190 | en | true |
| vzlnRt_6TWA | 275s | 105 | 95.8% (263.5s) | 3,097 | en | true |
| yhUsmXXp5Rw | 2282s | 595 | 100.0% (2281.8s) | 32,535 | en | true |
- 빈 응답 0건 ·
source/acquired_at/engine/usage_note동봉 확인 [실측·T7]. 전사 조회 자체는 캐시 읽기 — elapsed 0.01s [실측·t7_results.json]. duplicates필드: 동일 video_id로 재처리된 케이스가 여럿이면 최신 1건 반환 + 나머지 stems 명시(조용한 선택 금지) [계약·설계서 §7.3-3].- video_id 자동해석 폴백 체인(261117 수정): 스템 프리픽스
{video_id}_*≥ 케이스메타 ≥ MD 출처헤더 — additive [실측·SESSION_LOG 잔여 3건 완결].
3.3 배치 래퍼 3종 — prod 미노출 ("문의 필요")
youtube_batch_register·youtube_batch_run_now·youtube_batch_status는 prod 레버 YT_BATCH_ENABLED=off로 tools/list에 노출되지 않는다 [실측·승격 스모크 B: prod 배치 3종 미노출]. dev(:8765)에서는 on(dev 승격 — 67종) [실측·SESSION_LOG]. 외부 연동에서 전량 배치가 필요하면 사전에 운영자에게 문의 — 활성화는 사용자 승인 게이트 경유 [계약·설계서 §13·§14 P6].
참고 계약(문의 시): video_id별 ①기존 케이스 dedup ②미존재 시 케이스 생성 ③전사축 추출 ④스로틀 — 부분 실패 허용(failures[])·동일 video 재런은 skipped_dup [실측·dev: 동일 video 2회 런 → 양 런 succeeded·skipped=3·cases=0·재다운로드 0].
3.4 aiready_blog_create_draft — 초안 등록
| 항목 | 명세 [계약·blog.py:47-80 + publish_service.py:96-151] |
|---|---|
| 파라미터 | title: str (필수·1~300자) · body_markdown: str (필수·utf-8 2MB 이하 — 표·코드블록 지원) · tags: list[str] (0~20개·각 1~50자) · series: str (1~100자·옵션) · source_url: str (http/https·2048자 이하·옵션 — 원 출처 명시 계약 G-B6) |
| 반환 | {ok: true, execution_status: "completed", draft_id, preview_url, body_md_sha256, body_html_sha256, expires_note, target_id} |
| draft_id 형식 | {YYMMDD}_{slug8}_{hex6} (예: 261117_opensearch_a3f1c2) [계약·설계서 §3-2] |
| 변환 | 마크다운→HTML 결정론 변환(python-markdown·LLM 0) — 동일 입력 동일 해시. 코드블록·표·제목 계층 보존 [계약·설계서 §5 AC-1] |
| 감사 | action=draft_create 기록 — 해시만 기록·본문 원문 미기록 [실측·publish_service.py:135-137] |
요청 예시:
{ "name": "aiready_blog_create_draft",
"arguments": { "title": "OpenSearch 3.9 발화 요약 (내부 학습자료)",
"body_markdown": "# 요약\n\n출처: https://www.youtube.com/watch?v=vzlnRt_6TWA\n\n| 항목 | 값 |\n|---|---|\n| 길이 | 275s |",
"tags": ["내부학습", "요약"], "series": null,
"source_url": "https://www.youtube.com/watch?v=vzlnRt_6TWA" } }
응답 예시:
{ "ok": true, "execution_status": "completed",
"draft_id": "261117_opensea_a3f1c2",
"preview_url": "http://192.168.50.88:8770/preview/261117_opensea_a3f1c2",
"body_md_sha256": "<64hex>", "body_html_sha256": "<64hex>",
"expires_note": "초안은 publish 또는 별도 폐기 전까지 유지됩니다 — 게시 전 사람 검수 필수 (preview_url 확인)",
"target_id": "local_file" }
- preview_url을 사람이 육안 검수하는 단계를 거친다 [계약·설계서 §3-3 — 24호 §3.1 승계]. draft 수정 API는 없음 — 수정은 재등록 원칙(신규 create_draft 후 기존 draft 폐기) [계약·설계서 §3-3].
3.5 aiready_blog_publish — 게시 (confirm 게이트·발사 방지 핵심)
| 항목 | 명세 [계약·blog.py:82-104 + publish_service.py:154-256] |
|---|---|
| 파라미터 | draft_id: str (필수) · confirm: bool (boolean True만 허용 — 미지정·False·문자열 "true"·1 전부 거부 [실측·publish_service.py:157 if not (confirm is True and type(confirm) is bool)]) |
| 반환 (성공) | {ok: true, execution_status: "completed", draft_id, post_url, published_at(ISO-8601 KST), status: "published", body_md_sha256, body_html_sha256, target_id} |
| 게이트 순서 | ①confirm 엄격 검사 ②draft 존재·상태 ③일일 한도 ③'해시 대사(디스크 body.md 재계산 비교) ③''킬스위치 → ④어댑터 publish ⑤원자적 커밋(drafts→published) ⑥감사 기록 — 게이트 실패 시 부작용 0(어댑터 호출 이전 차단) [실측·publish_service.py 게이트 순서 + errors.py docstring] |
| 핵심 계약 | 본문을 직접 받아 게시하는 경로가 존재하지 않음 — publish 입력은 draft_id뿐(2단계 강제) |
요청 예시:
{ "name": "aiready_blog_publish",
"arguments": { "draft_id": "261117_opensea_a3f1c2", "confirm": true } }
거부 예시 (confirm 누락 — 감사에 result=rejected 메타만 기록·게시 0 진행):
{ "ok": false, "execution_status": "failed",
"error": { "code": "confirm_required",
"message": "confirm=true(boolean)가 필요합니다 — 게시는 실행되지 않았습니다",
"retryable": false, "retry_after_s": null,
"hint": "confirm=true로 재호출 — 게시는 실행되지 않았습니다" } }
3.6 aiready_blog_status — 상태·해시 대사 조회
| 항목 | 명세 [계약·blog.py:106-127 + publish_service.py:259-308] | |||||
|---|---|---|---|---|---|---|
| 파라미터 | draft_id 또는 post_url (택 1 — 둘 다 없으면 invalid_input) | |||||
| 반환 | `{ok, execution_status, status: draft | published | not_found | hash_mismatch, draft_id, post_url, published_at, body_md_sha256, body_html_sha256, target_id, target_reachable?: "true" | "false" | "unknown", probe_detail?}` |
| 대사 검증 | published이면 어댑터 verify_status(도달성·본문 대사) 시도 — 미지원 어댑터는 target_reachable:"unknown" 명시(조용한 성공 금지) [실측·publish_service.py:295-307] | |||||
| 해시 불일치 | status:"hash_mismatch" + probe_detail [계약·설계서 §4-3] |
응답 예시 (게시 후):
{ "ok": true, "execution_status": "completed",
"status": "published",
"draft_id": "261117_opensea_a3f1c2",
"post_url": "http://192.168.50.88:8770/posts/261117_opensea_a3f1c2",
"published_at": "2026-11-17T19:12:00+09:00",
"body_md_sha256": "<64hex>", "body_html_sha256": "<64hex>",
"target_reachable": "true", "target_id": "local_file" }
4. 전사 획득 흐름 (유튜브)
4.1 표준 시퀀스 — 케이스 자동생성 경로
전사는 케이스 산출물의 재해석이다. 최초 video_id는 케이스가 없으므로 create_case_from_url(기존 도구)로 케이스를 생성한 뒤 전사를 조회한다 [계약·설계서 §8.1 — 파일럿 경로와 동일]:
소비자 ai-ready MCP
│ 1. youtube_list_channel_videos ──▶ 캐시/yt-dlp flat-playlist (다운로드 0)
│ ◀── videos[] + next_page_token (마지막 page에서 null)
│
│ 2. youtube_get_video_transcript(video_id)
│ ◀── {transcript: null, reason: "no_case",
│ hint: "create_case_from_url로 케이스를 먼저 생성..."}
│
│ 3. create_case_from_url(url) ──▶ yt-dlp 2단계 다운로드(720p cap) → ASR+VLM → 케이스 MD
│ ◀── case_stem, video_id, duration_s (전사 취득 원가가 이 단계에 과금)
│
│ 4. youtube_get_video_transcript(video_id) ──▶ MD `## 영상_발화` 파싱
│ ◀── segments + source + acquired_at + engine + usage_note
- 3단계 대체:
case_stem을 이미 알고 있으면 전사 도구에case_stem직접 지정(우선 순위) [계약·youtube_transcript.py:161-167]. - 케이스 생성·처리 상태: 파이프라인 처리가 끝나지 않았으면
reason=case_not_ready— 완료 후 재호출 [계약·_REASON_HINTS]. - 연속 재호출 멱등: 이미 존재하는 video로 create_case_from_url 재호출 시 기존 케이스 재사용(dedup) — 중복 생성 없음 [실측·배치 dedup 실측과 동일 내부 경로].
4.2 provenance 필수 동봉 계약
모든 전사 성공 응답에는 다음 4필드가 항상 포함된다 [계약·설계서 P4 출처 정직 표기]:
| 필드 | 의미 | 실측 예 |
|---|---|---|
source | 출처(case_stem·pipeline·md_path) | {"pipeline": "create_case_from_url→video_to_mark(ASR)", ...} [실측·t7_results.json] |
acquired_at | 취득시각(=MD 갱신시각 ISO8601) | 2026-11-17T04:10:23+00:00 [실측] |
engine | 전사 엔진(모델명 정직 표기 — asr_model_gate 판정) | video_to_mark + ASR(faster_whisper_local) [실측] |
usage_note | 이용 조건 상수 | "내부 학습자료 용도 한정 — 외부 재게시 시 채널·라이선스 표기 필요" [실측·youtube_channel_fetch.py:53] |
소비자는 이 필드를 사용해 자료별 격리·출처 표기·취득시각 추적을 수행해야 한다(발행 전 3단 검증 문화 접속) [계약·설계서 §7.6].
4.3 reason enum — 부재·실패 사유 5종(+3)
부재·실패는 반드시 reason enum으로 구분 반환된다 — HTTP 200 + 빈 본문(빈 segments 위장)은 구조적으로 금지 [계약·P6 fail-fast + 설계서 §9 금지 패턴]. 코드 상수 [실측·youtube_transcript.py:44-51 _REASON_HINTS]:
| reason | 발생 조건 | 소비자 조치 (hint 요지) |
|---|---|---|
no_case | video_id에 해당 케이스 미존재 | create_case_from_url로 케이스 생성 후 재호출 (전사는 케이스 산출물에서 읽음 — 신규 취득 수행 안 함) |
case_not_ready | 케이스 존재하나 MD 미생성(처리 진행·실패) | 처리 완료 후 재호출 |
asr_empty | MD 존재·영상_발화 세그먼트 0 (음성 없음·ASR 빈 결과) | 원영상 음성 유무 확인 |
no_audio_stream | 전사축이 없는 케이스(무음 영상 등) | 정상 종료 취급 |
invalid_video_id | 11자 패턴 불일치 또는 video_id·case_stem 둘 다 공란 | video_id 형식 정정 |
rate_limited | 스로틀/YouTube 제한 감지 (§4.4) | retry_after_s 대기 후 재시도 |
cache_expired | 페이징 중 채널 캐시 만료 | page_token 없이 재호출(재나열) |
invalid_channel | /c/ 경로 등 지원 외 채널 URL | @handle 사용 [실측·파일럿] |
파일럿 검증: no_case·invalid_video_id·no_audio_stream 실측 + reason 5종 목업(T5·37 PASS) [실측·파일럿 판정 수용기준 4항].
4.4 레이트리밋·스로틀 계약
이중 방어 [계약·설계서 §7.5 + 실측·T9]:
| 층 | 동작 | 실측 |
|---|---|---|
| 사전 스로틀 | yt-dlp 호출(목록·다운로드 공용) 사이 최소 간격 강제 — YT_RATE_INTERVAL_S 기본 3s(단일)·배치 20s. 0=해제(사후 감지는 유지) | 실 Throttle 10회 실측: 대기 [0.0, 3.0×9] = 27.0s — 첫 즉시·이후 ≥3s 간격 [실측·T9] |
| 사후 감지 | yt-dlp stderr 스로틀 신호(HTTP Error 429·Sign in to confirm) 탐지 → 즉시 중단·구조화 반환 | rate_limited envelope 실측: {"error", "reason": "rate_limited", "retry_after_s": 120, "hint": "...권장 120s"} [실측·T9 — retry_after 120s] |
- 캐시 히트 시 스로틀·네트워크 호출 없음: 동일 채널 연속 10회 전부 캐시 히트(평균 5.0ms·YouTube 네트워크 호출 0회) [실측·T9].
- 소비자 규약:
rate_limited수신 시retry_after_s이상 대기 후 재시도 — 짧은 간격 재시도 남발 금지. 대량 획득은 배치 3종(§3.3 문의 필요) 또는 소규모 단위로 분할 요청.
5. 게시 흐름 (블로그)
5.1 표준 시퀀스 — draft→preview→confirm→status
소비자 blog_publish_mcp (:8770)
│ 1. aiready_blog_create_draft ──▶ 입력검증 → 결정론 MD→HTML → draft 영속 → 감사(해시만)
│ ◀── draft_id + preview_url + MD/HTML sha256
│
│ 2. (사람) GET /preview/{draft_id} ── 렌더 육안 검수 [필수 단계]
│
│ 3. aiready_blog_publish(confirm 생략) ──▶ ✗ confirm_required — 게시 0 진행
│ 3'. aiready_blog_publish(confirm=true) ──▶ 게이트 통과 → 원자적 커밋 → 감사
│ ◀── post_url + published_at + status:"published" + 해시
│
│ 4. aiready_blog_status(draft_id) ──▶ 원장 상태 + 어댑터 도달성·본문 대사 검증
│ ◀── status:"published" + target_reachable:"true" + 해시 일치
- 3단계의 confirm 생략 호출은 반드시 먼저 수행해 게이트를 확인하는 것을 권장(스모크 5단계 표준 절차) [계약·블로그 README "⑤ 도구 스모크"].
- post_url(LocalFile 어댑터):
http://<host>:8770/posts/{draft_id}— HTTP 200·본문 해시 대사 실검증 가능 [계약·설계서 §6-2].
5.2 해시 대사 (G-B3)
- create_draft 시점: 정규화 MD sha256 + 렌더 HTML sha256 산출·영속 [실측·publish_service.py:99-100].
- publish 시점: 디스크의 body.md를 재계산해 원장 해시와 비교 — 불일치 시
hash_mismatch거부(등록 후 무단 변조 차단) [실측·publish_service.py:197-210]. - status 시점: 게시 타깃의 본문과 HTML 해시 대사 — 불일치 시
status:"hash_mismatch"[실측·publish_service.py:302-305].
5.3 일일 한도·킬스위치
| 항목 | 계약 [실측·config.py + publish_service.py:180-195] |
|---|---|
| 일일 한도 | BLOG_DAILY_LIMIT 기본 10 — KST 자정 초기화. 초과 시 quota_exceeded + retryable: true + retry_after_s(자정까지 초) + hint "한도 상향은 사용자 합의 필요" |
| 킬스위치 | BLOG_PUBLISH_ENABLED 기본 on — off 시 publish 전면 거부(target_disabled)·런타임 판독(재기동 불요)·draft/status는 유지 |
| 한도 상향 | 사용자 사전 합의 필수 — 서버가 임의로 늘리지 않음 [계약·설계서 §2 비목표 원칙·§7 G-B5] |
5.4 실패 오류 구조 (envelope)
모든 실패는 동일 envelope [계약·errors.py to_envelope] — 9종 코드 [실측·errors.py:12-21]:
{ "ok": false, "execution_status": "failed",
"error": { "code": "<코드>", "message": "...",
"retryable": false, "retry_after_s": null, "hint": "..." } }
| code | 조건 | retryable |
|---|---|---|
invalid_input | 필수 누락·길이/크기 초과(title 1~300자·body 2MB·tags 0~20·series 1~100·source_url http/https 2048자) [실측·publish_service.py:26-58] | false |
confirm_required | publish confirm 미지정/오값 | false |
draft_not_found | draft_id 원장 무존재 | false |
invalid_state | 이미 published 등 상태 불일치 | false |
quota_exceeded | 일일 한도 초과 | true (retry_after_s=자정 KST까지 초) |
permission_denied | 어댑터 권한 오류 | false |
target_unavailable | 어댑터 미기동·자격 env 부재·내부 오류 | true (지수 백오프 권장) |
target_disabled | 킬스위치 BLOG_PUBLISH_ENABLED=off | — (운영자 문의) |
hash_mismatch | publish 시점 본문 대사 실패 | false — 재등록 필요 |
- 부작용 0 원칙: 게이트 실패(confirm·한도·해시·킬스위치)는 어댑터 호출 이전에 차단 — 파일 이동·"publish 성공" 감사 기록 없음(감사에는
result=rejected메타만) [실측·publish_service.py 각 게이트 분기 + errors.py docstring]. - 재시도:
retryable:true인 경우에만 재시도 —retry_after_s준수.retryable:false재시도는 무의미.
6. 제약·보안
6.1 이용약관·저작권 (유튜브 전사)
| 항목 | 계약 |
|---|---|
| 용도 한정 | 전사물은 내부 학습자료 용도 한정 — 모든 전사 응답에 usage_note 상수 동봉 [실측·youtube_channel_fetch.py:53] |
| 출처 표기 | 외부 재게시 시 채널·라이선스 표기 필요. 블로그 게시 시 원 출처는 초안 작성자(상류) 책임 — create_draft source_url 필드로 기록 지원 [계약·설계서 §7.6·G-B6] |
| 자막 트랙 미사용 | 전사는 ASR 파이프라인 산출 — 자막 트랙(captionTracks·timedtext) 경로를 서버에 두지 않음(pot 차단·약관 리스크 구조적 제거) [계약·설계서 §3 P2] |
| 우회 금지 | 브라우저 자동화·PoToken 제공자 우회 등은 정식 해법 아님 — 사용 금지 [계약·설계서 §1 비목표] |
6.2 어댑터·NA (블로그)
| 어댑터 | 상태 | 비고 [실측·external_api.py + README] |
|---|---|---|
local_file (기본) | 구현·운영 | published/{draft_id}/ 영속 + /posts/{draft_id} 서빙 — post_url 200·본문 대사 실검증 |
mock | 구현 | pytest·CI·롤백 레버 — 외부 부작용 0 |
external_api | NA | 게시 API 미확정 — "인터페이스만 정의·목업 유지·실연동 0(target_unavailable 고정)". 해소 조건: ①API 엔드포인트·payload 계약 ②인증 방식 ③할당량 정책이 사용자 합의 문서로 확정된 뒤 구현 착수 |
→ 외부 연동자는 현재 local_file 타깃 한정으로 간주한다. 외부 블로그 플랫폼 연동은 문의 필요(§7.2).
6.3 레버·prod 상태 (stable-261117 기준)
| 레버 | prod 상태 | 효과 [계약·설계서 §13] |
|---|---|---|
YT_CHANNEL_TOOLS | on — 2종 노출 [실측·승격 스모크 B] | off 시 유튜브 2종 tools/list 소멸 — 롤백 레버 |
YT_BATCH_ENABLED | off — 배치 3종 미노출 [실측·동일] | on 시 배치 3종 추가. 활성화는 사용자 승인 게이트 — 문의 필요 |
YT_RATE_INTERVAL_S | 3 (단일·기본) | 스로틀 간격 |
YT_CHANNEL_CACHE_TTL_S | 21600 (6h) | 0=캐시 비활성 |
YT_DATE_FILL_MAX | 50 | fill_dates 상세조회 상한 |
BLOG_PUBLISH_ENABLED | on | off 시 publish 전면 거부 |
BLOG_DAILY_LIMIT | 10 | 일일 게시 한도 — 상향은 사용자 합의 |
BLOG_TARGET | local_file | mock 전환 시 외부 부작용 0 |
- 레버는 재빌드 없이 env 원복만으로 롤백 가능 [계약·설계서 §13].
- ai-ready 무영향 보장: 블로그 서버는 ai-ready와 무접촉 — 철수(
compose down)해도 ai-ready·기존 케이스·파이프라인 불변 [계약·설계서 §13 + 회귀 게이트test_regression_no_contact].
6.4 데이터 격리·감사
- 감사 로그:
/data/blog/audit_log.jsonl—{ts, action, draft_id, body_md_sha256, body_html_sha256, result, post_url?}· 본문 원문 미기록(해시만) · append-only·삭제 도구 없음 [계약·G-B4 + README 볼륨 구조]. - 경계 가드: draft_id·파일명 정규화(구분자·
..·선두점·NUL 차단) — 경로 주입 차단 [계약·G-B7·ids.require_safe_draft_id]. - 유튜브 데이터: 토큰(사용자)별 데이터 루트 격리 — 다른 소비자의 케이스·전사 조회 불가(§2.1).
7. 제한사항·문의 채널·변경이력
7.1 제한사항 (알고 쓰기)
| # | 제한 | 내용·근거 |
|---|---|---|
| L1 | 채널 목록 범위 | /videos 탭 기준 — 파일럿 실측 합계 711(채널 헤더 표기 725과 차이: /shorts 13 + 라이브 등 미포함·탭 범위 차이). 쇼츠·라이브 포함이 필요하면 범위 확장 별도 요청 [실측·파일럿 T8] |
| L2 | published_at 기본 공란 | flat-playlist 메타 한계 — fill_dates=true로 보완(상한 YT_DATE_FILL_MAX=50·요청당 소요 수십 초급 [실측·dev 50편 134.6s]) |
| L3 | 전사 취득 단가 | 최초 1회는 케이스 생성(다운로드+ASR)이 선행 — 영상당 수십 초~수분(실측: 80s 영상→67s·2282s 영상→92.7s, RTF 0.84~0.04) [실측·T7]. 이후 전사 조회는 캐시 읽기(~0.01s) |
| L4 | lang 감지 신뢰도 | lang_detected는 문자비율 추정 — lang_mismatch는 경고일 뿐 거부 아님 [실측·youtube_transcript.py:212-217] |
| L5 | 발화커버 | 파일럿 95.8~100% — 영상 시작·끝의 무음 구간은 미커버 정상 [실측·T7] |
| L6 | 배치 3종 prod 미노출 | §3.3 — 전량 획득은 문의 필요 |
| L7 | 블로그 외부 타깃 NA | §6.2 — external_api 확정 전까지 local_file 한정 |
| L8 | 블로그 draft 수정 불가 | 수정은 재등록 원칙(§3.4) — 게시 이력·해시 추적 단순화 목적 [계약·설계서 §3-3] |
| L9 | 블로그 인증 범위 | v1 내부망(LAN 바인딩) — 내부망 밖 노출 금지 [계약·G-B7] |
| L10 | 결정론 변환 문법 세트 | 블로그 변환기는 핵심+tables·fenced_code·codehilite — 수식·Mermaid 등은 NA(미지원 문법은 요청 시 별건 확장) [계약·설계서 §5 NA] |
7.2 문의 채널
| 주제 | 문의처 |
|---|---|
배치 3종 활성화(YT_BATCH_ENABLED=on)·일일 한도 상향·전수 범위 확장(쇼츠·라이브) | 운영자(사용자 승인 게이트 경유) — 요청서에 용도·규모·기간 명시 권장 [계약·설계서 §14 P6·G-B5] |
| 블로그 외부 API 어댑터 확정(엔드포인트·인증·할당량) | 위와 동일 — NA 해소 조건 3종(§6.2) 합의 문서 선행 |
| 기술 문의·결함 보고 | 설계서·구현 근거를 첨부하여 보고: 유튜브 1_type_regrex/docs/aiready_mcp/261117_유튜브채널전사_AIReadyMCP확장_상세설계서.md · 블로그 261117_블로그게시_별도MCP_상세설계서.md |
| 토큰 발급·갱신 | CREDENTIALS.md 관리 주체 — 평문은 해당 문서에서만 취득(§2.1) |
7.3 변경이력
| 일자 | 버전 | 내용 |
|---|---|---|
| 2026-11-17 (오전) | 파일럿 | T7 전사 E2E 3편(발화커버 95.8~100%)·T8 전수 페이징(711·토큰 소멸)·T9 레이트리밋(스로틀 27s·retry_after 120s) — 2종 도구 조건부 수용·D1(video_id 자동해석 공란) 발견 [실측·파일럿 판정문] |
| 2026-11-17 (오후) | dev 패치 | D1 수정(resolver 폴백 체인: 스템 프리픽스≥케이스메타≥MD 출처헤더 — 자동해석 3/3) · published_at 충전(fill_dates — 50/50=100%) · 배치 dedup 재검증(2회 런 skipped=3·재다운로드 0) · dev 승격(tools 67종) [실측·SESSION_LOG 잔여 3건 완결] |
| 2026-11-17 (17:5x) | stable-261117 승격 | §3.5.4 M4 승격(사용자 승인 bf562ea1a) — prod에 youtube 2종 노출·배치 3종 off 유지 확인(스모크 B)·전 컨테이너 재빌드·마이그레이션 145·check-image-deps exit 0 [실측·SESSION_LOG 승격 완결] |
| 2026-11-17 | 본 문서 | 외부 연동 가이드 최초 작성 (설계서 2종·구현 코드·파일럿 실측 근거 인용) |
부록 A. 파일럿 실측 근거 인덱스 (본 문서가 인용한 실측 목록)
| # | 실측값 | 근거 |
|---|---|---|
| 1 | T7 발화커버 95.8~100%·3편 세그먼트/문자/lang/duration_consistent | docs/aiready_mcp/261117_유튜브전사_파일럿실측/T7T8T9_파일럿판정_261117.md §T7 · t7_results.json |
| 2 | T8 페이징 711(4페이지 200+200+200+111)·토큰 소멸·캐시 페이지당 ~0.01s·제목 711/711·published_at 0/711 공란 | 동일 판정문 §T8 · t8_videos.json(711건 전문) |
| 3 | T9 스로틀 27.0s([0.0, 3.0×9])·rate_limited envelope retry_after_s:120·캐시 히트 평균 5.0ms·네트워크 0회 | 동일 판정문 §T9 |
| 4 | reason 실측(no_case·invalid_video_id·no_audio_stream)+5종 목업 37 PASS | 동일 판정문 수용기준 4항 |
| 5 | prod tools 64종+youtube 2종·배치 3종 미노출 / dev 67종 | SESSION_LOG 261117 승격 스모크 B |
| 6 | D1 자동해석 3/3·published_at 50/50·배치 skipped_dup(2회 런·skipped=3) | SESSION_LOG 261117 잔여 3건 완결 |
| 7 | confirm 게이트 조건식(confirm is True and type(confirm) is bool)·게이트 순서·부작용 0 | blog_publish_mcp/server/service/publish_service.py:154-256 |
| 8 | 에러 코드 9종·envelope 구조 | blog_publish_mcp/server/core/errors.py |
| 9 | 한도 10·킬스위치·마스킹(mask_secret 앞 3자리)·BLOG_TOKEN_* 존재 확인 | blog_publish_mcp/server/core/config.py |
| 10 | usage_note 상수·YT_RATE_INTERVAL_S=3·YT_DATE_FILL_MAX=50·TTL 21600 | ai_ready/src/format_parsers/youtube_channel_fetch.py:25-92 |
| 11 | 도구 2종 파라미터·반환·reason hints·배치 3종 docstring | ai_ready_mcp/server/tools/youtube_transcript.py (324줄 전문) |
| 12 | 블로그 도구 3종 등록·envelope·preview_url | blog_publish_mcp/server/tools/blog.py (130줄 전문) |
| 13 | :8770 바인딩·env 레버·healthcheck·docker_default | blog_publish_mcp/docker-compose.blog.yml |
| 14 | 연결 방식(initialize 세션 유지·SSE 파싱·Bearer) | 파일럿 mcp_client.py |