Emlog MCP

🚀 Emlog MCP Server

Emlog MCP Server 是一個基於模型上下文協議（MCP）的 Emlog 博客系統集成服務，它允許 AI 助手通過標準化接口與 Emlog 博客進行交互，為博客管理和內容獲取提供了便捷的途徑。

🚀 快速開始

你可以選擇直接使用該服務，也可以進行本地開發安裝：

方法一：直接使用（推薦）

無需本地安裝，可直接在 Claude Desktop 配置中使用 emlog-mcp。請跳至 MCP 客戶端配置 部分。

方法二：本地開發安裝

1. 克隆項目

git clone https://github.com/eraincc/emlog-mcp.git
cd emlog-mcp

2. 安裝依賴

npm install

3. 環境變量配置

複製示例配置文件並進行編輯：

cp .env.example .env

在 .env 文件中設置以下環境變量：

# Emlog API 基礎 URL（必需）
EMLOG_API_URL=https://your-emlog-site.com

# Emlog API 密鑰（必需）
EMLOG_API_KEY=your_api_key_here

獲取 API 密鑰：

1. 登錄你的 Emlog 後臺管理系統。
2. 進入“設置”→“API 接口”。
3. 啟用 API 功能並生成 API 密鑰。
4. 將生成的密鑰複製到 .env 文件中。

4. 構建項目

npm run build

5. 運行服務

npm start

或者使用開發模式：

npm run dev

✨ 主要特性

資源

