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 - 投稿を Ship します（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"、API 関連カテゴリには match: "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: UI の言語

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 ドキュメント

---

Made with ❤️ by the esa team