신규 기능 외부 연동 가이드 — 유튜브 채널 전사 · 블로그 게시 (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)

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" 표]
토큰 SSOT1_type_regrex/docs/aiready_mcp/CREDENTIALS.md "발급 토큰(활성)" 표만이 평문 토큰의 단일 장소 — 타 문서·커밋·로그에 평문 기재 금지. 파일럿도 "토큰: unlimited-261019 (CREDENTIALS.md SSOT)" 방식으로 참조만 기록 [실측·파일럿 판정문 헤더]
과금도구별 포인트 정액(TOOL_COSTS) — 유튜브 전사는 케이스 산출물 재가공이므로 읽기 성격이나, 케이스 생성(create_case_from_url, 3P)에 전사 취득 원가(다운로드+ASR)가 과금된다. 전사·목록 도구 자체 과금은 운영 협의 항목 [계약·설계서 §10 "과금·정책 연동 [제안 — 운영 협의]"]
소유권 스코프토큰별 데이터 루트 격리 — 생성한 케이스·전사는 자기 데이터 루트에서만 조회

2.2 시크릿 취급 원칙 (양 서버 공통)

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: strnull, 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_limitedcache_expiredinvalid_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 상한)" }

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길이세그먼트발화커버문자langduration_consistent
tzmnr3mTibg80s2296.9% (77.5s)1,190entrue
vzlnRt_6TWA275s10595.8% (263.5s)3,097entrue
yhUsmXXp5Rw2282s595100.0% (2281.8s)32,535entrue

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

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: draftpublishednot_foundhash_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

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_casevideo_id에 해당 케이스 미존재create_case_from_url로 케이스 생성 후 재호출 (전사는 케이스 산출물에서 읽음 — 신규 취득 수행 안 함)
case_not_ready케이스 존재하나 MD 미생성(처리 진행·실패)처리 완료 후 재호출
asr_emptyMD 존재·영상_발화 세그먼트 0 (음성 없음·ASR 빈 결과)원영상 음성 유무 확인
no_audio_stream전사축이 없는 케이스(무음 영상 등)정상 종료 취급
invalid_video_id11자 패턴 불일치 또는 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]

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" + 해시 일치

5.2 해시 대사 (G-B3)

  1. create_draft 시점: 정규화 MD sha256 + 렌더 HTML sha256 산출·영속 [실측·publish_service.py:99-100].
  2. publish 시점: 디스크의 body.md를 재계산해 원장 해시와 비교 — 불일치 시 hash_mismatch 거부(등록 후 무단 변조 차단) [실측·publish_service.py:197-210].
  3. 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_requiredpublish confirm 미지정/오값false
draft_not_founddraft_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_mismatchpublish 시점 본문 대사 실패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_apiNA게시 API 미확정 — "인터페이스만 정의·목업 유지·실연동 0(target_unavailable 고정)". 해소 조건: ①API 엔드포인트·payload 계약 ②인증 방식 ③할당량 정책이 사용자 합의 문서로 확정된 뒤 구현 착수

→ 외부 연동자는 현재 local_file 타깃 한정으로 간주한다. 외부 블로그 플랫폼 연동은 문의 필요(§7.2).

6.3 레버·prod 상태 (stable-261117 기준)

레버prod 상태효과 [계약·설계서 §13]
YT_CHANNEL_TOOLSon — 2종 노출 [실측·승격 스모크 B]off 시 유튜브 2종 tools/list 소멸 — 롤백 레버
YT_BATCH_ENABLEDoff — 배치 3종 미노출 [실측·동일]on 시 배치 3종 추가. 활성화는 사용자 승인 게이트 — 문의 필요
YT_RATE_INTERVAL_S3 (단일·기본)스로틀 간격
YT_CHANNEL_CACHE_TTL_S21600 (6h)0=캐시 비활성
YT_DATE_FILL_MAX50fill_dates 상세조회 상한
BLOG_PUBLISH_ENABLEDonoff 시 publish 전면 거부
BLOG_DAILY_LIMIT10일일 게시 한도 — 상향은 사용자 합의
BLOG_TARGETlocal_filemock 전환 시 외부 부작용 0

6.4 데이터 격리·감사


7. 제한사항·문의 채널·변경이력

7.1 제한사항 (알고 쓰기)

#제한내용·근거
L1채널 목록 범위/videos 탭 기준 — 파일럿 실측 합계 711(채널 헤더 표기 725과 차이: /shorts 13 + 라이브 등 미포함·탭 범위 차이). 쇼츠·라이브 포함이 필요하면 범위 확장 별도 요청 [실측·파일럿 T8]
L2published_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)
L4lang 감지 신뢰도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. 파일럿 실측 근거 인덱스 (본 문서가 인용한 실측 목록)

#실측값근거
1T7 발화커버 95.8~100%·3편 세그먼트/문자/lang/duration_consistentdocs/aiready_mcp/261117_유튜브전사_파일럿실측/T7T8T9_파일럿판정_261117.md §T7 · t7_results.json
2T8 페이징 711(4페이지 200+200+200+111)·토큰 소멸·캐시 페이지당 ~0.01s·제목 711/711·published_at 0/711 공란동일 판정문 §T8 · t8_videos.json(711건 전문)
3T9 스로틀 27.0s([0.0, 3.0×9])·rate_limited envelope retry_after_s:120·캐시 히트 평균 5.0ms·네트워크 0회동일 판정문 §T9
4reason 실측(no_case·invalid_video_id·no_audio_stream)+5종 목업 37 PASS동일 판정문 수용기준 4항
5prod tools 64종+youtube 2종·배치 3종 미노출 / dev 67종SESSION_LOG 261117 승격 스모크 B
6D1 자동해석 3/3·published_at 50/50·배치 skipped_dup(2회 런·skipped=3)SESSION_LOG 261117 잔여 3건 완결
7confirm 게이트 조건식(confirm is True and type(confirm) is bool)·게이트 순서·부작용 0blog_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
10usage_note 상수·YT_RATE_INTERVAL_S=3·YT_DATE_FILL_MAX=50·TTL 21600ai_ready/src/format_parsers/youtube_channel_fetch.py:25-92
11도구 2종 파라미터·반환·reason hints·배치 3종 docstringai_ready_mcp/server/tools/youtube_transcript.py (324줄 전문)
12블로그 도구 3종 등록·envelope·preview_urlblog_publish_mcp/server/tools/blog.py (130줄 전문)
13:8770 바인딩·env 레버·healthcheck·docker_defaultblog_publish_mcp/docker-compose.blog.yml
14연결 방식(initialize 세션 유지·SSE 파싱·Bearer)파일럿 mcp_client.py