docuhand 0.1.0.dev1__tar.gz

docuhand-0.1.0.dev1/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

docuhand-0.1.0.dev1/LICENSE

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

docuhand-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: docuhand
+Version: 0.1.0.dev1
+Summary: Give your AI agent hands to operate real Word & WPS documents on Windows — an MCP server driving real Office apps via COM.
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: mcp<2,>=1.2
+Requires-Dist: olefile>=0.47
+Requires-Dist: pywin32<312,>=306
+Description-Content-Type: text/markdown
+
+# docuhand
+Give your AI agent hands to operate real Word &amp; WPS documents on Windows

docuhand-0.1.0.dev1/README.md

@@ -0,0 +1,2 @@
+# docuhand
+Give your AI agent hands to operate real Word & WPS documents on Windows

docuhand-0.1.0.dev1/docs/pitfalls.md

@@ -0,0 +1,207 @@
+# Battle-tested pitfalls
+
+Every entry here cost real debugging time on real Chinese-Windows machines.
+You get them pre-solved. (This file grows with every release — it is the
+record of production use, not marketing copy.)
+
+## 1. Built-in style NAMES are locale-dependent; style CONSTANTS are not
+
+`doc.Styles("Heading 1")` throws `com_error` on a Chinese-UI Word — the
+style is called `标题 1` there. Use the locale-independent numeric
+constants instead: `wdStyleHeading1 = -2`, `wdStyleNormal = -1`.
+**Rule: drive Word by number, never by display string** (the same reason
+`ComputeStatistics(2)` beats `"wdStatisticPages"`).
+
+## 2. Quitting a driven Word instance can die with RPC_S_CALL_FAILED
+
+A scripted `word.Quit()` may raise `(-2147023170, 'The remote procedure
+call failed')` even when every prior call succeeded and the document is
+already safely on disk. Do not let this kill your teardown: treat Quit as
+best-effort (or swallow in `atexit`) and never retry document work against
+an engine that RPC-dropped you — relaunch instead. This is the same crash
+class that motivates DocuHand's per-call fault isolation and
+Word→KWPS failover.
+
+## 3. Drive COM from one dedicated STA thread
+
+Calling COM objects from an asyncio event loop thread explodes with
+`RPC_E_WRONG_THREAD`; calling from "a thread per operation" explodes with
+a dozen orphaned WINWORD.EXE processes. One long-lived STA thread with a
+serial work queue fixes both. On timeout, *abandon* the whole thread
+(daemon) rather than trying to interrupt a stuck COM call — and reset any
+engine state that lived on that thread.
+
+## 4. Host MCP clients filter your subprocess environment
+
+Hermes (and other MCP hosts) pass stdio servers a **filtered** environment:
+only baseline vars (`PATH`, `SYSTEMROOT`, `APPDATA`, `TEMP`, ...) plus what
+you declare in the server's `env` config. COM survives this fine — but if
+your server needs anything else (e.g. an allowlist env var), it must be
+declared in the MCP server config, not assumed.
+
+## 5. GBK stdio is the invisible bomb on Chinese Windows
+
+Python defaults stdout/stderr to the GBK codec there. One un-encodable
+character in a JSON-RPC response (a Chinese path, a curly quote) raises
+`UnicodeEncodeError` and kills the MCP transport. Reconfigure
+`sys.stdout/stderr` to UTF-8 *before the first protocol write* — see
+`docuhand/_compat.py`. Every MCP server on a CJK Windows machine needs
+this; most don't know it yet.
+
+## 6. pythonw.exe makes a cleaner stdio MCP server on Windows
+
+Launching the server with `pythonw.exe` (windowless Python) avoids a
+console window flashing per host restart, and stdio transport works
+unchanged — verified with a real MCP client round-trip. Keep `python.exe`
+for your own CLI debugging.
+
+## 7. Lock detection needs three signals, not one
+
+A file open in Word/WPS shows: write-handle denial + a `~$xxxx` owner
+lockfile + (sometimes) a read-only attribute. But a read-only *attribute*
+alone also denies write handles — so `is_locked` must exclude the
+attribute case before calling it "open elsewhere", and the owner-lockfile
+name is truncated to 8+3 legacy (`report.doc` → `~$port.doc`).
+
+## 8. A poisoned PYTHONPATH explodes only at the compiled layer — and popping
+## the env var in conftest is not enough
+
+Dev boxes with a global `PYTHONPATH` (this one injects the Hermes install)
+look healthy until two venvs both ship the same package: the foreign
+site-packages sits **ahead of the project venv in `sys.path`**, pure-Python
+imports silently shadow (mcp, pydantic), and then `pydantic_core` dies with
+`ModuleNotFoundError` on a binary `.pyd` version mismatch — far away from
+the actual mistake.
+
+Two traps that cost an afternoon:
+
+- `os.environ.pop("PYTHONPATH")` **cannot save the parent pytest process**:
+  the paths were already expanded into `sys.path` at interpreter startup.
+  The env var and the `sys.path` entries must be scrubbed separately.
+- `StdioServerParameters(env=...)` does not help either — the import dies
+  in the *pytest parent*, before any child server is spawned.
+
+Fix (`tests/conftest.py`): pop the env var (children then inherit a clean
+environment) AND filter every PYTHONPATH entry out of `sys.path` (the
+parent then imports its own venv). Both, once, before any test module
+imports `mcp`.
+
+## 9. A corrupt file can pop a MODAL dialog through COM — headless is a lie
+### (and every in-COM defense fails somewhere)
+
+Feeding a structurally broken file to `Documents.Open` via COM can raise a
+**modal "file is corrupt" dialog** on the user's desktop — even though your
+app is headless and `DisplayAlerts = 0`. Empirical scorecard on a fake-zip
+`.docx`:
+
+| defense | result |
+|---|---|
+| `DisplayAlerts = 0` | dialog still appears |
+| `Application.FileValidation = 1` (wdFileValidationSkip) | **88 s hang** on WPS — the skip path itself stalls |
+| `Open(..., PasswordDocument="wrong-pw")` | 3 s clean error on Word; on **WPS the dynamic dispatch explodes with `AttributeError` on the unknown kwarg and the app object dies** (next call: RPC_S_SERVER_UNAVAILABLE) |
+| **validate the container in pure Python BEFORE COM** (`engine/container_guard.py`) | **modal is physically impossible — the engine never sees the trash** |
+
+Only the last one is portable across Word and WPS, and it is the only one
+that cannot regress with a new Office version. When a "password" error
+does arrive, trust it only if the container could actually be encrypted
+(check the OLE2 FIB fEncrypted bit at offset 0x0A); otherwise it is Word
+misjudging corruption as encryption — report OPEN_FAILED, not
+"ask the user for the password".
+
+**Rule: `Documents.Open` is a window into the user's desktop. Anything
+you can decide without the engine, decide without the engine.**
+
+## 10. `Word.Application` may not be Word — ProgID hijacking on WPS machines
+
+On a machine with WPS Office but no MS Word, the `Word.Application` ProgID
+can be **registered by WPS** ( compat takeover). Every COM probe then
+"succeeds with Word" while `'Kingsoft WPS'` sits in the `com_error`
+source. Two consequences:
+
+- Never trust `engine == "word"` for reporting unless you verified the
+  binary, not just the ProgID.
+- Machine-wide (`HKLM`) registry probing misses per-user WPS installs:
+  check `HKCU\Software\Classes\<ProgID>` too, or your "is WPS available?"
+  test says no while WPS works fine.
+
+## 11. git-bash heredocs feeding `python -` can hang forever
+
+`uv run python <<'EOF' ... EOF` from git-bash/MSYS on Windows may deliver
+stdin in a way `python -` never sees EOF for — the process hangs past its
+own logic with zero output (and stdout redirected to a file shows nothing
+because of block buffering). Write the script to a real file and run it;
+add `flush=True` to progress prints. Same box: PowerShell's `$_` is eaten
+by git-bash too — put PowerShell logic in a `.ps1` file instead.
+
+## 12. WPS's `Documents.Open` rejects RELATIVE paths with a bare failure
+
+Hand WPS a relative path (`examples\\dir\\a.doc`) while your server's cwd
+is perfectly correct and it fails with `文档打开失败` (error 3010) — the
+same call with an absolute path succeeds. Word tolerates relative paths;
+WPS does not. Rule: **`Path(...).expanduser().resolve()` every path at the
+engine boundary**, before it can reach COM. The server's cwd is an
+implementation detail the engine must never depend on.
+
+## 13. Old Office compat: a missing COM method raises AttributeError, not
+## TypeError
+
+`SaveAs2` did not exist before Word 2010. On a Word 2007 machine, late
+binding fails at **attribute access** with `AttributeError` — the call
+never happens, so a `TypeError`-shaped fallback net never fires and every
+conversion dies with OPEN_FAILED. Whenever you use a "modern" COM method
+with an old-engine fallback (`SaveAs2→SaveAs`, `ContentControls`→nothing,
+`OpenNoRepairDialog`→`Open`), the fallback must catch **both**
+`AttributeError` (method absent) and the arg-mismatch family (method
+present but rejects the signature). The user's fleet: government machines
+routinely still run Win7 + Office 2007/2010 — treat 2007 as a supported
+floor until the field data says otherwise.
+
+## 14. `Find.Execute(Replace:=wdReplaceAll)` returns True and replaces
+## NOTHING on WPS-as-Word
+
+On this engine family (WPS 12 masquerading as `Word.Application`,
+reporting `Name = "Microsoft Word"`, `Version = 12.0`), the one-call
+`Find.Execute(FindText=..., ReplaceWith=..., Replace=2)` completes
+**successfully** (returns True) yet the text is unchanged. No error, no
+dialog — the Replacement is silently dropped. The portable recipe (probe-
+verified on both the hijacked Word ProgID and real `KWPS.Application`):
+
+```python
+# per hit: FRESH story range + fresh Find, find-only, then set range text
+while True:
+    f = doc.Content.Find          # fresh Range + Find every iteration
+    f.ClearFormatting()
+    f.Forward = True
+    f.Wrap = 1                    # wdFindContinue
+    if not f.Execute(token):      # find ONLY — never pass Replace here
+        break
+    f.Parent.Text = value         # Parent IS the matched range
+```
+
+Subtleties that each cost a probe cycle:
+- Reusing one `Find` object across hits stops after the **first**
+  replacement (its internal range state is consumed by the hit).
+- A fresh `Find` from a *shared* Range object gets 2 of 3 — only a fresh
+  `doc.Content` per iteration is reliable.
+- `Wrap=0` (wdFindStop) under-counts; `Wrap=1` (continue) finds all.
+- A value that contains its own token would loop forever — cap iterations
+  and never interpolate data into `FindText`.
+- Same family trait: an un-saved doc's `Close()` can kill the whole app
+  instance (RPC_S_SERVER_UNAVAILABLE on the next property access) when the
+  instance is headless with zero documents. Keep a sentinel doc open
+  across multi-step scripts, `doc.Save()` before `Close(0)` when the doc
+  was just created, and treat `Quit` as best-effort (pitfall #2).
+
+## 15. `Cell.Text` does not exist on WPS-as-Word — read cells via
+## `Cell.Range.Text`
+
+Reading table cells with `table.Cell(r, c).Text` — the snippet every
+tutorial shows — raises `AttributeError: Cell.Text` on this engine
+family. The portable read is one indirection deeper:
+`table.Cell(r, c).Range.Text`, which returns the cell content with a
+`\r\x07` end-of-cell marker — strip `\x07` and `\r` (markdown-free cells
+matter for JSON output). Verified against a round-tripped legacy `.doc`:
+2×3 grid with CJK + decimal values reads back byte-perfect. Also: two
+`DispatchEx` launches inside one process can hard-segfault the second
+WPS instance (access violation in win32com) — probe scripts must reuse
+one app instance with a sentinel document.

docuhand-0.1.0.dev1/examples/hermes-config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "docuhand": {
+      "command": "D:/Repositories/docuhand/.venv/Scripts/pythonw.exe",
+      "args": ["-m", "docuhand"]
+    }
+  }
+}

