TianshangScribe
TianshangScribe
Procesamiento de documentos de Office multiplataforma para desarrolladores, automatización CLI y agentes de IA. Crea, edita, rellena plantillas y convierte documentos de Word (.docx), Excel (.xlsx) y PowerPoint (.pptx), con marcado estilo LaTeX, fórmulas matemáticas OMML nativas y un motor de plantillas ({{placeholders}}, bucles {{#each}}, condiciones {{#if}}). Incluye un servidor MCP con 7 herramientas (crear, editar, rellenar plantilla, convertir, extraer, validar, comparar) sobre transportes stdio, SSE y HTTP Streamable, con autenticación por token portador y limitación de velocidad.
Advertencia: API inestable \u2014 se esperan cambios incompatibles
Este proyecto está en pre-1.0 (0.x). Las opciones de CLI, las firmas de las herramientas MCP, la sintaxis de las plantillas y los formatos de salida no están congelados y pueden cambiar sin previo aviso. Compromiso de compatibilidad: cualquier cambio incompatible se anunciará en el CHANGELOG al menos con una versión de antelación y se acompañará de una guía de migración. Para uso en producción, fija una versión específica y revisa el CHANGELOG antes de actualizar.
Instalación
pip install tianshang-scribe
# Or from source:
git clone https://github.com/Tianshang301/TianshangScribe.git
cd TianshangScribe
pip install -e ".[dev]"Despliegue en Linux
Docker (recomendado para el servidor MCP sobre HTTP Streamable):
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)Paquete .deb (Debian / Ubuntu):
# Download from GitHub Releases
sudo dpkg -i tianshang-scribe_0.7.1_all.deb
tianshang-scribe --helppipx (CLI aislado):
pipx install tianshang-scribe
tianshang-scribe --helpRequiere Python 3.10+ · python-docx · openpyxl · python-pptx · typer · rich · lxml
Related MCP server: docx-forge-mcp
Inicio rápido
# 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.xlsxOpciones globales
Parámetro | Descripción |
| Ruta del documento de entrada (omitir con |
| Procesar documento de Word |
| Procesar libro de Excel |
| Procesar presentación de PowerPoint |
| Ruta del archivo de salida |
| Permitir sobrescribir archivos existentes |
| Salida como PDF |
| Leer desde la entrada estándar |
| Escribir en la salida estándar |
Cuando se omite -w/-e/-p, el tipo de documento se deduce de la extensión del archivo de entrada.
Operaciones
Opción | Descripción | Ejemplo |
| Crear documento en blanco |
|
| Añadir texto |
|
| Columna de destino para |
|
| Buscar y reemplazar |
|
| Eliminar contenido |
|
| Limpiar contenido / formatos / enlaces |
|
| Modificar contenido |
|
| Establecer estilo |
|
| Relleno de plantilla |
|
| Extraer datos ( |
|
| Establecer propiedades |
|
| Habilitar análisis LaTeX | |
| Añadir fórmula matemática (Word) |
|
| Dialecto de análisis matemático (office/mathtype) |
|
| Fuente matemática OMML (por defecto Cambria Math) |
|
| Incrustar como objeto OLE de MathType (MTEF) |
|
| Añadir encabezado (Word) |
|
| Modo de expresión regular | Usar con |
| Fusionar archivos |
|
| Dividir documento (solo Excel: |
|
| Añadir comentario (Word) / notas del orador (PPT) |
|
| Añadir tabla (Word) |
|
| Añadir gráfico (Excel) |
|
| Modo por lotes |
|
| Patrón glob para lote |
|
| Ruta de la base de datos SQLite de programación |
|
| Registrar programación |
|
| Eliminar programación |
|
| Listar programaciones |
|
| Ejecutar programación ahora |
|
| Ejecutar programaciones pendientes |
|
| Ejecutar script en sandbox |
|
| Leer desde stdin | |
| Escribir en stdout |
Opciones específicas de Word
Opción | Descripción | Ejemplo |
| Añadir encabezado |
|
| Añadir fórmula matemática |
|
| Habilitar marcado LaTeX | |
| Generar tabla de contenidos |
|
| Insertar salto de sección |
|
| Establecer encabezado de página |
|
| Establecer pie de página |
|
| Marca de agua de texto |
|
| Convertir a Markdown |
|
| Convertir a HTML |
|
Opciones específicas de Excel
Opción | Descripción | Ejemplo |
| Añadir hoja de cálculo |
|
| Eliminar hoja de cálculo |
|
| Renombrar hoja de cálculo |
|
| Establecer ancho de columna |
|
| Establecer alto de fila |
|
| Establecer fórmula de celda |
|
| Importar datos CSV |
|
| Ordenar rango |
|
| Añadir gráfico |
|
| Establecer contraseña |
|
| Eliminar contraseña |
|
| Exportar como CSV | |
| Exportar como JSON | |
| Exportar como HTML |
Marcado de estilo LaTeX
Incorpora el siguiente marcado en el contenido de --add. Habilítalo con --latex-style. Admite anidamiento.
Sintaxis | Efecto |
| Negrita |
| Cursiva |
| Versalitas |
| Subrayado |
| Romana (serif) |
| Sans-serif |
| Monoespaciada |
| Fuente específica |
| Tamaño de fuente (pt) |
| Color (hex) |
| Alineación centrada *— |
| Alineación izquierda *— |
| Alineación derecha *— |
| Interlineado *— |
| Sangría *— |
| Insertar encabezado |
| Salto de página |
| Insertar imagen |
*— Formato a nivel de párrafo (crea un nuevo párrafo).
Configuración de fuentes
Comando | Efecto |
| Fuente occidental predeterminada |
| Fuente CJK predeterminada |
| Fuente sans-serif |
| Fuente CJK sans-serif |
| Fuente monoespaciada |
| Fuente CJK monoespaciada |
Word OOXML separa de forma nativa w:ascii (occidental) y w:eastAsia (CJK), lo que permite el cambio automático de fuente en texto mixto.
Fórmulas matemáticas
Las fórmulas LaTeX con --math se convierten en OMML nativo de Word (Office Math Markup Language). El conversor es un analizador sintáctico descendente recursivo escrito a mano (expresión → término → factor → átomo) sobre un árbol de tokens anidado e inmutable (tokens de fracción, raíz, n-ario, sub/superíndice, acento, estilo y delimitador), despachado mediante una tabla de comandos O(1) con expresiones regulares precompiladas y división de argumentos sin copias. Usa --math-font "Times New Roman" para renderizar ecuaciones con una fuente serif estilo MathType en lugar de la fuente Cambria Math predeterminada de Word (<m:mathPr><m:mathFont>). --math-style mathtype cambia el dialecto de análisis de LaTeX para la compatibilidad con MathType. Usa --math-mtef para incrustar la fórmula como un objeto OLE real de MathType (binario MTEF) en su lugar, editable por MathType heredado (6.x y anteriores), el mismo formato que --extract math lee. La salida es estable byte a byte entre versiones (protegida por una suite de regresión de capturas de referencia).
Sintaxis compatible
Categoría | Comandos |
Fracciones |
|
Raíces |
|
Super/Subíndices |
|
Sumas/Integrales |
|
Límites |
|
Funciones con nombre |
|
Letras griegas |
|
Símbolos |
|
Relaciones |
|
Flechas |
|
Acentos |
|
Delimitadores |
|
Fuentes matemáticas |
|
Tipografía matemática
Conforme a los estándares de las principales revistas de matemáticas (AMS, Elsevier, Springer):
Contenido | Estilo | Ejemplo |
Variables de una sola letra | Cursiva |
|
Dígitos | Recta |
|
Funciones con nombre | Recta |
|
Letras griegas en minúsculas | Cursiva |
|
Letras griegas en mayúsculas | Recta |
|
Autodetección
Los comandos en el texto --add se reconocen automáticamente como matemáticas incluso sin envolverlos con $...$:
Con argumentos:
\frac\sqrt\sum\int\prod\limAcentos:
\hat{x}\bar{x}\vec{x}etc.Operadores unarios:
\sin\cos\tan\log\lnetc.H_{2}Oym^{2}en texto sin formato se convierten en subíndices/superíndices Unicode (H₂O / m²)
Sintaxis de estilo
--style usa pares clave-valor separados por comas:
--style "font=Times New Roman,size=14,bold,italic,color=FF0000,align=center"Clave | Alias | Valor | Descripción |
|
| Nombre de fuente | Fuente occidental |
|
| Nombre de fuente | Fuente CJK |
|
| pt | Tamaño de fuente |
| indica | Negrita | |
| indicador | Cursiva | |
| indicador | Subrayado | |
|
|
| Color hexadecimal |
|
|
| Alineación |
Las claves booleanas (bold italic underline) son True si están presentes.
Relleno de plantillas
Admite fuentes de datos JSON, CSV y YAML. Reemplaza {{placeholder}} en los documentos. Los objetos anidados se expanden mediante notación de puntos. Los bucles iteran sobre los valores de una lista. Los condicionales muestran u ocultan bloques.
{
"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}}Características de Excel
Característica | Opción de la CLI |
Gestión de hojas |
|
Tamaño de columnas/filas |
|
Fórmulas |
|
Importación de datos |
|
Exportación de datos |
|
Ordenación |
|
Gráficos |
|
Protección |
|
Características de PowerPoint
Característica | Descripción |
Gestión de diapositivas | Añadir, eliminar y reordenar diapositivas ( |
Diseños | Aplicar diseños de diapositiva por nombre o índice ( |
Notas del orador | Añadir notas del presentador ( |
Fórmulas matemáticas |
|
Transiciones | Configurar transiciones de diapositiva —fundido, empujar, barrido, etc. ( |
Compresión multimedia | Comprimir imágenes ( |
Protección | Establecer o quitar contraseña ( |
Códigos de salida
Código | Significado |
| Éxito |
| Error general |
| Error de argumentos |
| No implementado |
Servidor MCP
TianshangScribe incluye un servidor MCP (Model Context Protocol): los agentes de IA pueden crear, editar, rellenar plantillas, convertir y extraer datos de documentos de Office.
Conexión rápida
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"
}}}Herramientas (7)
Herramienta | Descripción |
| Crear archivos .docx / .xlsx / .pptx con bloques de contenido estructurado |
| Reemplazar, eliminar, modificar, aplicar estilos y añadir operaciones en documentos existentes |
| Rellenar |
| Convertir entre formatos (docx↔pdf/md/html, xlsx↔csv/json) |
| Extraer metadatos, texto completo o estructura del documento |
| Prevalidar los placeholders de la plantilla antes de rellenar con datos |
| Diferencia a nivel de párrafo entre dos archivos .docx |
Capacidades
Característica | Detalle |
Protocolo | MCP 2024-11-05 · stdio + SSE · JSON-RPC 2.0 |
Recursos |
|
Prompts | 5 plantillas de flujo de trabajo incorporadas ( |
Progreso |
|
Respuesta |
|
Esquema | Restricciones |
Producción (solo SSE)
# 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.7.1","uptime_seconds":3600,"active_sessions":3,"tools_available":7}
# 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
Documentación completa: 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 simulationArquitectura
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/ # 7 Agent tools
│ │ ├── _registry.py # tool registry (schemas auto-derived)
│ │ ├── create.py / edit.py / template.py / convert.py
│ │ ├── validate.py / compare.py
│ └── errors.py # structured error codes + fixes
└── utils/ # Utility functions
└── file_utils.pyPila tecnológica
Componente | Tecnología |
CLI | Typer + Rich |
Word | python-docx |
Excel | openpyxl |
PPT | python-pptx |
Matemáticas | Analizador descendente recursivo escrito a mano → OMML XML (árbol de tokens inmutable, tabla de ejecución de comandos) |
Plantillas | Motor propio ({{variable}}, {{#each}}, {{#if}}) |
office2pdf (binario Rust de ~2MB, cero dependencias) + alternativa LibreOffice | |
Calidad | pytest (936 pruebas) · ruff · mypy |
Compilar 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)Demostración
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 formulasPrueba de conformidad de la CLI:
python demo/test_cli.pyDesarrollo
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 checkLicencia
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