서버에 고정된 대상 폴더를 재귀적으로 훑어 파일 구조를 돌려줍니다.

폴더 분석의 출발점입니다. 각 항목의 allowed가 false이면 확장자 또는 크기 제한 때문에 다른 도구로 읽을 수 없다는 뜻이며, reason에 이유가 담깁니다.

Returns: ScanResponse: entries[]에 상대 경로·확장자·크기·수정 시각·허용 여부가 담기고, extension_counts에 확장자별 개수, truncated에 항목 수 제한으로 일부만 담겼는지 여부가 담깁니다.

Examples: - 사용: "이 폴더에 어떤 파일들이 있나요?" - 사용하지 않음: 이미 대상 파일을 알고 있고 원문이 필요할 때 → read_document_chunk

확장자·크기 제한을 통과한, 실제로 읽고 요약할 수 있는 문서 목록을 돌려줍니다.

여기서 얻은 relative_path를 다른 모든 도구에 그대로 넘깁니다.

Returns: DocumentListResponse: documents[]에 relative_path, 크기, 줄 수, 수정 시각이 담깁니다.

relative_path에 해당하는 문서 원문을 읽습니다.

긴 문서를 통째로 읽어 컨텍스트를 낭비하지 않도록 줄 범위를 지정할 수 있습니다.

Args: relative_path: 문서 상대 경로. start_line: 시작 줄(1부터). 기본 1. end_line: 끝 줄. 생략하면 끝까지. with_line_numbers: 줄 번호 접두사 부착 여부. 기본 True.

Returns: DocumentChunkResponse: content에 본문, total_lines에 전체 줄 수, truncated에 일부만 읽었는지 여부.

Raises: ToolFailure: DOCUMENT_NOT_FOUND / INVALID_PATH. 오류 메시지에 사용 가능한 relative_path 목록이 함께 담깁니다.

마크다운 헤딩, 번호 매김 항목, 전부 대문자 줄을 목차 후보로 추출합니다.

비정형 문서는 형식이 제각각이므로 규칙 기반 휴리스틱 세 가지를 함께 사용합니다. 결과에는 원문 줄 번호가 함께 담겨 근거로 쓸 수 있습니다.

Args: relative_path: 문서 상대 경로.

Returns: OutlineResponse: outline[]에 level, title, line이 담깁니다.

문서에서 날짜, 단위가 붙은 수치, 빈도 기반 핵심 용어 후보를 뽑습니다.

통계적 NLP가 아니라 정규식과 빈도 계산만 쓰는 결정적(deterministic) 추출이므로, 같은 문서에는 항상 같은 결과가 나옵니다.

Args: relative_path: 문서 상대 경로. max_terms: 분류별 최대 항목 수 (기본 20).

Returns: KeyTermsResponse: dates, numbers에 줄 번호와 원문이, frequent_terms에 용어·빈도가 담깁니다.

대상 폴더의 모든 문서와 표준 보고서 형식을 결합한 요약 프롬프트를 반환합니다.

이 MCP는 LLM API를 호출하지 않습니다. 요약은 호스트(Claude/Codex)가 하고, 이 도구는 '무엇을 어떤 형식으로 쓸지'에 대한 지시문과 원문 전체를 조립합니다.

Args: with_line_numbers: 원문 줄 번호 부착 및 인용 규칙 추가 여부 (기본 True).

Returns: PromptResponse: prompt에 규칙 + 필수 섹션 + 문서 목록 + 원문이 담긴 지시문.

요약 보고서 초안의 구조를 검사합니다. 저장 게이트입니다.

error가 하나라도 있으면 preview_save_report에서 승인 토큰이 발급되지 않습니다.

검사 항목: - error: H1 제목, 필수 섹션 5개(폴더 개요/파일 구조/문서별 요약/주요 키워드/확인 필요 사항) - warning: 섹션 순서, 자리표시자 잔존, 대상 폴더 표기 누락, 문서 경로 인용 누락

Args: report_markdown: 요약 보고서 초안 전문.

Returns: ValidationResponse: valid, error_count, warning_count, issues[](rule_id/severity/message/fix/line).

