document-adapter 0.1.0__py3-none-any.whl

document_adapter/__init__.py

@@ -0,0 +1,45 @@
+"""Document template editing — 통합 어댑터.
+
+사용법:
+    from document_adapter import load
+    doc = load("report.docx")
+    schema = doc.get_schema()
+    doc.set_cell(0, 1, 1, "홍길동")
+    doc.save("report_filled.docx")
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .base import DocumentAdapter, DocumentSchema, TableSchema
+from .docx_adapter import DocxAdapter
+from .hwpx_adapter import HwpxAdapter
+from .pptx_adapter import PptxAdapter
+
+__all__ = [
+    "load",
+    "DocumentAdapter",
+    "DocumentSchema",
+    "TableSchema",
+    "DocxAdapter",
+    "PptxAdapter",
+    "HwpxAdapter",
+]
+
+_ADAPTERS: dict[str, type[DocumentAdapter]] = {
+    ".docx": DocxAdapter,
+    ".pptx": PptxAdapter,
+    ".hwpx": HwpxAdapter,
+}
+
+
+def load(path: str | Path) -> DocumentAdapter:
+    """확장자로 적절한 어댑터를 선택해 문서를 연다."""
+    p = Path(path)
+    suffix = p.suffix.lower()
+    cls = _ADAPTERS.get(suffix)
+    if cls is None:
+        raise ValueError(
+            f"지원하지 않는 포맷: {suffix}. 지원: {sorted(_ADAPTERS.keys())}"
+        )
+    return cls(p)

document_adapter/base.py

@@ -0,0 +1,108 @@
+"""DocumentAdapter 공통 인터페이스.
+
+세 포맷(DOCX/PPTX/HWPX)의 공통 작업을 추상화:
+- 템플릿 렌더링 ({{key}} 치환)
+- 표 스키마 추출 (LLM 입력용)
+- 셀 수정 / 행 추가
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class TableSchema:
+    """표 한 개의 구조 (LLM에게 넘길 형태)."""
+    index: int
+    rows: int
+    cols: int
+    preview: list[list[str]]
+    location: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "index": self.index,
+            "rows": self.rows,
+            "cols": self.cols,
+            "location": self.location,
+            "preview": self.preview,
+        }
+
+
+@dataclass
+class DocumentSchema:
+    """문서 전체 스키마."""
+    format: str
+    source: str
+    placeholders: list[str] = field(default_factory=list)
+    tables: list[TableSchema] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "format": self.format,
+            "source": self.source,
+            "placeholders": self.placeholders,
+            "tables": [t.to_dict() for t in self.tables],
+        }
+
+
+class DocumentAdapter(ABC):
+    """모든 포맷 어댑터의 공통 부모."""
+
+    format: str = ""
+
+    def __init__(self, path: Path) -> None:
+        self.path = Path(path)
+        self._open()
+
+    # ---- lifecycle ----
+    @abstractmethod
+    def _open(self) -> None: ...
+
+    @abstractmethod
+    def save(self, path: Path | str | None = None) -> Path: ...
+
+    def close(self) -> None:
+        """일부 포맷(HWPX)은 명시적 close 필요."""
+        pass
+
+    # ---- inspection ----
+    @abstractmethod
+    def get_placeholders(self) -> list[str]:
+        """본문에서 사용된 {{key}} 목록 반환."""
+
+    @abstractmethod
+    def get_tables(self, min_rows: int = 1, min_cols: int = 1,
+                   preview_rows: int = 4, max_cell_len: int = 40) -> list[TableSchema]:
+        """필터 조건을 만족하는 표 스키마 목록."""
+
+    def get_schema(self) -> DocumentSchema:
+        return DocumentSchema(
+            format=self.format,
+            source=str(self.path),
+            placeholders=self.get_placeholders(),
+            tables=self.get_tables(),
+        )
+
+    # ---- editing ----
+    @abstractmethod
+    def render_template(self, context: dict[str, Any]) -> None:
+        """템플릿의 {{key}}를 context 값으로 치환."""
+
+    @abstractmethod
+    def set_cell(self, table_index: int, row: int, col: int, value: str) -> str:
+        """셀 값 교체. 원래 값 반환."""
+
+    @abstractmethod
+    def append_row(self, table_index: int, values: list[str]) -> None:
+        """표 끝에 새 행 추가."""
+
+    # ---- context manager ----
+    def __enter__(self) -> "DocumentAdapter":
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        self.close()

document_adapter/docx_adapter.py

