File Generator MCP Server

文件生成器MCP服务器

一个生产就绪的MCP（模型上下文协议）服务器，用于使用FastMCP生成各种文件类型。此服务器提供用于创建PDF、Word、Excel、CSV、JSON、文本、HTML、Markdown、PowerPoint、图像、日历事件和联系人卡片的异步工具。

特性

• 异步工具：所有MCP工具对于并发执行都是异步的
• 同步服务：服务使用高效的同步操作
• 输入验证：Pydantic模型验证所有输入
• 结构化响应：每个工具都返回元数据，包括文件路径、URI和特定于操作系统的命令
• 文件管理：自动创建输出文件夹和文件处理
• 生产就绪：完整的类型提示、错误处理和关注点分离
• 交叉平台的：用于文件下载和打开的操作系统感知命令

支持的文件类型

• PDF -文本转换为PDF文档
• DOCX 文件 -Word文档
• XLSX文件 -Excel电子表格
• CSV -逗号分隔值
• JSON -JSON格式的数据
• 文本 -纯文本文件
• 超文本标记语言 -具有样式的网页
• 医学博士 -Markdown文档
• PPTX文件 -PowerPoint演示文稿
• 便携式网络图形 -带文本的图像
• 工业控制系统 -日历事件
• VCF -联系人卡片（vCard）

安装

先决条件

• Python 3.14或更高版本
• pip包管理器

视窗

# Create virtual environment
python -m venv venv

# Activate virtual environment
venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the server
python main.py

Linux/macOS

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run the server
python main.py

项目结构

file-generator-mcp/
├── main.py                      # FastMCP server with all tool definitions
├── requirements.txt             # Python dependencies
├── tests.py                     # Test suite
├── validation.py                # Input validation logic
├── models/
│   ├── file_request.py          # FileRequest Pydantic model
│   ├── file_response.py         # Response builder function
│   └── metadata.py              # Metadata model
├── services/
│   ├── file_service.py          # File operation helpers
│   ├── pdf_service.py           # PDF generation
│   ├── word_service.py          # Word document generation
│   ├── excel_service.py         # Excel spreadsheet generation
│   ├── csv_service.py           # CSV file generation
│   ├── json_service.py          # JSON file generation
│   ├── txt_service.py           # Text file generation
│   ├── html_service.py          # HTML file generation
│   ├── markdown_service.py      # Markdown file generation
│   ├── pptx_service.py          # PowerPoint generation
│   ├── image_service.py         # Image file generation
│   ├── calendar_service.py      # Calendar event (ICS) generation
│   └── vcard_service.py         # Contact card (VCF) generation
├── output/                      # Generated files (auto-created)
└── README.md                    # This file

建筑

清晰的关注点分离

1. 服务层 (services/)：处理文件生成的同步函数
2. 工具层 (main.py)：通过异步MCP工具包装服务 asyncio.to_thread()
3. 模型图层 (models/)：用于验证和结构化响应的Pydantic模型
4. 验证层 (validation.py)：输入验证规则

刀具图案

每个工具都遵循以下模式：

@mcp.tool(description="...")
async def create_format(filename: str, content: str) -> dict:
    req = FileRequest(filename=filename, content=content)
    result = await asyncio.to_thread(service.generate_format, req)
    return result

响应结构

所有工具都以这种结构返回响应：

{
    "success": true,
    "filename": "example.pdf",
    "path": "/absolute/path/to/example.pdf",
    "uri": "file:///absolute/path/to/example.pdf",
    "download_command": "copy \"...\" \"%USERPROFILE%\\Downloads\\\"",
    "open_command": "start \"\" \"...\""
}

用法示例

创建PDF

# Request
{
    "filename": "my_document",
    "content": "This is the PDF content"
}

# Response
{
    "success": true,
    "filename": "my_document.pdf",
    "path": "c:\\Users\\Username\\Desktop\\file-generator-mcp\\output\\my_document.pdf",
    "uri": "file:///c:/Users/Username/Desktop/file-generator-mcp/output/my_document.pdf",
    "download_command": "copy \"...\" \"%USERPROFILE%\\Downloads\\\"",
    "open_command": "start \"\" \"...\""
}

创建Excel文件

# Request
{
    "filename": "data_table",
    "content": "Name\tAge\nJohn\t30\nJane\t28"
}

# Response includes same metadata structure

输入验证规则

文件名

• 不空
• 最多100个字符
• 仅限字母数字、下划线、破折号和空格
• 无路径遍历（否 .., /, \\)
• 没有Windows保留名称（CON、PRN、AUX、NUL等）

内容

• 不空

文件输出

所有生成的文件都保存到 output/ 项目目录中的文件夹。服务器提供：

• 绝对文件路径
• 文件URI（文件：//）
• 特定于操作系统的下载命令（复制到下载文件夹）
• 特定于操作系统的打开命令（打开文件）

测试

运行测试套件：

# With pytest
pytest tests.py -v

# Or directly with Python
python tests.py

错误处理

服务器包括全面的错误处理：

• 文件名验证无效，并显示特定错误消息
• 空内容验证
• 安全文件路径构建
• 操作系统感知命令生成

需求

看 requirements.txt 对于所有依赖关系：

• 主控程序 >=0.10.0-模型上下文协议框架
• 皮丹提克 >=2.0.0-数据验证
• fpdf2 >=2.7.0-PDF生成
• python docx >=0.8.11-Word文档
• 熊猫 >=2.0.0-数据操作
• openpyxl >=3.10.0-Excel支持
• python pptx >=0.6.21-PowerPoint演示文稿
• 枕头 >=10.0.0-图像处理
• 伊肯达尔 >=5.0.0-日历事件
• vobject >=0.9.6.1-vCard支持

代码质量

• ✅ 具有适当并发性的异步工具
• ✅ I/O操作的同步服务
• ✅ 完整的类型提示贯穿始终
• ✅ Pydantic验证模型
• ✅ 生产就绪实施
• ✅ 用于跨平台路径的Pathlib
• ✅ 适当分离关注点
• ✅ 错误处理和验证

发展

要使用新的文件类型扩展服务器，请执行以下操作：

1. 在中创建服务 services/new_service.py
2. 实施 generate_format(request: FileRequest) -> dict
3. 在中添加相应的异步工具 main.py
4. 将新依赖项添加到 requirements.txt
5. 用新格式更新此README

许可证

此项目按原样提供，用于模型上下文协议。

支持

有关问题或疑问，请参阅代码结构和文档字符串，以获取有关每个组件的详细信息。