# GenFiles MCP Server

GenFiles is a local-first MCP server for generating `PowerPoint`, `Excel`, `Word`, and `Markdown` files from agent requests. It runs over `streamable-http`, stores outputs locally under `generated_files/`, and returns machine-readable download metadata for every generated file.

For a single-instance private Azure VM deployment, see [Azure deployment](docs/azure-deployment.md). The root `docker-compose.yml` is a local example, not the Azure deployment configuration.

## What You Can Do

- Generate `PPTX`, `XLSX`, `DOCX`, and `MD` files through MCP tools.
- Review existing `DOCX` files and write targeted comments back into a reviewed copy.
- Register catalog images over HTTP for remote clients, then reuse their `asset_id` values in `DOCX` and `PPTX` generation.
- Return structured results containing `download_url`, `file_name`, `download_markdown`, and `assistant_response_markdown`.

## Quick Start

### 1. Install dependencies

```powershell
uv sync
```

### 2. Create `.env`

Copy the tracked template, then adjust values for your machine. `.env` is ignored by Git and is the server's local configuration source.

```powershell
Copy-Item .env.example .env
```

### 3. Start the MCP server

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\start_streamable_http.ps1
```

### 4. Use the default endpoints

```text
MCP:        http://127.0.0.1:8016/mcp
Downloads:  http://127.0.0.1:8016/downloads/{filename}
Catalog:    POST http://127.0.0.1:8016/image-catalog/assets
Search:     POST http://127.0.0.1:8016/image-catalog/search
Image GET:  http://127.0.0.1:8016/images/{asset_id}
Source extract: POST http://127.0.0.1:8016/source-extract (`.xlsx`, `.docx`, `.pptx`)
```

### 5. Change configuration

Change values in `.env`, then restart the server. For example, set a reachable base URL for clients on another machine:

```env
PUBLIC_BASE_URL=http://192.168.1.10:8016
```

Enable structured Word generation instead of Python-script Word generation:

```env
ENABLE_WORD_ELEMENT_FILLING=true
```

## Typical Flow

1. Start the server.
2. Connect your MCP client to `http://127.0.0.1:8016/mcp`.
3. Call `generate_powerpoint`, `generate_excel`, `generate_markdown`, or the active Word tool.
4. Download generated files from the returned `download_url`.
5. Register remote images with `POST /image-catalog/assets` and pass the returned `asset_id` values into the document-generation tool.

## Environment Variables

`server.py` loads `.env` on startup. Values already present in the process environment take precedence, which is useful for container or deployment configuration.

| Variable | Description | Example |
|---|---|---|
| `PORT` | Port where the MCP server listens. | `8016` |
| `LOCAL_OUTPUT_DIR` | Directory where generated files are saved. | `generated_files` |
| `PUBLIC_BASE_URL` | Base URL used to build `download_url` values. | `http://127.0.0.1:8016` |
| `GENERATED_FILE_TTL_SECONDS` | Generated document lifetime before cleanup. | `604800` (7 days) |
| `CLEANUP_INTERVAL_SECONDS` | How often the server runs cleanup. | `86400` (1 day) |
| `IMAGE_LIBRARY_DIR` | Permanent image catalog directory. | `image_library` |
| `IMAGE_CATALOG_DB` | SQLite database for catalog metadata. | `image_library/image_catalog.db` |
| `SOURCE_EXTRACT_MAX_CHARS` | Maximum text returned by the source-extraction endpoint. | `100000` |
| `REVIEWER_AI_ASSISTANT_NAME` | Author name used inside Word comments created by `review_docx`. | `GenFilesMCP` |
| `ENABLE_WORD_ELEMENT_FILLING` | Enables the structured Word builder instead of code-generation mode. | `false` |

## Source-document extraction

Submit exactly one `.xlsx`, `.docx`, or `.pptx` file as `multipart/form-data` to `POST /source-extract`. The response contains bounded plain text: worksheet rows are tab-separated, DOCX paragraphs/tables are labeled, and PPTX slide text/tables are grouped by slide.

## Current Image Support

- `DOCX`: Supports real image embedding from local image paths and permanent catalog `asset_id` values. Script mode accepts `images_list` and `image_ids`, and structured mode accepts image references inside document elements.
- `PPTX`: Supports real image embedding from local image paths and permanent catalog `asset_id` values. The generated script must use the preloaded `images` objects with `add_picture(...)`.
- `XLSX`: Supports catalog `asset_id` values and local image paths. Images are preloaded for the generation script, which anchors each image to a cell and sets its explicit pixel size while preserving aspect ratio.
- `MD`: Does not embed binary images into the file. Markdown content can reference images by path or URL, but there is no dedicated image preload pipeline.

## Image Catalog For Remote Clients

- Register one image at `POST /image-catalog/assets` using `multipart/form-data` with the binary field named `image`.
- Include `purpose`, `prompt`, `description`, `keywords` (JSON array), `style`, `aspect_ratio`, `embedding` (JSON number array), and `source` (`generated` or `user_upload`).
- Images are normalized to JPEG at quality 85, or PNG when transparency is required, with a maximum side length of 1920px.
- Exact duplicate binaries return the existing `asset_id` instead of storing another file.
- Search existing assets with `POST /image-catalog/search`, providing an embedding and optional style/aspect-ratio filters.
- Pass returned `asset_id` values as `image_ids` to `generate_word`, `generate_powerpoint`, or `generate_excel`. `images_list` remains available for same-machine local paths.

## Current Limits

- Generated files are saved on the host under `generated_files/` and served through `/downloads/{filename}`.
- Catalog images stay permanently under `image_library/` and are never removed by the cleanup worker.
- Generated documents are cleaned after 7 days by default. Set `GENERATED_FILE_TTL_SECONDS` to adjust this value.
- If a file is deleted from the host, its `download_url` will return `404`.

Additional setup notes live in [docs/installation.md](docs/installation.md), [docs/features.md](docs/features.md), and [docs/codex-plugin-streamable-http.md](docs/codex-plugin-streamable-http.md).