mcp-ms-office-documents: Instructions file for Codex

AGENTS.md

Operational brief for coding agents and humans alike. Rules here, reasons in docs/development/.

What this is

An MCP server (FastMCP 4, Python 3.12) that turns Markdown or structured input into Office files. Runs in Docker on port 8958, endpoint /mcp, streamable-HTTP. Entry point main.py. Six static tools (Word, Excel, PowerPoint, template listing, email, XML) plus dynamic tools registered from YAML templates.

Commands

pip install -r requirements-dev.txt
ruff check .                     # lint (CI)
pytest -m "not network"          # tests (CI); plain `pytest` includes network tests
pytest tests/test_docx_base.py   # one module
python main.py                   # run locally, no .env needed

Layout

main.py             tool handlers, startup order, health routes, server launch
config.py           the only module that reads os.environ; get_config() singleton
async_runner.py     run_blocking(): bounded thread pool for every blocking call
librechat_integration.py   request-header user context; upload_and_format_response()
upload_tools/       upload_file() / upload_file_async() dispatch; backends/<strategy>.py
template_utils.py   template file resolution (custom → default, container → local)
template_registry.py  YAML merging (master + *.d/) for specs and for the
                    kind-wide _global.yaml; live tool removal
inline_markdown.py  the inline-emphasis grammar shared by Word and PowerPoint
warning_channel.py  DocumentWarning + WarningChannel: what a build worked around
image_utils.py      image download/decode with the SSRF guard
metrics.py          in-process counters for the admin Status page
docx_tools/ xlsx_tools/ pptx_tools/ email_tools/ xml_tools/   one package per type
admin/              optional FastHTML admin UI (ADMIN_ENABLED); app.py holds
                    routes only — components.py (markup + theme),
                    sections.py (the product areas and their tabs), kinds.py
                    (dynamic kinds), base_templates.py (static base
                    templates), forms.py, views/ (views/sections.py = the
                    tabbed shell, Overview and the dashboard;
                    views/settings.py = the Word style mapping)
docs/               user reference (docs/*.md) and development docs (docs/development/)