MCP 능력 완결 — 세션 조회 파리티: hwp_doc_structure·hwp_doc_extract_data (에이전트 기본 도구 축) - #4858
Closed
kevin9327 wants to merge 1 commit into
Closed
MCP 능력 완결 — 세션 조회 파리티: hwp_doc_structure·hwp_doc_extract_data (에이전트 기본 도구 축)#4858kevin9327 wants to merge 1 commit into
kevin9327 wants to merge 1 commit into
Conversation
…ardkim#4856) 무상태 MCP 표면은 capabilities_mcp_covers_every_json_command 계약으로 모든 --json 명령이 도구로 노출됨이 보장되지만, 세션 표면(hwp_doc_*)에는 개요·조문 구조와 날짜·금액·수량 추출 축이 빠져 있었다. 세션으로 대형 문서를 한 번 열어 반복 조회하는 에이전트가 이 둘을 쓰려면 무상태 도구로 되돌아가 파일을 다시 읽고 재파싱해야 했다 — 세션의 존재 이유(재파싱 회피)를 무효화한다. - hwp_doc_structure: 열린 핸들의 개요/조문 계층. 무상태 export-structure 와 같은 코어(build_structure)·봉투(structure_json_value) 재사용 → 봉투 동형(source=docId). - hwp_doc_extract_data: 열린 핸들의 날짜·금액·수량. 무상태 extract-data 와 같은 코어(extract_data)·봉투(extract_data_json_value) 재사용 → raw/normalized·주소· totalItemCount/truncated(S7) 동형. kind·limit 인자, 전수 스캔 후 표시만 절단. 두 도구 모두 읽기 전용·멱등. tools/list↔tools/call 게이팅 동형을 위해 이름을 ALL_SESSION_TOOLS/SESSION_READ_TOOLS 단일 출처에 등재했고, 인접 조회 도구 (hwp_doc_info/fields/tables) 설명을 '언제 쓰나 / 봉투 모양 / 오류 회복' 3요소로 폴리시했다. 검증: cargo build; cargo test --lib(3702 pass); mcp 통합 13파일 전부 pass; cli_json_contract·spec_ledger·annotations(세션 수 16→18) green; 살아있는 mcp-serve 로 initialize→tools/list→tools/call 왕복 실증(양 도구 listed+callable, 봉투 동형·S7 절단 확인); rustfmt --check·clippy clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Collaborator
|
통합 PR #4883(4412546)로 병합 완료했습니다. 원 head와 CI를 다시 확인해 누적 반영했고, 상세 검토·메인터너 보정·검증 근거는 archive 검토 기록에 남겼습니다. 중복 병합을 막기 위해 이 원 PR을 닫습니다. 감사합니다. |
Collaborator
|
통합 PR #4883(4412546)로 병합 완료했습니다. 원 head와 CI를 다시 확인해 누적 반영했고, 상세 검토·메인터너 보정·검증 근거는 archive 검토 기록에 남겼습니다. 중복 병합을 막기 위해 이 원 PR을 닫습니다. 감사합니다. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
무엇을 — 에이전트 기본 도구 축, 세션 표면 완결
MCP 는 에이전트가 rhwp 에 붙는 표준 경로다. "붙는 즉시 rhwp 의 전 능력을 얻는다"가 목표이고, 이는 두 표면 각각에서 성립해야 한다.
capabilities_mcp_covers_every_json_command(tests/cli_json_contract.rs)가 모든--json명령의 MCP 노출을 기계 강제한다(제외는capabilities자신·진단dump-pages뿐).hwp_doc_*, 재파싱 없이 열린 핸들 반복 조회)에는 두 고빈도 조회 축이 빠져 있었다 → 이 PR 이 채운다.Fixes #4856.
새로 노출한 MCP 도구 (2)
hwp_doc_structureexport-structure로 되돌아가 파일 재파싱이 필요했다.hwp_doc_tree(안정 노드 ID)와 달리 의미 계층이다.hwp_doc_extract_dataraw+normalized(ISO-8601·정수),totalItemCount/truncated(S7 컨텍스트 절약)까지 동형.두 도구는 읽기 전용·멱등이고, 각각 무상태 판과 같은 코어·같은 봉투 helper 를 재사용한다(
build_structure+structure_json_value,extract_data+extract_data_json_value) — 세션 판과 무상태 판이 같은 문서에서 같은 값을 낸다(source자리에만 경로 대신 docId). 인자 오타(mode/kind)는 조용히 기본값으로 되돌아가지 않고isError로 거부한다.설명 폴리시
인접 세션 조회 도구
hwp_doc_info/hwp_doc_fields/hwp_doc_tables설명을 "언제 쓰나 / 봉투 모양 / 오류 회복(nextCall)" 3요소로 보강했다.불변식
tools/list↔tools/call게이팅 동형(목록에 없으면 호출 불가): 새 이름을agent_profiles::ALL_SESSION_TOOLS/SESSION_READ_TOOLS단일 출처에 등재 →아카이브검색·개발통합프로필이 자동 포함, 조회 전용 프로필도 안전.mcp_spec_ledger계약은 프로토콜 메서드 대장이라 도구 추가와 무관(green 유지, 대장 수정 불필요).mcp_tool_annotations_contract): 세션 도구 수 16→18, 두 도구 read-only·non-destructive·idempotent 판정 추가.검증
cargo build --bin rhwpOK.cargo test --lib— 3702 pass, 0 fail.mcp_server_contract25,mcp_session_query_contract6,mcp_tool_annotations_contract5 …) + 신규mcp_session_structure_extract_contract6 pass.cli_json_contract(31),agent_profile_router_contract(8),mcp_spec_ledger_contract(4).rhwp mcp-serve에initialize→tools/list→hwp_open→tools/call을 stdio JSON-RPC 로 왕복:tools/list에 나오고(listed)tools/call로 불린다(callable).hwp_doc_structure(mode=outline) →{mode:"outline", nodeCount, source:"doc-1", structure:{…}}(경로 아닌 핸들).hwp_doc_extract_data(kind=number, limit=3) →itemCount:3·totalItemCount:11·truncated:true(전수 스캔 후 표시만 절단).rustfmt --edition 2021 --check(변경 leaf 파일 전부) exit 0 ·cargo clippy --bin rhwpclean.