esa MCP Server

oficial

Servidor oficial do Model Context Protocol (MCP) para esa.io - versão de transporte STDIO.

O que você pode fazer com Esa MCP?

  • Pesquisar e ler publicações — Encontre publicações com esa_search_posts e, em seguida, busque uma publicação específica pelo número com esa_get_post para ver a contagem de backlinks e as estatísticas do conteúdo.
  • Criar e editar conteúdo — Crie publicações com esa_create_post, atualize-as com esa_update_post ou acrescente texto no início ou no fim usando esa_append_post e esa_prepend_post.
  • Gerenciar o ciclo de vida das publicações — Publique uma publicação com esa_ship_post, arquive-a com esa_archive_post, duplique-a com esa_duplicate_post ou reverta para uma revisão anterior.
  • Gerenciar comentários — Liste os comentários de uma publicação ou equipe e, em seguida, crie, atualize ou exclua comentários com esa_create_comment, esa_update_comment e esa_delete_comment.
  • Explorar categorias e equipes — Navegue pelos caminhos das categorias com esa_get_all_category_paths e confira os detalhes da equipe com esa_get_team_stats e esa_get_team_members.
  • Resumir uma publicação — Use o prompt esa_summarize_post para obter um resumo estruturado de uma publicação de uma determinada equipe.

Documentação

esa MCP Server

License: MIT

日本語 | English

Servidor oficial do Model Context Protocol (MCP) para esa.io - versão com transporte STDIO.

Visão geral

Este servidor MCP oferece integração perfeita entre assistentes de IA e esa.io, uma plataforma colaborativa de documentação. Ele permite que assistentes de IA leiam, criem, atualizem e gerenciem documentos do esa diretamente pelo Model Context Protocol.

Ferramentas disponíveis

Gerenciamento de equipes

  • esa_get_teams - Obter as equipes do esa às quais o usuário tem acesso
  • esa_get_team_stats - Obter estatísticas da equipe (membros, publicações, comentários, estrelas, acompanhamentos, usuários ativos)
  • esa_get_team_tags - Obter todas as tags usadas nas publicações da equipe, com contagem
  • esa_get_team_members - Obter membros da equipe com funções e informações de perfil

Gerenciamento de publicações

  • esa_search_posts - Pesquisar publicações no esa.io
  • esa_get_post - Obter uma publicação específica pelo número da publicação (inclui backlinks_count e body_md_stats com as contagens de caracteres e linhas do corpo)
  • esa_get_post_backlinks - Listar publicações que fazem referência a uma publicação específica, com paginação
  • esa_create_post - Criar uma nova publicação com tags, categoria e status WIP
  • esa_update_post - Atualizar uma publicação existente (título, conteúdo, tags, categoria, status WIP)
  • esa_append_post - Acrescentar conteúdo ao final do corpo de uma publicação (não é necessário buscar o corpo atual; salvo como uma nova revisão)
  • esa_prepend_post - Acrescentar conteúdo ao início do corpo de uma publicação (não é necessário buscar o corpo atual; salvo como uma nova revisão)

Ações em publicações

  • esa_archive_post - Arquivar uma publicação movendo-a para a categoria Archived/
  • esa_ship_post - Finalizar uma publicação (marcá-la como concluída definindo wip como false)
  • esa_duplicate_post - Duplicar uma publicação (criar uma nova publicação WIP com o mesmo título e corpo; também é possível duplicar entre equipes)
  • esa_rollback_post_revision - Reverter uma publicação para uma revisão especificada (o conteúdo restaurado é salvo como uma nova revisão; verifique o número da revisão por meio de revision_number em esa_get_post)

Gerenciamento de comentários

  • esa_get_comment - Obter um comentário específico pelo ID
  • esa_create_comment - Criar um novo comentário em uma publicação
  • esa_update_comment - Atualizar um comentário existente
  • esa_delete_comment - Excluir um comentário
  • esa_get_post_comments - Obter comentários de uma publicação específica com paginação
  • esa_get_team_comments - Obter comentários da equipe com paginação

Gerenciamento de categorias

  • esa_get_categories - Obter categorias e subcategorias de um caminho específico
  • esa_get_top_categories - Obter todas as categorias de nível superior de uma equipe
  • esa_get_all_category_paths - Obter todos os caminhos de categoria de uma equipe (com contagens de publicações; permite filtragem)
    • Ideal para entender a estrutura de categorias, planejar a organização e fazer limpeza
    • Exemplos de filtros: prefix: "dev" para categorias relacionadas a desenvolvimento, match: "api" para categorias relacionadas a APIs

Anexos

  • esa_get_attachment - Recuperar um arquivo anexado de publicações e comentários do esa
    • Retorna dados codificados em base64 para imagens compatíveis (JPEG, PNG, GIF, WebP) com menos de 30 MB
    • Retorna URLs assinadas (válidas por 5 minutos) para outros tipos de arquivo, imagens maiores ou quando forceSignedUrl é especificado

Ajuda e documentação

  • esa_get_search_options_help - Obter a documentação da sintaxe de pesquisa do esa
  • esa_get_markdown_syntax_help - Obter a documentação da sintaxe Markdown do esa
  • esa_search_help - Pesquisar na documentação do esa recursos e terminologia

Recursos disponíveis

  • esa_recent_posts - Buscar publicações atualizadas recentemente da equipe do esa
    • Modelo: esa://teams/{teamName}/posts/recent
    • Retorna: lista JSON de publicações atualizadas recentemente

Prompts disponíveis

  • esa_summarize_post - Resumir o conteúdo de uma publicação do esa
    • Entrada: nome da equipe e número da publicação
    • Saída: resumo estruturado do conteúdo da publicação

Configuração do cliente MCP

Adicione ao arquivo de configuração do seu cliente MCP:

Variáveis de ambiente obrigatórias

  • ESA_ACCESS_TOKEN: token de acesso
    • Escopos obrigatórios: read write ou admin:comment read:post write:post read:category read:tag read:attachment read:team read:member
    • Recomenda-se usar PAT v2.
  • LANG: idioma da interface

Exemplo para Claude Desktop

Adicione a claude_desktop_config.json:

Opção 1: Docker (recomendado)

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

Opção 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"
      }
    }
  }
}

Observação: substitua /path/to/your/node pela saída do comando which node.

Registro

Este pacote inclui registry.json na raiz do pacote, expondo ferramentas, recursos e prompts registrados. Ele pode ser usado programaticamente sem iniciar o servidor:

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

Esquema:

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

O arquivo é gerado novamente por npm run build:registry, e uma verificação de CI garante que ele permaneça sincronizado com o conjunto registrado.

Links

Suporte


Feito com ❤️ pela equipe do esa