NPX MD-to-DOCX MCP Server

一個強大的 Model Context Protocol (MCP) 伺服器,提供 Markdown 轉 DOCX 和智慧文字儲存功能。

🚀 快速安裝

波孵人 MCP 安裝寫法

{
  "npx-md-to-docx": {
    "transport": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "npx-md-to-docx"
    ]
  }
}

美波人 MCP 安裝寫法

在美波人的 Agent 設定中使用:

@welcome_msg("md生成docx生生不息啦～")
@begin settings
{
 "type":"botrun_hatch",
 "use_botrun_prompt":1,
 "agent_mode":1,
 "config": {
   "mcp_config": {
     "npx-md-to-docx": {
       "transport": "stdio",
       "command": "npx",
       "args": [
         "-y",
         "npx-md-to-docx"
       ]
     }
   }
 }
}
@end

🌟 功能特色

🔄 工具 1：Markdown → DOCX 轉換器

將 Markdown 檔案轉換為專業的 Word DOCX 格式。

支援的語法：

• ✅ 標題（H1-H6）
• ✅ 段落和換行
• ✅ 粗體、斜體、程式碼
• ✅ 列表（有序、無序）
• ✅ 程式碼區塊（含語法高亮資訊）
• ✅ 連結
• ✅ 引用區塊

安全性：

• 路徑遍歷防護
• 符號連結檢測
• 檔案覆蓋保護

📝 工具 2：智慧文字儲存為 Markdown

將純文字或 Markdown 內容儲存為結構化的 .md 檔案。

智慧功能：

• 🤖 自動標題提取（從 H1 或首行）
• 📁 三種組織策略（扁平式、分類式、日期式）
• 🏷️ 標籤系統
• 📋 自動 YAML Frontmatter
• 🔧 檔名清理和衝突處理
• ⏰ 時間戳記支援

📦 安裝

方式一：NPX 直接使用（推薦）

無需安裝，直接在 Claude Desktop 配置：

{
  "mcpServers": {
    "md-toolkit": {
      "command": "npx",
      "args": ["-y", "npx-md-to-docx"]
    }
  }
}

方式二：全域安裝

npm install -g npx-md-to-docx

然後配置：

{
  "mcpServers": {
    "md-toolkit": {
      "command": "npx-md-to-docx"
    }
  }
}

🚀 使用方式

在 Claude Desktop 中使用

配置完成後，重啟 Claude Desktop，即可使用以下功能：

範例 1：轉換 Markdown 為 DOCX

使用者：幫我把 README.md 轉換成 Word 檔案

Claude 會自動呼叫 convert_markdown_to_docx 工具：

{
  "markdownPath": "./README.md"
}

回應範例：

✅ Markdown 轉換成功！
已建立：README.docx (42.3 KB)
- 12 個標題
- 5 個程式碼區塊
- 3 個連結
- 耗時 180ms

範例 2：儲存會議記錄

使用者：記錄今天的會議：討論了新功能的設計方向，預計下週完成原型

Claude 會呼叫 save_text_as_markdown：

{
  "content": "# 會議記錄\n\n討論了新功能的設計方向，預計下週完成原型",
  "category": "meetings",
  "tags": ["會議", "設計"]
}

回應範例：

📝 已儲存至 ./markdown-files/meetings/會議記錄-20250113.md
- 自動生成標題：會議記錄
- 新增 frontmatter
- 分類：meetings

🛠️ 工具 API

convert_markdown_to_docx

輸入參數：

{
  markdownPath: string;              // 必填：Markdown 檔案路徑
  outputPath?: string;               // 選填：輸出 DOCX 路徑
  outputDir?: string;                // 選填：輸出目錄
  options?: {
    overwrite?: boolean;             // 是否覆蓋既有檔案（預設：false）
    preserveFormatting?: boolean;    // 保留原始格式（預設：true）
    includeMetadata?: boolean;       // 包含檔案 metadata（預設：true）
  };
}

輸出範例：

{
  "success": true,
  "message": "✅ Markdown 轉換成功",
  "input": {
    "path": "/path/to/input.md",
    "size": "2.3 KB",
    "lastModified": "2025-01-13T10:30:00Z"
  },
  "output": {
    "path": "/path/to/output.docx",
    "size": "45.6 KB",
    "createdAt": "2025-01-13T10:30:15Z"
  },
  "conversionStats": {
    "duration": "150ms",
    "headings": 8,
    "paragraphs": 23,
    "codeBlocks": 3,
    "links": 12
  }
}

save_text_as_markdown

輸入參數：

{
  content: string;                   // 必填：文字內容
  filename?: string;                 // 選填：檔案名稱
  category?: 'notes' | 'docs' | 'drafts' | 'meetings' |
             'todos' | 'journal' | 'snippets' | 'ideas' | 'archive';
  tags?: string[];                   // 選填：標籤陣列
  options?: {
    baseDir?: string;                // 基礎目錄（預設：./markdown-files）
    addFrontmatter?: boolean;        // 加入 frontmatter（預設：true）
    addTimestamp?: boolean;          // 檔名加入時間戳記（預設：true）
    autoTitle?: boolean;             // 自動提取標題（預設：true）
    organizationStrategy?: 'flat' | 'category' | 'date-based';  // 預設：category
    allowLargeFiles?: boolean;       // 允許大型檔案（預設：false）
  };
}

檔案組織策略：

1. 扁平式 (flat)：所有檔案在同一目錄

   ./markdown-files/
     ├── note-20250113.md
     ├── meeting-20250113.md
     └── draft-20250113.md

2. 分類式 (category)：按分類組織（預設）

   ./markdown-files/
     ├── notes/
     │   └── note-20250113.md
     ├── meetings/
     │   └── meeting-20250113.md
     └── docs/
         └── api-design.md

3. 日期式 (date-based)：按年月日組織

   ./markdown-files/
     └── 2025/
         └── 01-January/
             └── 13/
                 ├── note-103045.md
                 └── meeting-143520.md

輸出範例：

{
  "success": true,
  "message": "📝 Markdown 檔案已儲存",
  "file": {
    "path": "./markdown-files/meetings/會議記錄-20250113.md",
    "absolutePath": "/full/path/to/file.md",
    "size": "1.2 KB",
    "category": "meetings",
    "tags": ["工作", "週會"],
    "createdAt": "2025-01-13T10:30:45Z"
  },
  "metadata": {
    "autoGeneratedTitle": "會議記錄",
    "wordCount": 234,
    "lineCount": 18,
    "hasFrontmatter": true
  }
}

🔒 安全性

• 路徑遍歷防護：拒絕包含 ../ 的路徑
• 符號連結檢測：不允許處理符號連結
• 檔案大小限制：預設限制 1MB（可調整）
• 檔名清理：自動移除不安全字元
• 權限檢查：驗證讀寫權限

🧪 開發

本地開發

# 複製專案
git clone <repo-url>
cd npx-md-to-docx

# 安裝依賴
npm install

# 編譯
npm run build

# 執行測試
npm test

# 測試覆蓋率
npm run test:coverage

# 開發模式
npm run dev

測試

專案包含完整的單元測試（39 個測試案例，100% 通過）：

• ✅ PathValidator 測試
• ✅ MarkdownToDocxConverter 測試
• ✅ TextToMarkdownSaver 測試

npm test

使用 MCP Inspector 測試

npx @modelcontextprotocol/inspector node dist/index.js

📄 授權

MIT License

🤝 貢獻

歡迎提交 Issue 和 Pull Request！

📞 支援

如有問題，請開啟 GitHub Issue。