Document Converter MCP Server

這是一個 Model Context Protocol (MCP) server，用於在 Markdown 和 Word 文件之間進行轉換。它使用 pandoc 作為底層轉換引擎。

功能特色

• 🔄 雙向轉換: 支援 Markdown 轉 Word 和 Word 轉 Markdown
• ⚙️ 豐富選項: 支援多種 pandoc 轉換選項
• 🔍 狀態檢查: 檢查 pandoc 安裝狀態和支援格式
• 🛠️ 易於整合: 遵循 MCP 協議，易於與其他工具整合

安裝需求

1. 安裝 pandoc

在 macOS 上，您可以使用 Homebrew：

brew install pandoc

或者從官方網站下載安裝程式： https://pandoc.org/installing.html

2. 安裝 Node.js 依賴

npm install

建置與執行

建置 TypeScript 代碼

npm run build

執行 MCP Server

npm start

當 MCP server 成功啟動時，您會看到：

Document Converter MCP Server 已啟動

開發模式（自動重建和重啟）

npm run dev

驗證 MCP Server 運行狀態

您可以使用以下方法確認 MCP server 正常運行：

1. 檢查進程：

   ps aux | grep "node.*index.js"
   

2. 測試功能：

   node test-conversion.js
   node simulate-mcp-client.js
   

3. 查看日誌：MCP server 會在 stderr 輸出狀態信息

可用工具

1. convert_markdown_to_word

將 Markdown 文件轉換為 Word (.docx) 文件。

參數:

• inputPath (必需): Markdown 文件的完整路徑
• outputPath (可選): Word 文件的輸出路徑
• options (可選): 轉換選項
  • standalone: 產生完整文件 (預設: true)
  • toc: 產生目錄 (預設: false)
  • numberSections: 自動編號章節 (預設: false)
  • highlightStyle: 程式碼語法高亮樣式 (預設: "pygments")

2. convert_word_to_markdown

將 Word (.docx) 文件轉換為 Markdown 文件。

參數:

• inputPath (必需): Word 文件的完整路徑
• outputPath (可選): Markdown 文件的輸出路徑
• options (可選): 轉換選項
  • extractMedia: 提取媒體文件到指定目錄
  • wrapText: 文字換行方式 ("auto", "none", "preserve")
  • atxHeaders: 使用 ATX 樣式標題 (預設: true)

3. check_pandoc_installation

檢查 pandoc 是否已安裝並顯示版本信息。

4. list_supported_formats

列出 pandoc 支援的所有輸入和輸出格式。

使用範例

轉換 Markdown 到 Word

{
  "tool": "convert_markdown_to_word",
  "arguments": {
    "inputPath": "/Users/alex/MCP_test/test.md",
    "outputPath": "/Users/alex/MCP_test/test.docx",
    "options": {
      "toc": true,
      "numberSections": true
    }
  }
}

轉換 Word 到 Markdown

{
  "tool": "convert_word_to_markdown",
  "arguments": {
    "inputPath": "/Users/alex/MCP_test/TDD 簡介拷貝.docx",
    "outputPath": "/Users/alex/MCP_test/TDD_intro.md",
    "options": {
      "extractMedia": "./media",
      "atxHeaders": true
    }
  }
}

整合到 MCP 客戶端

Claude Desktop

在 Claude Desktop 中使用此 MCP server，請按照以下步驟：

1. 找到配置文件位置：

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 添加 MCP server 配置：

{
  "mcpServers": {
    "document-converter": {
      "command": "node",
      "args": ["/Users/alex/MCP_test/dist/index.js"],
      "env": {}
    }
  }
}

3. 重啟 Claude Desktop 以載入新的 MCP server

其他 MCP 客戶端

此 MCP server 遵循標準的 MCP 協議，可以與任何支援 MCP 的客戶端整合：

• 命令: node
• 參數: ["/Users/alex/MCP_test/dist/index.js"]
• 通訊協議: stdio
• 功能: 提供 4 個文件轉換工具

驗證整合

整合成功後，您應該能夠在 MCP 客戶端中看到以下 4 個可用工具：

• convert_markdown_to_word
• convert_word_to_markdown
• check_pandoc_installation
• list_supported_formats

支援的文件格式

此 MCP server 專門針對以下格式進行了優化：

• 輸入: Markdown (.md), Word (.docx)
• 輸出: Markdown (.md), Word (.docx)

pandoc 本身支援更多格式，您可以使用 list_supported_formats 工具查看完整列表。

故障診斷

常見問題

1. "pandoc: command not found"

   • 確保已安裝 pandoc 並且在 PATH 中可用
   • 執行 which pandoc 檢查安裝位置

2. "找不到輸入文件"

   • 確保文件路徑正確且文件存在
   • 使用絕對路徑以避免路徑問題

3. 轉換失敗

   • 檢查輸入文件是否損壞
   • 確保您有寫入輸出目錄的權限

MCP 服務相關問題

4. MCP server 無法啟動

   • 確保已執行 npm run build 建置項目
   • 檢查 Node.js 版本是否支援 ES modules
   • 查看終端錯誤信息以了解具體問題

5. MCP 客戶端無法連接

   • 確認配置文件路徑正確
   • 檢查 MCP server 路徑 /Users/alex/MCP_test/dist/index.js 是否存在
   • 重啟 MCP 客戶端（如 Claude Desktop）

6. 工具無法使用

   • 使用 node simulate-mcp-client.js 測試 MCP server 功能
   • 檢查 pandoc 是否正確安裝
   • 確認文件權限設置正確

調試方法

• 測試 MCP server:

  cd /Users/alex/MCP_test
  npm start
  

• 測試轉換功能:

  node test-conversion.js
  

• 模擬 MCP 客戶端:

  node simulate-mcp-client.js
  

檢查安裝

使用 check_pandoc_installation 工具驗證 pandoc 是否正確安裝。

MCP 服務管理

快速服務管理

使用提供的服務管理腳本來管理 MCP server：

# 啟動 MCP server
./mcp-service.sh start

# 檢查服務狀態
./mcp-service.sh status

# 查看實時日誌
./mcp-service.sh logs

# 停止服務
./mcp-service.sh stop

# 重啟服務
./mcp-service.sh restart

# 測試功能
./mcp-service.sh test

服務狀態檢查

執行 ./mcp-service.sh status 會顯示：

• ✅ 服務運行狀態
• 🔢 進程 ID (PID)
• 💾 內存使用情況
• 🔧 系統依賴檢查（pandoc、Node.js）

日誌管理

• 服務日誌存儲在 mcp-server.log
• 使用 ./mcp-service.sh logs 查看實時日誌
• 日誌包含啟動信息和錯誤詳情

詳細整合指南

查看 MCP_INTEGRATION_GUIDE.md 了解：

• Claude Desktop 配置步驟
• 其他 MCP 客戶端整合
• 故障排除和調試技巧

授權

MIT License

貢獻

歡迎提交 Issues 和 Pull Requests！