office-docs-mcp 0.1.0__tar.gz

office_docs_mcp-0.1.0/.env.example

@@ -0,0 +1 @@
+OFFICE_DOCS_MCP_LOGGING__LEVEL=INFO

office_docs_mcp-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          if [ -f uv.lock ]; then
+            uv sync --locked --group dev --python ${{ matrix.python-version }}
+          else
+            uv sync --group dev --python ${{ matrix.python-version }}
+          fi
+
+      - name: Lint
+        run: uv run --python ${{ matrix.python-version }} ruff check .
+
+      - name: Format check
+        run: uv run --python ${{ matrix.python-version }} ruff format --check .
+
+      - name: Test
+        run: uv run --python ${{ matrix.python-version }} pytest -v

office_docs_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,70 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: |
+          if [ -f uv.lock ]; then
+            uv sync --locked --group dev
+          else
+            uv sync --group dev
+          fi
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format check
+        run: uv run ruff format --check .
+
+      - name: Test
+        run: uv run pytest -v
+
+  publish:
+    name: Publish to PyPI
+    needs: [test]
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          enable-cache: true
+
+      - name: Build distribution packages
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

office_docs_mcp-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Virtual environment
+.venv/
+
+# Python byte-code and caches
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.coverage
+htmlcov/
+.pytest_cache/
+.ruff_cache/
+
+# Environment and secrets
+.env
+*.env.local
+
+# Databases and data dirs
+data/
+*.db
+*.sqlite3
+
+# IDE / Editor configs
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS files
+.DS_Store
+Thumbs.db

office_docs_mcp-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