@@ -0,0 +1,75 @@
+"""DOCX 어댑터: python-docx (편집) + docxtpl (템플릿 렌더)."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from docx import Document
+from docxtpl import DocxTemplate
+
+from .base import DocumentAdapter, TableSchema
+
+TAG_PATTERN = re.compile(r"\{\{\s*(\w+)\s*\}\}")
+
+
+class DocxAdapter(DocumentAdapter):
+    format = "docx"
+
+    def _open(self) -> None:
+        self._doc = Document(self.path)
+
+    def save(self, path: Path | str | None = None) -> Path:
+        target = Path(path) if path else self.path
+        self._doc.save(target)
+        self.path = target
+        return target
+
+    # ---- inspection ----
+    def get_placeholders(self) -> list[str]:
+        keys: set[str] = set()
+        for p in self._doc.paragraphs:
+            keys.update(TAG_PATTERN.findall(p.text))
+        for table in self._doc.tables:
+            for row in table.rows:
+                for cell in row.cells:
+                    keys.update(TAG_PATTERN.findall(cell.text))
+        return sorted(keys)
+
+    def get_tables(self, min_rows: int = 1, min_cols: int = 1,
+                   preview_rows: int = 4, max_cell_len: int = 40) -> list[TableSchema]:
+        schemas: list[TableSchema] = []
+        for i, t in enumerate(self._doc.tables):
+            rows, cols = len(t.rows), len(t.columns)
+            if rows < min_rows or cols < min_cols:
+                continue
+            preview: list[list[str]] = []
+            for row in list(t.rows)[:preview_rows]:
+                preview.append([c.text.strip()[:max_cell_len] for c in row.cells])
+            schemas.append(TableSchema(index=i, rows=rows, cols=cols, preview=preview))
+        return schemas
+
+    # ---- editing ----
+    def render_template(self, context: dict[str, Any]) -> None:
+        """docxtpl 기반 Jinja2 렌더. 참고:
+        - `{%tr for row in rows %}` / `{%tr endfor %}`는 **각각 별도 행**에 두어야 함
+        - 같은 행에 두면 `<w:tr>` 전체가 `{% for %}`로 교체되어 endfor 손실
+        """
+        tpl = DocxTemplate(self.path)
+        tpl.render(context)
+        tpl.save(self.path)
+        # 렌더 후 _doc 재로드
+        self._doc = Document(self.path)
+
+    def set_cell(self, table_index: int, row: int, col: int, value: str) -> str:
+        cell = self._doc.tables[table_index].rows[row].cells[col]
+        old = cell.text
+        cell.text = value
+        return old
+
+    def append_row(self, table_index: int, values: list[str]) -> None:
+        table = self._doc.tables[table_index]
+        new_row = table.add_row()
+        for i, v in enumerate(values):
+            if i < len(new_row.cells):
+                new_row.cells[i].text = v

document_adapter/hwpx_adapter.py

@@ -0,0 +1,126 @@
+"""HWPX 어댑터: python-hwpx 기반.
+
+버그 회피:
+- set_cell_text()는 빈 셀에서 lxml/ElementTree 혼용 에러가 발생 (v2.9.0) →
+  cell.paragraphs[0].text 직접 할당으로 우회
+- replace_text_in_runs()는 한글 공백이 run으로 쪼개질 때 매칭 실패 →
+  위치 기반 편집을 권장
+
+부가:
+- manifest fallback 로그가 기본적으로 매우 시끄러움 → logging 레벨 조정
+"""
+from __future__ import annotations
+
+import logging
+import re
+from pathlib import Path
+from typing import Any, Iterator
+
+# 경고성 로그 억제 (manifest fallback 등)
+logging.getLogger("hwpx").setLevel(logging.ERROR)
+
+from hwpx.document import HwpxDocument
+
+from .base import DocumentAdapter, TableSchema
+
+TAG_PATTERN = re.compile(r"\{\{\s*(\w+)\s*\}\}")
+
+
+class HwpxAdapter(DocumentAdapter):
+    format = "hwpx"
+
+    def _open(self) -> None:
+        self._doc = HwpxDocument.open(self.path)
+
+    def save(self, path: Path | str | None = None) -> Path:
+        target = Path(path) if path else self.path
+        self._doc.save_to_path(target)
+        self.path = target
+        return target
+
+    def close(self) -> None:
+        self._doc.close()
+
+    # ---- helpers ----
+    def _iter_tables(self) -> Iterator[tuple[int, Any]]:
+        idx = 0
+        for section in self._doc.sections:
+            for para in section.paragraphs:
+                for tbl in para.tables:
+                    yield idx, tbl
+                    idx += 1
+
+    def _get_table(self, table_index: int):
+        for idx, tbl in self._iter_tables():
+            if idx == table_index:
+                return tbl
+        raise IndexError(f"HWPX table index {table_index} not found")
+
+    @staticmethod
+    def _cell_text(cell) -> str:
+        return " ".join(p.text for p in cell.paragraphs).strip()
+
+    # ---- inspection ----
+    def get_placeholders(self) -> list[str]:
+        text = self._doc.export_text()
+        return sorted(set(TAG_PATTERN.findall(text)))
+
+    def get_tables(self, min_rows: int = 1, min_cols: int = 1,
+                   preview_rows: int = 4, max_cell_len: int = 40) -> list[TableSchema]:
+        schemas: list[TableSchema] = []
+        for idx, tbl in self._iter_tables():
+            rows, cols = tbl.row_count, tbl.column_count
+            if rows < min_rows or cols < min_cols:
+                continue
+            preview: list[list[str]] = []
+            for r in range(min(rows, preview_rows)):
+                row_cells = []
+                for c in range(cols):
+                    text = self._cell_text(tbl.cell(r, c))
+                    row_cells.append(text[:max_cell_len])
+                preview.append(row_cells)
+            schemas.append(TableSchema(index=idx, rows=rows, cols=cols, preview=preview))
+        return schemas
+
+    # ---- editing ----
+    def render_template(self, context: dict[str, Any]) -> None:
+        """본문 + 표 셀의 {{key}}를 paragraph 단위로 치환."""
+        # 본문
+        for section in self._doc.sections:
+            for para in section.paragraphs:
+                text = para.text
+                if TAG_PATTERN.search(text):
+                    para.text = TAG_PATTERN.sub(
+                        lambda m: str(context.get(m.group(1), m.group(0))), text
+                    )
+        # 표 셀
+        for _, tbl in self._iter_tables():
+            for r in range(tbl.row_count):
+                for c in range(tbl.column_count):
+                    cell = tbl.cell(r, c)
+                    for para in cell.paragraphs:
+                        text = para.text
+                        if TAG_PATTERN.search(text):
+                            para.text = TAG_PATTERN.sub(
+                                lambda m: str(context.get(m.group(1), m.group(0))), text
+                            )
+
+    def set_cell(self, table_index: int, row: int, col: int, value: str) -> str:
+        """set_cell_text 버그 우회: paragraph.text 직접 할당."""
+        tbl = self._get_table(table_index)
+        cell = tbl.cell(row, col)
+        paragraphs = list(cell.paragraphs)
+        old = self._cell_text(cell)
+        if paragraphs:
+            paragraphs[0].text = value
+            for p in paragraphs[1:]:
+                p.text = ""
+        return old
+
+    def append_row(self, table_index: int, values: list[str]) -> None:
+        """python-hwpx에는 표준 add_row API가 없음.
+        대안: 템플릿에 충분한 빈 행을 미리 만들고 set_cell로 채우는 전략."""
+        raise NotImplementedError(
+            "HWPX는 python-hwpx에 동적 행 추가 공식 API가 없음. "
+            "템플릿에 여분 행을 두고 set_cell로 채우는 방식을 권장."
+        )

document_adapter/mcp_server.py

@@ -0,0 +1,64 @@
+"""MCP stdio server — Claude Desktop/Code에서 document-adapter tool을 호출하게 해준다.
+
+실행:
+    python -m document_adapter.mcp_server
+
+Claude Desktop 설정 예시 (~/Library/Application Support/Claude/claude_desktop_config.json):
+{
+  "mcpServers": {
+    "document-adapter": {
+      "command": "/path/to/venv/bin/python",
+      "args": ["-m", "document_adapter.mcp_server"]
+    }
+  }
+}
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+from mcp.types import TextContent, Tool
+
+from .tools import TOOL_DEFINITIONS, call_tool
+
+logging.basicConfig(level=logging.INFO)
+log = logging.getLogger("document-adapter-mcp")
+
+server: Server = Server("document-adapter")
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    return [
+        Tool(
+            name=t["name"],
+            description=t["description"],
+            inputSchema=t["input_schema"],
+        )
+        for t in TOOL_DEFINITIONS
+    ]
+
+
+@server.call_tool()
+async def on_call_tool(name: str, arguments: dict) -> list[TextContent]:
+    log.info("tool call: %s %s", name, list(arguments.keys()))
+    result = call_tool(name, arguments)
+    return [TextContent(type="text", text=json.dumps(result, ensure_ascii=False, indent=2))]
+
+
+async def main() -> None:
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())
+
+
+def main_sync() -> None:
+    """Console script entry point."""
+    asyncio.run(main())
+
+
+if __name__ == "__main__":
+    main_sync()

