esa MCP Server

esa MCP Server

日本語 | English

Máy chủ Model Context Protocol (MCP) chính thức cho esa.io - phiên bản truyền tải STDIO.

Tổng quan

Máy chủ MCP này cung cấp khả năng tích hợp liền mạch giữa các trợ lý AI và esa.io, một nền tảng tài liệu cộng tác. Nó cho phép các trợ lý AI đọc, tạo, cập nhật và quản lý tài liệu esa trực tiếp thông qua Model Context Protocol.

Công cụ có sẵn

Quản lý nhóm

• esa_get_teams - Lấy các nhóm esa mà người dùng có thể truy cập
• esa_get_team_stats - Lấy thống kê nhóm (thành viên, bài viết, bình luận, sao, theo dõi, người dùng hoạt động)
• esa_get_team_tags - Lấy tất cả thẻ được sử dụng trong bài viết của nhóm kèm số lượng
• esa_get_team_members - Lấy thành viên nhóm với vai trò và thông tin hồ sơ

Quản lý bài viết

• esa_search_posts - Tìm kiếm bài viết trong esa.io
• esa_get_post - Lấy một bài viết cụ thể theo số bài viết (bao gồm backlinks_count và body_md_stats với số ký tự và số dòng của nội dung)
• esa_get_post_backlinks - Liệt kê các bài viết tham chiếu đến một bài viết cụ thể với phân trang
• esa_create_post - Tạo bài viết mới với thẻ, danh mục và trạng thái WIP
• esa_update_post - Cập nhật bài viết hiện có (tiêu đề, nội dung, thẻ, danh mục, trạng thái WIP)
• esa_append_post - Thêm nội dung vào cuối phần thân bài viết (không cần lấy nội dung hiện tại; được lưu dưới dạng bản sửa đổi mới)
• esa_prepend_post - Thêm nội dung vào đầu phần thân bài viết (không cần lấy nội dung hiện tại; được lưu dưới dạng bản sửa đổi mới)

Hành động với bài viết

• esa_archive_post - Lưu trữ bài viết bằng cách chuyển vào danh mục Archived/
• esa_ship_post - Xuất bản bài viết (đánh dấu hoàn thành bằng cách đặt wip thành false)
• esa_duplicate_post - Nhân bản bài viết (tạo bài viết WIP mới với cùng tiêu đề và nội dung; hỗ trợ nhân bản chéo nhóm)

Quản lý bình luận

• esa_get_comment - Lấy bình luận cụ thể theo ID
• esa_create_comment - Tạo bình luận mới cho bài viết
• esa_update_comment - Cập nhật bình luận hiện có
• esa_delete_comment - Xóa bình luận
• esa_get_post_comments - Lấy bình luận cho một bài viết cụ thể với phân trang
• esa_get_team_comments - Lấy bình luận của nhóm với phân trang

Quản lý danh mục

• esa_get_categories - Lấy danh mục và danh mục con cho một đường dẫn cụ thể
• esa_get_top_categories - Lấy tất cả danh mục cấp cao nhất cho một nhóm
• esa_get_all_category_paths - Lấy tất cả đường dẫn danh mục trong một nhóm (kèm số lượng bài viết, hỗ trợ lọc)
  • Hoàn hảo để hiểu cấu trúc danh mục, lập kế hoạch tổ chức và dọn dẹp
  • Ví dụ bộ lọc: prefix: "dev" cho các danh mục liên quan đến phát triển, match: "api" cho các danh mục liên quan đến API

Tệp đính kèm

• esa_get_attachment - Truy xuất tệp đính kèm từ bài viết và bình luận esa
  • Trả về dữ liệu mã hóa base64 cho các hình ảnh được hỗ trợ (JPEG, PNG, GIF, WebP) dưới 30MB
  • Trả về URL đã ký (có hiệu lực trong 5 phút) cho các loại tệp khác, hình ảnh lớn hơn hoặc khi forceSignedUrl được chỉ định

Trợ giúp & Tài liệu

• esa_get_search_options_help - Lấy tài liệu cú pháp tìm kiếm esa
• esa_get_markdown_syntax_help - Lấy tài liệu cú pháp Markdown esa
• esa_search_help - Tìm kiếm tài liệu esa cho các tính năng và thuật ngữ

Tài nguyên có sẵn

• esa_recent_posts - Lấy các bài viết cập nhật gần đây từ nhóm esa
  • Mẫu: esa://teams/{teamName}/posts/recent
  • Trả về: Danh sách JSON các bài viết được cập nhật gần đây

Lời nhắc có sẵn

• esa_summarize_post - Tóm tắt nội dung bài viết esa
  • Đầu vào: Tên nhóm và số bài viết
  • Đầu ra: Tóm tắt có cấu trúc của nội dung bài viết

Cấu hình MCP Client

Thêm vào tệp cấu hình MCP client của bạn:

Biến môi trường bắt buộc

• ESA_ACCESS_TOKEN: Mã truy cập
  • Phạm vi bắt buộc: read write hoặc admin:comment read:post write:post read:category read:tag read:attachment read:team read:member
  • PAT v2 được khuyến nghị.
• LANG: Ngôn ngữ cho giao diện người dùng

Ví dụ Claude Desktop

Thêm vào claude_desktop_config.json:

Tùy chọn 1: Docker (Khuyến nghị)

{
  "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"
      }
    }
  }
}

Tùy chọn 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"
      }
    }
  }
}

Lưu ý: Thay thế /path/to/your/node bằng đầu ra của lệnh which node.

Sổ đăng ký

Gói này xuất xưởng registry.json tại thư mục gốc của gói, hiển thị các công cụ, tài nguyên và lời nhắc đã đăng ký. Nó có thể được sử dụng theo chương trình mà không cần khởi tạo máy chủ:

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

Lược đồ:

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

Tệp được tạo lại bởi npm run build:registry và một kiểm tra CI đảm bảo nó đồng bộ với tập hợp đã đăng ký.

Liên kết

• esa.io - Nền tảng tài liệu cộng tác
• Model Context Protocol - Tìm hiểu thêm về MCP
• Tài liệu API - Tham khảo API esa.io
• Claude Desktop - Trợ lý AI có hỗ trợ MCP

Hỗ trợ

• 📧 Hỗ trợ: Biểu mẫu phản hồi
• 🐛 Vấn đề: GitHub Issues
• 📖 Trợ giúp: Tài liệu esa

---

Được tạo với ❤️ bởi đội ngũ esa