ms-word-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ms_word_mcp-0.1.0/.github/workflows/publish.yml +65 -0
- ms_word_mcp-0.1.0/.github/workflows/release-tagged.yml +67 -0
- ms_word_mcp-0.1.0/.github/workflows/test.yml +55 -0
- ms_word_mcp-0.1.0/.gitignore +12 -0
- ms_word_mcp-0.1.0/LICENSE +21 -0
- ms_word_mcp-0.1.0/PKG-INFO +198 -0
- ms_word_mcp-0.1.0/README.md +171 -0
- ms_word_mcp-0.1.0/SECURITY.md +12 -0
- ms_word_mcp-0.1.0/docs/PROBES.md +336 -0
- ms_word_mcp-0.1.0/docs/ROADMAP.md +129 -0
- ms_word_mcp-0.1.0/docs/images/equation-numbers-mac.png +0 -0
- ms_word_mcp-0.1.0/docs/reference/equations.md +581 -0
- ms_word_mcp-0.1.0/docs/reference/math-autocorrect.json +558 -0
- ms_word_mcp-0.1.0/docs/reference/word-object-model.md +1824 -0
- ms_word_mcp-0.1.0/docs/research/similar-projects.md +44 -0
- ms_word_mcp-0.1.0/pyproject.toml +61 -0
- ms_word_mcp-0.1.0/scripts/live_check.py +1118 -0
- ms_word_mcp-0.1.0/scripts/probes/find_replace_speed.py +50 -0
- ms_word_mcp-0.1.0/scripts/probes/hyperlink_removal.py +42 -0
- ms_word_mcp-0.1.0/scripts/probes/mac_bulk_reads.py +62 -0
- ms_word_mcp-0.1.0/scripts/probes/mac_core.py +82 -0
- ms_word_mcp-0.1.0/scripts/probes/mac_equations.py +57 -0
- ms_word_mcp-0.1.0/scripts/probes/mac_floating_pictures.py +157 -0
- ms_word_mcp-0.1.0/scripts/probes/mac_layout.py +160 -0
- ms_word_mcp-0.1.0/scripts/probes/mac_notes_links.py +162 -0
- ms_word_mcp-0.1.0/scripts/probes/mac_shapes.py +243 -0
- ms_word_mcp-0.1.0/scripts/probes/mac_tables.py +104 -0
- ms_word_mcp-0.1.0/scripts/probes/mac_tables_inactive.py +109 -0
- ms_word_mcp-0.1.0/scripts/probes/nested_fields.py +119 -0
- ms_word_mcp-0.1.0/scripts/probes/numbered_headings.py +56 -0
- ms_word_mcp-0.1.0/scripts/probes/outline_speed.py +63 -0
- ms_word_mcp-0.1.0/scripts/probes/paragraph_read_speed.py +53 -0
- ms_word_mcp-0.1.0/scripts/probes/picture_crop.py +103 -0
- ms_word_mcp-0.1.0/scripts/probes/restart_numbering.py +77 -0
- ms_word_mcp-0.1.0/scripts/probes/shape_kinds.py +44 -0
- ms_word_mcp-0.1.0/scripts/probes/shape_look.py +64 -0
- ms_word_mcp-0.1.0/scripts/probes/shapes_windows.py +322 -0
- ms_word_mcp-0.1.0/scripts/probes/windows_checks.py +133 -0
- ms_word_mcp-0.1.0/scripts/probes/windows_equations.py +137 -0
- ms_word_mcp-0.1.0/scripts/probes/windows_layout.py +123 -0
- ms_word_mcp-0.1.0/scripts/probes/windows_math_autocorrect.py +34 -0
- ms_word_mcp-0.1.0/scripts/probes/windows_style_add.py +66 -0
- ms_word_mcp-0.1.0/scripts/probes/windows_style_steps.py +78 -0
- ms_word_mcp-0.1.0/scripts/probes/windows_tables.py +102 -0
- ms_word_mcp-0.1.0/scripts/probes/windows_undo_inactive.py +56 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/__init__.py +3 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/backend/__init__.py +27 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/backend/com.py +202 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/backend/documents.py +58 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/backend/mac.py +149 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/backend/worker.py +269 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/server.py +653 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/__init__.py +0 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/_common.py +196 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/_outline.py +121 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/_props.py +828 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/_word.py +404 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/documents.py +306 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/edit.py +54 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/equations.py +333 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/fields.py +537 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/formatting.py +539 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/latex.py +344 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/links.py +514 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/lists.py +416 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/mac.py +1196 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/notes.py +257 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/page.py +726 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/references.py +649 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/screen.py +269 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/shapes.py +1464 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/tables.py +1413 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/text.py +566 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/tools/view.py +147 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/utils/__init__.py +0 -0
- ms_word_mcp-0.1.0/src/ms_word_mcp/utils/offload.py +31 -0
- ms_word_mcp-0.1.0/tests/conftest.py +43 -0
- ms_word_mcp-0.1.0/tests/fakeword.py +978 -0
- ms_word_mcp-0.1.0/tests/test_com_undo.py +77 -0
- ms_word_mcp-0.1.0/tests/test_documents.py +135 -0
- ms_word_mcp-0.1.0/tests/test_fields.py +113 -0
- ms_word_mcp-0.1.0/tests/test_formatting.py +275 -0
- ms_word_mcp-0.1.0/tests/test_latex.py +47 -0
- ms_word_mcp-0.1.0/tests/test_links.py +189 -0
- ms_word_mcp-0.1.0/tests/test_lists.py +117 -0
- ms_word_mcp-0.1.0/tests/test_mac_parity.py +29 -0
- ms_word_mcp-0.1.0/tests/test_notes.py +110 -0
- ms_word_mcp-0.1.0/tests/test_outline.py +90 -0
- ms_word_mcp-0.1.0/tests/test_page_references.py +110 -0
- ms_word_mcp-0.1.0/tests/test_screen.py +20 -0
- ms_word_mcp-0.1.0/tests/test_server.py +214 -0
- ms_word_mcp-0.1.0/tests/test_shapes.py +443 -0
- ms_word_mcp-0.1.0/tests/test_tables.py +66 -0
- ms_word_mcp-0.1.0/tests/test_text.py +248 -0
- ms_word_mcp-0.1.0/tests/test_view.py +27 -0
- ms_word_mcp-0.1.0/tests/test_worker.py +133 -0
- ms_word_mcp-0.1.0/uv.lock +1507 -0
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
# Trigger: when a version tag (e.g. v1.2.3) is pushed to main
|
|
4
|
+
on:
|
|
5
|
+
push:
|
|
6
|
+
tags:
|
|
7
|
+
- 'v[0-9]*.[0-9]*.[0-9]*'
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
# ------------------------------------------------------------------ #
|
|
11
|
+
# Job 0: Gate the release on the same tests PRs run
|
|
12
|
+
# ------------------------------------------------------------------ #
|
|
13
|
+
test:
|
|
14
|
+
name: Tests
|
|
15
|
+
uses: ./.github/workflows/test.yml
|
|
16
|
+
|
|
17
|
+
# ------------------------------------------------------------------ #
|
|
18
|
+
# Job 1: Build the wheel and sdist
|
|
19
|
+
# ------------------------------------------------------------------ #
|
|
20
|
+
build:
|
|
21
|
+
name: Build distribution packages
|
|
22
|
+
needs: test
|
|
23
|
+
runs-on: ubuntu-latest
|
|
24
|
+
steps:
|
|
25
|
+
- uses: actions/checkout@v4
|
|
26
|
+
|
|
27
|
+
- name: Install uv
|
|
28
|
+
uses: astral-sh/setup-uv@v5
|
|
29
|
+
|
|
30
|
+
- name: Set up Python
|
|
31
|
+
run: uv python install
|
|
32
|
+
|
|
33
|
+
- name: Build wheel and sdist
|
|
34
|
+
run: uv build
|
|
35
|
+
|
|
36
|
+
- name: Upload build artifacts
|
|
37
|
+
uses: actions/upload-artifact@v4
|
|
38
|
+
with:
|
|
39
|
+
name: dist
|
|
40
|
+
path: dist/
|
|
41
|
+
|
|
42
|
+
# ------------------------------------------------------------------ #
|
|
43
|
+
# Job 2: Publish to PyPI via Trusted Publishing (OIDC — no token needed)
|
|
44
|
+
# ------------------------------------------------------------------ #
|
|
45
|
+
publish:
|
|
46
|
+
name: Publish to PyPI
|
|
47
|
+
needs: build
|
|
48
|
+
runs-on: ubuntu-latest
|
|
49
|
+
environment:
|
|
50
|
+
name: pypi
|
|
51
|
+
url: https://pypi.org/p/ms-word-mcp
|
|
52
|
+
|
|
53
|
+
# Required for OIDC Trusted Publishing
|
|
54
|
+
permissions:
|
|
55
|
+
id-token: write
|
|
56
|
+
|
|
57
|
+
steps:
|
|
58
|
+
- name: Download build artifacts
|
|
59
|
+
uses: actions/download-artifact@v4
|
|
60
|
+
with:
|
|
61
|
+
name: dist
|
|
62
|
+
path: dist/
|
|
63
|
+
|
|
64
|
+
- name: Publish to PyPI
|
|
65
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
name: Release is tagged
|
|
2
|
+
|
|
3
|
+
# A release reaches PyPI because a v* tag was pushed, and for no other reason.
|
|
4
|
+
# publish.yml listens for that tag and nothing else, so a version bump that
|
|
5
|
+
# arrives on main without one is a release that looks finished and was never
|
|
6
|
+
# published. That is what happened to v2.0.0: it sat on main for two days
|
|
7
|
+
# while PyPI stayed at 1.10.0, and it surfaced by accident while cutting the
|
|
8
|
+
# next release.
|
|
9
|
+
#
|
|
10
|
+
# This runs where someone is already looking, on the pull request that takes a
|
|
11
|
+
# release into main.
|
|
12
|
+
on:
|
|
13
|
+
pull_request:
|
|
14
|
+
branches: [main]
|
|
15
|
+
push:
|
|
16
|
+
branches: [main]
|
|
17
|
+
|
|
18
|
+
permissions:
|
|
19
|
+
contents: read
|
|
20
|
+
|
|
21
|
+
jobs:
|
|
22
|
+
tagged:
|
|
23
|
+
name: The version on main has a tag
|
|
24
|
+
runs-on: ubuntu-latest
|
|
25
|
+
steps:
|
|
26
|
+
# Every tag, and enough history to ask whether one is an ancestor.
|
|
27
|
+
- uses: actions/checkout@v4
|
|
28
|
+
with:
|
|
29
|
+
fetch-depth: 0
|
|
30
|
+
|
|
31
|
+
- name: The version in pyproject.toml is tagged
|
|
32
|
+
shell: bash
|
|
33
|
+
run: |
|
|
34
|
+
version=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
|
|
35
|
+
echo "pyproject.toml says $version"
|
|
36
|
+
|
|
37
|
+
if ! git rev-parse -q --verify "refs/tags/v$version" >/dev/null; then
|
|
38
|
+
echo "::error::No tag v$version. publish.yml only runs on a pushed" \
|
|
39
|
+
"tag, so this version would reach main without reaching PyPI." \
|
|
40
|
+
"Tag it on develop first: git tag v$version && git push origin v$version." \
|
|
41
|
+
"A tag does not rerun this check: rerun it on the pull request afterwards."
|
|
42
|
+
exit 1
|
|
43
|
+
fi
|
|
44
|
+
echo "tag v$version exists"
|
|
45
|
+
|
|
46
|
+
# Only on a pull request. A squash merge rewrites the commit, so on main
|
|
47
|
+
# itself the tag never points at anything here and asking would fail
|
|
48
|
+
# every release.
|
|
49
|
+
#
|
|
50
|
+
# The tag has to be the head of this branch, not merely somewhere in its
|
|
51
|
+
# history. Anything pushed after the tag was cut is absent from what
|
|
52
|
+
# publish.yml built, so the release on PyPI would be missing code that
|
|
53
|
+
# main is about to advertise as part of it.
|
|
54
|
+
- name: The tag is the commit being merged
|
|
55
|
+
if: github.event_name == 'pull_request'
|
|
56
|
+
shell: bash
|
|
57
|
+
env:
|
|
58
|
+
HEAD_SHA: ${{ github.event.pull_request.head.sha }}
|
|
59
|
+
run: |
|
|
60
|
+
version=$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)
|
|
61
|
+
tagged=$(git rev-parse "v$version^{commit}")
|
|
62
|
+
|
|
63
|
+
if [ "$tagged" != "$HEAD_SHA" ]; then
|
|
64
|
+
echo "::error::Tag v$version points at $tagged, and this branch is at $HEAD_SHA. Whatever came after the tag was not in what was published, so the release would be missing it. Tag the head of this branch and publish that."
|
|
65
|
+
exit 1
|
|
66
|
+
fi
|
|
67
|
+
echo "tag v$version is this branch's head, $tagged"
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
name: Tests
|
|
2
|
+
|
|
3
|
+
# Runs on every push and pull request, and is called by publish.yml so a
|
|
4
|
+
# release cannot ship without passing the same checks.
|
|
5
|
+
on:
|
|
6
|
+
push:
|
|
7
|
+
branches: [main, develop]
|
|
8
|
+
pull_request:
|
|
9
|
+
workflow_dispatch:
|
|
10
|
+
workflow_call:
|
|
11
|
+
|
|
12
|
+
permissions:
|
|
13
|
+
contents: read
|
|
14
|
+
|
|
15
|
+
jobs:
|
|
16
|
+
windows:
|
|
17
|
+
name: pytest (Windows, ${{ matrix.label }})
|
|
18
|
+
runs-on: windows-latest
|
|
19
|
+
strategy:
|
|
20
|
+
fail-fast: false
|
|
21
|
+
matrix:
|
|
22
|
+
include:
|
|
23
|
+
- label: locked
|
|
24
|
+
key: locked
|
|
25
|
+
run: uv run --frozen pytest -q
|
|
26
|
+
- label: mcp 1.x
|
|
27
|
+
key: mcp1
|
|
28
|
+
run: >-
|
|
29
|
+
uv run --no-project --with "mcp[cli]>=1.0,<2" --with "pywin32>=306"
|
|
30
|
+
--with "pydantic>=2" --with "anyio>=4" --with pytest python -m pytest -q
|
|
31
|
+
env:
|
|
32
|
+
PYTHONIOENCODING: utf-8
|
|
33
|
+
PYTHONUTF8: "1"
|
|
34
|
+
UV_PYTHON: "3.12"
|
|
35
|
+
steps:
|
|
36
|
+
- uses: actions/checkout@v4
|
|
37
|
+
- uses: astral-sh/setup-uv@v5
|
|
38
|
+
with:
|
|
39
|
+
cache-suffix: ${{ matrix.key }}
|
|
40
|
+
- run: uv python install 3.12
|
|
41
|
+
- run: ${{ matrix.run }}
|
|
42
|
+
|
|
43
|
+
macos:
|
|
44
|
+
name: pytest (macOS)
|
|
45
|
+
runs-on: macos-latest
|
|
46
|
+
timeout-minutes: 20
|
|
47
|
+
env:
|
|
48
|
+
UV_PYTHON: "3.12"
|
|
49
|
+
steps:
|
|
50
|
+
- uses: actions/checkout@v4
|
|
51
|
+
- uses: astral-sh/setup-uv@v5
|
|
52
|
+
with:
|
|
53
|
+
cache-suffix: macos
|
|
54
|
+
- run: uv python install 3.12
|
|
55
|
+
- run: uv run --frozen pytest -q -o faulthandler_timeout=120
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 ykuwai
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: ms-word-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Real-time Microsoft Word control on Windows and macOS: an MCP server that works in the document beside you
|
|
5
|
+
Project-URL: Homepage, https://github.com/ykuwai/ms-word-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/ykuwai/ms-word-mcp
|
|
7
|
+
Project-URL: Issues, https://github.com/ykuwai/ms-word-mcp/issues
|
|
8
|
+
Author: ykuwai
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: ai-agent,applescript,automation,com,llm,mcp,microsoft-word,word
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: MacOS :: MacOS X
|
|
16
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Topic :: Office/Business :: Office Suites
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Requires-Dist: anyio>=4.0.0
|
|
21
|
+
Requires-Dist: appscript>=1.4.0; sys_platform == 'darwin'
|
|
22
|
+
Requires-Dist: mcp[cli]<3.0.0,>=1.23.0
|
|
23
|
+
Requires-Dist: pydantic>=2.0.0
|
|
24
|
+
Requires-Dist: pyobjc-framework-quartz>=10.0; sys_platform == 'darwin'
|
|
25
|
+
Requires-Dist: pywin32>=306; sys_platform == 'win32'
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# ms-word-mcp
|
|
29
|
+
|
|
30
|
+
An MCP server that drives a live Microsoft Word on Windows and macOS, so an AI
|
|
31
|
+
can write and format a document while you work in it.
|
|
32
|
+
|
|
33
|
+
> **Status:** early release (0.x). Tool names and arguments may still change.
|
|
34
|
+
|
|
35
|
+
## What it is for
|
|
36
|
+
|
|
37
|
+
- **Working beside you.** Every write goes through a range, never through your
|
|
38
|
+
cursor or selection, so you can keep typing while the AI writes elsewhere in
|
|
39
|
+
the same document. The window scrolls to what it changed (`WORD_FOLLOW_EDITS`),
|
|
40
|
+
and each tool call is one Undo in Word.
|
|
41
|
+
- **Read back after every write.** A result says what Word actually holds now,
|
|
42
|
+
and lists as `warnings` whatever did not take.
|
|
43
|
+
- **Every script.** Latin, East Asian (Chinese, Japanese, Korean) and
|
|
44
|
+
complex-script (Arabic, Hebrew...) text each have their own font. East Asian
|
|
45
|
+
layouts get spacing in grid lines and indents in character widths, line
|
|
46
|
+
breaking rules, hanging punctuation and emphasis marks; lists can be
|
|
47
|
+
numbered in full-width digits, ①, 一, ア, 가, א, α, а and more. Vertical
|
|
48
|
+
text and ruby (furigana) too.
|
|
49
|
+
- **Styles first.** Every character and paragraph property can be set on a
|
|
50
|
+
style as well as on text, so a document's look is defined once.
|
|
51
|
+
- **Equations.** From LaTeX or UnicodeMath, built by Word's own equation
|
|
52
|
+
editor, numbered (1), (2)... at the right margin by fields that renumber
|
|
53
|
+
themselves.
|
|
54
|
+
- **Official sources.** Every member and constant is checked against
|
|
55
|
+
Microsoft's documentation
|
|
56
|
+
([docs/reference](https://github.com/ykuwai/ms-word-mcp/tree/main/docs/reference)),
|
|
57
|
+
and what the documentation leaves unstated is measured on a real Word
|
|
58
|
+
([docs/PROBES.md](https://github.com/ykuwai/ms-word-mcp/blob/main/docs/PROBES.md)).
|
|
59
|
+
|
|
60
|
+
## Tools
|
|
61
|
+
|
|
62
|
+
The server lists three tools by default (catalog mode): `word_describe` lists
|
|
63
|
+
the rest a line each and gives their arguments, `word_run` runs one and
|
|
64
|
+
`word_run_steps` runs several in order. Set `WORD_TOOL_MODE=full` to list
|
|
65
|
+
every tool instead.
|
|
66
|
+
|
|
67
|
+
| Area | Tools |
|
|
68
|
+
|---|---|
|
|
69
|
+
| Word and documents | `word_get_app_info`, `word_list_documents`, `word_activate_document`, `word_open_document`, `word_create_document`, `word_save_document`, `word_save_document_as` (also PDF), `word_close_document` |
|
|
70
|
+
| Reading | `word_get_document_info`, `word_get_outline`, `word_get_paragraphs` |
|
|
71
|
+
| Writing | `word_insert_paragraphs`, `word_set_paragraph_text`, `word_delete_paragraphs`, `word_find_replace` |
|
|
72
|
+
| Formatting | `word_format_text`, `word_set_paragraph_format` |
|
|
73
|
+
| Styles | `word_apply_style`, `word_list_styles`, `word_get_style`, `word_set_style` |
|
|
74
|
+
| Lists | `word_apply_list`, `word_set_list_level`, `word_restart_numbering`, `word_remove_list`, `word_get_list` |
|
|
75
|
+
| Tables | `word_insert_table`, `word_list_tables`, `word_get_table`, `word_set_table`, `word_set_table_cells`, `word_format_table_cells`, `word_insert_table_rows`, `word_delete_table_rows`, `word_insert_table_columns` (Windows), `word_delete_table_columns`, `word_merge_table_cells`, `word_delete_table` |
|
|
76
|
+
| Pictures, captions, cross-references | `word_insert_picture`, `word_list_pictures`, `word_set_picture`, `word_insert_caption`, `word_list_captions`, `word_insert_cross_reference` |
|
|
77
|
+
| The page | `word_get_page_setup`, `word_set_page_setup` (paper, margins, columns, document grid, vertical text), `word_get_headers_footers`, `word_set_header_footer`, `word_set_page_numbers`, `word_add_ruby` (furigana) |
|
|
78
|
+
| Equations | `word_insert_equation`, `word_list_equations`, `word_get_equation` |
|
|
79
|
+
| Floating shapes and pictures | `word_insert_shape`, `word_insert_text_box`, `word_insert_line`, `word_insert_floating_picture`, `word_list_shapes`, `word_set_shape`, `word_delete_shape` |
|
|
80
|
+
| Footnotes and endnotes | `word_insert_note`, `word_list_notes`, `word_set_note`, `word_delete_note` |
|
|
81
|
+
| Hyperlinks and bookmarks | `word_insert_hyperlink`, `word_list_hyperlinks`, `word_set_hyperlink`, `word_remove_hyperlink`, `word_add_bookmark`, `word_list_bookmarks`, `word_delete_bookmark` |
|
|
82
|
+
| Fields and tables of contents | `word_insert_table_of_contents`, `word_insert_field`, `word_list_fields`, `word_update_fields` |
|
|
83
|
+
| View | `word_get_view`, `word_set_view` |
|
|
84
|
+
| Seeing a page | `word_get_page_image`: a picture of a page as Word lays it out, so the model can check the layout |
|
|
85
|
+
| Undo | `word_undo`, `word_redo` |
|
|
86
|
+
|
|
87
|
+
Every tool that works on a document takes an optional `document` argument (a
|
|
88
|
+
full path or file name), so a call lands in the document it names whatever
|
|
89
|
+
another conversation has chosen.
|
|
90
|
+
|
|
91
|
+
## Setting it up
|
|
92
|
+
|
|
93
|
+
Requirements: Microsoft Word (Microsoft 365 or 2021+) on Windows 10/11 or
|
|
94
|
+
macOS, and [uv](https://docs.astral.sh/uv/).
|
|
95
|
+
|
|
96
|
+
Claude Code:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
claude mcp add word uvx ms-word-mcp
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Other clients (Claude Desktop, Cursor, `.mcp.json`):
|
|
103
|
+
|
|
104
|
+
```json
|
|
105
|
+
{
|
|
106
|
+
"mcpServers": {
|
|
107
|
+
"word": {
|
|
108
|
+
"command": "uvx",
|
|
109
|
+
"args": ["ms-word-mcp"]
|
|
110
|
+
}
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
## Settings
|
|
116
|
+
|
|
117
|
+
| Variable | Default | What it does |
|
|
118
|
+
|---|---|---|
|
|
119
|
+
| `WORD_TOOL_MODE` | `catalog` | `catalog` lists three tools that reach the rest; `full` lists every tool. |
|
|
120
|
+
| `WORD_MAC_FILES_DIR` | the document's folder | macOS: where Word writes the PDF a page picture is drawn from, for a moment. By default the document's own folder (Word already has access there), or Word's own folder for a document never saved. |
|
|
121
|
+
| `WORD_ALLOW_ACTIVE_FIELDS` | `off` | Allow fields that reach outside the document: INCLUDETEXT, INCLUDEPICTURE, INCLUDE, LINK, IMPORT, RD, EMBED, DATABASE, DDE, DDEAUTO, MACROBUTTON, PRINT, ASK, FILLIN. Off, `word_insert_field` refuses them and `word_update_fields` leaves the ones already in a document as they are. On, Word may stop and ask you about them in a dialog of its own, and the tool waits until you answer. |
|
|
122
|
+
| `WORD_ALLOW_NETWORK_PATHS` | `off` | Allow files named by a network path (`\\\\server\\share\\...`). Off, they are refused: saving to one sends the document to that server, and even checking for the file connects to it with your credentials. |
|
|
123
|
+
| `WORD_FOLLOW_EDITS` | `on` | Scroll the document's window to each change. With a second window open on the document (View > New Window), the last one follows and the first stays where you are. |
|
|
124
|
+
|
|
125
|
+
## Security
|
|
126
|
+
|
|
127
|
+
The server runs on your computer with your permissions and talks to one local
|
|
128
|
+
client over stdio; it opens no port and makes no network request of its own.
|
|
129
|
+
|
|
130
|
+
An AI using these tools can read and change any document open in Word, open
|
|
131
|
+
any file Word can open, and save or embed files wherever your account can
|
|
132
|
+
write or read. Text inside a document, a web page or another tool's answer can
|
|
133
|
+
try to steer the AI, so check what it does with documents you received from
|
|
134
|
+
someone else, and approve its tool calls where that matters.
|
|
135
|
+
|
|
136
|
+
What the server does about it:
|
|
137
|
+
|
|
138
|
+
- Macros are disabled while it opens a document or creates one from a template.
|
|
139
|
+
Word would otherwise run them. The document stays open with macros off.
|
|
140
|
+
- Fields that reach outside the document are refused and left alone unless you
|
|
141
|
+
set `WORD_ALLOW_ACTIVE_FIELDS` (see [Settings](#settings)).
|
|
142
|
+
- Network paths are refused unless you set `WORD_ALLOW_NETWORK_PATHS`.
|
|
143
|
+
- A new link goes to http, https, mailto or tel, or to a path relative to the
|
|
144
|
+
document. A link the document already has is left as it is.
|
|
145
|
+
|
|
146
|
+
What it does not do: a document opened through these tools does not get Word's
|
|
147
|
+
Protected View, so open only documents you would open yourself.
|
|
148
|
+
|
|
149
|
+
To report a vulnerability, see
|
|
150
|
+
[SECURITY.md](https://github.com/ykuwai/ms-word-mcp/blob/main/SECURITY.md).
|
|
151
|
+
|
|
152
|
+
## On macOS
|
|
153
|
+
|
|
154
|
+
- The first call asks for permission to control Microsoft Word (System
|
|
155
|
+
Settings > Privacy & Security > Automation).
|
|
156
|
+
- Word for Mac is sandboxed: it writes without asking only inside
|
|
157
|
+
`~/Library/Containers/com.microsoft.Word/Data/Documents`; saving elsewhere
|
|
158
|
+
may make Word ask for access.
|
|
159
|
+
- `word_get_page_image` has Word save a PDF next to the document for a moment
|
|
160
|
+
and draws the page from it. For a document never saved, the PDF goes in
|
|
161
|
+
Word's own folder, and macOS may ask once whether the app the server runs
|
|
162
|
+
in may read Word's data. On Windows the page comes from Word directly.
|
|
163
|
+
Neither captures the screen.
|
|
164
|
+
- Each change is its own Undo step (Word for Mac's scripting cannot group
|
|
165
|
+
them), and a style can be changed but not created. Tools say so in their
|
|
166
|
+
results.
|
|
167
|
+
- Word asks you about each file outside its own folder, so `word_insert_picture`
|
|
168
|
+
puts a copy in Word's folder for a moment and reads it there. The first time,
|
|
169
|
+
macOS may ask once whether the app the server runs in may use Word's data.
|
|
170
|
+
- Word for Mac makes a table only in the active document, so inserting a
|
|
171
|
+
table brings its document forward for a moment and then gives the
|
|
172
|
+
previously active one back. Columns cannot be added to a table there.
|
|
173
|
+
|
|
174
|
+
## Development
|
|
175
|
+
|
|
176
|
+
```bash
|
|
177
|
+
git clone https://github.com/ykuwai/ms-word-mcp.git
|
|
178
|
+
cd ms-word-mcp
|
|
179
|
+
uv sync
|
|
180
|
+
uv run pytest -q # no Word needed
|
|
181
|
+
uv run python scripts/live_check.py # runs every tool on a real Word, in a scratch document
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
The live check creates a document, runs the tools on it, prints PASS or FAIL
|
|
185
|
+
for each step, exports a PDF and closes the document. It touches no other
|
|
186
|
+
document.
|
|
187
|
+
|
|
188
|
+
On Windows, while a client has the server running, `uv sync` cannot replace
|
|
189
|
+
`.venv\Scripts\ms-word-mcp.exe`; run the tests with `uv run --no-sync`, or
|
|
190
|
+
stop the server first.
|
|
191
|
+
|
|
192
|
+
## Credits
|
|
193
|
+
|
|
194
|
+
Built with [ppt-mcp](https://github.com/ykuwai/ppt-mcp)'s design.
|
|
195
|
+
|
|
196
|
+
## License
|
|
197
|
+
|
|
198
|
+
MIT
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# ms-word-mcp
|
|
2
|
+
|
|
3
|
+
An MCP server that drives a live Microsoft Word on Windows and macOS, so an AI
|
|
4
|
+
can write and format a document while you work in it.
|
|
5
|
+
|
|
6
|
+
> **Status:** early release (0.x). Tool names and arguments may still change.
|
|
7
|
+
|
|
8
|
+
## What it is for
|
|
9
|
+
|
|
10
|
+
- **Working beside you.** Every write goes through a range, never through your
|
|
11
|
+
cursor or selection, so you can keep typing while the AI writes elsewhere in
|
|
12
|
+
the same document. The window scrolls to what it changed (`WORD_FOLLOW_EDITS`),
|
|
13
|
+
and each tool call is one Undo in Word.
|
|
14
|
+
- **Read back after every write.** A result says what Word actually holds now,
|
|
15
|
+
and lists as `warnings` whatever did not take.
|
|
16
|
+
- **Every script.** Latin, East Asian (Chinese, Japanese, Korean) and
|
|
17
|
+
complex-script (Arabic, Hebrew...) text each have their own font. East Asian
|
|
18
|
+
layouts get spacing in grid lines and indents in character widths, line
|
|
19
|
+
breaking rules, hanging punctuation and emphasis marks; lists can be
|
|
20
|
+
numbered in full-width digits, ①, 一, ア, 가, א, α, а and more. Vertical
|
|
21
|
+
text and ruby (furigana) too.
|
|
22
|
+
- **Styles first.** Every character and paragraph property can be set on a
|
|
23
|
+
style as well as on text, so a document's look is defined once.
|
|
24
|
+
- **Equations.** From LaTeX or UnicodeMath, built by Word's own equation
|
|
25
|
+
editor, numbered (1), (2)... at the right margin by fields that renumber
|
|
26
|
+
themselves.
|
|
27
|
+
- **Official sources.** Every member and constant is checked against
|
|
28
|
+
Microsoft's documentation
|
|
29
|
+
([docs/reference](https://github.com/ykuwai/ms-word-mcp/tree/main/docs/reference)),
|
|
30
|
+
and what the documentation leaves unstated is measured on a real Word
|
|
31
|
+
([docs/PROBES.md](https://github.com/ykuwai/ms-word-mcp/blob/main/docs/PROBES.md)).
|
|
32
|
+
|
|
33
|
+
## Tools
|
|
34
|
+
|
|
35
|
+
The server lists three tools by default (catalog mode): `word_describe` lists
|
|
36
|
+
the rest a line each and gives their arguments, `word_run` runs one and
|
|
37
|
+
`word_run_steps` runs several in order. Set `WORD_TOOL_MODE=full` to list
|
|
38
|
+
every tool instead.
|
|
39
|
+
|
|
40
|
+
| Area | Tools |
|
|
41
|
+
|---|---|
|
|
42
|
+
| Word and documents | `word_get_app_info`, `word_list_documents`, `word_activate_document`, `word_open_document`, `word_create_document`, `word_save_document`, `word_save_document_as` (also PDF), `word_close_document` |
|
|
43
|
+
| Reading | `word_get_document_info`, `word_get_outline`, `word_get_paragraphs` |
|
|
44
|
+
| Writing | `word_insert_paragraphs`, `word_set_paragraph_text`, `word_delete_paragraphs`, `word_find_replace` |
|
|
45
|
+
| Formatting | `word_format_text`, `word_set_paragraph_format` |
|
|
46
|
+
| Styles | `word_apply_style`, `word_list_styles`, `word_get_style`, `word_set_style` |
|
|
47
|
+
| Lists | `word_apply_list`, `word_set_list_level`, `word_restart_numbering`, `word_remove_list`, `word_get_list` |
|
|
48
|
+
| Tables | `word_insert_table`, `word_list_tables`, `word_get_table`, `word_set_table`, `word_set_table_cells`, `word_format_table_cells`, `word_insert_table_rows`, `word_delete_table_rows`, `word_insert_table_columns` (Windows), `word_delete_table_columns`, `word_merge_table_cells`, `word_delete_table` |
|
|
49
|
+
| Pictures, captions, cross-references | `word_insert_picture`, `word_list_pictures`, `word_set_picture`, `word_insert_caption`, `word_list_captions`, `word_insert_cross_reference` |
|
|
50
|
+
| The page | `word_get_page_setup`, `word_set_page_setup` (paper, margins, columns, document grid, vertical text), `word_get_headers_footers`, `word_set_header_footer`, `word_set_page_numbers`, `word_add_ruby` (furigana) |
|
|
51
|
+
| Equations | `word_insert_equation`, `word_list_equations`, `word_get_equation` |
|
|
52
|
+
| Floating shapes and pictures | `word_insert_shape`, `word_insert_text_box`, `word_insert_line`, `word_insert_floating_picture`, `word_list_shapes`, `word_set_shape`, `word_delete_shape` |
|
|
53
|
+
| Footnotes and endnotes | `word_insert_note`, `word_list_notes`, `word_set_note`, `word_delete_note` |
|
|
54
|
+
| Hyperlinks and bookmarks | `word_insert_hyperlink`, `word_list_hyperlinks`, `word_set_hyperlink`, `word_remove_hyperlink`, `word_add_bookmark`, `word_list_bookmarks`, `word_delete_bookmark` |
|
|
55
|
+
| Fields and tables of contents | `word_insert_table_of_contents`, `word_insert_field`, `word_list_fields`, `word_update_fields` |
|
|
56
|
+
| View | `word_get_view`, `word_set_view` |
|
|
57
|
+
| Seeing a page | `word_get_page_image`: a picture of a page as Word lays it out, so the model can check the layout |
|
|
58
|
+
| Undo | `word_undo`, `word_redo` |
|
|
59
|
+
|
|
60
|
+
Every tool that works on a document takes an optional `document` argument (a
|
|
61
|
+
full path or file name), so a call lands in the document it names whatever
|
|
62
|
+
another conversation has chosen.
|
|
63
|
+
|
|
64
|
+
## Setting it up
|
|
65
|
+
|
|
66
|
+
Requirements: Microsoft Word (Microsoft 365 or 2021+) on Windows 10/11 or
|
|
67
|
+
macOS, and [uv](https://docs.astral.sh/uv/).
|
|
68
|
+
|
|
69
|
+
Claude Code:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
claude mcp add word uvx ms-word-mcp
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Other clients (Claude Desktop, Cursor, `.mcp.json`):
|
|
76
|
+
|
|
77
|
+
```json
|
|
78
|
+
{
|
|
79
|
+
"mcpServers": {
|
|
80
|
+
"word": {
|
|
81
|
+
"command": "uvx",
|
|
82
|
+
"args": ["ms-word-mcp"]
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
## Settings
|
|
89
|
+
|
|
90
|
+
| Variable | Default | What it does |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `WORD_TOOL_MODE` | `catalog` | `catalog` lists three tools that reach the rest; `full` lists every tool. |
|
|
93
|
+
| `WORD_MAC_FILES_DIR` | the document's folder | macOS: where Word writes the PDF a page picture is drawn from, for a moment. By default the document's own folder (Word already has access there), or Word's own folder for a document never saved. |
|
|
94
|
+
| `WORD_ALLOW_ACTIVE_FIELDS` | `off` | Allow fields that reach outside the document: INCLUDETEXT, INCLUDEPICTURE, INCLUDE, LINK, IMPORT, RD, EMBED, DATABASE, DDE, DDEAUTO, MACROBUTTON, PRINT, ASK, FILLIN. Off, `word_insert_field` refuses them and `word_update_fields` leaves the ones already in a document as they are. On, Word may stop and ask you about them in a dialog of its own, and the tool waits until you answer. |
|
|
95
|
+
| `WORD_ALLOW_NETWORK_PATHS` | `off` | Allow files named by a network path (`\\\\server\\share\\...`). Off, they are refused: saving to one sends the document to that server, and even checking for the file connects to it with your credentials. |
|
|
96
|
+
| `WORD_FOLLOW_EDITS` | `on` | Scroll the document's window to each change. With a second window open on the document (View > New Window), the last one follows and the first stays where you are. |
|
|
97
|
+
|
|
98
|
+
## Security
|
|
99
|
+
|
|
100
|
+
The server runs on your computer with your permissions and talks to one local
|
|
101
|
+
client over stdio; it opens no port and makes no network request of its own.
|
|
102
|
+
|
|
103
|
+
An AI using these tools can read and change any document open in Word, open
|
|
104
|
+
any file Word can open, and save or embed files wherever your account can
|
|
105
|
+
write or read. Text inside a document, a web page or another tool's answer can
|
|
106
|
+
try to steer the AI, so check what it does with documents you received from
|
|
107
|
+
someone else, and approve its tool calls where that matters.
|
|
108
|
+
|
|
109
|
+
What the server does about it:
|
|
110
|
+
|
|
111
|
+
- Macros are disabled while it opens a document or creates one from a template.
|
|
112
|
+
Word would otherwise run them. The document stays open with macros off.
|
|
113
|
+
- Fields that reach outside the document are refused and left alone unless you
|
|
114
|
+
set `WORD_ALLOW_ACTIVE_FIELDS` (see [Settings](#settings)).
|
|
115
|
+
- Network paths are refused unless you set `WORD_ALLOW_NETWORK_PATHS`.
|
|
116
|
+
- A new link goes to http, https, mailto or tel, or to a path relative to the
|
|
117
|
+
document. A link the document already has is left as it is.
|
|
118
|
+
|
|
119
|
+
What it does not do: a document opened through these tools does not get Word's
|
|
120
|
+
Protected View, so open only documents you would open yourself.
|
|
121
|
+
|
|
122
|
+
To report a vulnerability, see
|
|
123
|
+
[SECURITY.md](https://github.com/ykuwai/ms-word-mcp/blob/main/SECURITY.md).
|
|
124
|
+
|
|
125
|
+
## On macOS
|
|
126
|
+
|
|
127
|
+
- The first call asks for permission to control Microsoft Word (System
|
|
128
|
+
Settings > Privacy & Security > Automation).
|
|
129
|
+
- Word for Mac is sandboxed: it writes without asking only inside
|
|
130
|
+
`~/Library/Containers/com.microsoft.Word/Data/Documents`; saving elsewhere
|
|
131
|
+
may make Word ask for access.
|
|
132
|
+
- `word_get_page_image` has Word save a PDF next to the document for a moment
|
|
133
|
+
and draws the page from it. For a document never saved, the PDF goes in
|
|
134
|
+
Word's own folder, and macOS may ask once whether the app the server runs
|
|
135
|
+
in may read Word's data. On Windows the page comes from Word directly.
|
|
136
|
+
Neither captures the screen.
|
|
137
|
+
- Each change is its own Undo step (Word for Mac's scripting cannot group
|
|
138
|
+
them), and a style can be changed but not created. Tools say so in their
|
|
139
|
+
results.
|
|
140
|
+
- Word asks you about each file outside its own folder, so `word_insert_picture`
|
|
141
|
+
puts a copy in Word's folder for a moment and reads it there. The first time,
|
|
142
|
+
macOS may ask once whether the app the server runs in may use Word's data.
|
|
143
|
+
- Word for Mac makes a table only in the active document, so inserting a
|
|
144
|
+
table brings its document forward for a moment and then gives the
|
|
145
|
+
previously active one back. Columns cannot be added to a table there.
|
|
146
|
+
|
|
147
|
+
## Development
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
git clone https://github.com/ykuwai/ms-word-mcp.git
|
|
151
|
+
cd ms-word-mcp
|
|
152
|
+
uv sync
|
|
153
|
+
uv run pytest -q # no Word needed
|
|
154
|
+
uv run python scripts/live_check.py # runs every tool on a real Word, in a scratch document
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
The live check creates a document, runs the tools on it, prints PASS or FAIL
|
|
158
|
+
for each step, exports a PDF and closes the document. It touches no other
|
|
159
|
+
document.
|
|
160
|
+
|
|
161
|
+
On Windows, while a client has the server running, `uv sync` cannot replace
|
|
162
|
+
`.venv\Scripts\ms-word-mcp.exe`; run the tests with `uv run --no-sync`, or
|
|
163
|
+
stop the server first.
|
|
164
|
+
|
|
165
|
+
## Credits
|
|
166
|
+
|
|
167
|
+
Built with [ppt-mcp](https://github.com/ykuwai/ppt-mcp)'s design.
|
|
168
|
+
|
|
169
|
+
## License
|
|
170
|
+
|
|
171
|
+
MIT
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
Please report a vulnerability privately, through
|
|
4
|
+
[GitHub's private vulnerability reporting](https://github.com/ykuwai/ms-word-mcp/security/advisories/new),
|
|
5
|
+
rather than in a public issue. Say what an attacker can do, and how to
|
|
6
|
+
reproduce it.
|
|
7
|
+
|
|
8
|
+
Only the latest release and the `main` branch are supported. The project is
|
|
9
|
+
pre-release, so fixes land there first.
|
|
10
|
+
|
|
11
|
+
What the server protects against, and what it leaves to you, is in the
|
|
12
|
+
[Security section of the README](README.md#security).
|