document_adapter/pptx_adapter.py

@@ -0,0 +1,109 @@
+"""PPTX 어댑터: python-pptx + 자체 {{key}} 치환 엔진."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Iterator
+
+from pptx import Presentation
+from pptx.slide import Slide
+
+from .base import DocumentAdapter, TableSchema
+
+TAG_PATTERN = re.compile(r"\{\{\s*(\w+)\s*\}\}")
+
+
+class PptxAdapter(DocumentAdapter):
+    format = "pptx"
+
+    def _open(self) -> None:
+        self._prs = Presentation(self.path)
+
+    def save(self, path: Path | str | None = None) -> Path:
+        target = Path(path) if path else self.path
+        self._prs.save(target)
+        self.path = target
+        return target
+
+    # ---- helpers ----
+    def _iter_tables(self) -> Iterator[tuple[int, int, Any]]:
+        """(global_index, slide_number_1based, table) 순회."""
+        g_idx = 0
+        for s_idx, slide in enumerate(self._prs.slides, 1):
+            for shape in slide.shapes:
+                if shape.has_table:
+                    yield g_idx, s_idx, shape.table
+                    g_idx += 1
+
+    def _iter_text_frames(self) -> Iterator[Any]:
+        for slide in self._prs.slides:
+            for shape in slide.shapes:
+                if shape.has_text_frame:
+                    yield shape.text_frame
+                if shape.has_table:
+                    for row in shape.table.rows:
+                        for cell in row.cells:
+                            yield cell.text_frame
+
+    # ---- inspection ----
+    def get_placeholders(self) -> list[str]:
+        keys: set[str] = set()
+        for tf in self._iter_text_frames():
+            keys.update(TAG_PATTERN.findall(tf.text))
+        return sorted(keys)
+
+    def get_tables(self, min_rows: int = 1, min_cols: int = 1,
+                   preview_rows: int = 4, max_cell_len: int = 40) -> list[TableSchema]:
+        schemas: list[TableSchema] = []
+        for g_idx, s_idx, table in self._iter_tables():
+            rows = list(table.rows)
+            cols = list(table.columns)
+            if len(rows) < min_rows or len(cols) < min_cols:
+                continue
+            preview: list[list[str]] = []
+            for row in rows[:preview_rows]:
+                preview.append([c.text.strip()[:max_cell_len] for c in row.cells])
+            schemas.append(TableSchema(
+                index=g_idx, rows=len(rows), cols=len(cols),
+                preview=preview, location=f"slide {s_idx}",
+            ))
+        return schemas
+
+    # ---- editing ----
+    def render_template(self, context: dict[str, Any]) -> None:
+        """paragraph 단위로 {{key}}를 치환. run이 쪼개진 경우를 처리하기 위해
+        paragraph 전체 텍스트를 재조립 후 첫 run에 담는다 (서식 일부 손실 가능)."""
+        for tf in self._iter_text_frames():
+            for para in tf.paragraphs:
+                full_text = "".join(run.text for run in para.runs)
+                if not TAG_PATTERN.search(full_text):
+                    continue
+                rendered = TAG_PATTERN.sub(
+                    lambda m: str(context.get(m.group(1), m.group(0))),
+                    full_text,
+                )
+                if para.runs:
+                    para.runs[0].text = rendered
+                    for run in para.runs[1:]:
+                        run.text = ""
+
+    def _get_table(self, table_index: int):
+        for g_idx, _, table in self._iter_tables():
+            if g_idx == table_index:
+                return table
+        raise IndexError(f"PPTX table index {table_index} not found")
+
+    def set_cell(self, table_index: int, row: int, col: int, value: str) -> str:
+        table = self._get_table(table_index)
+        cell = table.cell(row, col)
+        old = cell.text
+        cell.text = value
+        return old
+
+    def append_row(self, table_index: int, values: list[str]) -> None:
+        """python-pptx는 표 행 추가 API를 제공하지 않는다.
+        LLM에게는 '지원 안 함'으로 알리는 게 정직한 방식."""
+        raise NotImplementedError(
+            "PPTX는 python-pptx에 동적 행 추가 API가 없음. "
+            "템플릿 단계에서 충분한 빈 행을 만들어 두고 set_cell로 채우는 방식을 권장."
+        )

document_adapter/tools.py

@@ -0,0 +1,232 @@
+"""LLM tool 정의 + 실행 함수.
+
+동일 구현을 MCP 서버와 Claude API Tool Use 양쪽에서 재사용한다.
+각 함수는 JSON-serializable dict를 반환.
+"""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from . import load
+
+# -------- JSON schemas (Claude API tool use와 MCP 공용) --------
+
+TOOL_DEFINITIONS: list[dict[str, Any]] = [
+    {
+        "name": "inspect_document",
+        "description": (
+            "문서(.docx/.pptx/.hwpx)의 구조를 분석한다. "
+            "placeholders({{key}} 태그 목록)와 tables(각 표의 행/열/미리보기)를 반환한다. "
+            "LLM이 어떤 필드를 채우거나 수정할지 판단할 때 먼저 호출해야 한다."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": "문서 절대경로",
+                },
+                "min_rows": {
+                    "type": "integer",
+                    "description": "표 필터: 최소 행 수 (기본 1)",
+                    "default": 1,
+                },
+                "min_cols": {
+                    "type": "integer",
+                    "description": "표 필터: 최소 열 수 (기본 1)",
+                    "default": 1,
+                },
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "render_template",
+        "description": (
+            "문서의 {{key}} placeholder를 context의 값으로 치환해 새 파일로 저장한다. "
+            "DOCX는 docxtpl(Jinja2 loop/if 지원), PPTX/HWPX는 단순 {{key}} 치환."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "템플릿 파일 경로"},
+                "context": {
+                    "type": "object",
+                    "description": "{{key}}에 주입할 값 dict",
+                    "additionalProperties": True,
+                },
+                "output_path": {
+                    "type": "string",
+                    "description": "결과 저장 경로 (생략 시 원본 옆에 _rendered 붙여 저장)",
+                },
+            },
+            "required": ["path", "context"],
+        },
+    },
+    {
+        "name": "set_cell",
+        "description": (
+            "특정 표의 셀 값을 교체한다. table_index는 inspect_document의 tables 배열 인덱스. "
+            "PPTX는 슬라이드 경계와 무관한 전역 index."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "table_index": {"type": "integer"},
+                "row": {"type": "integer"},
+                "col": {"type": "integer"},
+                "value": {"type": "string"},
+                "output_path": {
+                    "type": "string",
+                    "description": "생략 시 원본 덮어쓰기",
+                },
+            },
+            "required": ["path", "table_index", "row", "col", "value"],
+        },
+    },
+    {
+        "name": "append_row",
+        "description": (
+            "표 끝에 새 행을 추가한다. **DOCX만 지원** — PPTX/HWPX는 API 미지원으로 에러 반환. "
+            "그 경우 템플릿 단계에서 충분한 빈 행을 두고 set_cell로 채워야 한다."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "table_index": {"type": "integer"},
+                "values": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "새 행의 각 셀 값. 열 수보다 적으면 나머지는 공백.",
+                },
+                "output_path": {"type": "string"},
+            },
+            "required": ["path", "table_index", "values"],
+        },
+    },
+]
+
+
+# -------- 실행 함수 --------
+
+def _resolve_output(path: str, output_path: str | None, suffix: str = "_out") -> Path:
+    if output_path:
+        return Path(output_path)
+    p = Path(path)
+    return p.with_name(f"{p.stem}{suffix}{p.suffix}")
+
+
+def inspect_document(path: str, min_rows: int = 1, min_cols: int = 1) -> dict[str, Any]:
+    doc = load(path)
+    try:
+        schema = doc.get_schema()
+        # min_rows/min_cols 필터 재적용
+        filtered = [t for t in doc.get_tables(min_rows=min_rows, min_cols=min_cols)]
+        result = schema.to_dict()
+        result["tables"] = [t.to_dict() for t in filtered]
+        return result
+    finally:
+        doc.close()
+
+
+def render_template(path: str, context: dict[str, Any],
+                    output_path: str | None = None) -> dict[str, Any]:
+    out = _resolve_output(path, output_path, "_rendered")
+    shutil.copy2(path, out)
+
+    doc = load(out)
+    try:
+        before = doc.get_placeholders()
+        doc.render_template(context)
+        doc.save()
+    finally:
+        doc.close()
+
+    # 검증 재로드
+    doc2 = load(out)
+    try:
+        after = doc2.get_placeholders()
+    finally:
+        doc2.close()
+
+    return {
+        "output_path": str(out),
+        "placeholders_before": before,
+        "placeholders_after": after,
+        "rendered_count": len(before) - len(after),
+    }
+
+
+def set_cell(path: str, table_index: int, row: int, col: int, value: str,
+             output_path: str | None = None) -> dict[str, Any]:
+    target = Path(output_path) if output_path else Path(path)
+    if output_path and Path(path) != target:
+        shutil.copy2(path, target)
+
+    doc = load(target)
+    try:
+        old = doc.set_cell(table_index, row, col, value)
+        doc.save()
+    finally:
+        doc.close()
+
+    return {
+        "output_path": str(target),
+        "table_index": table_index,
+        "row": row,
+        "col": col,
+        "previous_value": old,
+        "new_value": value,
+    }
+
+
+def append_row(path: str, table_index: int, values: list[str],
+               output_path: str | None = None) -> dict[str, Any]:
+    target = Path(output_path) if output_path else Path(path)
+    if output_path and Path(path) != target:
+        shutil.copy2(path, target)
+
+    doc = load(target)
+    try:
+        doc.append_row(table_index, values)
+        doc.save()
+        new_tables = doc.get_tables()
+    finally:
+        doc.close()
+
+    target_schema = next((t for t in new_tables if t.index == table_index), None)
+    return {
+        "output_path": str(target),
+        "table_index": table_index,
+        "new_row_count": target_schema.rows if target_schema else None,
+        "appended_values": values,
+    }
+
+
+# -------- 이름으로 dispatch --------
+
+TOOL_HANDLERS = {
+    "inspect_document": inspect_document,
+    "render_template": render_template,
+    "set_cell": set_cell,
+    "append_row": append_row,
+}
+
+
+def call_tool(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    """이름으로 tool 실행. 예외도 dict로 직렬화."""
+    handler = TOOL_HANDLERS.get(name)
+    if handler is None:
+        return {"error": f"unknown tool: {name}"}
+    try:
+        return handler(**arguments)
+    except NotImplementedError as e:
+        return {"error": "not_implemented", "message": str(e)}
+    except (IndexError, ValueError, FileNotFoundError) as e:
+        return {"error": type(e).__name__, "message": str(e)}
+    except Exception as e:
+        return {"error": "unexpected", "type": type(e).__name__, "message": str(e)}

document_adapter-0.1.0.dist-info/METADATA

@@ -0,0 +1,252 @@
+Metadata-Version: 2.4
+Name: document-adapter
+Version: 0.1.0
+Summary: LLM-friendly document template editing (DOCX/PPTX/HWPX) with MCP server and Claude API tool-use support
+Author-email: Son Seongjun <sonsj97@plateer.com>
+License: MIT
+Project-URL: Homepage, https://github.com/PlateerLab/document-adapter
+Project-URL: Repository, https://github.com/PlateerLab/document-adapter
+Keywords: mcp,llm,document,docx,pptx,hwpx,template,claude
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-docx>=1.1
+Requires-Dist: docxtpl>=0.20
+Requires-Dist: python-pptx>=1.0
+Requires-Dist: python-hwpx>=2.9
+Requires-Dist: mcp>=1.0
+Provides-Extra: claude
+Requires-Dist: anthropic>=0.40; extra == "claude"
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# document-adapter
+
+**LLM이 DOCX / PPTX / HWPX 문서를 직접 편집할 수 있게 해주는 통합 어댑터 + MCP 서버.**
+
+세 가지 오피스 포맷을 하나의 파이썬 인터페이스로 추상화하고, Claude Desktop / Claude Code / Anthropic API Tool Use에서 바로 호출할 수 있는 MCP 도구로 노출합니다. 양식 문서의 빈 셀을 자동으로 채우거나, 템플릿의 `{{key}}`를 치환하거나, 기존 표의 내용을 수정하는 작업을 LLM 에이전트가 수행할 수 있습니다.
+
+## 지원 포맷
+
+| 포맷 | 백엔드 | 템플릿 렌더 | 표 읽기 | 셀 수정 | 행 추가 |
+|---|---|---|---|---|---|
+| `.docx` | `docxtpl` + `python-docx` | Jinja2 (`{%tr%}` loop 포함) | ✅ | ✅ | ✅ |
+| `.pptx` | `python-pptx` | `{{key}}` 치환 | ✅ (슬라이드 위치 포함) | ✅ | ❌ (미지원) |
+| `.hwpx` | `python-hwpx` (Pure Python) | `{{key}}` 치환 | ✅ | ✅ | ❌ (미지원) |
+
+- HWPX는 한컴오피스 설치가 **불필요**합니다 (macOS/Linux 서버에서 그대로 동작).
+- 구버전 `.hwp`(바이너리 포맷)는 지원하지 않습니다 — `.hwpx`로 변환 후 사용하세요.
+
+## 설치
+
+```bash
+pip install -e .
+
+# Claude API 예시 스크립트까지 쓰려면
+pip install -e ".[claude]"
+```
+
+Python 3.10+ 필요.
+
+## 빠른 시작 — 파이썬 API
+
+```python
+from document_adapter import load
+
+doc = load("report_template.docx")
+
+# 1. 구조 파악
+schema = doc.get_schema()
+print(schema.placeholders)   # ['author', 'date', 'title']
+print(schema.tables)         # [TableSchema(index=0, rows=7, cols=2, ...), ...]
+
+# 2. 템플릿 렌더
+doc.render_template({
+    "title": "Q1 운영 리포트",
+    "author": "손성준",
+    "date": "2026-04-15",
+})
+doc.save("report_filled.docx")
+
+# 3. 기존 양식 파일의 표 셀 수정
+doc = load("checklist.docx")
+old = doc.set_cell(table_index=1, row=1, col=1, value="○○전자")
+doc.append_row(1, ["새 항목", "값"])  # DOCX만 지원
+doc.save("checklist_filled.docx")
+doc.close()
+```
+
+확장자로 자동 분기되므로 `.pptx` / `.hwpx`도 동일한 API를 사용합니다.
+
+## MCP 서버로 사용 — Claude Desktop / Claude Code
+
+### 실행
+
+```bash
+python -m document_adapter.mcp_server
+# 또는 설치 후
+document-adapter-mcp
+```
+
+### Claude Desktop 설정
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "document-adapter": {
+      "command": "/absolute/path/to/venv/bin/python",
+      "args": ["-m", "document_adapter.mcp_server"]
+    }
+  }
+}
+```
+
+재시작하면 Claude Desktop에서 아래 4개 도구를 사용할 수 있습니다.
+
+### Claude Code 설정
+
+```bash
+claude mcp add document-adapter \
+  /absolute/path/to/venv/bin/python -m document_adapter.mcp_server
+```
+
+## Anthropic API Tool Use로 사용
+
+`document_adapter.tools`가 Claude API의 tool schema 형식과 그대로 호환됩니다.
+
+```python
+import anthropic
+from document_adapter.tools import TOOL_DEFINITIONS, call_tool
+
+client = anthropic.Anthropic()
+
+resp = client.messages.create(
+    model="claude-opus-4-6",
+    max_tokens=4096,
+    tools=[{
+        "name": t["name"],
+        "description": t["description"],
+        "input_schema": t["input_schema"],
+    } for t in TOOL_DEFINITIONS],
+    messages=[{
+        "role": "user",
+        "content": "report_template.docx의 표 구조를 확인하고 빈 셀을 적절히 채워줘",
+    }],
+)
+
+# tool_use 블록을 받으면 call_tool(name, args)로 실행 후 결과 반환
+```
+
+전체 agent loop 예시는 [`examples/claude_api_example.py`](examples/claude_api_example.py) 참고.
+
+## 노출되는 4개 도구
+
+| 도구 | 설명 |
+|---|---|
+| `inspect_document` | 문서 구조(placeholders, tables)를 JSON으로 반환. **항상 첫 호출로 사용** |
+| `render_template` | `{{key}}`를 context dict 값으로 치환해 새 파일 저장 |
+| `set_cell` | 특정 표의 `(row, col)` 셀 값 교체 |
+| `append_row` | 표 끝에 새 행 추가 (DOCX 전용) |
+
+### `inspect_document` 반환 예시
+
+```json
+{
+  "format": "docx",
+  "source": "/path/to/checklist.docx",
+  "placeholders": [],
+  "tables": [
+    {
+      "index": 1,
+      "rows": 7,
+      "cols": 2,
+      "location": null,
+      "preview": [
+        {"row": 0, "cells": ["항목", "기입 내용"]},
+        {"row": 1, "cells": ["고객사 / 조직", ""]},
+        {"row": 2, "cells": ["현업 담당부서 / 책임자", ""]}
+      ]
+    }
+  ]
+}
+```
+
+LLM은 이 preview를 보고 **"빈 셀이 어디 있는지 / 어떤 값을 넣어야 하는지"** 를 판단하여 `set_cell`을 호출합니다.
+
+## 템플릿 작성 규칙
+
+### DOCX — Jinja2 전체 문법 사용 가능
+
+```
+{{ report_title }}
+작성자: {{ author }}
+
+{% for item in items %}- {{ item.name }}: {{ item.value }}
+{% endfor %}
+```
+
+**표 행 반복은 `{%tr for ... %}` / `{%tr endfor %}`를 각각 별도 행에 두어야 합니다.**
+같은 행에 두 태그를 넣으면 `<w:tr>` 전체가 `{% for %}`로 교체되어 `endfor`가 손실됩니다.
+
+```
+┌─────────────────────┬─────┬─────┐
+│ 항목                │ 목표 │ 실적 │    <- 헤더
+├─────────────────────┼─────┼─────┤
+│ {%tr for r in rows %}          │    <- for 행
+├─────────────────────┼─────┼─────┤
+│ {{ r.name }}        │ {{ r.target }} │ {{ r.actual }} │  <- 반복 본문
+├─────────────────────┼─────┼─────┤
+│ {%tr endfor %}                 │    <- endfor 행
+└─────────────────────┴─────┴─────┘
+```
+
+### PPTX / HWPX — 단순 `{{key}}` 치환만
+
+loop / if / filter는 지원하지 않습니다. PPTX는 placeholder가 여러 `run`으로 쪼개질 수 있어, 어댑터가 paragraph 전체 텍스트를 재조립한 뒤 첫 `run`에 다시 담는 방식으로 처리합니다 (서식 일부 손실 가능).
+
+## 내장된 버그 회피
+
+| 포맷 | 문제 | 어댑터의 처리 |
+|---|---|---|
+| HWPX | `python-hwpx 2.9.0`의 `set_cell_text()`가 빈 셀에서 lxml/ElementTree 혼용 `TypeError` 발생 | `paragraphs[0].text = value` 직접 할당으로 우회 |
+| HWPX | `replace_text_in_runs()`가 한글 공백이 run으로 쪼개진 경우 매칭 실패 | 위치 기반 API만 사용 |
+| HWPX | `manifest fallback` 경고 로그가 과도하게 출력됨 | `logging.getLogger("hwpx")` 레벨을 `ERROR`로 조정 |
+| PPTX | placeholder가 여러 `run`으로 쪼개져 단순 `run.text` 치환이 실패 | paragraph 전체 재조립 |
+| DOCX | `docxtpl`의 `{%tr%}`를 같은 행에 두면 파싱 에러 | README에 배치 규칙 명시 |
+
+## 프로젝트 구조
+
+```
+document_adapter/
+├── __init__.py        # load() dispatcher
+├── base.py            # DocumentAdapter ABC, TableSchema, DocumentSchema
+├── docx_adapter.py    # DocxAdapter
+├── pptx_adapter.py    # PptxAdapter
+├── hwpx_adapter.py    # HwpxAdapter (버그 회피 포함)
+├── tools.py           # Tool 정의 + call_tool dispatcher
+└── mcp_server.py      # MCP stdio server
+
+examples/
+└── claude_api_example.py
+```
+
+## 라이선스
+
+MIT
+
+## Credits
+
+- [`python-docx`](https://github.com/python-openxml/python-docx)
+- [`docxtpl`](https://github.com/elapouya/python-docx-template)
+- [`python-pptx`](https://github.com/scanny/python-pptx)
+- [`python-hwpx`](https://github.com/airmang/python-hwpx)
+- [`mcp`](https://github.com/modelcontextprotocol/python-sdk)

document_adapter-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+document_adapter/__init__.py,sha256=YqjF6xhkI1X2sbO5XfZE9kQVA4RMzTuwu7TpuMUGJDk,1121
+document_adapter/base.py,sha256=pQlYsSnMJfYa-GaSkzSlwqVhe1udRyv6STTryuEFftc,3001
+document_adapter/docx_adapter.py,sha256=IxpSXKaD_9kspalKcQ3AbsVJodK6pJ_t5XoUy5fv5Kg,2702
+document_adapter/hwpx_adapter.py,sha256=46uIkn8dDHeJkx4u3xU1ZZaXTTovdgzHWN1ZN0HFep0,4683
+document_adapter/mcp_server.py,sha256=veEl7S5EJMP0OLSlQI6pWvFSKJ-0lWm0GHX46G0EfC4,1609
+document_adapter/pptx_adapter.py,sha256=doV9NjgyK5OrrB-TkrvYrwhusqCfxZXjk_iiLkJOy-g,4215
+document_adapter/tools.py,sha256=84jib-rNQUhWFER1R6k7zIzBDGHgnx6MCHCh2keAcp0,7608
+document_adapter-0.1.0.dist-info/licenses/LICENSE,sha256=QjKz-cVDxa_NbNhNYo9ek6yDMnR4YHA2pKg-upo93x4,1068
+document_adapter-0.1.0.dist-info/METADATA,sha256=pGILinIsgp7YVDeNQ7hfPk_UObx8Ro-rqxYS-wPkQ0E,8809
+document_adapter-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+document_adapter-0.1.0.dist-info/entry_points.txt,sha256=krV-Z-Yc1M3qe2I1pxhEJX7wdwbKwfX-8sEN3-3CuQo,79
+document_adapter-0.1.0.dist-info/top_level.txt,sha256=WGApqbHX1xpY13c2OvG83DxDZToMonYK2xkWN_QeT8M,17
+document_adapter-0.1.0.dist-info/RECORD,,

document_adapter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

document_adapter-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+document-adapter-mcp = document_adapter.mcp_server:main_sync

document_adapter-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plateer Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

document_adapter-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+document_adapter