esa MCP Server

oficial

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

GitHub
58

Documentação

esa MCP Server

License: MIT

日本語 | English

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

Visão Geral

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

Ferramentas Disponíveis

Gerenciamento de Equipe

  • esa_get_teams - Obter as equipes acessíveis ao usuário no esa
  • esa_get_team_stats - Obter estatísticas da equipe (membros, posts, comentários, estrelas, observações, usuários ativos)
  • esa_get_team_tags - Obter todas as tags usadas nos posts da equipe com contagem
  • esa_get_team_members - Obter membros da equipe com funções e informações de perfil

Gerenciamento de Posts

  • esa_search_posts - Pesquisar posts no esa.io
  • esa_get_post - Obter um post específico pelo número do post (inclui backlinks_count e body_md_stats com contagens de caracteres e linhas do corpo)
  • esa_get_post_backlinks - Listar posts que referenciam um post específico com paginação
  • esa_create_post - Criar um novo post com tags, categoria e status WIP
  • esa_update_post - Atualizar post existente (título, conteúdo, tags, categoria, status WIP)
  • esa_append_post - Anexar conteúdo ao final do corpo de um post (sem necessidade de buscar o corpo atual; salvo como uma nova revisão)
  • esa_prepend_post - Prefixar conteúdo no início do corpo de um post (sem necessidade de buscar o corpo atual; salvo como uma nova revisão)

Ações em Posts

  • esa_archive_post - Arquivar um post movendo-o para a categoria Archived/
  • esa_ship_post - Enviar um post (marcar como concluído definindo wip como false)
  • esa_duplicate_post - Duplicar um post (criar um novo post WIP com o mesmo título e corpo; duplicação entre equipes também é suportada)

Gerenciamento de Comentários

  • esa_get_comment - Obter um comentário específico por ID
  • esa_create_comment - Criar um novo comentário em um post
  • esa_update_comment - Atualizar um comentário existente
  • esa_delete_comment - Excluir um comentário
  • esa_get_post_comments - Obter comentários de um post específico 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 para 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 em uma equipe (com contagens de posts, suporta filtros)
    • Perfeito para entender a estrutura de categorias, planejamento organizacional e limpeza
    • Exemplos de filtro: prefix: "dev" para relacionado a desenvolvimento, match: "api" para categorias relacionadas a API

Anexos

  • esa_get_attachment - Recuperar um arquivo de anexo de posts e comentários do esa
    • Retorna dados codificados em base64 para imagens suportadas (JPEG, PNG, GIF, WebP) com menos de 30MB
    • 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 documentação da sintaxe de pesquisa do esa
  • esa_get_markdown_syntax_help - Obter documentação da sintaxe Markdown do esa
  • esa_search_help - Pesquisar na documentação do esa por funcionalidades e terminologia

Recursos Disponíveis

  • esa_recent_posts - Buscar posts recentemente atualizados da equipe do esa
    • Modelo: esa://teams/{teamName}/posts/recent
    • Retorna: Lista JSON de posts recentemente atualizados

Prompts Disponíveis

  • esa_summarize_post - Resumir o conteúdo de um post do esa
    • Entrada: Nome da equipe e número do post
    • Saída: Resumo estruturado do conteúdo do post

Configuração do Cliente MCP

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

Variáveis de Ambiente Obrigatórias

  • ESA_ACCESS_TOKEN: Token de Acesso
    • Escopos necessários: read write ou admin:comment read:post write:post read:category read:tag read:attachment read:team read:member
    • PAT v2 é recomendado.
  • LANG: Idioma para a interface do usuário

Exemplo para Claude Desktop

Adicione ao 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"
      }
    }
  }
}

Nota: Substitua /path/to/your/node pela saída do comando which node.

Registro

Este pacote envia registry.json na raiz do pacote, expondo ferramentas, recursos e prompts registrados. Ele pode ser consumido 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 é regenerado 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 esa