docuhand-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "docuhand"
+version = "0.1.0.dev1"
+description = "Give your AI agent hands to operate real Word & WPS documents on Windows — an MCP server driving real Office apps via COM."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+dependencies = [
+    # MCP SDK: stay on 1.x — 2.x removed streamablehttp_client and broke
+    # HTTP MCP clients (lesson learned in the Hermes venv, 2026-09-10).
+    "mcp>=1.2,<2",
+    # pywin32: pinned <312 — 312+ breaks MCP tool discovery in the Hermes
+    # venv on this machine; 311 is fine for COM automation.
+    "olefile>=0.47",
+    "pywin32>=306,<312",
+]
+
+[project.scripts]
+docuhand = "docuhand.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/docuhand"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# A poisoned global PYTHONPATH (this dev box injects the Hermes venv) makes
+# a foreign venv's packages shadow our own via sys.path; tests/conftest.py
+# scrubs env + sys.path before any test imports mcp. The `com` marker keeps
+# COM integration tests out of the default run (`-m com` opts in).
+addopts = '-m "not com"'
+markers = [
+    "com: integration tests that drive real Word/WPS via COM (run locally with -m com, never in CI)",
+]

docuhand-0.1.0.dev1/scripts/check_word.ps1

@@ -0,0 +1,8 @@
+$procs = Get-Process WINWORD -ErrorAction SilentlyContinue
+if ($procs) {
+    $procs | ForEach-Object { Write-Output ("ORPHAN {0}" -f $_.Id) }
+    $procs | Stop-Process -Force
+    Write-Output "KILLED"
+} else {
+    Write-Output "no WINWORD running"
+}

