Content
# Tool List
[English](#english)
> Local MCP servers and `$` skills for safe HWPX, Microsoft Excel, and QGIS QGS/QGZ workflows in Codex on Windows.
## English
### Overview
This project provides three local toolsets that let Codex inspect and edit office documents, spreadsheets, and GIS projects on Windows.
- `$hwpx-local`: validate HWPX packages; analyze merged cells, headers, body rows, bottom-form rows, and inner/outer borders; search, extract, and replace text; verify opening in Hancom Hangul; export PDF
- `$excel-local`: inspect workbooks, sheets, and formulas; read and search ranges; write while preserving formatting; recalculate with Excel; export PDF
- `$qgis-local`: inspect QGS/QGZ projects and layers; audit missing data sources; rebase project paths; discover and run QGIS Processing algorithms
Each toolset works as a local MCP server. The included `$` skill can also call the verified local runner directly when the MCP tools are not visible in the current Codex task.
### Safety model
- Mutating operations create a separate output copy by default instead of overwriting the source.
- HWPX operations validate ZIP/XML integrity, Excel operations can use native Excel COM for fidelity, and QGZ operations inspect the embedded QGS XML and layer sources.
- File paths and JSON payloads are passed as UTF-8.
- User documents, test artifacts, virtual environments, and machine-specific runtime paths are excluded from Git.
### Requirements
- Windows 10/11
- [uv](https://docs.astral.sh/uv/) and Python 3.11
- Codex CLI
- Optional native applications:
- Hancom Hangul for native HWPX open checks and PDF export
- Microsoft Excel for high-fidelity COM editing, recalculation, and PDF export
- QGIS for Processing algorithms
### Install
```powershell
git clone https://github.com/kdhchgo-bit/hwpx-excel-qgis-qgz-mcp.git
cd hwpx-excel-qgis-qgz-mcp
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1
```
Pass a custom QGIS Processing path when needed:
```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 `
-QgisProcessPath 'C:\OSGeo4W\bin\qgis_process-qgis-ltr.bat'
```
The installer creates the project virtual environment, registers all three MCP servers with Codex, and installs the three `$` skills in the user's global skill directory. Open a new Codex task or restart the app, then invoke `$hwpx-local`, `$excel-local`, or `$qgis-local`.
### Example prompts
```text
$hwpx-local inspect D:\docs\report.hwpx and create a separate copy that replaces 250mm with 350mm.
$hwpx-local analyze merged cells, header/body/footer roles, and inner/outer borders in every table in D:\docs\form.hwpx.
$excel-local read Summary!G3:H30 in D:\data\estimate.xlsx and fill values while preserving the existing format.
$qgis-local audit missing layer sources in D:\GIS\project.qgz and create a copy with rebased paths.
```
Natural-language routing can select a skill automatically, but explicitly naming `$skill-name` is the most reliable option.
### Verification
```powershell
.\.venv\Scripts\python.exe -m pytest
.\.venv\Scripts\python.exe .\scripts\smoke_mcp.py
```
`verify_real_files.py` uses private local files and installed desktop applications. It is intended for workstation acceptance testing, not generic public CI.
## Available tools
| Server / skill | Tools |
|---|---|
| `hwpx-local` | `hwpx_validate`, `hwpx_inspect`, `hwpx_analyze_tables`, `hwpx_extract_text`, `hwpx_find_text`, `hwpx_replace_text`, `hwpx_native_open_check`, `hwpx_export_pdf` |
| `excel-local` | `excel_inspect`, `excel_read_range`, `excel_find`, `excel_write_range`, `excel_recalculate`, `excel_export_pdf` |
| `qgis-local` | `qgz_inspect`, `qgz_audit_sources`, `qgz_rebase_paths`, `qgis_list_algorithms`, `qgis_algorithm_help`, `qgis_run_algorithm` |
## Technical references
- [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [QGIS project files](https://docs.qgis.org/3.44/en/docs/user_manual/introduction/project_files.html)
- [QGIS QGS/QGZ file formats](https://docs.qgis.org/3.44/en/docs/user_manual/appendices/qgis_file_formats.html)