• 博客文章 (emlog://articles) - 獲取所有博客文章列表
• 分類 (emlog://categories) - 獲取所有分類信息
• 評論 (emlog://comments) - 獲取評論列表（基於最新文章）
• 微筆記 (emlog://notes) - 獲取微筆記列表
• 草稿文章 (emlog://drafts) - 獲取所有草稿文章列表
• 用戶信息 (emlog://user) - 獲取當前用戶信息

工具

• create_article - 創建新的博客文章
• update_article - 更新現有的博客文章
• get_article - 獲取特定文章的詳細信息
• search_articles - 搜索文章（支持關鍵字、標籤、分類過濾）
• like_article - 點贊文章
• add_comment - 添加評論
• get_comments - 獲取特定文章的評論列表
• create_note - 創建微筆記
• upload_file - 上傳文件（圖片和其他媒體資源）
• get_user_info - 獲取用戶信息
• get_draft_list - 獲取草稿文章列表
• get_draft_detail - 獲取特定草稿的詳細信息

🔧 技術細節

本項目使用的技術棧如下：

• TypeScript - 類型安全的 JavaScript 超集
• Node.js - JavaScript 運行時環境
• MCP SDK - 模型上下文協議 TypeScript SDK
• Axios - HTTP 客戶端庫
• Zod - 以 TypeScript 為先的模式驗證庫
• form-data - 多部分表單數據處理

📦 安裝指南

方法一：直接使用（推薦）

使用 emlog-mcp 直接在 Claude Desktop 配置中，無需本地安裝。跳轉至 MCP 客戶端配置 部分。

方法二：本地開發安裝

1. 克隆項目

git clone https://github.com/eraincc/emlog-mcp.git
cd emlog-mcp

2. 安裝依賴

npm install

3. 環境變量配置

複製示例配置文件並編輯：

cp .env.example .env

在 .env 文件中設置以下環境變量：

# Emlog API 基礎 URL（必需）
EMLOG_API_URL=https://your-emlog-site.com

# Emlog API 密鑰（必需）
EMLOG_API_KEY=your_api_key_here

獲取 API 密鑰：

1. 登錄你的 Emlog 後臺管理系統。
2. 進入“設置”→“API 接口”。
3. 啟用 API 功能並生成 API 密鑰。
4. 將生成的密鑰複製到 .env 文件中。

4. 構建項目

npm run build

5. 運行服務

npm start

或者使用開發模式：

npm run dev

💻 使用示例

基礎用法

創建博客文章

// 通過 MCP 工具調用
{
  "name": "create_article",
  "arguments": {
    "title": "My New Article",
    "content": "This is the article content, supporting HTML and Markdown formats.",
    "sort_id": 1,
    "tag": "technology,programming,MCP",
    "is_private": "n",
    "allow_comment": "y"
  }
}

搜索文章

// 搜索包含關鍵字的文章
{
  "name": "search_articles",
  "arguments": {
    "keyword": "technology",
    "page": 1,
    "count": 10
  }
}

獲取文章列表

// 通過 MCP 資源訪問
{
  "uri": "emlog://articles"
}

獲取草稿列表

// 獲取草稿列表
{
  "name": "get_draft_list",
  "arguments": {
    "count": 10
  }
}

獲取草稿詳情

// 獲取特定草稿的詳細信息
{
  "name": "get_draft_detail",
  "arguments": {
    "id": 123
  }
}

上傳文件

// 上傳圖片文件
{
  "name": "upload_file",
  "arguments": {
    "file_path": "/path/to/image.jpg"
  }
}

創建微筆記

// 發佈微筆記
{
  "name": "create_note",
  "arguments": {
    "content": "This is a micro note",
    "is_private": false
  }
}

📚 詳細文檔

MCP 客戶端配置

Claude Desktop 配置

添加到 Claude Desktop 配置文件（通常位於 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "emlog": {
      "command": "npx",
      "args": ["emlog-mcp"],
      "env": {
        "EMLOG_API_URL": "https://your-emlog-site.com",
        "EMLOG_API_KEY": "your_api_key_here"
      }
    }
  }
}

注意： 此配置直接使用已發佈的 npm 包 emlog-mcp，無需本地安裝或編譯。npx 將自動下載並運行最新版本。

項目還提供了示例配置文件 claude-desktop-config.json 以供參考。

其他 MCP 客戶端

對於其他支持 MCP 的客戶端，請參考其各自的文檔進行標準輸入輸出傳輸配置。

API 接口文檔

本服務基於 Emlog 的 REST API 構建，支持以下主要操作：

文章管理

• GET /api/article_list - 獲取文章列表
• GET /api/article_view - 獲取特定文章的詳細信息
• POST /api/article_save - 創建/更新文章
• POST /api/article_like - 點贊文章

草稿管理

• GET /api/draft_list - 獲取草稿列表
• GET /api/draft_detail - 獲取特定草稿的詳細信息

分類管理

• GET /api/sort_list - 獲取分類列表

評論管理

• GET /api/comment_list - 獲取評論列表
• POST /api/comment_save - 發佈評論

微筆記

• GET /api/note_list - 獲取微筆記列表
• POST /api/note_save - 發佈微筆記

文件上傳

• POST /api/upload - 上傳文件

用戶管理

• GET /api/userinfo - 獲取用戶信息

🔧 錯誤處理

本服務包含全面的錯誤處理機制：

• 網絡錯誤 - 自動重試和超時處理
• API 錯誤 - 返回詳細的錯誤信息
• 認證錯誤 - API 密鑰驗證失敗提示
• 參數錯誤 - 輸入參數驗證和提示

🛠️ 開發與調試

可用腳本

# 構建項目
npm run build

# 啟動服務
npm start

# 開發模式（自動重啟）
npm run dev

# 監聽模式（自動編譯）
npm run watch

# 運行測試
npm test

日誌輸出

服務將運行時狀態信息輸出到標準錯誤輸出（stderr），用於調試：

Emlog MCP server running on stdio

測試服務

項目包含一個簡單的測試腳本 test-server.js，用於驗證服務是否正常工作：

node test-server.js

⚠️ 安全考慮

1. API 密鑰保護 - 確保 API 密鑰不被洩露，使用環境變量進行存儲。
2. HTTPS 連接 - 在生產環境中，建議使用 HTTPS 連接到 Emlog API。
3. 權限控制 - 確保 API 密鑰具有適當的權限範圍。
4. 輸入驗證 - 對所有用戶輸入進行驗證和清理。

🐞 故障排除

常見問題

1. 連接失敗
   • 檢查 EMLOG_API_URL 是否正確。
   • 確認 Emlog 站點是否可訪問。
2. 認證失敗
   • 驗證 EMLOG_API_KEY 是否有效。
   • 檢查 API 密鑰權限。
3. 工具調用失敗
   • 在錯誤消息中檢查具體原因。
   • 確認參數格式是否正確。

📁 項目結構

emlog-mcp/
├── src/                    # 源代碼目錄
│   ├── index.ts           # MCP 服務主入口
│   └── emlog-client.ts    # Emlog API 客戶端
├── dist/                  # 編譯輸出目錄
├── docs/                  # 文檔目錄
│   └── api_doc.md        # 詳細的 Emlog API 文檔
├── .env.example          # 環境變量示例文件
├── .gitignore            # Git 忽略文件配置
├── claude-desktop-config.json  # Claude Desktop 配置示例
├── test-server.js        # 測試腳本
├── package.json          # 項目配置和依賴
├── tsconfig.json         # TypeScript 配置
└── README.md             # 項目文檔

🤝 貢獻

歡迎提交 Issues 和 Pull Requests 來改進本項目。在提交代碼之前，請確保：

1. 代碼通過 TypeScript 編譯檢查。
2. 遵循項目的代碼風格。
3. 添加適當的錯誤處理。
4. 更新相關文檔。

📄 許可證

本項目採用 MIT 許可證。

🔗 相關鏈接

• 項目倉庫
• 模型上下文協議
• MCP TypeScript SDK
• Emlog 官方網站
• Emlog API 文檔