esa MCP Server

esa MCP Server

日本語 | English

esa.io 的官方 Model Context Protocol (MCP) 伺服器 - STDIO 傳輸版本。

概覽

此 MCP 伺服器提供 AI 助理與 esa.io（一個協作文件平台）之間的無縫整合。它讓 AI 助理能夠透過 Model Context Protocol 直接讀取、建立、更新和管理 esa 文件。

可用工具

團隊管理

• esa_get_teams - 取得使用者可存取的 esa 團隊
• esa_get_team_stats - 取得團隊統計資料（成員、文章、留言、星號、監看、活躍使用者）
• esa_get_team_tags - 取得團隊文章中使用的所有標籤及其數量
• esa_get_team_members - 取得團隊成員及其角色和個人資料資訊

文章管理

• esa_search_posts - 在 esa.io 中搜尋文章
• esa_get_post - 透過文章編號取得特定文章（包含 backlinks_count 和 body_md_stats，附帶內文的字元和行數統計）
• esa_get_post_backlinks - 列出引用特定文章的文章，支援分頁
• esa_create_post - 建立新文章，可設定標籤、分類和 WIP 狀態
• esa_update_post - 更新現有文章（標題、內容、標籤、分類、WIP 狀態）
• esa_append_post - 在文章內文末端附加內容（無需取得當前內文；會儲存為新修訂版本）
• esa_prepend_post - 在文章內文開頭前置內容（無需取得當前內文；會儲存為新修訂版本）

文章操作

• esa_archive_post - 封存文章，將其移至 Archived/ 分類
• esa_ship_post - 發布文章（將 wip 設為 false 以標記為完成）
• esa_duplicate_post - 複製文章（建立具有相同標題和內文的新 WIP 文章；亦支援跨團隊複製）

留言管理

• esa_get_comment - 透過 ID 取得特定留言
• esa_create_comment - 在文章上建立新留言
• esa_update_comment - 更新現有留言
• esa_delete_comment - 刪除留言
• esa_get_post_comments - 取得特定文章的留言，支援分頁
• esa_get_team_comments - 取得團隊留言，支援分頁

分類管理

• esa_get_categories - 取得特定路徑的分類和子分類
• esa_get_top_categories - 取得團隊的所有頂層分類
• esa_get_all_category_paths - 取得團隊中的所有分類路徑（包含文章數量，支援篩選）
  • 非常適合用於了解分類結構、組織規劃和清理
  • 篩選範例：prefix: "dev" 用於開發相關，match: "api" 用於 API 相關分類

附件

• esa_get_attachment - 從 esa 文章和留言中擷取附件檔案
  • 針對支援的圖片（JPEG、PNG、GIF、WebP）且小於 30MB 的檔案，回傳 base64 編碼的資料
  • 針對其他檔案類型、較大的圖片，或指定 forceSignedUrl 時，回傳簽章 URL（有效期 5 分鐘）

說明與文件

• esa_get_search_options_help - 取得 esa 搜尋語法文件
• esa_get_markdown_syntax_help - 取得 esa Markdown 語法文件
• esa_search_help - 搜尋 esa 文件以查找功能和術語

可用資源

• esa_recent_posts - 從 esa 團隊擷取最近更新的文章
  • 範本：esa://teams/{teamName}/posts/recent
  • 回傳：最近更新文章的 JSON 列表

可用提示

• esa_summarize_post - 摘要 esa 文章內容
  • 輸入：團隊名稱和文章編號
  • 輸出：文章內容的結構化摘要

MCP 客戶端設定

新增至您的 MCP 客戶端設定檔：

必要的環境變數

• ESA_ACCESS_TOKEN：存取權杖
  • 必要範圍：read write 或 admin:comment read:post write:post read:category read:tag read:attachment read:team read:member
  • 建議使用 PAT v2。
• LANG：使用者介面的語言

Claude Desktop 範例

新增至 claude_desktop_config.json：

選項 1：Docker（建議）

{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ESA_ACCESS_TOKEN",
        "-e",
        "LANG",
        "ghcr.io/esaio/esa-mcp-server"
      ],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "en"
      }
    }
  }
}

選項 2：npx

{
  "mcpServers": {
    "esa": {
      "command": "/Users/your-username/.nodenv/shims/npx",
      "args": ["@esaio/esa-mcp-server"],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "en"
      }
    }
  }
}

注意：請將 /path/to/your/node 替換為 which node 指令的輸出。

登錄

此套件在套件根目錄提供 registry.json，公開已註冊的工具、資源和提示。可以在不啟動伺服器的情況下以程式方式使用：

import registry from "@esaio/esa-mcp-server/registry.json" with { type: "json" };

結構描述：

{
  "tools": [{ "name": "esa_get_teams" }, "..."],
  "resources": [
    { "name": "esa_recent_posts", "uriTemplate": "esa://teams/{teamName}/posts/recent" }
  ],
  "prompts": [{ "name": "esa_summarize_post" }]
}

該檔案由 npm run build:registry 重新產生，並且 CI 檢查會強制確保它與已註冊的集合保持同步。

連結

• esa.io - 協作文件平台
• Model Context Protocol - 了解更多關於 MCP 的資訊
• API 文件 - esa.io API 參考
• Claude Desktop - 支援 MCP 的 AI 助理

支援

• 📧 支援：回饋表單
• 🐛 問題：GitHub Issues
• 📖 說明：esa 文件

---

由 esa 團隊用 ❤️ 打造