esa MCP Server

官方

esa.io 的官方模型上下文协议（MCP）服务器——STDIO 传输版本。

GitHub
58

文档

esa MCP Server

License: MIT

日本語 | English

esa.io 的官方模型上下文协议 (MCP) 服务器 - STDIO 传输版本。

概述

此 MCP 服务器在 AI 助手与协作文档平台 esa.io 之间提供无缝集成。它使 AI 助手能够通过模型上下文协议直接读取、创建、更新和管理 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 团队用 ❤️ 制作