使用说明

MCP-PPTX服务器

MCP（模型上下文协议）服务器，用于生成具有自动web主题提取功能的PowerPoint演示文稿。

特性

Web主题提取：使用Playwright自动从网站中提取颜色、字体和徽标
PowerPoint生成：根据结构化规范创建专业演示文稿
主题应用程序：将提取的主题自动应用于演示文稿
代码幻灯片：用于显示具有语法适当格式的源代码的专用布局
智能子弹格式化：前缀项目符号的自动粗体格式（冒号和破折号规则）
资产缓存：高效缓存下载的图像和资源
验证：生成前对甲板规格进行全面验证
优雅降级：具有回退功能的强大错误处理
默认主题：未指定主题时，秘密AI默认主题（红色、青色、白色）

建筑

服务器实现了架构中描述的5个主要工具：

scrape_theme -从网站中提取主题元素
list_templates -列出可用的PowerPoint模板
validate_deck -验证甲板规格
generate_presentation -生成PowerPoint文件
merge_themes -组合多个刮除的主题

安装

先决条件

Python 3.8+
Conda（推荐）或virtualenv

使用Conda进行设置（推荐）

# Clone the repository
git clone <repository-url>
cd mcp-pptx

# Create conda environment
conda create -n mcp-pptx python=3.11
conda activate mcp-pptx

# Install package in development mode
pip install -e .

# Install Playwright browsers
playwright install chromium

使用pip/virtualenv进行设置

# Clone the repository
git clone <repository-url>
cd mcp-pptx

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install package in development mode
pip install -e .

# Install Playwright browsers
playwright install chromium

用法

Claude桌面配置

通过编辑以下内容在Claude Desktop中配置MCP服务器：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "MCP PPTX": {
      "command": "/Users/ki11erc0der/miniconda/envs/mcp-pptx/bin/python",
      "args": ["/Users/ki11erc0der/Workspace/mcp-pptx/run_server.py"],
      "env": {
        "MCP_PPTX_OUTPUT_DIR": "/Users/ki11erc0der/pptx-output"
      }
    }
  }
}

备注：调整路径以匹配您的系统：

替换 /Users/ki11erc0der/miniconda/envs/mcp-pptx/bin/python 使用Python路径
替换 /Users/ki11erc0der/Workspace/mcp-pptx/run_server.py 使用服务器脚本路径
集 MCP_PPTX_OUTPUT_DIR 到您想要的输出目录

在conda环境中查找Python路径：

conda activate mcp-pptx
which python  # macOS/Linux
where python  # Windows

查看日志

实时监控MCP服务器日志：

macOS:

tail -f ~/Library/Logs/Claude/mcp-server-MCP\ PPTX.log

视窗:

Get-Content "$env:APPDATA\Claude\Logs\mcp-server-MCP PPTX.log" -Wait

作为独立的MCP服务器

{
  "mcpServers": {
    "mcp-pptx": {
      "command": "python",
      "args": ["-m", "mcp_pptx"]
    }
  }
}

直接使用

from mcp_pptx.server import MCPPPTXServer

server = MCPPPTXServer()
await server.run()

快速开始

安装并激活环境：

conda activate mcp-pptx
pip install -e .

配置Claude Desktop（请参阅上面的配置部分）
重新启动克劳德桌面

创建演示文稿：

Create a 5-slide presentation about Python basics with:
- Title slide
- Introduction with bullet points
- A code example showing a simple function
- Best practices section
- Thank you slide

Use the default theme.

Claude使用示例

基本演示文稿

Create a 10-slide presentation about NICE Actimize using their website theme

使用Web剪贴

1. Scrape the theme from https://example.com
2. Create a presentation about the company using the scraped theme

带代码示例

Create a Python tutorial presentation with:
- Title slide introducing Python
- 3 code slides showing:
  * Basic syntax
  * Functions and loops
  * File handling
- Summary slide

Use CODE layout for all code examples and split long code across multiple slides.

使用智能子弹格式

Create a presentation about project phases with these bullets:
- Phase 1: Planning and requirements gathering
- Phase 2: Design and architecture
- Implementation - Building the core features
- Testing - Quality assurance and bug fixes
- Deployment - Production release

使用直接主题颜色

Create a 5-slide presentation using these colors:
- Primary: #E3342F (red)
- Accent: #1CCBD0 (cyan)
- Background: white

Include title slide, 3 content slides, and closing slide.

配置

环境变量

MCP_PPTX_OUTPUT_DIR 或 OUTPUT_DIR：默认输出目录（默认： ~/pptx-output)
CACHE_DIR：资产缓存目录（默认： ~/.cache/mcp-pptx/assets)
MAX_CACHE_AGE_HOURS：缓存过期时间（默认值：24小时）
MCP_PPTX_DEBUG：启用调试日志记录（设置为 1 或 true)

Claude Desktop中的示例配置：

{
  "mcpServers": {
    "MCP PPTX": {
      "command": "/path/to/python",
      "args": ["/path/to/run_server.py"],
      "env": {
        "MCP_PPTX_OUTPUT_DIR": "/Users/username/pptx-output",
        "MCP_PPTX_DEBUG": "1"
      }
    }
  }
}

模板和主题目录

模板：将PowerPoint模板（.potx文件）放置在 themes/ 目录
默认主题：服务器包含默认的Secret AI主题(themes/default_theme.json)与：
- 主色：红色（#E3342F）
- 次要颜色：浅桃红色（#FFE9D3）
- 主色调：青色（#1CCBD0）
- 背景：白色（#FFFFFF）
- 文字：深灰色（#111827）