office_docs_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,192 @@
+# AGENTS.md - Office Docs MCP Server
+
+이 문서는 AI 에이전트와 개발자가 `office_docs_mcp` 프로젝트의 구조, 설계 원칙, TDD 개발 워크플로우를 이해하고 일관성 있게 협업할 수 있도록 돕는 지침서입니다.
+
+---
+
+## 1. 프로젝트 개요 (Project Overview)
+
+`office_docs_mcp`는 LLM(대형 언어 모델)이 오피스 문서(Excel, Word, PowerPoint)를 안정적이고 효율적으로 읽고 쓸 수 있도록 지원하는 **Model Context Protocol (MCP)** 서버입니다.
+
+### 핵심 설계 철학
+1. **LLM 친화적 인터페이스 (Token & Context Conscious)**:
+   - 전체 문서를 무작정 텍스트로 덤프하지 않고, **개요 조회(Outline/Metadata) -> 범위/페이징 읽기(Chunked Read) -> 정밀 쓰기(Precise Write)** 흐름을 제공합니다.
+   - 반환 데이터는 토큰 효율이 높고 가독성이 좋은 Markdown 테이블 또는 정형화된 JSON 형식을 취합니다.
+2. **테스트 주도 개발 (TDD)**:
+   - 모든 기능은 요구사항 정의 -> 실패하는 테스트 작성(Red) -> 최소 구현(Green) -> 리팩토링(Refactor) 순서로 개발합니다.
+   - 실제 파일 IO 테스트는 `pytest`의 `tmp_path` 픽스처를 활용하여 독립적이고 빠르게 수행합니다.
+3. **안전한 파일 조작 (Safe File I/O)**:
+   - 파일 유효성 검사(경로 존재 여부, 확장자 검사)를 철저히 수행합니다.
+   - 기존 파일 덮어쓰기 시 백업 또는 안전 장치를 제공합니다.
+
+---
+
+## 2. 기술 스택 및 의존성 (Tech Stack)
+
+- **Language Runtime**: Python >= 3.12
+- **Package & Environment Manager**: `uv`
+- **MCP Framework**: `mcp` (Official Python MCP SDK - FastMCP)
+- **Office Document Libraries**:
+  - **Excel (`.xlsx`, `.xlsm`)**: `openpyxl` (표준, 셀 단위 조작, 수식 및 서식 지원)
+  - **Word (`.docx`)**: `python-docx` (단락, 표, 헤딩 조작 표준)
+  - **PowerPoint (`.pptx`)**: `python-pptx` (슬라이드, 셰이프, 텍스트, 표 조작 표준)
+- **Linting & Formatting**: `ruff`
+- **Testing**: `pytest`
+
+---
+
+## 3. 디렉토리 구조 (Directory Structure)
+
+```text
+office_docs_mcp/
+├── AGENTS.md                  # 에이전트용 개발 가이드 (본 문서)
+├── README.md                  # 사용자용 프로젝트 설명서
+├── CHANGELOG.md               # 변경 이력 기록 (Keep a Changelog)
+├── CONTRIBUTING.md            # 기여 가이드
+├── SECURITY.md                # 보안 정책
+├── LICENSE                    # 라이선스 (MIT)
+├── pyproject.toml             # uv 패키지 및 의존성 정의
+├── config.toml                # 런타임 설정 파일
+├── src/
+│   └── office_docs_mcp/
+│       ├── __init__.py
+│       ├── main.py            # CLI 진입점 (serve 명령어 제공)
+│       ├── server.py          # FastMCP 서버 인스턴스 및 도구 바인딩
+│       ├── common/            # 공통 유틸리티 (파일 검증, 페이징, 설정 관리 등)
+│       │   ├── __init__.py
+│       │   ├── config_manager.py
+│       │   └── file_utils.py
+│       ├── excel/             # Excel 전용 로직 (.xlsx)
+│       │   ├── __init__.py
+│       │   ├── reader.py
+│       │   └── writer.py
+│       ├── word/              # Word 전용 로직 (.docx)
+│       │   ├── __init__.py
+│       │   ├── reader.py
+│       │   └── writer.py
+│       └── powerpoint/        # PowerPoint 전용 로직 (.pptx)
+│           ├── __init__.py
+│           ├── reader.py
+│           └── writer.py
+└── tests/
+    ├── __init__.py
+    ├── test_smoke.py
+    ├── test_config_cli.py     # CLI config 서브명령어 테스트
+    ├── test_excel.py          # Excel 서비스 및 도구 단위 테스트
+    ├── test_word.py           # Word 서비스 및 도구 단위 테스트
+    ├── test_powerpoint.py     # PowerPoint 서비스 및 도구 단위 테스트
+    └── test_server.py         # MCP 도구 등록 및 실행 통합 테스트
+```
+
+---
+
+## 4. MCP 도구 명세 (Tool Specifications)
+
+### 4.1 Excel 도구군 (`excel_*`)
+- `excel_get_metadata(file_path: str)`: 시트 목록, 시트별 최대 행/열 수, 컬럼 헤더 요약.
+- `excel_read_sheet(file_path: str, sheet_name: str | None = None, start_row: int = 1, end_row: int = 50, start_col: int = 1, end_col: int = 20, format: str = "markdown")`:
+  - 특정 시트의 지정된 행/열 범위를 읽어 반환 (기본 1-based 인덱스 사용, LLM 직관성 일치).
+- `excel_write_cell(file_path: str, sheet_name: str, coordinate: str, value: Any)`:
+  - 예: `A1` 또는 행/열 번호로 단일 셀 값 변경.
+- `excel_write_range(file_path: str, sheet_name: str, start_cell: str, data: list[list[Any]])`:
+  - 시작 셀(`A1` 등)부터 2차원 리스트 데이터를 연속 기입.
+- `excel_append_rows(file_path: str, sheet_name: str, rows: list[list[Any]])`:
+  - 시트 맨 마지막 행 뒤에 새로운 행들 추가.
+- `excel_create_workbook(file_path: str, sheet_names: list[str] | None = None)`:
+  - 빈 엑셀 파일 생성.
+
+### 4.2 Word 도구군 (`word_*`)
+- `word_get_outline(file_path: str)`: 문서의 헤딩(제목) 목록, 전체 단락 수, 표(Table) 개수 등 구조 요약.
+- `word_read_paragraphs(file_path: str, start_idx: int = 0, count: int = 30)`:
+  - 단락 단위로 본문 텍스트 슬라이싱 읽기.
+- `word_append_paragraph(file_path: str, text: str, style: str | None = None)`:
+  - 문서 끝에 새 단락 또는 헤딩 추가.
+- `word_read_table(file_path: str, table_idx: int = 0, format: str = "markdown")`:
+  - 특정 순번의 표 내용을 Markdown 표나 2차원 배열로 읽기.
+- `word_append_table_row(file_path: str, table_idx: int, row_data: list[str])`:
+  - 특정 표에 행 데이터 추가.
+- `word_create_document(file_path: str, title: str | None = None)`:
+  - 빈 워드 문서 생성.
+
+### 4.3 PowerPoint 도구군 (`ppt_*`)
+- `ppt_get_outline(file_path: str)`: 전체 슬라이드 수, 각 슬라이드의 제목 및 포함된 셰이프 종류 요약.
+- `ppt_read_slide(file_path: str, slide_idx: int)`:
+  - 특정 슬라이드의 모든 텍스트 상자 및 표 내용 추출.
+- `ppt_add_slide(file_path: str, title: str, content: str | None = None, layout_idx: int = 1)`:
+  - 제목과 본문을 포함하는 새 슬라이드 생성.
+- `ppt_update_slide_text(file_path: str, slide_idx: int, shape_idx: int, text: str)`:
+  - 특정 슬라이드의 지정된 셰이프 텍스트 수정.
+- `ppt_create_presentation(file_path: str, title: str | None = None)`:
+  - 빈 프레젠테이션 파일 생성.
+
+---
+
+## 5. TDD 워크플로우 (Test-Driven Development)
+
+에이전트가 새로운 도구나 기능을 추가할 때는 **반드시** 다음 절차를 준수합니다:
+
+1. **테스트 우선 작성 (`Red`)**:
+   - `tests/test_<format>.py`에 테스트 케이스를 먼저 작성합니다.
+   - 임시 파일은 반드시 pytest의 `tmp_path: pathlib.Path`를 사용하여 디스크 오염을 방지합니다.
+   - 예시:
+     ```python
+     def test_excel_write_and_read(tmp_path):
+         file_path = tmp_path / "sample.xlsx"
+         excel_create_workbook(str(file_path))
+         excel_write_cell(str(file_path), "Sheet", "B2", "Hello MCP")
+         result = excel_read_sheet(
+             str(file_path), "Sheet", start_row=2, end_row=2, start_col=2, end_col=2
+         )
+         assert "Hello MCP" in result
+     ```
+2. **최소 코드 구현 (`Green`)**:
+   - `src/office_docs_mcp/<format>/` 하위에 비즈니스 로직을 구현합니다.
+   - `uv run pytest tests/test_<format>.py` 실행 후 테스트가 통과하는지 확인합니다.
+3. **리팩토링 및 린트 (`Refactor`)**:
+   - 예외 처리(파일 누락, 인덱스 초과 등)를 강화합니다.
+   - `uv run ruff check .` 및 `uv run ruff format .`을 실행하여 컨벤션을 유지합니다.
+4. **MCP 도구 등록 및 검증**:
+   - `server.py`에 `@mcp.tool()` 데코레이터를 추가하고 문서화 docstring을 작성합니다.
+
+---
+
+## 6. 개발 필수 명령어 (Development Commands)
+
+모든 작업은 `uv`를 통해 수행합니다:
+
+```bash
+# 가상환경 동기화 및 패키지 설치
+uv sync --group dev
+
+# 새로운 패키지 추가 (예: 의존성 추가 시)
+uv add openpyxl python-docx python-pptx mcp
+
+# 테스트 실행
+uv run pytest
+
+# 특정 테스트 파일 단독 실행
+uv run pytest tests/test_excel.py -v
+
+# 린트 및 포맷 검사
+uv run ruff check .
+uv run ruff format --check .
+
+# MCP 서버 로컬 실행 (Stdio 모드)
+uv run office-docs-mcp serve
+```
+
+---
+
+## 7. 구현 시 주의사항 (Guidelines & Pitfalls)
+
+1. **1-Based vs 0-Based 인덱스**:
+   - 엑셀은 사용자/LLM 친화적으로 **1-based** (행 1, 열 1 = A1)를 기본값으로 통일합니다.
+   - 워드/파워포인트의 인덱스(단락, 슬라이드, 표)는 API 설명서(docstring)에 기준(0-based)을 명확하게 명시합니다.
+2. **Excel 수식(Formula) 처리**:
+   - `openpyxl`에서 `data_only=False`일 때는 수식 문자열(`=SUM(A1:A10)`), `data_only=True`일 때는 직전 저장된 계산값을 읽습니다.
+   - 읽기 도구 파라미터에 `evaluate_formulas: bool = True` 옵션을 두어 LLM이 필요에 따라 수식 자체 또는 계산값을 선택할 수 있게 합니다.
+3. **대용량 파일 방어**:
+   - 기본 `read` 호출 시 반환 최대 행/단락 수에 상한선(`max_rows=100`, `max_paragraphs=50` 등)을 두고, 필요 시 페이징을 유도합니다.
+4. **타입 힌트와 Docstring**:
+   - FastMCP는 함수의 Type Hint와 Docstring을 파싱하여 LLM 도구의 JSON Schema와 Description을 자동 생성합니다.
+   - 따라서 모든 도구 함수에는 **상세한 설명, 파라미터 의미, 사용 예시**를 반드시 Docstring에 기재합니다.

