MCP Documents

🚀 文檔生成器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許可證。

🤝 貢獻說明

歡迎大家貢獻代碼！請遵循清晰的架構原則，併為新功能添加測試。