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 12 tools (7 unified + 5 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 --help

pipx (isolated CLI):

pipx install tianshang-scribe
tianshang-scribe --help

Requires Python 3.10+ · python-docx · openpyxl · python-pptx · typer · rich · lxml

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.xlsx

Global Options

When -w/-e/-p is omitted, the document type is inferred from the input file extension.

Operations

Word-Specific Options

Excel-Specific Options

LaTeX Style Markup

Embed the following markup in --add content. Enable with --latex-style. Supports nesting.

*— Paragraph-level formatting (creates a new paragraph).

Font Configuration

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

Math Typography

Conforms to mainstream math journal standards (AMS, Elsevier, Springer):

Auto-Detection

Commands in --add text are automatically recognized as math even without $...$ wrapping:

• With arguments: \frac \sqrt \sum \int \prod \lim
• Accents: \hat{x} \bar{x} \vec{x} etc.
• Unary operators: \sin \cos \tan \log \ln etc.
• H_{2}O and m^{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"

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

PPT Features

Exit Codes

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 (12)

Capabilities

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.8.1","uptime_seconds":3600,"active_sessions":3,"tools_available":12}

# 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 simulation

Architecture

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/              # 12 Agent tools (7 unified + 5 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.py

Tech Stack

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 formulas

CLI compliance test:

python demo/test_cli.py

Development

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 check

License

Apache-2.0