office_docs_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> **Note on Versioning**: Version `0.y.z` indicates initial development. Public APIs and tool signatures may undergo refinements based on feedback before reaching `1.0.0`.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-19
+
+### Added
+- **MCP Server**: FastMCP server with Stdio and SSE transport support via `office-docs-mcp serve`.
+- **Excel Tools (`excel_*`)**:
+  - `excel_get_metadata`: Inspect workbook structure, sheet names, dimensions, and column previews.
+  - `excel_read_sheet`: Range reading with 1-based indexing, formula toggle (`evaluate_formulas`), and markdown/raw output.
+  - `excel_write_cell`: Write values or formulas to specific cells.
+  - `excel_write_range`: Continuous 2D block data insertion.
+  - `excel_append_rows`: Append rows to sheet end.
+  - `excel_create_workbook`: Initialize blank workbook with custom sheet names.
+- **Word Tools (`word_*`)**:
+  - `word_get_outline`: Document outline with heading tree, paragraph, and table counts.
+  - `word_read_paragraphs`: Chunked 0-based paragraph reading with style info.
+  - `word_read_table`: Read tables as Markdown or 2D matrix.
+  - `word_append_paragraph`: Append paragraphs or headings with automatic heading level parsing.
+  - `word_append_table_row`: Append rows to existing tables.
+  - `word_write_table_cell`: Update individual table cells.
+  - `word_create_document`: Create blank `.docx` documents with optional title heading.
+- **PowerPoint Tools (`ppt_*`)**:
+  - `ppt_get_outline`: Slide count, titles, and shape statistics.
+  - `ppt_read_slide`: Extract text frames and table data from slides.
+  - `ppt_add_slide`: Add slide with title and content placeholder (with automatic fallback to text boxes).
+  - `ppt_update_slide_text`: Update text in designated slide shapes.
+  - `ppt_create_presentation`: Create blank `.pptx` presentations with optional title slide.
+- **CLI Commands & Configuration**:
+  - `office-docs-mcp serve`: Launch the MCP server.
+  - `office-docs-mcp tools`: List registered tools with `--plain` and `--json` machine-readable output flags.
+  - `office-docs-mcp config show`: Display effective configuration or specific key (`--json`, `--toml`).
+  - `office-docs-mcp config init`: Initialize configuration with default values (`--force`, `--local`, `--path`).
+  - `office-docs-mcp config path`: Display active configuration file path (`--json`, `--local`).
+  - `office-docs-mcp config set <key> <value>`: Modify configuration keys with automatic type parsing and atomic writing.
+  - `office-docs-mcp config get <key>`: Retrieve specific configuration values by dotted path.
+  - Platform-standard configuration directory support (Linux XDG, macOS Application Support, Windows AppData).
+  - Persistent `--no-color` flag and shell completion generation (`completion <bash|zsh|fish>`).
+- **Open-Source, Governance & CI/CD**:
+  - MIT License (`LICENSE`).
+  - Contribution guidelines (`CONTRIBUTING.md`).
+  - Security disclosure policy (`SECURITY.md`).
+  - GitHub Actions CI workflow with matrix testing across Python 3.12 and 3.13.
+  - GitHub Actions automated release pipeline (`release.yml`) for PyPI Trusted Publishing and GitHub Releases upon version tag push.

