# Document Converter MCP Server

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

## 功能特色

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

## 安裝需求

### 1. 安裝 pandoc

在 macOS 上，您可以使用 Homebrew：
```bash
brew install pandoc
```

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

### 2. 安裝 Node.js 依賴

```bash
npm install
```

## 建置與執行

### 建置 TypeScript 代碼
```bash
npm run build
```

### 執行 MCP Server
```bash
npm start
```

當 MCP server 成功啟動時，您會看到：
```
Document Converter MCP Server 已啟動
```

### 開發模式（自動重建和重啟）
```bash
npm run dev
```

### 驗證 MCP Server 運行狀態

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

1. **檢查進程**：
   ```bash
   ps aux | grep "node.*index.js"
   ```

2. **測試功能**：
   ```bash
   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
```javascript
{
  "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
```javascript
{
  "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 配置**：
```json
{
  "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**:
  ```bash
  cd /Users/alex/MCP_test
  npm start
  ```

- **測試轉換功能**:
  ```bash
  node test-conversion.js
  ```

- **模擬 MCP 客戶端**:
  ```bash
  node simulate-mcp-client.js
  ```

### 檢查安裝
使用 `check_pandoc_installation` 工具驗證 pandoc 是否正確安裝。

## MCP 服務管理

### 快速服務管理

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

```bash
# 啟動 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](./MCP_INTEGRATION_GUIDE.md) 了解：
- Claude Desktop 配置步驟
- 其他 MCP 客戶端整合
- 故障排除和調試技巧

## 授權

MIT License

## 貢獻

歡迎提交 Issues 和 Pull Requests！