# PPT Design MCP

Template-driven PowerPoint design MCP server for Windows.

This project wraps Microsoft PowerPoint COM automation behind a Python adapter
and exposes a small MCP tool surface. MCP tools validate parameters, call the
adapter, and return a uniform result shape. COM calls stay in
`ppt_design_mcp.adapters`.

## Requirements

- Windows desktop
- Microsoft PowerPoint installed
- Python 3.11+
- `pywin32`
- Official MCP Python SDK

## Install

```powershell
uv sync
```

If you are not using `uv`, install the project dependencies from
`pyproject.toml` into a Python 3.11+ environment.

## Run the MCP Server

```powershell
uv run ppt-design-mcp
```

Equivalent module form:

```powershell
uv run python -m ppt_design_mcp.server
```

The server uses stdio transport through FastMCP's default `run()` behavior.

## Exposed Tools

Every tool returns:

- `ok`: boolean
- `tool`: tool name
- `message`: human-readable status or error
- `data`: structured payload
- `error_code`: error class name, or `null` on success

Tools:

- `powerpoint_status`
- `open_template_as_new`
- `inspect_slides`
- `duplicate_slide`
- `set_named_shape_text`
- `fill_named_shape_with_image`
- `export_slide_png`
- `save_and_close`

## Safety Notes

- Source templates are opened read-only and must not be overwritten.
- Generated files should be saved under `output/`.
- Shapes are addressed by stable shape names, not shape indexes.
- PowerPoint COM logic is not implemented in MCP tool functions.

## Template Registry

Template page metadata is stored in local JSON manifest files. A manifest
points to a PowerPoint template file and lists reusable template pages:

```json
{
  "template_file": "../output/presentations/com-smoke-test.pptx",
  "templates": [
    {
      "template_id": "com-smoke-title",
      "source_slide": 1,
      "purpose": "Smoke-test title slide for adapter and MCP validation",
      "style": "PowerPoint default title layout",
      "slots": [
        {
          "shape_name": "Title 1",
          "type": "text",
          "max_chars": 80
        }
      ]
    }
  ]
}
```

Files under `templates/` are ignored by Git in this repository so existing
designer templates and their manifests stay local unless they are reviewed and
published intentionally.

Use `ppt_design_mcp.templates.load_template_registry()` to load a manifest.
The registry exposes:

- `list_templates()`
- `get_template(template_id)`
- `check_consistency(inspector)`

`check_consistency()` uses an object with `list_slides()` and `list_shapes()` to
verify that the manifest matches the real template. It reports:

- missing template files
- missing named shapes
- duplicate `template_id` values
- illegal `source_slide` page numbers

The registry does not perform page planning and does not call any large model.

## Local Validation

```powershell
py -3.12 -m pytest
py -3.12 scripts/build_demo.py
```