office_docs_mcp-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,58 @@
+# Contributing to office_docs_mcp
+
+Thank you for your interest in contributing to `office_docs_mcp`! This project follows a strict Test-Driven Development (TDD) workflow and high code-quality standards.
+
+---
+
+## 1. Development Setup
+
+1. Ensure you have Python >= 3.12 and [`uv`](https://docs.astral.sh/uv/) installed.
+2. Clone the repository and install dependencies:
+   ```bash
+   uv sync --group dev
+   ```
+3. Run test suite and linters to verify your local environment:
+   ```bash
+   uv run pytest
+   uv run ruff check .
+   uv run ruff format --check .
+   ```
+
+---
+
+## 2. Test-Driven Development (TDD) Workflow
+
+All new features and bugfixes must follow the Red-Green-Refactor cycle:
+
+1. **Red**: Write a failing unit or integration test under `tests/` using pytest's `tmp_path` fixture for safe file I/O.
+2. **Green**: Implement the minimal code in `src/office_docs_mcp/` to make the test pass.
+3. **Refactor**: Clean up the implementation, optimize performance, and ensure clean docstrings and type annotations.
+4. **Lint & Format**:
+   ```bash
+   uv run ruff check . --fix
+   uv run ruff format .
+   ```
+
+---
+
+## 3. Pull Request Guidelines
+
+- Keep pull requests focused on a single change or feature.
+- Ensure all CI checks pass.
+- Update `CHANGELOG.md` under `[Unreleased]` with your changes.
+- Update `README.md` and docstrings if public tool signatures or behavior change.
+- Never commit binary files, credentials, or generated files.
+
+---
+
+## 4. Release Process
+
+1. Update the version in `pyproject.toml`, `src/office_docs_mcp/__init__.py`, and `src/office_docs_mcp/main.py`.
+2. Move relevant unreleased notes in `CHANGELOG.md` to the new version heading with release date.
+3. Commit and push changes to `main`.
+4. Create and push a semver tag:
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+5. GitHub Actions (`.github/workflows/release.yml`) will run tests, build distribution wheels, publish to PyPI using Trusted Publishing (OIDC), and create a GitHub Release.

office_docs_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antigravity Team
+
+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.

office_docs_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: office_docs_mcp
+Version: 0.1.0
+Summary: Model Context Protocol (MCP) server for reading and writing Office documents (Excel, Word, PowerPoint)
+Author: Antigravity Team
+License: MIT
+License-File: LICENSE
+Keywords: excel,mcp,model-context-protocol,office,openpyxl,powerpoint,python-docx,python-pptx,word
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: mcp>=2.2.0
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: python-docx>=1.2.0
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: wpycli
+Requires-Dist: wpyconf
+Requires-Dist: wpylog
+Description-Content-Type: text/markdown
+
+# office_docs_mcp
+
+[![CI](https://github.com/wkqco33/office_docs_mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/wkqco33/office_docs_mcp/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python: 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](pyproject.toml)
+
+LLM(대형 언어 모델)이 오피스 문서(Excel, Word, PowerPoint)를 안정적이고 토큰 효율적으로 읽고 쓸 수 있도록 지원하는 **Model Context Protocol (MCP)** 서버입니다.
+
+> **버전 안내**: 본 프로젝트는 현재 초기 개발 단계(`0.y.z`)이며, 사용자 피드백에 따라 도구 인터페이스가 지속적으로 개선되고 있습니다.
+
+---
+
+## 주요 기능
+
+- **Excel (`.xlsx`, `.xlsm`)**:
+  - `excel_get_metadata`: 시트 목록, 크기, 컬럼 요약 조회
+  - `excel_read_sheet`: 지정된 행/열 범위(1-based)를 Markdown 테이블 또는 2차원 배열로 읽기 (수식/값 토글 지원)
+  - `excel_write_cell`: 단일 셀(`A1` 등) 값/수식 쓰기
+  - `excel_write_range`: 시작 셀부터 2차원 데이터 연속 기입
+  - `excel_append_rows`: 시트 마지막 행 뒤에 데이터 추가
+  - `excel_create_workbook`: 새 빈 엑셀 파일 생성
+- **Word (`.docx`)**:
+  - `word_get_outline`: 문서 헤딩(제목) 목록 및 단락/표 개수 조회
+  - `word_read_paragraphs`: 단락 슬라이싱 읽기 (0-based 페이징)
+  - `word_read_table`: 표 내용을 Markdown 테이블 또는 2차원 배열로 읽기
+  - `word_append_paragraph`: 문서 끝에 단락/헤딩 추가 (헤딩 레벨 자동 처리)
+  - `word_append_table_row`: 특정 표에 새 행 추가
+  - `word_write_table_cell`: 특정 표의 셀 텍스트 수정
+  - `word_create_document`: 새 워드 문서 생성
+- **PowerPoint (`.pptx`)**:
+  - `ppt_get_outline`: 전체 슬라이드 수 및 각 슬라이드 제목/셰이프 요약 조회
+  - `ppt_read_slide`: 특정 슬라이드의 텍스트 상자 및 표 내용 추출
+  - `ppt_add_slide`: 제목과 본문을 포함하는 새 슬라이드 추가 (플레이스홀더 부재 시 자동 텍스트박스 폴백)
+  - `ppt_update_slide_text`: 슬라이드 내 특정 셰이프 텍스트 수정
+  - `ppt_create_presentation`: 새 프레젠테이션 파일 생성
+
+---
+
+## 시작하기
+
+### 1. 요구 사항
+- Python >= 3.12
+- [uv](https://docs.astral.sh/uv/) 패키지 관리자
+
+### 2. 설치 및 가상환경 동기화
+```bash
+uv sync --group dev
+```
+
+### 3. CLI 명령어
+
+```bash
+# MCP 서버 실행 (기본 Stdio 트랜스포트)
+uv run office-docs-mcp serve
+
+# SSE 트랜스포트로 실행
+uv run office-docs-mcp serve --transport sse
+
+# 등록된 MCP 도구 목록 확인 (사람 가독형)
+uv run office-docs-mcp tools
+
+# 기계 판독용 단일 라인 목록
+uv run office-docs-mcp tools --plain
+
+# 기계 판독용 JSON 스키마 덤프
+uv run office-docs-mcp tools --json
+
+# 설정 관리 서브명령어 (각 플랫폼 기본 경로 표준 지원)
+# - Linux: ~/.config/office_docs_mcp/config.toml ($XDG_CONFIG_HOME)
+# - macOS: ~/Library/Application Support/office_docs_mcp/config.toml
+# - Windows: %APPDATA%/office_docs_mcp/config.toml
+uv run office-docs-mcp config show                  # 현재 병합된 설정 전체 확인 (JSON)
+uv run office-docs-mcp config show --toml           # TOML 형식으로 확인
+uv run office-docs-mcp config init                  # 플랫폼 기본 경로에 config.toml 생성
+uv run office-docs-mcp config init --local          # 현재 작업 디렉토리에 ./config.toml 생성
+uv run office-docs-mcp config path                  # 플랫폼 기본 설정 파일 경로 확인 (--json 지원)
+uv run office-docs-mcp config path --local          # 로컬 설정 파일 경로 확인
+uv run office-docs-mcp config set logging.level DEBUG # 플랫폼 설정 파일 키 변경
+uv run office-docs-mcp config set --local logging.level DEBUG # 로컬 설정 파일 키 변경
+uv run office-docs-mcp config get logging.level       # 특정 설정 값 조회
+
+# 셸 자동완성 스크립트 생성
+uv run office-docs-mcp completion bash > /etc/bash_completion.d/office-docs-mcp
+```
+
+### 4. Claude Desktop / MCP 클라이언트 연동 설정 예시
+
+`claude_desktop_config.json` 등에 아래와 같이 추가합니다:
+
+```json
+{
+  "mcpServers": {
+    "office-docs": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/path/to/office_docs_mcp",
+        "run",
+        "office-docs-mcp",
+        "serve"
+      ]
+    }
+  }
+}
+```
+
+---
+
+## 개발 및 테스트 (TDD)
+
+```bash
+# 전체 단위 및 통합 테스트 실행
+uv run pytest -v
+
+# 린트 및 코드 스타일 검증
+uv run ruff check .
+uv run ruff format --check .
+```
+
+자세한 기여 방법 및 개발 가이드는 아래 문서를 참고하세요:
+- [AGENTS.md](AGENTS.md): AI 에이전트 및 개발자를 위한 설계 원칙 및 TDD 지침
+- [CONTRIBUTING.md](CONTRIBUTING.md): 기여 가이드라인
+- [CHANGELOG.md](CHANGELOG.md): 변경 이력
+- [SECURITY.md](SECURITY.md): 보안 정책
+- [LICENSE](LICENSE): MIT License