docuhand-0.1.0.dev1/scripts/make_demo_docs.py

@@ -0,0 +1,67 @@
+"""Generate synthetic demo documents (no real/personal data) via real Word COM.
+
+Creates examples/demo-files/DocuHand_Demo.{doc,docx} — the files the
+end-to-end demo and integration tests run against.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import pythoncom
+import win32com.client
+
+DEMO_DIR = Path(__file__).resolve().parents[1] / "examples" / "demo-files"
+WD_FORMAT_DOC = 0
+WD_FORMAT_DOCX = 16
+WD_DO_NOT_SAVE = 0
+# Built-in style CONSTANTS are locale-independent; style *names* are not
+# ("Heading 1" breaks on Chinese-UI Word — it's "标题 1" there).
+WD_STYLE_NORMAL = -1
+WD_STYLE_HEADING1 = -2
+WD_STYLE_HEADING2 = -3
+
+TEXT = [
+    (WD_STYLE_HEADING1, "DocuHand Demo Document"),
+    (WD_STYLE_NORMAL, "This file is synthetic demo data generated for the DocuHand end-to-end test. It contains no real or personal information."),
+    (WD_STYLE_HEADING2, "Section 1: Format stress"),
+    (WD_STYLE_NORMAL, "A legacy .doc binary like this one is unreadable to XML-based libraries. DocuHand drives the real application instead."),
+    (WD_STYLE_NORMAL, "Chinese text sample: 文档体检 / 格式检测 / 锁定状态 — CJK content must survive every round trip."),
+    (WD_STYLE_HEADING2, "Section 2: Structure"),
+    (WD_STYLE_NORMAL, "The document carries a bookmark, a field code and multiple paragraphs so inspect_document has something real to report."),
+]
+
+
+def main() -> int:
+    DEMO_DIR.mkdir(parents=True, exist_ok=True)
+    pythoncom.CoInitialize()
+    word = win32com.client.DispatchEx("Word.Application")
+    word.Visible = False
+    word.DisplayAlerts = 0
+    try:
+        doc = word.Documents.Add()
+        sel = word.Selection
+        for style, text in TEXT:
+            sel.Style = doc.Styles(style)
+            sel.TypeText(text)
+            sel.TypeParagraph()
+        doc.Bookmarks.Add("DemoBookmark", doc.Paragraphs(2).Range)
+        doc.Fields.Add(doc.Paragraphs(1).Range, 33)  # 33 = wdFieldFileName
+
+        docx_path = DEMO_DIR / "DocuHand_Demo.docx"
+        doc.SaveAs2(str(docx_path), FileFormat=WD_FORMAT_DOCX)
+        print(f"[OK] {docx_path}")
+
+        doc.SaveAs2(str(DEMO_DIR / "DocuHand_Demo.doc"), FileFormat=WD_FORMAT_DOC)
+        print(f"[OK] {DEMO_DIR / 'DocuHand_Demo.doc'}")
+
+        doc.Close(WD_DO_NOT_SAVE)
+    finally:
+        word.Quit(WD_DO_NOT_SAVE)
+        pythoncom.CoUninitialize()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())