mcp-docgen 0.1.0__tar.gz

mcp_docgen-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Touka Project (Otoha)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_docgen-0.1.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: mcp-docgen
+Version: 0.1.0
+Summary: Markdown-driven MCP server that generates Word (.docx), Excel (.xlsx) and PowerPoint (.pptx) documents — by the Touka project.
+Keywords: mcp,model-context-protocol,docx,xlsx,pptx,word,excel,powerpoint,document-generation,markdown
+Author: Otoha (Touka Project)
+Author-email: Otoha (Touka Project) <whitekinglight@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Office Suites
+Classifier: Topic :: Text Processing :: Markup
+Requires-Dist: python-docx>=1.1
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: xlsxwriter>=3.2
+Requires-Dist: python-pptx>=1.0
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mcp>=1.26
+Maintainer: Touka Project
+Maintainer-email: Touka Project <whitekinglight@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# mcp-docgen
+
+A Markdown-driven [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server
+that turns Markdown — and structured data — into **Word (`.docx`)**,
+**PowerPoint (`.pptx`)**, and **Excel (`.xlsx`)** files.
+
+Built entirely on mature, permissively-licensed Python libraries
+([`python-docx`](https://github.com/python-openxml/python-docx),
+[`python-pptx`](https://github.com/scanny/python-pptx),
+[`openpyxl`](https://foss.heptapod.net/openpyxl/openpyxl),
+[`XlsxWriter`](https://github.com/jmcnamara/XlsxWriter),
+[`markdown-it-py`](https://github.com/executablebooks/markdown-it-py)) — no proprietary
+dependencies. **MIT licensed.**
+
+> Part of the **Touka** project: giving AI agents the ability to produce real Office
+> documents using only open-source building blocks.
+
+## Why
+
+LLMs are great at producing Markdown. `mcp-docgen` exposes three tools that convert that
+Markdown into polished Office documents, so any MCP-capable assistant (Claude Desktop,
+Touka, …) can hand a user a finished `.docx` / `.pptx` / `.xlsx`.
+
+## Install & run
+
+Once published to PyPI:
+
+```bash
+uvx mcp-docgen
+```
+
+From a local checkout (before publishing):
+
+```bash
+uv sync
+uv run mcp-docgen
+```
+
+The server speaks MCP over **stdio**.
+
+## MCP client configuration
+
+```jsonc
+{
+  "mcpServers": {
+    "docgen": {
+      "command": "uvx",
+      "args": ["mcp-docgen"],
+      "env": { "MCP_DOCGEN_OUTPUT_DIR": "/absolute/path/to/output" }
+    }
+  }
+}
+```
+
+From a local checkout, swap the command for:
+
+```jsonc
+{ "command": "uv", "args": ["run", "--directory", "/path/to/mcp-docgen", "mcp-docgen"] }
+```
+
+## Tools
+
+Each tool returns `{"path": "<absolute path of the written file>"}`.
+
+### `create_docx(markdown, output_path, title?)`
+
+Markdown → Word. Supports headings, **bold** / *italic* / `inline code`, bullet and
+numbered lists (nested), tables, block quotes, fenced code blocks, and horizontal rules.
+
+### `create_pptx(markdown, output_path, title?)`
+
+Markdown → PowerPoint, using this slide convention:
+
+| Markdown | Result |
+| --- | --- |
+| `# Heading` | starts a **new slide** (the heading becomes its title) |
+| content below a heading | **bullet points** (nested lists indent) |
+| `---` (horizontal rule) | an explicit **slide break** |
+
+`title` adds a leading title slide.
+
+### `create_xlsx(sheets, output_path)`
+
+Structured data → Excel. `sheets` is a list of worksheets:
+
+```json
+[
+  {
+    "name": "Sales",
+    "rows": [["Region", "Revenue"], ["APAC", 1200000], ["EMEA", 900000]],
+    "header": true
+  }
+]
+```
+
+Cells may be strings, numbers, booleans, or `null`. The first row is a **bold, frozen
+header** unless the sheet sets `"header": false`.
+
+## Output directory & safety
+
+All files are written inside one base directory — `MCP_DOCGEN_OUTPUT_DIR`, or `./out`
+relative to the working directory by default. `output_path` is always interpreted
+relative to that base, and any path that tries to escape it (via `..` or an absolute
+path) is rejected. The server makes **no network calls** and spawns **no subprocesses**.
+
+## Examples
+
+```bash
+uv run python examples/generate_samples.py
+# writes report.docx, review.pptx and sales.xlsx into examples/output/
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT © 2026 Touka Project — see [LICENSE](LICENSE).
+
+Document generation is powered by python-docx, python-pptx, openpyxl, and XlsxWriter;
+Markdown parsing by markdown-it-py. All MIT/BSD licensed.

mcp_docgen-0.1.0/README.md

@@ -0,0 +1,126 @@
+# mcp-docgen
+
+A Markdown-driven [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server
+that turns Markdown — and structured data — into **Word (`.docx`)**,
+**PowerPoint (`.pptx`)**, and **Excel (`.xlsx`)** files.
+
+Built entirely on mature, permissively-licensed Python libraries
+([`python-docx`](https://github.com/python-openxml/python-docx),
+[`python-pptx`](https://github.com/scanny/python-pptx),
+[`openpyxl`](https://foss.heptapod.net/openpyxl/openpyxl),
+[`XlsxWriter`](https://github.com/jmcnamara/XlsxWriter),
+[`markdown-it-py`](https://github.com/executablebooks/markdown-it-py)) — no proprietary
+dependencies. **MIT licensed.**
+
+> Part of the **Touka** project: giving AI agents the ability to produce real Office
+> documents using only open-source building blocks.
+
+## Why
+
+LLMs are great at producing Markdown. `mcp-docgen` exposes three tools that convert that
+Markdown into polished Office documents, so any MCP-capable assistant (Claude Desktop,
+Touka, …) can hand a user a finished `.docx` / `.pptx` / `.xlsx`.
+
+## Install & run
+
+Once published to PyPI:
+
+```bash
+uvx mcp-docgen
+```
+
+From a local checkout (before publishing):
+
+```bash
+uv sync
+uv run mcp-docgen
+```
+
+The server speaks MCP over **stdio**.
+
+## MCP client configuration
+
+```jsonc
+{
+  "mcpServers": {
+    "docgen": {
+      "command": "uvx",
+      "args": ["mcp-docgen"],
+      "env": { "MCP_DOCGEN_OUTPUT_DIR": "/absolute/path/to/output" }
+    }
+  }
+}
+```
+
+From a local checkout, swap the command for:
+
+```jsonc
+{ "command": "uv", "args": ["run", "--directory", "/path/to/mcp-docgen", "mcp-docgen"] }
+```
+
+## Tools
+
+Each tool returns `{"path": "<absolute path of the written file>"}`.
+
+### `create_docx(markdown, output_path, title?)`
+
+Markdown → Word. Supports headings, **bold** / *italic* / `inline code`, bullet and
+numbered lists (nested), tables, block quotes, fenced code blocks, and horizontal rules.
+
+### `create_pptx(markdown, output_path, title?)`
+
+Markdown → PowerPoint, using this slide convention:
+
+| Markdown | Result |
+| --- | --- |
+| `# Heading` | starts a **new slide** (the heading becomes its title) |
+| content below a heading | **bullet points** (nested lists indent) |
+| `---` (horizontal rule) | an explicit **slide break** |
+
+`title` adds a leading title slide.
+
+### `create_xlsx(sheets, output_path)`
+
+Structured data → Excel. `sheets` is a list of worksheets:
+
+```json
+[
+  {
+    "name": "Sales",
+    "rows": [["Region", "Revenue"], ["APAC", 1200000], ["EMEA", 900000]],
+    "header": true
+  }
+]
+```
+
+Cells may be strings, numbers, booleans, or `null`. The first row is a **bold, frozen
+header** unless the sheet sets `"header": false`.
+
+## Output directory & safety
+
+All files are written inside one base directory — `MCP_DOCGEN_OUTPUT_DIR`, or `./out`
+relative to the working directory by default. `output_path` is always interpreted
+relative to that base, and any path that tries to escape it (via `..` or an absolute
+path) is rejected. The server makes **no network calls** and spawns **no subprocesses**.
+
+## Examples
+
+```bash
+uv run python examples/generate_samples.py
+# writes report.docx, review.pptx and sales.xlsx into examples/output/
+```
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check .
+```
+
+## License
+
+MIT © 2026 Touka Project — see [LICENSE](LICENSE).
+
+Document generation is powered by python-docx, python-pptx, openpyxl, and XlsxWriter;
+Markdown parsing by markdown-it-py. All MIT/BSD licensed.

mcp_docgen-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "mcp-docgen"
+version = "0.1.0"
+description = "Markdown-driven MCP server that generates Word (.docx), Excel (.xlsx) and PowerPoint (.pptx) documents — by the Touka project."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Otoha (Touka Project)", email = "whitekinglight@gmail.com" },
+]
+maintainers = [
+    { name = "Touka Project", email = "whitekinglight@gmail.com" },
+]
+keywords = [
+    "mcp",
+    "model-context-protocol",
+    "docx",
+    "xlsx",
+    "pptx",
+    "word",
+    "excel",
+    "powerpoint",
+    "document-generation",
+    "markdown",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Office Suites",
+    "Topic :: Text Processing :: Markup",
+]
+dependencies = [
+    "python-docx>=1.1",
+    "openpyxl>=3.1",
+    "xlsxwriter>=3.2",
+    "python-pptx>=1.0",
+    "markdown-it-py>=3.0",
+    "mcp>=1.26",
+]
+
+[project.scripts]
+mcp-docgen = "mcp_docgen.server:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.8",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.5,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "C4"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

mcp_docgen-0.1.0/src/mcp_docgen/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-docgen: a Markdown-driven MCP server for .docx / .xlsx / .pptx generation."""
+
+__version__ = "0.1.0"

mcp_docgen-0.1.0/src/mcp_docgen/blocks.py

@@ -0,0 +1,90 @@
+"""Document intermediate representation (IR).
+
+A writer-agnostic block model produced by :mod:`mcp_docgen.markdown_parser` and
+consumed by the docx / pptx writers. Keeping the IR in one place (SRP) lets every
+writer share a single normalized structure instead of re-walking Markdown tokens.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Run:
+    """A styled inline text run."""
+
+    text: str
+    bold: bool = False
+    italic: bool = False
+    code: bool = False
+    strike: bool = False
+    link: str | None = None
+
+
+@dataclass
+class Heading:
+    """A section heading (``level`` 1-6)."""
+
+    level: int
+    runs: list[Run]
+
+
+@dataclass
+class Paragraph:
+    """A block of inline text."""
+
+    runs: list[Run]
+
+
+@dataclass
+class ListItem:
+    """One item of a list; may itself contain blocks (e.g. nested lists)."""
+
+    blocks: list[Block] = field(default_factory=list)
+
+
+@dataclass
+class ListBlock:
+    """An ordered or unordered list."""
+
+    ordered: bool
+    items: list[ListItem]
+
+
+@dataclass
+class CodeBlock:
+    """A fenced or indented code block."""
+
+    text: str
+    language: str | None = None
+
+
+@dataclass
+class BlockQuote:
+    """A block quote wrapping nested blocks."""
+
+    blocks: list[Block]
+
+
+@dataclass
+class TableCell:
+    """A single table cell."""
+
+    runs: list[Run]
+
+
+@dataclass
+class Table:
+    """A table with a header row and zero or more body rows."""
+
+    header: list[TableCell]
+    rows: list[list[TableCell]]
+
+
+@dataclass
+class ThematicBreak:
+    """A horizontal rule (``---``). Used by the pptx writer as a slide break."""
+
+
+Block = Heading | Paragraph | ListBlock | CodeBlock | BlockQuote | Table | ThematicBreak

mcp_docgen-0.1.0/src/mcp_docgen/docx_writer.py

@@ -0,0 +1,146 @@
+"""Render the document IR into a Word (.docx) file via python-docx."""
+
+from __future__ import annotations
+
+import contextlib
+from pathlib import Path
+
+from docx import Document
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from docx.shared import Inches, Pt, RGBColor
+
+from .blocks import (
+    BlockQuote,
+    CodeBlock,
+    Heading,
+    ListBlock,
+    Paragraph,
+    Table,
+    ThematicBreak,
+)
+
+_MONO_FONT = "Consolas"
+_LINK_COLOR = RGBColor(0x06, 0x6C, 0xC0)
+
+
+def render_docx(blocks, title: str | None = None):
+    """Build and return a python-docx ``Document`` from IR blocks."""
+    doc = Document()
+    if title:
+        doc.add_paragraph(title, style="Title")
+    for block in blocks:
+        _render_block(doc, block)
+    return doc
+
+
+def write_docx(blocks, output_path: str | Path, title: str | None = None) -> Path:
+    """Render ``blocks`` and save the .docx to ``output_path``."""
+    path = Path(output_path)
+    render_docx(blocks, title=title).save(str(path))
+    return path
+
+
+def _render_block(doc, block) -> None:
+    if isinstance(block, Heading):
+        _add_runs(doc.add_paragraph(style=_heading_style(block.level)), block.runs)
+    elif isinstance(block, Paragraph):
+        _add_runs(doc.add_paragraph(), block.runs)
+    elif isinstance(block, ListBlock):
+        _render_list(doc, block, level=0)
+    elif isinstance(block, CodeBlock):
+        _render_code(doc, block)
+    elif isinstance(block, BlockQuote):
+        _render_quote(doc, block)
+    elif isinstance(block, Table):
+        _render_table(doc, block)
+    elif isinstance(block, ThematicBreak):
+        _add_horizontal_rule(doc)
+
+
+def _heading_style(level: int) -> str:
+    return f"Heading {min(max(level, 1), 9)}"
+
+
+def _add_runs(paragraph, runs, *, force_bold: bool = False) -> None:
+    for run in runs:
+        r = paragraph.add_run(run.text)
+        if run.bold or force_bold:
+            r.bold = True
+        if run.italic:
+            r.italic = True
+        if run.strike:
+            r.font.strike = True
+        if run.code:
+            r.font.name = _MONO_FONT
+        if run.link:
+            r.font.underline = True
+            r.font.color.rgb = _LINK_COLOR
+
+
+def _render_list(doc, list_block: ListBlock, level: int) -> None:
+    style = "List Number" if list_block.ordered else "List Bullet"
+    for item in list_block.items:
+        for child in item.blocks:
+            if isinstance(child, Paragraph):
+                p = doc.add_paragraph(style=style)
+                if level >= 1:
+                    p.paragraph_format.left_indent = Inches(0.25 * (level + 1))
+                _add_runs(p, child.runs)
+            elif isinstance(child, ListBlock):
+                _render_list(doc, child, level + 1)
+            else:
+                _render_block(doc, child)
+
+
+def _render_code(doc, code: CodeBlock) -> None:
+    lines = code.text.split("\n")
+    if lines and lines[-1] == "":
+        lines = lines[:-1]
+    p = doc.add_paragraph()
+    for i, line in enumerate(lines):
+        r = p.add_run(line)
+        r.font.name = _MONO_FONT
+        r.font.size = Pt(9)
+        if i != len(lines) - 1:
+            r.add_break()
+
+
+def _render_quote(doc, quote: BlockQuote) -> None:
+    for child in quote.blocks:
+        if isinstance(child, Paragraph):
+            _add_runs(doc.add_paragraph(style="Quote"), child.runs)
+        else:
+            _render_block(doc, child)
+
+
+def _render_table(doc, table: Table) -> None:
+    ncols = len(table.header) or (len(table.rows[0]) if table.rows else 0)
+    if ncols == 0:
+        return
+    docx_table = doc.add_table(rows=0, cols=ncols)
+    with contextlib.suppress(KeyError):  # template always ships Table Grid
+        docx_table.style = "Table Grid"
+    if table.header:
+        cells = docx_table.add_row().cells
+        for i, cell in enumerate(table.header):
+            _add_runs(cells[i].paragraphs[0], cell.runs, force_bold=True)
+    for row in table.rows:
+        cells = docx_table.add_row().cells
+        for i, cell in enumerate(row):
+            if i < ncols:
+                _add_runs(cells[i].paragraphs[0], cell.runs)
+
+
+def _add_horizontal_rule(doc) -> None:
+    """Append an empty paragraph carrying a bottom border (a visual ``<hr>``)."""
+    p = doc.add_paragraph()
+    p_pr = p._p.get_or_add_pPr()
+    borders = OxmlElement("w:pBdr")
+    bottom = OxmlElement("w:bottom")
+    bottom.set(qn("w:val"), "single")
+    bottom.set(qn("w:sz"), "6")
+    bottom.set(qn("w:space"), "1")
+    bottom.set(qn("w:color"), "auto")
+    borders.append(bottom)
+    p_pr.append(borders)

mcp_docgen-0.1.0/src/mcp_docgen/markdown_parser.py

@@ -0,0 +1,147 @@
+"""Parse Markdown into the document IR (:mod:`mcp_docgen.blocks`).
+
+Pure transformation: text in, ``list[Block]`` out, no IO. Built on markdown-it-py's
+:class:`~markdown_it.tree.SyntaxTreeNode`, which turns the flat token stream into a
+nested tree that is straightforward to walk.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+from markdown_it import MarkdownIt
+from markdown_it.tree import SyntaxTreeNode
+
+from .blocks import (
+    Block,
+    BlockQuote,
+    CodeBlock,
+    Heading,
+    ListBlock,
+    ListItem,
+    Paragraph,
+    Run,
+    Table,
+    TableCell,
+    ThematicBreak,
+)
+
+# CommonMark + GitHub-flavoured tables and strikethrough. ``ignoreInvalid=True`` keeps
+# construction safe across markdown-it-py versions; linkify is intentionally left off
+# to avoid the optional ``linkify-it-py`` dependency.
+_MD = MarkdownIt("commonmark").enable(["table", "strikethrough"], True)
+
+
+@dataclass(frozen=True)
+class _Style:
+    """Inline styling state carried down the recursion (internal)."""
+
+    bold: bool = False
+    italic: bool = False
+    code: bool = False
+    strike: bool = False
+    link: str | None = None
+
+
+def parse_markdown(text: str) -> list[Block]:
+    """Parse a Markdown string into a list of document blocks (IR)."""
+    tokens = _MD.parse(text or "")
+    root = SyntaxTreeNode(tokens)
+    return _blocks(root.children)
+
+
+def _blocks(nodes: list[SyntaxTreeNode]) -> list[Block]:
+    out: list[Block] = []
+    for node in nodes:
+        block = _block(node)
+        if block is not None:
+            out.append(block)
+    return out
+
+
+def _block(node: SyntaxTreeNode) -> Block | None:
+    t = node.type
+    if t == "heading":
+        return Heading(level=int(node.tag[1:]), runs=_inline_of(node))
+    if t == "paragraph":
+        return Paragraph(runs=_inline_of(node))
+    if t == "bullet_list":
+        return ListBlock(ordered=False, items=_items(node))
+    if t == "ordered_list":
+        return ListBlock(ordered=True, items=_items(node))
+    if t in ("fence", "code_block"):
+        language = (node.info or "").strip() or None
+        return CodeBlock(text=node.content, language=language)
+    if t == "blockquote":
+        return BlockQuote(blocks=_blocks(node.children))
+    if t == "table":
+        return _table(node)
+    if t == "hr":
+        return ThematicBreak()
+    return None
+
+
+def _items(list_node: SyntaxTreeNode) -> list[ListItem]:
+    return [
+        ListItem(blocks=_blocks(child.children))
+        for child in list_node.children
+        if child.type == "list_item"
+    ]
+
+
+def _table(table_node: SyntaxTreeNode) -> Table:
+    header: list[TableCell] = []
+    rows: list[list[TableCell]] = []
+    for section in table_node.children:
+        if section.type == "thead":
+            for tr in section.children:
+                header = [TableCell(runs=_inline_of(cell)) for cell in tr.children]
+        elif section.type == "tbody":
+            for tr in section.children:
+                rows.append([TableCell(runs=_inline_of(cell)) for cell in tr.children])
+    return Table(header=header, rows=rows)
+
+
+def _inline_of(node: SyntaxTreeNode) -> list[Run]:
+    """Collect styled runs from a block node wrapping a single ``inline`` child."""
+    for child in node.children:
+        if child.type == "inline":
+            return _runs(child.children, _Style())
+    return []
+
+
+def _runs(nodes: list[SyntaxTreeNode], style: _Style) -> list[Run]:
+    out: list[Run] = []
+    for node in nodes:
+        t = node.type
+        if t == "text":
+            if node.content:
+                out.append(_run(style, node.content))
+        elif t == "code_inline":
+            out.append(_run(replace(style, code=True), node.content))
+        elif t == "softbreak":
+            out.append(_run(style, " "))
+        elif t == "hardbreak":
+            out.append(_run(style, "\n"))
+        elif t == "strong":
+            out.extend(_runs(node.children, replace(style, bold=True)))
+        elif t == "em":
+            out.extend(_runs(node.children, replace(style, italic=True)))
+        elif t == "s":
+            out.extend(_runs(node.children, replace(style, strike=True)))
+        elif t == "link":
+            out.extend(_runs(node.children, replace(style, link=node.attrs.get("href"))))
+        elif node.children:
+            out.extend(_runs(node.children, style))
+    return out
+
+
+def _run(style: _Style, text: str) -> Run:
+    return Run(
+        text=text,
+        bold=style.bold,
+        italic=style.italic,
+        code=style.code,
+        strike=style.strike,
+        link=style.link,
+    )

mcp_docgen-0.1.0/src/mcp_docgen/paths.py

@@ -0,0 +1,45 @@
+"""Output-path resolution and jail for generated files.
+
+All writes are confined to a single base directory (``MCP_DOCGEN_OUTPUT_DIR`` or,
+by default, ``./out`` under the working directory). Any path that resolves outside
+the base — via ``..`` traversal or an absolute path — is rejected. This keeps a
+server that anyone can install from writing arbitrary files on the host.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+ENV_OUTPUT_DIR = "MCP_DOCGEN_OUTPUT_DIR"
+DEFAULT_SUBDIR = "out"
+
+
+def output_base() -> Path:
+    """Return (creating if needed) the absolute base directory for outputs."""
+    raw = os.environ.get(ENV_OUTPUT_DIR)
+    base = Path(raw) if raw else Path.cwd() / DEFAULT_SUBDIR
+    base = base.resolve()
+    base.mkdir(parents=True, exist_ok=True)
+    return base
+
+
+def resolve_output_path(output_path: str, expected_suffix: str) -> Path:
+    """Resolve ``output_path`` inside the jail, coercing the file suffix.
+
+    Raises:
+        ValueError: if ``output_path`` is empty.
+        PermissionError: if the resolved path escapes the output base directory.
+    """
+    if not output_path or not str(output_path).strip():
+        raise ValueError("output_path must be a non-empty path")
+    base = output_base()
+    target = (base / output_path).resolve()
+    try:
+        target.relative_to(base)
+    except ValueError as exc:
+        raise PermissionError(f"output_path escapes the allowed output directory ({base})") from exc
+    if target.suffix.lower() != expected_suffix:
+        target = target.with_suffix(expected_suffix)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    return target

mcp_docgen-0.1.0/src/mcp_docgen/pptx_writer.py

@@ -0,0 +1,146 @@
+"""Render the document IR into a PowerPoint (.pptx) deck via python-pptx.
+
+Slide convention:
+  * ``# H1``      -> starts a new slide; the heading text becomes the slide title.
+  * content below -> bullet points in the slide body (lists nest by indent level).
+  * ``---`` (hr)  -> an explicit slide break (a new, untitled slide).
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from pathlib import Path
+
+from pptx import Presentation
+
+from .blocks import (
+    BlockQuote,
+    CodeBlock,
+    Heading,
+    ListBlock,
+    Paragraph,
+    Run,
+    Table,
+    ThematicBreak,
+)
+
+_MONO_FONT = "Consolas"
+_MAX_LEVEL = 4
+
+
+def render_pptx(blocks, title: str | None = None):
+    """Build and return a python-pptx ``Presentation`` from IR blocks."""
+    prs = Presentation()
+    if title:
+        _add_title_slide(prs, title)
+    for slide_title, content in _split_into_slides(blocks):
+        _add_content_slide(prs, slide_title, content)
+    return prs
+
+
+def write_pptx(blocks, output_path: str | Path, title: str | None = None) -> Path:
+    """Render ``blocks`` and save the .pptx to ``output_path``."""
+    path = Path(output_path)
+    render_pptx(blocks, title=title).save(str(path))
+    return path
+
+
+def _split_into_slides(blocks):
+    """Group the block stream into (title, content_blocks) slides."""
+    slides: list[tuple[str | None, list]] = []
+    cur_title: str | None = None
+    cur_blocks: list = []
+
+    def flush() -> None:
+        nonlocal cur_title, cur_blocks
+        if cur_title is not None or cur_blocks:
+            slides.append((cur_title, cur_blocks))
+        cur_title, cur_blocks = None, []
+
+    for block in blocks:
+        if isinstance(block, Heading) and block.level == 1:
+            flush()
+            cur_title = _runs_text(block.runs)
+        elif isinstance(block, ThematicBreak):
+            flush()
+        else:
+            cur_blocks.append(block)
+    flush()
+    return slides
+
+
+def _add_title_slide(prs, title: str) -> None:
+    slide = prs.slides.add_slide(prs.slide_layouts[0])
+    slide.shapes.title.text = title
+
+
+def _add_content_slide(prs, title: str | None, blocks) -> None:
+    slide = prs.slides.add_slide(prs.slide_layouts[1])
+    slide.shapes.title.text = title or ""
+    body = slide.placeholders[1].text_frame
+    body.clear()
+    first = True
+    for runs, level in _bullets(blocks, 0):
+        para = body.paragraphs[0] if first else body.add_paragraph()
+        first = False
+        para.level = min(level, _MAX_LEVEL)
+        _write_runs(para, runs)
+
+
+def _bullets(blocks, level: int) -> list[tuple[list[Run], int]]:
+    """Flatten content blocks into (runs, indent_level) bullet rows."""
+    out: list[tuple[list[Run], int]] = []
+    for block in blocks:
+        if isinstance(block, Paragraph):
+            out.append((block.runs, level))
+        elif isinstance(block, Heading):
+            out.append(([replace(r, bold=True) for r in block.runs], level))
+        elif isinstance(block, ListBlock):
+            for item in block.items:
+                for child in item.blocks:
+                    next_level = level + 1 if isinstance(child, ListBlock) else level
+                    out.extend(_bullets([child], next_level))
+        elif isinstance(block, CodeBlock):
+            for line in _code_lines(block.text):
+                out.append(([Run(text=line, code=True)], level))
+        elif isinstance(block, BlockQuote):
+            for child in block.blocks:
+                if isinstance(child, Paragraph):
+                    out.append(([replace(r, italic=True) for r in child.runs], level))
+                else:
+                    out.extend(_bullets([child], level))
+        elif isinstance(block, Table):
+            out.extend(_table_bullets(block, level))
+    return out
+
+
+def _table_bullets(table: Table, level: int) -> list[tuple[list[Run], int]]:
+    rows = []
+    if table.header:
+        rows.append(([Run(text=" | ".join(_runs_text(c.runs) for c in table.header))], level))
+    for row in table.rows:
+        rows.append(([Run(text=" | ".join(_runs_text(c.runs) for c in row))], level))
+    return rows
+
+
+def _code_lines(text: str) -> list[str]:
+    lines = text.split("\n")
+    if lines and lines[-1] == "":
+        lines = lines[:-1]
+    return lines
+
+
+def _write_runs(paragraph, runs) -> None:
+    for run in runs:
+        r = paragraph.add_run()
+        r.text = run.text
+        if run.bold:
+            r.font.bold = True
+        if run.italic:
+            r.font.italic = True
+        if run.code:
+            r.font.name = _MONO_FONT
+
+
+def _runs_text(runs) -> str:
+    return "".join(r.text for r in runs)

mcp_docgen-0.1.0/src/mcp_docgen/server.py

@@ -0,0 +1,112 @@
+"""mcp-docgen: a Markdown-driven MCP server that generates Office documents.
+
+Exposes three tools over the Model Context Protocol:
+  * ``create_docx`` — Markdown -> Word (.docx)
+  * ``create_pptx`` — Markdown -> PowerPoint (.pptx)
+  * ``create_xlsx`` — structured rows -> Excel (.xlsx)
+"""
+
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from .docx_writer import write_docx
+from .markdown_parser import parse_markdown
+from .paths import resolve_output_path
+from .pptx_writer import write_pptx
+from .xlsx_writer import write_xlsx
+
+MAX_MARKDOWN_CHARS = 1_000_000
+MAX_SHEET_CELLS = 1_000_000
+
+mcp = FastMCP("mcp-docgen")
+
+
+@mcp.tool()
+def create_docx(markdown: str, output_path: str, title: str | None = None) -> dict:
+    """Create a Word (.docx) document from Markdown.
+
+    Args:
+        markdown: Document body as Markdown — headings, lists, tables, bold/italic,
+            inline code, fenced code blocks and block quotes are supported.
+        output_path: Destination filename, relative to the server's output directory.
+            The ``.docx`` suffix is enforced.
+        title: Optional heading rendered with Word's "Title" style at the top.
+
+    Returns:
+        ``{"path": <absolute path of the written .docx>}``.
+    """
+    _check_text(markdown)
+    target = resolve_output_path(output_path, ".docx")
+    write_docx(parse_markdown(markdown), target, title=title)
+    return {"path": str(target)}
+
+
+@mcp.tool()
+def create_pptx(markdown: str, output_path: str, title: str | None = None) -> dict:
+    """Create a PowerPoint (.pptx) deck from Markdown.
+
+    Slide convention: each top-level ``# Heading`` starts a new slide and becomes its
+    title; content beneath becomes bullet points (nested lists indent); a ``---``
+    horizontal rule forces a slide break.
+
+    Args:
+        markdown: Slide content as Markdown.
+        output_path: Destination filename, relative to the server's output directory.
+            The ``.pptx`` suffix is enforced.
+        title: Optional text for a leading title slide.
+
+    Returns:
+        ``{"path": <absolute path of the written .pptx>}``.
+    """
+    _check_text(markdown)
+    target = resolve_output_path(output_path, ".pptx")
+    write_pptx(parse_markdown(markdown), target, title=title)
+    return {"path": str(target)}
+
+
+@mcp.tool()
+def create_xlsx(sheets: list[dict], output_path: str) -> dict:
+    """Create an Excel (.xlsx) workbook from structured sheet data.
+
+    Args:
+        sheets: A list of worksheets, each ``{"name": str, "rows": [[cell, ...], ...]}``.
+            Cells may be strings, numbers, booleans or null. The first row of each sheet
+            is a bold, frozen header unless the sheet sets ``"header": false``.
+        output_path: Destination filename, relative to the server's output directory.
+            The ``.xlsx`` suffix is enforced.
+
+    Returns:
+        ``{"path": <absolute path of the written .xlsx>}``.
+    """
+    _check_sheets(sheets)
+    target = resolve_output_path(output_path, ".xlsx")
+    write_xlsx(sheets, target)
+    return {"path": str(target)}
+
+
+def _check_text(text: str) -> None:
+    if not isinstance(text, str):
+        raise ValueError("markdown must be a string")
+    if len(text) > MAX_MARKDOWN_CHARS:
+        raise ValueError(f"markdown exceeds the {MAX_MARKDOWN_CHARS}-character limit")
+
+
+def _check_sheets(sheets) -> None:
+    if not isinstance(sheets, list):
+        raise ValueError("sheets must be a list of sheet objects")
+    total = 0
+    for sheet in sheets:
+        for row in (sheet or {}).get("rows") or []:
+            total += len(row)
+    if total > MAX_SHEET_CELLS:
+        raise ValueError(f"sheets exceed the {MAX_SHEET_CELLS}-cell limit")
+
+
+def main() -> None:
+    """Console entry point: run the MCP server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

mcp_docgen-0.1.0/src/mcp_docgen/xlsx_writer.py

@@ -0,0 +1,80 @@
+"""Render structured sheet data into an Excel (.xlsx) workbook via openpyxl.
+
+Input shape (JSON-friendly), one dict per worksheet::
+
+    [{"name": "Sheet1", "rows": [["Header A", "Header B"], ["a1", "b1"]], "header": true}]
+
+``rows`` is a list of rows, each a list of cell values (str / int / float / bool / null).
+The first row is treated as a bold, frozen header unless ``header`` is ``false``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from openpyxl import Workbook
+from openpyxl.styles import Font
+from openpyxl.utils import get_column_letter
+
+_INVALID_TITLE_CHARS = set("[]:*?/\\")
+_MAX_TITLE = 31
+
+
+def render_xlsx(sheets):
+    """Build and return an openpyxl ``Workbook`` from structured sheet data."""
+    wb = Workbook()
+    default = wb.active
+    used: set[str] = set()
+    created = False
+    for index, sheet in enumerate(sheets or []):
+        name = sheet.get("name") or f"Sheet{index + 1}"
+        rows = sheet.get("rows") or []
+        header = sheet.get("header", True)
+        ws = wb.create_sheet(title=_safe_title(name, used))
+        created = True
+        for row in rows:
+            ws.append(list(row))
+        if header and rows:
+            _style_header(ws, len(rows[0]))
+        _autosize(ws, rows)
+    if created:
+        wb.remove(default)
+    return wb
+
+
+def write_xlsx(sheets, output_path: str | Path) -> Path:
+    """Render ``sheets`` and save the .xlsx to ``output_path``."""
+    path = Path(output_path)
+    render_xlsx(sheets).save(str(path))
+    return path
+
+
+def _safe_title(name: str, used: set[str]) -> str:
+    cleaned = "".join(" " if c in _INVALID_TITLE_CHARS else c for c in str(name)).strip()
+    cleaned = cleaned[:_MAX_TITLE] or "Sheet"
+    base = cleaned
+    counter = 2
+    while cleaned in used:
+        suffix = f" ({counter})"
+        cleaned = base[: _MAX_TITLE - len(suffix)] + suffix
+        counter += 1
+    used.add(cleaned)
+    return cleaned
+
+
+def _style_header(ws, ncols: int) -> None:
+    bold = Font(bold=True)
+    for col in range(1, ncols + 1):
+        ws.cell(row=1, column=col).font = bold
+    ws.freeze_panes = "A2"
+
+
+def _autosize(ws, rows) -> None:
+    widths: dict[int, int] = {}
+    for row in rows:
+        for idx, cell in enumerate(row, start=1):
+            length = len(str(cell)) if cell is not None else 0
+            if length > widths.get(idx, 0):
+                widths[idx] = length
+    for idx, length in widths.items():
+        ws.column_dimensions[get_column_letter(idx)].width = min(max(length + 2, 8), 60)