数据模型

DeckSpec 的

演示文稿的完整规范，包括：

标题、副标题、作者
主题说明：
- 选项1：从网站上删除主题（使用 scrape_theme 工具优先）
- 选项2：模板文件路径(.potx 文件）
- 选项3：直接颜色和字体（简化格式）
幻灯片规格，包括布局和内容
输出首选项

使用直接颜色/字体的示例：

{
  "title": "My Presentation",
  "theme": {
    "colors": {
      "primary": "#E3342F",
      "secondary": "#1CCBD0",
      "accent": "#FFE9D3",
      "background": "#FFFFFF",
      "text": "#111827"
    },
    "fonts": {
      "heading": "Calibri",
      "body": "Arial"
    }
  },
  "slides": [...]
}

废血红素

网页主题提取结果：

调色板（主要、次要、重音、背景、文本）
字体调色板（标题、正文字体）
带有缓存资源的徽标规范
源URL和提取警告

支持的布局

TITLE -红色背景的标题幻灯片
TITLE_CONTENT -带内容区域的标题（白色背景，红色标题栏）
SECTION -带旋转颜色的分段分隔器（青色→ Red → 桃）
TWO_COL -并排内容的两列布局
CODE -单空间字体和浅灰色背景的代码幻灯片
IMAGE_FOCUS -以图像为中心的布局
TABLE -桌子布局
CHART -图表布局
BLANK -空白幻灯片

布局示例

代码布局 -显示源代码：

{
  "layout": "CODE",
  "title": "Python Example",
  "content": [
    {
      "type": "code",
      "code": "def hello():\n    print('Hello, World!')",
      "language": "python"
    }
  ]
}

特征：

字体：Courier New，20pt
代码框背景：浅灰色（#F5F5F5）
幻灯片背景：白色
保留缩进和格式
自动将长代码（>15行）拆分到多张幻灯片上

支持的内容类型

文本内容 -纯文本或段落
要点 -具有智能格式（见下文）
图像 -带有URL、alt文本和字幕
表格 -标题和数据行
图表 -各种类型的数据
代码 -具有语法格式的源代码

智能子弹格式化

项目符号使用两个规则自动格式化为粗体前缀：

结肠规则：1-4个单词，后跟 : → Bold

"Goal: Achieve success" → "Goal:" is bold
"Key Point: Important info" → "Key Point:" is bold

达世币规则：1-4个单词，后跟 - → Bold

"Goal - Achieve success" → "Goal -" is bold
"Important Note - Details here" → "Important Note -" is bold

优先：首先检查冒号规则，然后检查破折号规则

错误处理

服务器实现了三个级别的错误处理：

错误 -块生成（无效架构，缺少文件）
警告 -记录，生成继续（缺少图像，布局回退）
信息 -响应返回（资产状态、自动选择）

发展

运行测试

该项目在 tests/ 目录：

# Test default theme application
python tests/test_default_theme.py

# Test bullet splitting rules (colon and dash)
python tests/test_bullet_splitting.py

# Test CODE slide layout
python tests/test_code_slides.py

# Test code splitting across multiple slides
python tests/test_code_splitting.py

# Test all layouts
python tests/test_all_layouts.py

# Test bullet logic unit tests
python tests/test_bullet_logic.py

# Test direct color specification
python tests/test_direct_colors.py

# Run all tests with pytest (if available)
pytest tests/

代码格式化

black src/
isort src/

类型检查

mypy src/

调试

启用调试日志记录：

export MCP_PPTX_DEBUG=1  # macOS/Linux
set MCP_PPTX_DEBUG=1     # Windows

然后监视日志：

tail -f ~/Library/Logs/Claude/mcp-server-MCP\ PPTX.log  # macOS

故障排除

服务器未出现在Claude桌面中

验证配置文件位置：
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- 窗户： %APPDATA%\Claude\claude_desktop_config.json

检查Python路径：

conda activate mcp-pptx
which python  # Should match path in config

验证服务器脚本是否存在：
```
ls -la /path/to/run_server.py
```

检查日志是否有错误：

tail -50 ~/Library/Logs/Claude/mcp-server-MCP\ PPTX.log

导入错误

如果您看到导入错误，请确保软件包安装正确：

conda activate mcp-pptx
cd /path/to/mcp-pptx
pip install -e .

剧作家问题

如果网页抓取失败：

conda activate mcp-pptx
playwright install chromium

输出目录问题

确保输出目录存在并且可写：

mkdir -p ~/pptx-output
chmod 755 ~/pptx-output

测试

测试文件位于 tests/ 目录：

tests/test_default_theme.py -测试默认的Secret AI主题应用程序
tests/test_direct_colors.py -测试直接颜色规格
tests/test_all_layouts.py -测试所有幻灯片布局
tests/test_bullet_splitting.py -测试项目符号格式规则
tests/test_code_slides.py -测试CODE布局功能
tests/test_code_splitting.py -测试自动代码拆分
tests/test_bullet_logic.py -子弹分割逻辑的单元测试
tests/test_models.py -数据模型的单元测试
tests/test_server.py -MCP服务器的单元测试

所有测试都在中创建输出 ~/pptx-output/ 目录。

运行所有测试：

# Run individual tests
python tests/test_code_slides.py

# Run all tests with pytest
pytest tests/

许可证

MIT许可证