보고서에 언급된 파일명이 현재 폴더 스캔 결과에 실제로 있는지 대조합니다.

"문서에 없는 파일을 만들어 내지 않는다"는 규칙을 사람 눈 대신 기계가 확인합니다.

중요: 이 검사는 자문(advisory) 입니다. 휴리스틱이므로 오탐이 있을 수 있고, 저장을 막지 않습니다. 저장 게이트는 validate_report_draft(구조)와 사용자 승인입니다.

Args: report_markdown: 요약 보고서 초안 전문.

Returns: GroundingResponse: status(GROUNDED / MOSTLY_GROUNDED / NEEDS_EVIDENCE_REVIEW), score(0-100), findings[].

이미 저장된 보고서와 초안의 차이를 보여 줍니다.

같은 report_id로 두 번째 저장을 하면 기존 파일을 덮어씁니다. 무엇이 사라지는지 먼저 확인해 사고를 막는 용도입니다.

Args: report_id: 보고서 id. report_markdown: 초안 전문. diff_preview_lines: unified diff 미리보기 줄 수 (기본 40).

Returns: DiffResponse: diff.write_mode가 CREATE / OVERWRITE / NO_CHANGE 중 하나.

저장 대상·변경 내용·검증 결과를 한 번에 보여 주고 승인 토큰을 발급합니다.

저장 직전의 단일 관문입니다. 구조 검증을 통과했을 때만 approval_token이 발급되며, 토큰은 (report_id, 본문) 해시라서 승인받은 내용과 저장되는 내용이 달라질 수 없습니다.

토큰은 사용자 승인을 대신하지 않습니다. 응답의 approval_request를 사용자에게 그대로 보여 주고, 사용자가 명시적으로 승인한 뒤에만 save_approved_report를 호출하세요.

Args: report_id: 보고서 id. report_markdown: 저장할 보고서 전문. include_preview: 전문을 응답에 다시 담을지 여부 (기본 False). max_preview_chars: preview 최대 길이 (기본 4000).

Returns: PreviewResponse: status(AWAITING_APPROVAL / NEEDS_REVISION), approval_token, validation, diff, approval_request.

미리보기에서 발급된 승인 토큰이 일치할 때만 보고서를 파일로 저장합니다.

이 서버에서 유일한 쓰기 도구입니다. 호출 전 반드시 두 조건을 만족해야 합니다.

1. preview_save_report가 AWAITING_APPROVAL을 돌려주고 토큰을 발급했다.

2. 사용자가 그 내용을 보고 명시적으로 저장을 승인했다.

토큰은 기술적 무결성(승인한 내용 == 저장되는 내용)만 보장합니다. 사용자 승인을 대신하지 않습니다. 사용자가 "저장해"라고 말하지 않았다면 호출하지 마세요.

Args: report_id: 보고서 id. report_markdown: 저장할 보고서 전문. approval_token: 미리보기가 발급한 토큰. expected_write_mode: 선택. 지정하면 실제 write_mode와 다를 때 거부합니다.

Returns: SaveResponse: path(저장 경로), audit(감사 로그 경로), write_mode(CREATE / OVERWRITE / NO_CHANGE).

Raises: ToolFailure: TOKEN_MISMATCH, VALIDATION_FAILED, WRITE_MODE_CHANGED, INVALID_REPORT_ID. 모두 복구 방법이 메시지에 포함됩니다.

이미 저장된 요약 보고서 목록을 조회합니다.

같은 report_id로 저장하면 덮어쓰기가 되므로, 저장 전에 무엇이 있는지 확인하는 용도입니다.

Returns: SavedListResponse: saved[]에 report_id, 경로, 줄 수, 수정 시각(UTC), 내용 해시 앞 16자.

보고서 저장 감사 로그를 최신순으로 조회합니다.

AWAITING_APPROVAL → SAVED 흐름의 실행 증거를 확인할 때 사용합니다.

Args: limit: 최대 건수 (기본 20). report_id: 특정 보고서로 필터링 (선택).

Returns: AuditResponse: events[] 최신순.