Skip to main content
Glama
README.md
# safe-pptx-mcp

A reduced-surface, offline presentation editor exposed through Model Context Protocol (MCP) **stdio only**. Version 0.1.0 requires Python 3.11 or later.

This is a derivative of [Office-PowerPoint-MCP-Server](https://github.com/GongRzhe/Office-PowerPoint-MCP-Server) at commit `3631ba2ec0c24504476f78bf74d329c9be11caaa`, with a narrower, rewritten API and selected helpers adapted. It is **not** an API-compatible upstream fork, an endorsed upstream release, or a security-certified product. See [NOTICE](<NOTICE>) and [LICENSE](<LICENSE>).

[Security model](<SECURITY.md>) · [Contributing](<CONTRIBUTING.md>)

## Scope

- Create, open, inspect, save, and close presentations using opaque in-memory presentation IDs.
- Add slides, text, basic shapes, straight connectors, native editable tables, and local PNG/JPEG pictures; set speaker notes.
- Read presentation files and pictures only from an explicitly selected input root.
- Save only to a new relative `.pptx` path below a separate output root, using atomic no-clobber publication. Subdirectories are allowed only when their parent directories already exist; the server does not create output directories. There is no overwrite option.

There is no COM automation, macro execution, remote URL fetching, HTTP/SSE server, arbitrary-file reader, subprocess tool, presentation rendering, or embedded workbook support. Installing the SDK's dependencies does not enable its other transports in this application.

## Quickstart: isolated locked environment

Use a reviewed source checkout containing the committed `uv.lock`, an already available Python interpreter, and `uv` (CI pins uv 0.13.9). Run these commands from the project directory. Do **not** install into a global or host application's Python environment.

```sh
uv sync --locked --no-install-project --no-build
```

This synchronizes the project-local `.venv` from the lockfile and does not install/build the project itself. Third-party source builds are disabled; use a fresh trusted cache when wheel provenance matters, because uv can reuse previously built cached wheels. If no compatible wheel exists, stop rather than silently allowing a source build. Missing or stale locks are errors, not permission to resolve new versions. Initial environment preparation may need network access; normal server operation does not.

Create two **existing, trusted, distinct, nonoverlapping** directories named `input` and `output`. For example:

**POSIX shell**

```sh
mkdir -p input output
export PYTHONPATH=src
uv run --locked --no-sync python -m safe_pptx_mcp.server --input-root input --output-root output
```

**PowerShell**

```powershell
New-Item -ItemType Directory -Force input, output | Out-Null
$env:PYTHONPATH = 'src'
uv run --locked --no-sync python -m safe_pptx_mcp.server --input-root input --output-root output
```

The process waits for an MCP client on stdin/stdout; it does not open a web page or listen on a network port. Reserve stdout for protocol messages. `--input-root` and `--output-root` are mandatory. Neither root may be the other root or contain it. Do not select a home directory, shared folder, credential directory, or a directory another process can modify concurrently.

The package also declares the console entry point `safe-pptx-mcp = safe_pptx_mcp.server:main`. It is available only after a separate reviewed installation of the local package; the source-mode quickstart above deliberately avoids running the build backend.

### Generic MCP client configuration

Replace every angle-bracket placeholder before use. Point the interpreter to the project-local virtual environment, `PYTHONPATH` to the source directory, and the roots to existing `input` and `output` directories. Use client-resolved absolute paths if the client's working directory is not the project directory. Escape backslashes in JSON on Windows. Client configuration formats can differ; this is a minimal stdio pattern, not an application-specific loader recipe.

```json
{
  "mcpServers": {
    "safe-pptx": {
      "command": "<project-venv-python>",
      "args": [
        "-m", "safe_pptx_mcp.server",
        "--input-root", "<input-directory>",
        "--output-root", "<output-directory>"
      ],
      "env": {
        "PYTHONPATH": "<project-directory>/src"
      }
    }
  }
}
```

For a disconnected runtime, prepare the reviewed environment first and invoke its interpreter directly as above. Do not let a client download dependencies on demand. The MCP client or model provider may itself use a network or transmit tool results; this server cannot make those components offline or confidential.

## Tools and workflow

Use MCP `tools/list` for the authoritative parameter schemas. The reduced tool names are:

| Tools | Purpose |
| --- | --- |
| `create_presentation`, `open_presentation` | Create a blank presentation or open an allowed local `.pptx`; return a presentation ID. |
| `save_presentation`, `close_presentation` | Save to a new output-relative `.pptx` path or discard the in-memory presentation. |
| `add_slide`, `add_text`, `add_shape` | Add bounded native slide content. |
| `add_connector`, `add_table`, `add_picture` | Add a straight connector, a native table, or an allowed local PNG/JPEG. |
| `set_notes` | Set bounded speaker notes. |
| `get_presentation_info`, `get_slide_info` | Inspect bounded presentation/slide structure and text. |

A typical session creates a presentation, adds content using its ID, inspects it, saves to a new output-relative `.pptx` path, then closes it. Opening uses an input-relative presentation path; adding a picture uses an input-relative image path. Saving permits subdirectories below the output root only when all parent directories already exist; it never creates directories or accepts a destination outside that root. IDs belong to the running process, not the filesystem. Unsaved changes disappear when the process exits. To edit a saved result in a later session, deliberately copy it into the trusted input directory first.

## Strict v1 package policy and limits

Only the allowed presentation XML/package metadata and PNG/JPEG image parts are accepted. The validator rejects external relationships and active or unsupported content rather than attempting to sanitize it. Existing pictures inside opened packages are subject to the same strict policy as newly added pictures.

Macros, ActiveX/OLE, embedded workbooks, SVG/EMF, embedded fonts, audio/video, opaque printer settings, and other unsupported part types are rejected. Only the trusted library-provided blank template has its printer-setting relationship omitted when creating a new deck; imported files are not silently sanitized. Some ordinary presentations from other editors will therefore be refused. This is an intentional compatibility tradeoff, not a claim of complete format support.

| Limit | Maximum |
| --- | --- |
| Compressed package | 20 MiB |
| Total unpacked package data | 100 MiB |
| Package parts | 1,000 |
| Individual image file | 10 MiB |
| Decoded image pixels | 20,000,000 |
| Cumulative image budget per presentation | 20 MiB |
| Open in-memory presentations | 5 |
| Slides per presentation | 100 |
| Shapes per slide | 200 |
| Shapes per presentation | 2,000 |
| Individual text input | 32,000 characters |
| Total text per table | 50,000 characters |
| Aggregate editable slide and notes-body text per presentation | 500,000 characters |
| Native table dimensions | 1–50 rows × 1–20 columns |
| Shapes per notes master or notes slide | 20 |
| Stdio protocol line | 512 KiB |

On import, the cumulative image budget counts the uncompressed bytes of accepted image parts, not their compressed ZIP sizes. Tables must have a rectangular actual physical cell grid within the row/column bounds. Notes masters/slides reject duplicate cloneable `body`, `sldImg`, or `sldNum` placeholders and unknown placeholder enum values.

Other parameters are bounded as well; consult the tool schemas and validation errors. Limits reduce resource exposure but are not hard process memory/CPU quotas. Save validation may refuse a presentation that would exceed package limits.

## Security boundary

Error output is deliberately limited: only application-authored messages are sanitized and capped at 300 characters; SDK errors are generic. This is not a guarantee that client logs, surrounding runtime diagnostics, or permitted presentation inspection results contain no sensitive data.

**Application path policy is not an operating-system sandbox.** Run with low privileges and exclusive trusted roots. A hostile same-user process mutating directories or files concurrently, including Windows reparse-point and check/use races, is outside the guarantee. Use OS isolation and deny network access at the OS level when your deployment requires it. Review [SECURITY.md](<SECURITY.md>) before accepting untrusted inputs.

No static review, exact dependency pin, or CI run establishes that the complete transitive dependency graph is vulnerability-free. Pillow 13.0.0 was selected instead of 12.3.0 after metadata identified an EXIF parsing denial of service affecting JPEG inputs ([CVE-2026-128066](https://osv.dev/vulnerability/GHSA-wqgw-9xfh-qf2g), reported fixed in 13.0.0). Limiting formats alone would not remove that risk. This targeted update is not a complete CVE assessment; keep reviewing dependencies and the locked graph.

## Dependencies and development

Direct runtime pins in [pyproject.toml](<pyproject.toml>) are:

- [mcp 1.30.0](https://pypi.org/pypi/mcp/1.30.0/json), the official SDK's stable 1.x maintenance release; use `mcp.server.fastmcp`, **not** the independent `fastmcp` distribution.
- [python-pptx 1.0.2](https://pypi.org/pypi/python-pptx/1.0.2/json).
- [Pillow 13.0.0](https://pypi.org/pypi/Pillow/13.0.0/json).
- [lxml 6.1.3](https://pypi.org/pypi/lxml/6.1.3/json).

The declared build backend is `setuptools.build_meta`, pinned to [setuptools 84.2.1](https://pypi.org/pypi/setuptools/84.2.1/json). Published metadata confirms these versions exist and their Python requirements admit Python 3.11; this is not a test result for every future interpreter or platform. The lockfile records transitive resolutions. Review changes to both metadata and lock together. Runtime dependencies may include network-capable libraries even though this application exposes only stdio.

Tests use the standard-library `unittest`; no pytest dependency is needed. With `PYTHONPATH=src` set as above:

```sh
uv run --locked --no-sync python -m unittest discover -s tests -v
uv run --locked --no-sync python -m unittest tests.test_stdio -v
```

[CI](<.github/workflows/ci.yml>) is configured for Linux and Windows, locked wheel-only dependency synchronization, unit tests, and a stdio protocol smoke test. Configuration alone does not mean those hosted jobs have passed. Dependency installation in CI uses network access; the runtime scope remains offline-only local editing.

## License and provenance

The exact upstream MIT copyright and license are preserved in [LICENSE](<LICENSE>). MIT permits modification and redistribution subject to preserving its notice and permission text, and provides no warranty. [NOTICE](<NOTICE>) records the source SHA and derivative scope. Dependencies have their own license obligations. These files do not assert that a repository or package has already been published.