TianshangScribe
The server provides 7 MCP tools for creating, editing, templating, converting, extracting, validating, and comparing Office documents (Word, Excel, PowerPoint).
Create new .docx/.xlsx/.pptx files from structured content blocks (headings, paragraphs, formulas, tables, images) with LaTeX-style markup and math formulas.
Edit existing documents via ordered operations: replace, delete, modify, style, add text, or clear; supports regex and in-place overwrite with backup option.
Fill templates with JSON data: {{placeholders}}, {{#each}} loops, {{#if}}/{{#unless}} conditions; writes a new file without modifying the template.
Convert documents: Word↔PDF/Markdown/HTML, Excel↔PDF/CSV/JSON/HTML, PowerPoint→PDF.
Extract metadata, text, or structure (paragraphs/sheets/slides) from any supported document.
Validate templates before filling to catch missing keys and unresolved placeholders.
Compare two .docx files at paragraph level (add/remove/change), plus snapshot/restore document states.
All tools support optional dry-run, backup, and deterministic IDs; read‑only tools (extract, validate) never modify inputs.
Allows Coze agents to create, edit, template-fill, and convert Word, Excel, and PowerPoint documents, including LaTeX-style markup and math formula rendering.
TianshangScribe
Cross-platform Office document processing for developers, CLI automation, and AI agents. Create, edit, template-fill, and convert Word (.docx), Excel (.xlsx), and PowerPoint (.pptx) documents, with LaTeX-style markup, native OMML math formulas, and a template engine ({{placeholders}}, {{#each}} loops, {{#if}} conditions). Ships an MCP Server with 14 tools (7 unified + 7 dedicated Excel/PPT tools) over stdio, SSE, and Streamable HTTP transports, with bearer-token auth and rate limiting.
Warning: Unstable API \u2014 breaking changes expected
This project is pre-1.0 (0.x). The CLI options, MCP tool signatures, template syntax, and output formats are not frozen and may change without notice. Compatibility commitment: any breaking change will be announced in the CHANGELOG at least one release in advance and accompanied by a migration guide. For production use, pin to a specific version and review the CHANGELOG before upgrading.
Install
pip install tianshang-scribe
# Or from source:
git clone https://github.com/Tianshang301/TianshangScribe.git
cd TianshangScribe
pip install -e ".[dev]"Linux Deployment
Docker (recommended for MCP Server over Streamable HTTP):
git clone https://github.com/Tianshang301/TianshangScribe.git
cd TianshangScribe
docker compose up -d
# Streamable HTTP MCP Server at http://localhost:8080/mcp
# (override transport / auth / rate limits via TIANSHANG_SCRIBE_* env vars).deb package (Debian / Ubuntu):
# Download from GitHub Releases
sudo dpkg -i tianshang-scribe_0.8.0_all.deb
tianshang-scribe --helppipx (isolated CLI):
pipx install tianshang-scribe
tianshang-scribe --helpRequires Python 3.10+ · python-docx · openpyxl · python-pptx · typer · rich · lxml
Related MCP server: docx-forge-mcp
Quick Start
# Create a Word document
tianshang-scribe -w --create -a "Hello World" -o hello.docx
# Replace text (--regex for regex mode)
tianshang-scribe input.docx -r "old" --replace-new "new" -o output.docx
# LaTeX markup with nesting
tianshang-scribe -w --create --latex-style \
-s "font=Times New Roman,size=14" \
-a "\bfseries{\itshape{bold italic}} \fontsize{24}{Heading} \color{FF0000}{red}" \
-o styled.docx
# Math formulas —auto-converted to native Word OMML
tianshang-scribe -w --create \
--math "x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}" \
--math "\sum_{i=0}^{n} i^2" \
-o formulas.docx
# Template filling (JSON / CSV / YAML →{{placeholder}})
tianshang-scribe template.docx -t data.json -o filled.docx
# Convert to PDF (office2pdf ~2MB, or LibreOffice fallback)
tianshang-scribe input.docx --topdf -o output.pdf
# MCP Server —stdio mode (Claude Code / Cursor)
python -m tianshang_scribe.mcp.server
# MCP Server —SSE mode (Dify / Coze / FastGPT)
python -m tianshang_scribe.mcp.server --transport sse --port 8080
# Excel: import CSV, sort, export JSON
tianshang-scribe -e --create --from-csv data.csv --sort "A1:A10 asc" --to-json -o out.json
# Excel: add formula, protect workbook
tianshang-scribe budget.xlsx --formula "B10 =SUM(B2:B9)" --protect "p@ss" -o protected.xlsxGlobal Options
Parameter | Description |
| Input document path (omit with |
| Process Word document |
| Process Excel workbook |
| Process PowerPoint presentation |
| Output file path |
| Allow overwriting existing files |
| Output as PDF |
| Read from standard input |
| Write to standard output |
When -w/-e/-p is omitted, the document type is inferred from the input file extension.
Operations
Option | Description | Example |
| Create blank document |
|
| Add text |
|
| Target column for |
|
| Find and replace |
|
| Delete content |
|
| Clear content / formats / links |
|
| Modify content |
|
| Set style |
|
| Template filling |
|
| Extract data ( |
|
| Set properties |
|
| Enable LaTeX parsing | |
| Add math formula (Word) |
|
| Math parsing dialect (office/mathtype) |
|
| OMML math font (default Cambria Math) |
|
| Embed as MathType OLE object (MTEF) |
|
| Add heading (Word) |
|
| Regex mode | Use with |
| Merge files |
|
| Split document (Excel only: |
|
| Add comment (Word) / speaker notes (PPT) |
|
| Add table (Word) |
|
| Add chart (Excel) |
|
| Batch mode |
|
| Glob pattern for batch |
|
| Schedule SQLite DB path |
|
| Register schedule |
|
| Remove schedule |
|
| List schedules |
|
| Run schedule now |
|
| Run due schedules |
|
| Run script in sandbox |
|
| Read from stdin | |
| Write to stdout |
Word-Specific Options
Option | Description | Example |
| Add heading |
|
| Add math formula |
|
| Enable LaTeX markup | |
| Generate table of contents |
|
| Insert section break |
|
| Set page header |
|
| Set page footer |
|
| Text watermark |
|
| Convert to Markdown |
|
| Convert to HTML |
|
Excel-Specific Options
Option | Description | Example |
| Add worksheet |
|
| Delete worksheet |
|
| Rename worksheet |
|
| Set column width |
|
| Set row height |
|
| Set cell formula |
|
| Import CSV data |
|
| Sort range |
|
| Add chart |
|
| Freeze panes |
|
| Set number format |
|
| Conditional format |
|
| Data validation |
|
| Set password |
|
| Remove password |
|
| Export as CSV | |
| Export as JSON | |
| Export as HTML |
LaTeX Style Markup
Embed the following markup in --add content. Enable with --latex-style. Supports nesting.
Syntax | Effect |
| Bold |
| Italic |
| Small caps |
| Underline |
| Roman (serif) |
| Sans-serif |
| Monospace |
| Specific font |
| Font size (pt) |
| Color (hex) |
| Center align **—* |
| Left align **—* |
| Right align **—* |
| Line spacing **—* |
| Indent **—* |
| Insert heading |
| Page break |
| Insert image |
**—* Paragraph-level formatting (creates a new paragraph).
Font Configuration
Command | Effect |
| Default Western font |
| Default CJK font |
| Sans-serif font |
| CJK sans-serif font |
| Monospace font |
| CJK monospace font |
Word OOXML natively separates w:ascii (Western) and w:eastAsia (CJK) fonts, enabling automatic font switching in mixed-script text.
Math Formulas
LaTeX math formulas via --math are converted to native Word OMML (Office Math Markup Language). The converter is a hand-written recursive-descent parser (expression → term → factor → atom) over a nested, immutable token tree (fraction, root, N-ary, sub/sup, accent, styled, delimiter tokens), dispatched through an O(1) command table with precompiled regexes and zero-copy argument slicing. Use --math-font "Times New Roman" to render equations with a MathType-style serif font instead of Word's default Cambria Math (<m:mathPr><m:mathFont>). --math-style mathtype switches the LaTeX parsing dialect for MathType compatibility. Use --math-mtef to embed the formula as a real MathType OLE object (MTEF binary) instead — editable by legacy MathType (6.x and earlier), the same format --extract math reads back. Output is byte-for-byte stable across releases (guarded by a golden-snapshot regression suite).
Supported Syntax
Category | Commands |
Fractions |
|
Roots |
|
Sup/Subscripts |
|
Sums/Integrals |
|
Limits |
|
Named Functions |
|
Greek Letters |
|
Symbols |
|
Relations |
|
Arrows |
|
Accents |
|
Brackets |
|
Math Fonts |
|
Math Typography
Conforms to mainstream math journal standards (AMS, Elsevier, Springer):
Content | Style | Example |
Single-letter variables | Italic |
|
Digits | Upright |
|
Named functions | Upright |
|
Lowercase Greek | Italic |
|
Uppercase Greek | Upright |
|
Auto-Detection
Commands in --add text are automatically recognized as math even without $...$ wrapping:
With arguments:
\frac\sqrt\sum\int\prod\limAccents:
\hat{x}\bar{x}\vec{x}etc.Unary operators:
\sin\cos\tan\log\lnetc.H_{2}Oandm^{2}in plain text become Unicode sub/superscripts (H₂O / m²)
Style Syntax
--style uses comma-separated key-value pairs:
--style "font=Times New Roman,size=14,bold,italic,color=FF0000,align=center"Key | Aliases | Value | Description |
|
| Font name | Western font |
|
| Font name | CJK font |
|
| pt | Font size |
| flag | Bold | |
| flag | Italic | |
| flag | Underline | |
|
|
| Hex color |
|
|
| Alignment |
Boolean keys (bold italic underline) are True when present.
Template Filling
Supports JSON, CSV, and YAML data sources. Replaces {{placeholder}} in documents. Nested objects expand with dot notation. Loops iterate over list values. Conditionals show/hide blocks.
{
"name": "John Doe",
"date": "2026-07-28",
"user": { "city": "Beijing" },
"show": true,
"paid": false,
"items": [
{ "product": "Widget", "price": "10" },
{ "product": "Gadget", "price": "20" }
]
}{{name}} → John Doe
{{user.city}} → Beijing
{{#each items}} → repeats the block for each item
{{product}}: {{price}}
{{/each}}
{{#if show}} → shown only when show is truthy
Confidential content
{{/if}}
{{#if role=admin}} → shown only when role equals "admin"
Admin dashboard
{{/if}}
{{#unless paid}} → shown only when paid is falsy
Payment required
{{/unless}}Excel Features
Feature | CLI Option |
Sheet management |
|
Column/row sizing |
|
Formulas |
|
Data import |
|
Data export |
|
Sorting |
|
Charts |
|
Protection |
|
PPT Features
Feature | Description |
Slide management | Add, delete, reorder slides ( |
Layouts | Apply slide layouts by name or index ( |
Speaker notes | Add presenter notes ( |
Math formulas |
|
Transitions | Set slide transitions —fade, push, wipe, etc. ( |
Export | Save slides as images ( |
Media compression | Compress images ( |
Tables & charts | Insert table/chart on the last slide ( |
Protection | Set/remove password ( |
Interactive Session (open)
tianshang-scribe open <file> [--latex-style] [--env-file <file>] [-w|-e|-p] opens a document in an interactive REPL that holds it in memory; save persists, quit prompts on unsaved changes.
doc.docx> add "Hello"
doc.docx> table @data.csv # relative paths resolve against the document's directory
doc.docx> env alias h1 "heading 1" # define a command alias
doc.docx> h1 "Summary" # use it immediately
doc.docx> save
doc.docx> quitCommands: add heading table math replace delete style extract info path save env help quit.
The session automatically enters the document's directory on start (restored on exit), so @data.csv, path out.docx, and save rel.docx all resolve relative to the document.
REPL environment files configure defaults per project or user. Load order: --env-file wins, then <project>/.scribe/repl.rc over ~/.tianshang-scribe/repl.rc.
[repl]
latex_style = true
[aliases]
h1 = heading 1
[startup]
commands = style font=Times New Roman,size=12,cjk-font=SimSun
latex onenvshows the current environment;env alias <name> <command...>/env unalias <name>manage aliases at runtime.Default fonts go through
[startup]stylecommands (set_stylemerges persistently);[repl]only holdslatex_style.
Exit Codes
Code | Meaning |
| Success |
| General error |
| Argument error |
| Not implemented |
MCP Server
TianshangScribe includes an MCP (Model Context Protocol) server —AI Agents can create, edit, fill templates, convert, and extract data from Office documents.
Quick Connect
stdio (Claude Code, Cursor):
{"mcpServers": {"tianshang-scribe": {
"command": "python", "args": ["-m", "tianshang_scribe.mcp.server"]
}}}SSE (Dify, Coze, FastGPT):
python -m tianshang_scribe.mcp.server --transport sse --host 0.0.0.0 --port 8080{"mcpServers": {"tianshang-scribe": {
"url": "http://localhost:8080/sse", "transport": "sse"
}}}Tools (14)
Tool | Description |
| Create .docx / .xlsx / .pptx with structured content blocks |
| Replace, delete, modify, style, add operations on existing docs |
| Fill |
| Convert between formats (docx↔pdf/md/html, xlsx↔csv/json) |
| Extract metadata, full text, or document structure |
| Pre-check template placeholders against data before filling |
| Paragraph-level diff between two .docx files |
| Create .xlsx from typed sheet specs (headers/rows/formulas/formats) |
| Typed Excel ops: write_cell, set_formula, sort, add_sheet, … |
| Create .pptx from typed slide specs (title/bullets/table/chart) |
| Typed PPT ops: add_slide, add_text, add_table, add_chart, … |
| Read-only workbook profiling: types, nulls, duplicates, samples |
Capabilities
Feature | Detail |
Protocol | MCP 2024-11-05 · stdio + SSE · JSON-RPC 2.0 |
Resources |
|
Prompts | 5 built-in workflow templates ( |
Progress |
|
Response | Multi-type |
Schema |
|
Production (SSE only)
# With authentication
TIANSHANG_SCRIBE_AUTH_TOKEN="secret" \
python -m tianshang_scribe.mcp.server --transport sse --host 0.0.0.0 --port 8080
# Health check
curl http://localhost:8080/health
# {"status":"ok","version":"0.9.0","uptime_seconds":3600,"active_sessions":3,"tools_available":14}
# CORS whitelist
python -m tianshang_scribe.mcp.server --transport sse --cors-origins "https://coze.com,https://dify.ai"Endpoints: GET /health · GET /sse · POST /message?session_id=X
Full documentation: docs/mcp/README.md.
python tests/integration/mcp/mcp_stdio_smoke.py # 9/9 quick tests (stdio)
python tests/integration/mcp/test_sse.py # 3/3 SSE transport tests
python tests/integration/mcp/mcp_agent_sim.py # 11-scenario Agent simulationArchitecture
src/
└── tianshang_scribe/ # importable package (tianshang_scribe.*)
├── cli/ # Typer CLI entry
│ ├── main.py # Command parsing & dispatch
│ └── global_opts.py # File path / type inference
├── core/ # Document engine abstraction
│ ├── document.py # DocumentABC unified interface
│ ├── word_engine.py # Word engine (python-docx)
│ ├── excel_engine.py# Excel engine (openpyxl)
│ └── ppt_engine.py # PPT engine (python-pptx)
├── rendering/ # Style & formula rendering
│ ├── styles.py # TextStyle dataclass
│ ├── latex_parser.py # LaTeX markup parser
│ ├── math_omml.py # LaTeX →OMML math converter
│ └── template.py # Template filling engine
├── transform/ # Format conversion
│ └── pdf.py # PDF export (office2pdf + LibreOffice)
├── mcp/ # MCP Server (official mcp SDK 2.x)
│ ├── server.py # build_server + entry (stdio / SSE / Streamable HTTP)
│ ├── transport.py # transport wiring + ASGI middleware
│ ├── schemas.py # pydantic models + as_dict
│ ├── auth.py # Bearer token auth
│ ├── rate_limit.py # token bucket rate limiting
│ ├── metrics.py # Prometheus-style metrics
│ ├── security.py # read-only / destructive classification
│ ├── prompts.py # 5 prompt workflows
│ ├── tools/ # 14 Agent tools (7 unified + 7 dedicated)
│ │ ├── _registry.py # tool registry (schemas auto-derived)
│ │ ├── _dedicated_schemas.py # typed param models for dedicated tools
│ │ ├── create.py / edit.py / template.py / convert.py
│ │ ├── validate.py / compare.py
│ │ ├── excel_create.py / excel_edit.py / analyze_excel.py
│ │ └── ppt_create.py / ppt_edit.py
│ └── errors.py # structured error codes + fixes
└── utils/ # Utility functions
└── file_utils.pyTech Stack
Component | Technology |
CLI | Typer + Rich |
Word | python-docx |
Excel | openpyxl |
PPT | python-pptx |
Math | Hand-written recursive-descent parser → OMML XML (immutable token tree, command dispatch table) |
Templates | Custom engine ({{placeholder}}, {{#each}}, {{#if}}) |
office2pdf (~2MB Rust binary, zero deps) + LibreOffice fallback | |
Quality | pytest (936 tests) · ruff · mypy |
Build EXE
pip install pyinstaller
pyinstaller --onefile --name tianshang-scribe --hidden-import openpyxl.cell._writer --hidden-import openpyxl.cell.read_only --hidden-import openpyxl.styles --hidden-import openpyxl.chart --hidden-import openpyxl.comments src/tianshang_scribe/cli/main.py
# dist/tianshang-scribe.exe (~35 MB)Demo
python -m demo.generate_demos
# demo/demo_word.docx —LaTeX + math + TOC + watermark
# demo/demo_excel.xlsx —CSV import + formulas + chart + protection
# demo/demo_ppt.pptx —slides + notes + transitions + math formulasCLI compliance test:
python demo/test_cli.pyDevelopment
git clone https://github.com/Tianshang301/TianshangScribe.git
cd TianshangScribe
pip install -e ".[dev]"
pytest tests/ -v # Run tests
ruff check src/tianshang_scribe/ tests/ # Lint
mypy src/tianshang_scribe/ # Type checkLicense
Apache-2.0
Maintenance
Related MCP Servers
- AlicenseBqualityDmaintenanceA universal MCP server for document processing, conversion, and automation. Handle PDF, DOCX, HTML, Markdown, and more through a unified API and toolset.1333139MIT
- AlicenseAqualityDmaintenanceMCP server for Word document (.docx) creation and manipulation — the production-grade document automation tool for AI agents.938MIT
- AlicenseAqualityBmaintenanceMCP server for reading, writing, editing, formatting, and exporting Microsoft Office documents (Word, Excel, PowerPoint) via stdio JSON-RPC, with 47 tools and cross-platform support.47MIT
- AlicenseCqualityDmaintenanceA unified MCP server for document processing that enables creating, editing, and converting Word documents (DOCX), PDFs, Markdown, and images, with support for templates, formatting, and batch operations.100MIT
Related MCP Connectors
Generate PDF/DOCX/XLSX/PPTX from templates+JSON. Convert Office/HTML/MD to PDF. Universal templating
Use your own Word templates to convert Markdown → DOCX/PDF/HTML from any MCP-compatible AI.
Markdown in, any format out. PDFs merged, split, watermarked. Runs on our own doc engines.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Tianshang301/TianshangScribe'
If you have feedback or need assistance with the MCP directory API, please join our Discord server