JinDaGe - mcp-documents MCP Details

article

README

🚀 文档生成器MCP服务器

文档生成器MCP服务器用于创建DOCX和PDF文档，支持STDIO和HTTP两种传输方式，有效解决了文档生成和传输的问题，为用户提供了便捷的文档处理方案。

🚀 快速开始

使用uv快速启动

# 克隆仓库
git clone <repository-url>
cd docx_mcp

# 若未安装uv，可进行安装
pip install uv

# 配置环境并安装依赖
uv venv
uv pip install -e .

# 运行服务器
uv run python main.py

✨ 主要特性

创建DOCX文档 - 全面支持段落、表格和样式设置。
创建PDF文档 - 能够生成包含文本和表格的PDF文件。
会话管理 - 可逐步构建文档。
多种传输方式 - 支持本地CLI使用的STDIO方式和网络访问的HTTP方式。
清晰的架构 - 分为领域层、基础设施层和表示层。
Base64支持 - 对于小文件，可将文档以Base64编码形式返回。
MCP资源 - 可通过URI访问生成的文档。

📦 安装指南

使用pip安装

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

# 或者使用pyproject.toml
pip install -e .

使用uv安装（推荐）

# 使用uv安装依赖
uv pip install -r requirements.txt

# 或者以可编辑包的形式安装
uv pip install -e .

# 使用uv创建虚拟环境
uv venv

💻 使用示例

STDIO模式（默认）

适用于本地CLI工具和桌面应用程序：

# 直接使用python运行
python main.py

# 使用uv运行
uv run python main.py

HTTP模式

适用于网络访问和多客户端场景：

# 直接使用python运行
python main.py --transport http --host 0.0.0.0 --port 8000

# 使用uv运行
uv run python main.py --transport http --host 0.0.0.0 --port 8000

使用FastMCP CLI

# STDIO模式
fastmcp run presentation/server.py:mcp
# 或者使用uv
uv run fastmcp run presentation/server.py:mcp

# HTTP模式
fastmcp run presentation/server.py:mcp --transport http --port 8000
# 或者使用uv
uv run fastmcp run presentation/server.py:mcp --transport http --port 8000

基础用法

# 使用MCP客户端创建简单DOCX文档
result = await client.call_tool("create_docx", {
    "title": "Hello World",
    "paragraphs": ["This is a test document"],
    "return_base64": true
})

高级用法

# 创建会话
session = await client.call_tool("create_document_session", {
    "title": "Report"
})

# 添加内容
await client.call_tool("add_paragraph", {
    "document_id": session["document_id"],
    "text": "Introduction",
    "style": "bold"
})

# 保存为PDF
result = await client.call_tool("save_document", {
    "document_id": session["document_id"],
    "format": "pdf"
})

📚 详细文档

可用工具

`create_docx`

一次性创建完整的DOCX文档。

{
    "title": "My Document",
    "paragraphs": [
        "Simple text paragraph",
        {
            "text": "Styled paragraph",
            "style": "bold",
            "alignment": "center",
            "font_size": 14
        }
    ],
    "tables": [
        {
            "headers": ["Name", "Age"],
            "data": [["Alice", "30"], ["Bob", "25"]]
        }
    ],
    "return_base64": false
}

`create_pdf`

创建与DOCX结构类似的PDF文档。

`create_document_session`

启动一个会话，用于逐步构建文档。

`add_paragraph`

在会话中向文档添加段落。

`add_table`

在会话中向文档添加表格。

`save_document`

将会话中的文档保存为DOCX或PDF格式。

`list_documents`

列出当前会话中的所有文档。

项目架构

docx_mcp/
├── core/               # 领域层（业务逻辑）
│   ├── models/        # 文档、段落、表格模型
│   └── interfaces/    # 写入器接口
├── infrastructure/     # 基础设施层
│   ├── docx_writer.py # python-docx实现
│   └── pdf_writer.py  # fpdf2实现
├── application/        # 应用层
│   └── services/      # 文档服务
├── presentation/       # 表示层
│   └── server.py      # 带有工具的FastMCP服务器
└── main.py            # 入口点

MCP资源

可通过MCP资源访问文档：

documents://{filename} - 根据文件名获取文档内容。
documents://list - 列出所有生成的文档。

传输模式

STDIO传输

通过标准输入/输出进行通信。
每个客户端启动一个新的服务器进程。
适用于CLI工具和桌面应用程序。

HTTP传输

在指定端口上运行Web服务器。
支持多个并发客户端。
支持全双工通信。
URL: http://host:port/mcp

MCP客户端配置

Claude桌面配置

Windows

添加到Claude桌面配置文件（%APPDATA%\Claude\claude_desktop_config.json）：

macOS/Linux

添加到Claude桌面配置文件（~/.claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "documents-work": {
      "command": "uv",
      "args": ["run", "python", "C:/Users/batashev/Desktop/MyProjects/docx_mcp/main.py"],
      "env": {}
    }
  }
}

其他配置方式

使用相对路径：

{
  "mcpServers": {
    "documents-work": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "C:/Users/batashev/Desktop/MyProjects/docx_mcp"
    }
  }
}

使用pip代替uv：

{
  "mcpServers": {
    "documents-work": {
      "command": "python",
      "args": ["C:/Users/batashev/Desktop/MyProjects/docx_mcp/main.py"]
    }
  }
}

使用自定义输出目录：

{
  "mcpServers": {
    "documents-work": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "C:/Users/batashev/Desktop/MyProjects/docx_mcp",
      "env": {
        "OUTPUT_DIR": "C:/Users/batashev/Documents/generated_docs"
      }
    }
  }
}

测试

# 测试STDIO模式
python main.py
# 或者使用uv
uv run python main.py

# 测试HTTP模式
python main.py --transport http --port 8000
# 或者使用uv
uv run python main.py --transport http --port 8000

# 运行示例
python examples.py
# 或者使用uv
uv run python examples.py

# 在另一个终端中，使用curl或MCP客户端进行测试
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

📄 许可证

本项目采用MIT许可证。

🤝 贡献说明

欢迎大家贡献代码！请遵循清晰的架构原则，并为新功能添加测试。