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.
