Skip to main content
Glama
Sign In
deenesjakoruzh
ppt-word-gen

ppt-word-gen

by muli4561
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

ppt-word-mcp

Сервис генерации редактируемых PPTX и стандартизированных Word-отчётов с симуляцией на базе ИИ
Единый лёгкий сервис предоставляет MCP (Model Context Protocol) Server, REST API и Web Demo на одном порту.

🚀 MCP (Model Context Protocol) сервис

ppt-word-gen нативно реализует стандартный протокол MCP (поддерживает два транспортных канала: Streamable HTTP и STDIO), позволяя различным Agent-клиентам (таким как Claude Code, Claude Desktop, Cursor, Cline, OpenWebUI и др.) самостоятельно выполнять извлечение формата документов, подтверждение пользователем, асинхронную генерацию в очереди, семантические многораундовые правки и безопасную загрузку файлов.

1. Конфигурация подключения клиента (.mcp.json)

В корне проекта уже встроен .mcp.json — при открытии этого каталога инструменты Agent автоматически обнаружат и загрузят сервис.

Способ A: режим HTTP-транспорта (рекомендуется для развёртывания в контейнерах / локальной сети / на локальной машине)

Создайте или отредактируйте .mcp.json в корне проекта:

{
  "mcpServers": {
    "ppt-word-gen": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Если в сервисе включена аутентификация Bearer Token (задан PPT_WORD_GEN_TOKEN), можно добавить заголовок запроса:

{
  "mcpServers": {
    "ppt-word-gen": {
      "type": "http",
      "url": "http://YOUR_SERVER_IP:8000/mcp",
      "headers": {
        "Authorization": "Bearer ${PPT_WORD_GEN_TOKEN}"
      }
    }
  }
}

Одношаговая регистрация через CLI Claude Code:

# 项目级注册（写入当前目录 .mcp.json）
claude mcp add --transport http --scope project ppt-word-gen http://127.0.0.1:8000/mcp

# 用户全局注册
claude mcp add --transport http --scope user ppt-word-gen http://127.0.0.1:8000/mcp

Способ B: режим STDIO-транспорта (локальный запуск через Python-процесс без HTTP-порта)

Запустите напрямую через Python-процесс в конфигурации клиента:

{
  "mcpServers": {
    "ppt-word-gen": {
      "command": "python",
      "args": ["-m", "ppt_word_gen.mcp_stdio"]
    }
  }
}

2. Основной совместный рабочий процесс MCP

[用户输入 / 来源资料 / 模板]
             │
             ▼
[可选：upload_file / create_upload_ticket 暂存来源文件与 Word 模板]
             │
             ▼
[preview_word_report_format 提取模板默认格式（字体、字号、行距、多级标题、编号规范）]
             │
             ▼
[向用户展示预览并获取确认 ➔ 获得绑定格式哈希的 confirmation_token]
             │
             ▼
[generate_presentation / generate_word_report 发起异步生成任务]
             │
             ▼
[wait_generation_task / get_generation_task 轮询进度状态]
             │
             ▼
[get_artifact 获取 24 小时有效的安全签名 ResourceLink 下载链接]
             │
             ▼
[可选：revise_presentation / revise_word_report 进行多轮语义增量修订]

3. Полный набор инструментов MCP (15 Tools)

Название инструмента

Описание функции

Ключевые параметры

list_generation_profiles

Выводит типы документов для генерации, поддерживаемые форматы и соглашения о бинарной загрузке

нет

preview_word_report_format

Извлекает формат шаблона по умолчанию (или встроенного шаблона) и применяет изменения; возвращает информацию о формате и confirmation_token

template_upload_id, custom_format

generate_presentation

Создаёт асинхронную задачу генерации редактируемого PPTX

prompt, format, source_upload_ids, model и др.

generate_word_report

Отправляет задачу Word-отчёта (обязательно с confirmation_token)

title, report_type, confirmation_token, source_upload_ids

get_generation_task

Запрашивает этап, процент прогресса, ошибки и статус артефакта асинхронной задачи PPT или Word

task_id, task_type

wait_generation_task

Ожидает до 55 секунд; возвращает результат сразу по завершении задачи, при таймауте — последний статус

task_id, task_type, timeout_seconds

cancel_generation_task

Запрашивает отмену ещё не завершённой асинхронной задачи генерации

task_id, task_type

get_artifact

После завершения задачи возвращает прямую ссылку на безопасную подписанную загрузку на 24 часа со стандартным ResourceLink

task_id, task_type

upload_file

Встроенная загрузка небольших файлов в Base64 (не более 5MB)

filename, content_base64, purpose

create_upload_ticket

Создаёт одноразовый адрес PUT-загрузки для больших файлов (чтобы не занимать контекст Agent)

filename, purpose, max_bytes

list_business_templates

Выводит встроенные и корпоративные пользовательские шаблоны бизнес-стандартов PPT/Word

нет

register_business_template

Регистрирует шаблон корпоративных бизнес-требований и стилевых стандартов

template_id, name, spec

delete_business_template

Удаляет пользовательский бизнес-шаблон (встроенные шаблоны защищены и не удаляются)

template_id

revise_presentation

Использует существующий PPTX как контекст и генерирует новую версию по инструкции на естественном языке

parent_task_id, revision_prompt

revise_word_report

После подтверждения пользователем формата инкрементально генерирует новую версию на основе существующего DOCX

parent_task_id, confirmation_token, revision_instructions

4. Правила MCP и ресурсы активов (4 Resources)

Agent может напрямую читать руководства по стандартам и дизайнерские ограничения:

  • ppt-word://rules/workflow：полные правила взаимодействия MCP и подтверждения формата

  • ppt-word://rules/presentation：стандарты дизайна и вёрстки Master PPT

  • ppt-word://rules/word-report：стандарты вёрстки симуляционных и инженерных Word-отчётов

  • ppt-word://templates/catalog：каталог бизнес-шаблонов и краткий справочник стандартов

Related MCP server: Formatix AI MCP Server

📁 Структура проекта

ppt-word-gen/
├── ppt_word_gen/              # Python 核心业务包
│   ├── app.py                 # FastAPI 入口（Demo、REST API、MCP Streamable HTTP）
│   ├── mcp_server.py          # MCP Server 实现（15 工具、4 资源、双向协议）
│   ├── mcp_stdio.py           # MCP STDIO 运行入口
│   ├── tasks.py               # PPT 异步任务队列与状态机
│   ├── report_tasks.py        # Word 异步任务队列与状态机
│   ├── report_agent.py        # Word 报告生成 Agent
│   ├── report_documents.py    # Word 文档排版、格式继承与 GBK 修复引擎
│   ├── word_format.py         # Word 格式解析、修改与防篡改 Token 校验
│   ├── signed_tokens.py       # HMAC-SHA256 签名下载与上传票据
│   ├── pptmaster.py           # PPT Master 脚本适配与执行
│   ├── upload_store.py        # 临时文件上传与生命周期管理
│   ├── task_store.py          # SQLite 持久化任务存储
│   └── config.py              # 全局配置读取
├── assets/word_templates/     # 内置 Word 模板（CID629 电驱系统联合仿真 v1.5）
├── skills/ai-simulation-report/# 仿真报告标准契约与校验规则
├── static/                    # 前端 Web Demo 页面
├── tests/                     # 41 项单元测试与集成测试
├── Dockerfile                 # 容器构建文件（支持联网/离线两种模式）
├── docker-compose.yml         # 生产/测试容器编排配置
├── build-overlay.ps1          # 企业级解密与离线 wheel 构建脚本
├── requirements.txt           # 依赖清单
├── .env.example               # 环境变量参考模板
└── .mcp.json                  # MCP 配置文件

💻 Быстрый локальный запуск

1. Установка зависимостей и выполнение тестов

# 安装依赖
python -m pip install -r requirements.txt

# 运行全套 41 项自动化测试
python -m unittest discover -s tests -v

2. Запуск сервиса

# 启动 HTTP + MCP 服务（默认监听 0.0.0.0:8000）
python -m ppt_word_gen

  • Страница Web Demo：http://127.0.0.1:8000/demo

  • Интерактивная документация OpenAPI：http://127.0.0.1:8000/docs

  • HTTP-эндпоинт MCP：http://127.0.0.1:8000/mcp

  • Проверка работоспособности：http://127.0.0.1:8000/health

🐳 Развёртывание в контейнерах Docker / WSL

1. Стандартное развёртывание

В терминале Ubuntu / WSL:

cd /path/to/ppt-word-gen
cp .env.example .env.compose

# 按需修改 .env.compose（接入真实模型时设置 MOCK_LLM=0 并填写 API Key）
sudo service docker start
docker compose --env-file .env.compose up -d --build --wait

2. Корпоративная офлайн-сборка Wheel

В средах с защитой от утечки корпоративных данных (DLP) или изолированной внутренней сетью выполните в Windows PowerShell:

pwsh ./build-overlay.ps1

Этот скрипт автоматически безопасно копирует через файловый поток и вызывает OFFLINE_INSTALL=1 для локальной офлайн-сборки Wheel.

3. Проверка состояния сервиса и остановка

# 查看容器状态与健康指标
docker compose ps
curl http://127.0.0.1:8000/health

# 停止容器（数据保留在 ppt-word-gen-data 卷中）
docker compose stop

⚙️ Описание переменных окружения

Скопируйте .env.example в .env или .env.compose:

Имя переменной

Значение по умолчанию

Описание

LLM_BASE_URL

https://dashscope.aliyuncs.com/compatible-mode/v1

Base URL совместимого интерфейса OpenAI

LLM_API_KEY

нет

API-ключ большой языковой модели

LLM_MODEL

qwen3.7-plus

Название модели создания по умолчанию

MOCK_LLM

1

1 — полное самотестирование и демонстрация без API-ключа; для подключения реальной модели измените на 0

PPT_WORD_GEN_TOKEN

пусто

Аутентификация Bearer Token; при пустом значении аутентификация не требуется

PUBLIC_BASE_URL

http://127.0.0.1:8000

Базовый URL для загрузки артефактов и больших файлов (при вызове из локальной сети укажите внутренний IP сервера)

DOWNLOAD_SIGNING_SECRET

пусто (генерируется автоматически)

Секрет подписи HMAC для создания 24-часовых временных учётных данных загрузки

MAX_CONCURRENT_TASKS

2

Максимальное количество параллельных задач обработки PPT

MAX_CONCURRENT_REPORT_TASKS

1

Максимальное количество параллельных задач обработки Word

MCP_INLINE_UPLOAD_MB

5

Лимит встроенной загрузки MCP в Base64 (МБ)

MAX_UPLOAD_MB

20

Лимит загрузки REST / больших файлов по Ticket (МБ)

🔌 Основные REST API

Метод запроса

Путь

Описание

GET

/health

Проверка работоспособности сервиса (включая хранилище SQLite и статус очереди задач)

GET

/demo

Встроенная веб-страница демонстрации

GET

/api/v1/word-format

Получение формата встроенного шаблона Word по умолчанию и токена подтверждения

POST

/api/v1/word-format

Извлечение формата пользовательского шаблона, применение изменений и генерация токена подтверждения

POST

/api/v1/report-tasks

Отправка задачи генерации симуляционного/технического Word-отчёта

GET

/api/v1/report-tasks/{id}

Запрос прогресса и деталей задачи Word-отчёта

GET

/api/v1/report-tasks/{id}/result

Загрузка сгенерированного отчёта DOCX

POST

/api/v1/tasks

Отправка задачи генерации презентации PPT

GET

/api/v1/tasks/{id}

Запрос прогресса и деталей задачи PPT

GET

/api/v1/tasks/{id}/result

Загрузка сгенерированного файла PPTX

POST

/api/v1/uploads

Временное хранение бинарных исходных файлов или шаблонов

PUT

/api/v1/upload-tickets/{token}

Интерфейс прямой загрузки больших файлов (одноразовый)

GET

/api/v1/artifacts/{token}

Безопасный интерфейс загрузки с подписью HMAC на 24 часа

POST

/mcp

Эндпоинт протокола MCP Streamable HTTP

📄 Лицензия с открытым исходным кодом

Данный проект распространяется по лицензии MIT License.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers